@mornya/react-social-libs
Version:
The project of React.js Social Share and Widget modules.
472 lines (420 loc) • 19.7 kB
Markdown
# React Social Libs
React.js Social Share and Widget library.
> This project has been created by [Vessel CLI](https://www.npmjs.com/package/@mornya/vessel).
For a simple and quick reference about it, click [here](https://mornya.github.io/documents/guide/vessel.md).
## About
React용 소셜 공유 및 위젯 컴포넌트를 제공한다.<br>
## Installation
해당 라이브러리를 사용 할 프로젝트에서는 아래와 같이 의존성 모듈로 설치한다.
```bash
$ npm install --save @mornya/react-social-libs
or
$ yarn add @mornya/react-social-libs
```
### How to use?
SPA 혹은 `Next.js` 등의 SSR 형태의 앱에서 모두 아래와 같이 바로 사용이 가능하다.
> 라이브러리 내 스타일 시트 `share.css`는 정적이나 동적으로 import 하도록 하며, 혹은 해당 css 파일을 참조하여 커스터마이징 된 css를 생성하여 사용한다.
```jsx harmony
import React from 'react';
import { Share, Widget } from '@mornya/react-social-libs';
import '@mornya/react-social-libs/dist/social.css';
export default () => (
<>
<div>
<Share.Facebook extra={{ ... }}/>
<Share.KakaoTalk/>
</div>
<div>
<Widget.FacebookLike extra={{ ... }}/>
</div>
</>
);
```
또한 개별 공유 컴포넌트 사용을 위해 아래와 같이 import 할 수 있다.
```jsx harmony
import React from 'react';
import { KakaoStory } from '@mornya/react-social-libs/dist/share/KakaoStory';
export default () => (
<KakaoStory
title="카카오스토리 공유"
extra={{
appId: 'xxxxxxxxxxxxxxxx',
hashtags: ['mornya', '카카오_스토리_공유'],
}}
/>
);
```
### Using TypeScript
`Social.*` 타이핑을 프로젝트 전역에서 사용 할 수 있도록 아래와 같이 `tsconfig.json` 파일 등에 추가한다.
```json
{
"include": [
"node_modules/@mornya/react-social-libs/dist"
]
}
```
### Customized button
공유하기 버튼의 경우 children으로 버튼 아이콘 및 모양을 지정할 수 있다.
```tsx
import React from 'react';
import { Naver as ShareNaver } from '@mornya/react-social-libs/dist/share/Naver';
export default () => (
<ShareNaver
title="네이버 공유"
extra={{ title: (OG) => `[네이버 홈 공유] ${OG.description}` }}
>
{({ onClick }) => (
<button type="button" onClick={onClick}>
<img
src="https://blog.kakaocdn.net/dn/tfdqL/btqB2H454gr/VeiTKsIcomeWSznAnPc3JK/img.png"
alt="NAVER"
width={64}
/>
</button>
)}
</ShareNaver>
);
```
### Meta tags
공유 / 위젯 모듈에서는 기본적으로 OpenGraph 포함한 메타태그 값을 참조하여 활용한다. 아래는 참조되는 메타태그이며, 참조에 필요한 값은 페이지 <head> 영역에 메타태그를 선언해주면 된다.
```typescript jsx
<head>
<meta property="og:title" content="제목" />
<meta name="keywords" content="공유, 위젯, 소셜" />
<!-- ... -->
</head>
```
각 컴포넌트의 props 중, `extra`의 `title`, `message`는 OG 값을 파라미터로 받는 함수이며 string으로 리턴해주면 해당 값에 따른 공유 제목, 메시지를 커스터마이즈 하여 보여준다.
```jsx harmony
import React from 'react';
import { Email as ShareEmail } from '@mornya/react-social-libs/dist/share/Email';
export default () => (
<ShareEmail
extra={{
title: (og) => og.title,
message: (og) => `${og.content}\n\n${og.url}`,
}}
/>
);
```
OG 파라미터 값에 해당하는 항목은 아래와 같다.
| *종류* | *참조하는 메타태그 값* |
|----------------------------------------------|-----------------|
| title | og:title |
| description | og:description |
| url | og:url |
| type | og:type |
| siteName | og:siteName |
| image | og:image |
| keywords | keywords |
| videoDuration<br>(og:type이 video.movie일 경우) | video:duration |
| musicDuration<br>(og:type이 music.song일 경우) | music:duration |
## Social modules
상세 설정은 아래 내용 참고.
<details>
<summary> <strong>공유하기 버튼</strong></summary>
소셜 공유하기 버튼. 사용 가능한 공유하기 버튼의 종류는 아래와 같다 (ABC순).
- <img src="./dist/icons-128/band.png" alt="밴드" style="width:16px;height:16px;vertical-align:middle"> 밴드
- <img src="./dist/icons-128/clipboard.png" alt="클립보드(Clipboard) 복사" style="width:16px;height:16px;vertical-align:middle"> 클립보드(Clipboard) 복사
- <img src="./dist/icons-128/email.png" alt="이메일(Email)" style="width:16px;height:16px;vertical-align:middle"> 이메일(Email)
- <img src="./dist/icons-128/facebook.png" alt="Facebook" style="width:16px;height:16px;vertical-align:middle"> Facebook
- <img src="./dist/icons-128/flipboard.png" alt="Flipboard" style="width:16px;height:16px;vertical-align:middle"> Flipboard
- <img src="./dist/icons-128/gmail.png" alt="Gmail" style="width:16px;height:16px;vertical-align:middle"> Gmail
- <img src="./dist/icons-128/kakaotalk.png" alt="KakaoTalk" style="width:16px;height:16px;vertical-align:middle"> KakaoTalk
- <img src="./dist/icons-128/line.png" alt="Line" style="width:16px;height:16px;vertical-align:middle"> Line
- <img src="./dist/icons-128/linkedin.png" alt="LinkedIn" style="width:16px;height:16px;vertical-align:middle"> LinkedIn
- <img src="./dist/icons-128/naver.png" alt="Naver" style="width:16px;height:16px;vertical-align:middle"> Naver
- <img src="./dist/icons-128/reddit.png" alt="Reddit" style="width:16px;height:16px;vertical-align:middle"> Reddit
- <img src="./dist/icons-128/skype.png" alt="Skype" style="width:16px;height:16px;vertical-align:middle"> Skype
- <img src="./dist/icons-128/sms.png" alt="SMS" style="width:16px;height:16px;vertical-align:middle"> SMS
- <img src="./dist/icons-128/telegram.png" alt="Telegram" style="width:16px;height:16px;vertical-align:middle"> Telegram
- <img src="./dist/icons-128/tumblr.png" alt="Tumblr" style="width:16px;height:16px;vertical-align:middle"> Tumblr
- <img src="./dist/icons-128/twitter.png" alt="Twitter" style="width:16px;height:16px;vertical-align:middle"> Twitter
모든 컴포넌트는 공통적으로 아래와 같은 props를 전달할 수 있다.
* `title`: (string) 마우스 오버시 나타나는 문자열.
* `extra`: (object) 공유 버튼 별 사용되는 특별 인자 값.
* `defaultIconSize`: (number) 기본 아이콘 사용시 (children이 존재하지 않을 경우) 아이콘의 가로 및 세로 픽셀.
* `children`: (node) 공유 버튼을 커스텀하게 꾸미고 싶을 경우 버튼 하위 컴포넌트를 지정해 줄 수 있음.
* `className`: (string) 공유 버튼의 클래스 지정.
* `style`: (object) 공유 버튼의 스타일 지정.
* `onBefore`: (func) 공유 버튼이 클릭되면 공유하기 기능 실행에 앞서 지정된 해당 콜백함수가 실행된다.
* `onComplete`: (func) 공유 버튼이 클릭된 후 공유가 완료되었을 때 지정된 해당 콜백함수가 실행된다.
* `onError`: (func) 공유 진행 중 오류가 발생되었을 경우 지정된 해당 콜백함수가 실행된다.
위 props 중 extra 값을 지정해야 할 경우 아래와 같이 공유 버튼 별 지정 방식에 맞춰 선언한다.
> 파라미터로 전달되는 `og` 값은 공유하기 컴포넌트에서 전달해 주는 OpenGraph 태그 속성 값 객체.
> `<meta property="og:title" content=""/>` 식으로 페이지 헤더에 정의된 메타태그에서 추출 됨.
```
og = {
title,
description,
image,
url,
type,
site_name
}
```
### <img src="./dist/icons-128/band.png" alt="밴드" style="width:24px;height:24px;line-height:1;vertical-align:middle"> Band
`message`: (func) 커스텀 공유 메시지 지정
```ecmascript 6
extra = {
message: (og) => `${og.title}\n\n${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/clipboard.png" alt="클립보드 복사" style="width:24px;height:24px;vertical-align:middle"> Clipboard Copy
`message`: (func) 커스텀 공유 메시지 지정
```ecmascript 6
extra = {
message: (og) => `${og.title}\n\n${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/email.png" alt="이메일" style="width:24px;height:24px;vertical-align:middle"> Email
`title`: (func) 타이틀 문자열\
`message`: (func) 본문 삽입 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
message: (og) => `${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/facebook.png" alt="Facebook" style="width:24px;height:24px;vertical-align:middle"> Facebook
`appId`: (string) 페이스북 API에 등록된 appId\
`permissions`: (array) 사용하고자 하는 퍼미션 목록\
`caption`: (string) 공유 후 페이스북에 노출되는 화면의 caption 항목\
`title`: (func) 공유 후 페이스북에 노출되는 화면의 title 항목\
`message`: (func) 공유 후 페이스북에 노출되는 화면의 message 항목\
`admins`: (string) 페이스북 API 참조
`isUseOAuth`: (bool) OAuth2를 이용한 공유를 실행할지, 링크 공유를 실행할지의 여부\
`isDebug`: (bool) 디버깅용 API를 호출할지, 프로덕션용을 호출할지 여부
```ecmascript 6
extra = {
appId: '',
permissions: [ 'public_profile', 'email', 'user_friends' ], // 기본 권한만! 추가 필요권한은 option 파라미터로 인입해야 함
caption: '',
title: (og) => og.title,
message: (_og) => '',
admins: '',
isUseOAuth: true,
isDebug: false,
}
```
### <img src="./dist/icons-128/flipboard.png" alt="Flipboard" style="width:24px;height:24px;vertical-align:middle"> Flipboard
`message`: (func) 커스텀 공유 메시지 지정
```ecmascript 6
extra = {
message: (og) => `[${og.title}] ${og.content}`,
}
```
### <img src="./dist/icons-128/gmail.png" alt="Gmail" style="width:24px;height:24px;vertical-align:middle"> Gmail
`title`: (func) 타이틀 문자열\
`message`: (func) 본문 삽입 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
message: (og) => `${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/kakaotalk.png" alt="KakaoTalk" style="width:24px;height:24px;vertical-align:middle"> KakaoTalk
`appId`: (string) 카카오 API에 등록된 appId\
`message`: (func) 공유 후 카카오톡에 노출되는 화면의 내용 항목\
`image`: (func) 공유 후 카카오톡에 노출되는 이미지\
`width`: (number) 공유 후 카카오톡에 노출되는 이미지 너비\
`height`: (number) 공유 후 카카오톡에 노출되는 이미지 높이
```ecmascript 6
extra = {
appId: '',
message: (og) => `${og.title}\n${og.content}`,
image: (og) => og.image,
width: 300,
height: 200,
}
```
### <img src="./dist/icons-128/line.png" alt="Line" style="width:24px;height:24px;vertical-align:middle"> Line
`message`: (func) 커스텀 공유 메시지 지정
```ecmascript 6
extra = {
message: (og) => `${og.title}\n\n${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/linkedin.png" alt="LinkedIn" style="width:24px;height:24px;vertical-align:middle"> LinkedIn
사용되는 extra 없음
### <img src="./dist/icons-128/naver.png" alt="Naver" style="width:24px;height:24px;vertical-align:middle"> Naver
`title`: (func) 타이틀 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
}
```
### <img src="./dist/icons-128/naverblog.png" alt="NaverBlog" style="width:24px;height:24px;vertical-align:middle"> NaverBlog
`title`: (func) 타이틀 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
}
```
### <img src="./dist/icons-128/reddit.png" alt="Reddit" style="width:24px;height:24px;vertical-align:middle"> Reddit
`title`: (func) 타이틀 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
}
```
### <img src="./dist/icons-128/skype.png" alt="Skype" style="width:24px;height:24px;vertical-align:middle"> Skype
`message`: (func) 본문 메시지 문자열
```ecmascript 6
extra = {
message: (og) => `${og.title}\n\n${og.content}\n\n${og.url}`,
}
```
### <img src="./dist/icons-128/sms.png" alt="SMS" style="width:24px;height:24px;vertical-align:middle"> SMS
`message`: (func) 본문 메시지 문자열\
`target`: (string) 핸드폰 번호나 E-mail 등의 공유 대상 지정
```ecmascript 6
extra = {
message: (og) => `${og.title}\n\n${og.content}\n\n${og.url}`,
target: '',
}
```
### <img src="./dist/icons-128/telegram.png" alt="Telegram" style="width:24px;height:24px;vertical-align:middle"> Telegram
`message`: (func) 추가 채팅 메시지 (공유 메시지와는 별개)
```ecmascript 6
extra = {
message: (og) => ``,
}
```
### <img src="./dist/icons-128/tumblr.png" alt="Tumblr" style="width:24px;height:24px;vertical-align:middle"> Tumblr
`title`: (func) 타이틀 문자열\
`message`: (func) 본문 삽입 문자열
```ecmascript 6
extra = {
title: (og) => og.title,
message: (og) => og.content,
}
```
### <img src="./dist/icons-128/twitter.png" alt="Twitter" style="width:24px;height:24px;vertical-align:middle"> Twitter
`message`: (func) 본문 삽입 문자열\
`hashtags`: (array) 공유 후 트위터에 노출되는 해시태그 문자열 목록
```ecmascript 6
extra = {
message: (og) => `[${og.title}]\n${og.content}`,
hashtags: [],
}
```
</details>
<details>
<summary> <strong>위젯</strong></summary>
소셜 위젯 기능. 사용 가능한 위젯의 종류는 아래와 같다.
- <img src="./dist/icons-128/facebook.png" alt="FacebookLike" style="width:16px;height:16px;vertical-align:middle"> FacebookLike
- <img src="./dist/icons-128/flipboard.png" alt="FlipboardFlipit" style="width:16px;height:16px;vertical-align:middle"> FlipboardFlipit
- <img src="./dist/icons-128/kakaostory.png" alt="KakaoStoryFollow" style="width:16px;height:16px;vertical-align:middle"> KakaoStoryFollow
- <img src="./dist/icons-128/tumblr.png" alt="TumblrFollow" style="width:16px;height:16px;vertical-align:middle"> TumblrFollow
- <img src="./dist/icons-128/tumblr.png" alt="TumblrPost" style="width:16px;height:16px;vertical-align:middle"> TumblrPost
- <img src="./dist/icons-128/twitter.png" alt="TwitterFollow" style="width:16px;height:16px;vertical-align:middle"> TwitterFollow
- <img src="./dist/icons-128/twitter.png" alt="TwitterMessage" style="width:16px;height:16px;vertical-align:middle"> TwitterMessage
- <img src="./dist/icons-128/twitter.png" alt="TwitterTweet" style="width:16px;height:16px;vertical-align:middle"> TwitterTweet
모든 컴포넌트는 공통적으로 아래와 같은 props를 전달할 수 있다.
* `extra`: (object) 공유 버튼 별 사용되는 특별 인자 값.
* `children`: (function) 공유 버튼을 커스텀하게 꾸미고 싶을 경우 버튼 하위 컴포넌트를 지정해 줄 수 있다.
* `className`: (string) 공유 버튼의 클래스 지정.
* `style`: (object) 공유 버튼의 스타일 지정.
위 props 중 extra 값을 지정해야 할 경우 아래와 같이 공유 버튼 별 지정 방식에 맞춰 선언한다.
> 파라미터로 전달되는 `og` 값은 공유하기 컴포넌트에서 전달해 주는 OpenGraph 태그 속성 값 객체.
> `<meta property="og:title" content=""/>` 식으로 페이지 헤더에 정의된 메타태그에서 추출 됨.
```
og = {
title,
description,
image,
url,
type,
site_name
}
```
### <img src="./dist/icons-128/facebook.png" alt="FacebookLike" style="width:24px;height:24px;line-height:1;vertical-align:middle"> FacebookLike
`appId`: (string) 페이스북 API에 등록된 appId\
`pageUrl`: (string) "좋아요" 대상 페이지 URL\
`isDark`: (bool) 다크 칼라 스킴 사용 여부\
`isDebug`: (bool) 디버깅용 API를 호출할지, 프로덕션용을 호출할지 여부\
`onLogin`: (func) 페이스북 계정 로그인 이벤트 발생시 콜백함수\
`onLogout`: (func) 페이스북 계정 로그아웃 이벤트 발생시 콜백함수\
`onLike`: (func) "좋아요" 버튼 클릭 이벤트 발생시 콜백함수 (API 퍼미션 리뷰 필요)\
`onUnlike`: (func) "좋아요" 버튼 클릭 해제 이벤트 발생시 콜백함수 (API 퍼미션 리뷰 필요)
```ecmascript 6
extra = {
appId: '',
pageUrl: '',
isDark: false,
isDebug: false,
onLogin: (response) => {},
onLogout: (response) => {},
onLike: (response) => {},
onUnlike: (response) => {},
}
```
### <img src="./dist/icons-128/flipboard.png" alt="FlipboardFlipit" style="width:24px;height:24px;line-height:1;vertical-align:middle"> FlipboardFlipit
`profileUrl`: (string) 팬 페이지 URL (ex. 'mornya')\
`popover`: (string) 마우스 오버시 팝오버 메시지
```ecmascript 6
extra = {
profileUrl: '',
popover: 'Flip it!',
}
```
### <img src="./dist/icons-128/kakaostory.png" alt="KakaoStoryFollow" style="width:24px;height:24px;line-height:1;vertical-align:middle"> KakaoStoryFollow
`appId`: (string) 카카오 API에 등록된 appId\
`subscribeChannelId`: (string) 팔로우(구독) 대상 채널 ID (예를 들어, 'mornya'로 입력하면 실제 구독 대상 채널은 http://story.kakao.com/ch/mornya/app 입니다)\
`showFollowerCount`: (bool) 구독 횟수 카운트를 버튼 옆에 표시 할 지 여부
```ecmascript 6
extra = {
appId: '',
subscribeChannelId: '',
showFollowerCount: true,
}
```
### <img src="./dist/icons-128/tumblr.png" alt="TumblrFollow" style="width:24px;height:24px;line-height:1;vertical-align:middle"> TumblrFollow
`tumblelog`: (string) 팔로우 할 텀블로그명 (ex. 'mornya')
```ecmascript 6
extra = {
tumblelog: '',
}
```
### <img src="./dist/icons-128/tumblr.png" alt="TumblrPost" style="width:24px;height:24px;line-height:1;vertical-align:middle"> TumblrPost
`없음`
### <img src="./dist/icons-128/twitter.png" alt="TwitterFollow" style="width:24px;height:24px;line-height:1;vertical-align:middle"> TwitterFollow
`screenName`: (string) 팔로우 할 대상 스크린네임 (ex. '@mornyacom')
```ecmascript 6
extra = {
screenName: '',
showScreenName: false,
}
```
### <img src="./dist/icons-128/twitter.png" alt="TwitterMessage" style="width:24px;height:24px;line-height:1;vertical-align:middle"> TwitterMessage
`screenName`: (string) 메시지 보낼 대상 스크린네임 (ex. '@mornyacom')\
`recipientId`: (string) 수신 대상자 목록\
`hashtags`: (array) 공유 후 메시지에 노출되는 해시태그 문자열 목록
```ecmascript 6
extra = {
screenName: '',
recipientId: '',
hashtags: [],
}
```
### <img src="./dist/icons-128/twitter.png" alt="TwitterTweet" style="width:24px;height:24px;line-height:1;vertical-align:middle"> TwitterTweet
`hashtags`: (array) 트윗 후 메시지에 노출되는 해시태그 문자열 목록\
`showScreenName`: (bool) 공유 버튼에 스크린네임을 표시 할 지 여부
```ecmascript 6
extra = {
hashtags: [],
showScreenName: false,
}
```
</details>
## Change Log
해당 프로젝트의 [CHANGELOG.md](CHANGELOG.md) 파일 참조.
## License
해당 프로젝트의 [LICENSE](LICENSE) 파일 참조.