@vchatcloud/react-ui-kit
Version:
VChatCloud UI Kit for react integration
526 lines (419 loc) • 16.6 kB
Markdown
[](https://www.npmjs.com/package/@vchatcloud/react-ui-kit)
VChatCloud React UI Kit은 UI 컴포넌트를 제공하여 VChatCloud 채팅 서비스를 React에 통합하기 쉽게 만들어줍니다.
- [VChatCloud React UI Kit](
- [목차](
- [설치](
- [사용법](
- [코드 예시](
- [컴포넌트 설명](
- [VChatCloudApp](
- [주의사항](
- [커스터마이징](
- [컴포넌트 변경](
- [색상 변경](
- [추가 정보](
해당 라이브러리는 react 18버전을 지원합니다.
```bash
npm install react@~18 react-dom@~18 @vchatcloud/react-ui-kit
```
우선 사용하려는 프로젝트의 `index.html`에 해당 내용을 작성합니다.
```html
<head>
<!-- ... -->
<!-- 아래 내용을 추가합니다. -->
<script src="https://www.vchatcloud.com/lib/e7lib-latest.min.js"></script>
<script src="https://www.vchatcloud.com/lib/vchatcloud-last.min.js"></script>
</head>
```
그 후 프로젝트에서 UI Kit을 사용하려면, 필요한 컴포넌트를 import하여 사용합니다.
`VChatCloudApp` 컴포넌트를 사용하여 VChatCloud를 설정하고 실행할 수 있습니다.
```tsx
import { VChatCloudApp, ChannelUserGrade } from "@vchatcloud/react-ui-kit";
import { FC, useEffect, useRef } from "react";
const App: FC = () => {
const [roomId, clientKey, nickName, grade, userInfo] = [
"YOUR_ROOM_ID",
// clientKey는 원하는 값을 사용하면 되지만, 사용자끼리 중복되지 않도록 주의해주세요.
// 같은 clientKey로 로그인 시 기존에 로그인 된 사용자는 접속이 종료됩니다.
// 또는 `setRandomClientKey`함수를 불러와 사용할 수 있습니다.
"YOUR_CLIENT_KEY",
"YOUR_NICKNAME",
"user",
{ profile: 1 },
];
const privateContainer = useRef<HTMLDivElement>(null);
// private container 사용 시
useEffect(() => {
if (!privateContainer.current) return;
privateContainer.current.style.display = "none";
const observer = new MutationObserver(() => {
if (!privateContainer.current) return;
privateContainer.current.style.display =
privateContainer.current.children.length === 0 ? "none" : "block";
});
observer.observe(privateContainer.current, { childList: true });
return () => observer.disconnect();
}, []);
return (
<>
<div className="app" style={{ width: "100%", height: "100vh" }}>
<VChatCloudApp
clientKey={clientKey}
email="YOUR_EMAIL" // VChatCloud CMS계정 ID
grade={grade}
nickName={nickName}
privateContainer=".private-container" // querySelector 파라미터 또는 HTMLElement
roomId={roomId}
sessionType="parameter"
userInfo={userInfo}
// logoUrl="LOGO_IMG_URL"
// company="YOUR_COMPANY_NAME"
/>
</div>
{/* 비밀채팅용 wrapper */}
<div
className="app private-container"
ref={privateContainer}
style={{ width: "100%", height: "100vh" }}
/>
</>
);
};
export default App;
```
`VChatCloudApp` 컴포넌트는 VChatCloud 서비스를 설정하고 실행하는 메인 컴포넌트입니다. 주요 props는 다음과 같습니다:
- `clientKey` : 사용자 고유의 클라이언트 키.
- `email` : VChatCloud CMS 계정 ID.
- `grade` : 사용자 등급 (`user`, `userManager` 등).
- `nickName` : 사용자 닉네임.
- `roomId` : 채팅방 ID.
- `privateContainer` : 비밀 채팅을 위한 HTML 컨테이너 (`querySelector 파라미터` 또는 `HTMLElement`).
- `sessionType` : 세션 타입
- `login` : 로그인 화면을 사용해 접속자가 원하는 닉네임과 프로필을 설정할 수 있습니다.
- `parameter` : 파라미터로 사용자의 정보를 불러와 사용합니다. 개발자가 지정한 정보를 사용하게 됩니다.
- `private` : 파라미터와 동일하게 사용자의 정보를 불러와 사용하지만, 비밀채팅을 이용할 때 설정합니다.
- `userInfo` : 추가 사용자 정보 (객체 형태). `userInfo.profile`에 숫자를 지정하면 기본 제공하는 프로필 이미지를 사용할 수 있습니다. _(1 ~ 48까지 제공)_
- `logoUrl` : 로그인 화면에서 표시할 로고 이미지를 변경할 수 있습니다.
- `company` : 로그인 화면에서 표시할 푸터의 회사 정보를 변경할 수 있습니다.
- **`StrictMode` 비활성화 필요** : 개발서버로 실행 시 `StrictMode`를 비활성화 하여야 오류가 발생하지 않습니다.
- **중복된 `clientKey` 주의** : 같은 clientKey로 로그인 시 기존에 로그인 된 사용자가 접속이 종료됩니다. `setRandomClientKey` 함수를 사용하여 랜덤 clientKey를 생성할 수 있습니다.
`VChatCloudApp`을 사용하는 대신 `VChatCloudProvider`를 사용하실 수 있습니다. `VChatCloudProvider`내부에 원하는 컴포넌트를 사용하실 수 있으며, `useVChatCloud`훅을 불러와 필요한 데이터에 접근할 수 있습니다. 단 `useVChatCloud`훅을 사용할 경우 반드시 `VChatCloudProvider` 컴포넌트 내부에서 사용하여야 합니다.
```tsx
import { VChatCloudApp, useVChatCloud } from "@vchatcloud/react-ui-kit";
import { useCallback } from "react";
const SendButton = () => {
const { channel } = useVChatCloud();
const send = useCallback(() => {
channel?.sendMessage({ message: "Hello VChatCloud!" });
}, [channel]);
return <button onClick={send}>전송</button>;
};
const App = () => {
return (
<VChatCloudProvider
clientKey={clientKey}
company={company}
email={email}
grade={grade}
logoUrl={logoUrl}
nickName={nickName}
privateContainer={privateContainer}
roomId={roomId}
sessionType={sessionType}
url={url}
userInfo={userInfo}
onDisconnect={onDisconnect}
>
{/* 원하는 컴포넌트로 재정의하세요. */}
<SendButton />
</VChatCloudProvider>
);
};
export default App;
```
css 변수를 사용하여 원하는 부분을 덮어 써 색상을 재 지정할 수 있습니다.
목록은 아래에 있습니다.
<details>
```css
/* 일반, 라이트 모드 */
:root,
:root .light {
--button-primary:
--button-secondary:
--image-invert: none;
--scrollbar-bg:
--login-bg:
--login-desc:
--login-footer:
--profile-shadow: 1px 1.7px 7px 0 rgba(201, 201, 201, 0.3);
--profile-border:
--profile-bg:
--profile-button-bg:
--profile-img-border:
--profile-input-border:
--profile-input-color:
--profile-input-focus-border:
--notify-toast-box-shadow: 1.5px 2.6px 5px 0 rgba(168, 168, 168, 0.3);
--notify-toast-bg-color:
--notify-toast-text-color:
--drawer-color-bg:
--drawer-color-text:
--drawer-color-border:
--drawer-color-shadow: rgba(168, 168, 168, 0.3);
--drawer-color-drawer-border:
--file-drawer-border-color:
--file-drawer-header-title-color:
--file-drawer-tab-color:
--file-drawer-tab-focus-color:
--file-drawer-tab-focus-border-color:
--file-drawer-select-count-color:
--file-drawer-save-color:
--preview-item-checked-border-color:
--file-item-preview-bg:
--file-item-preview-border:
--file-item-preview-text:
--file-item-preview-sub-text:
--translate-modal-shadow: rgba(168, 168, 168, 0.3);
--translate-modal-popup-bg:
--translate-modal-border-color:
--translate-modal-title-color:
--translate-modal-translate-bg-color:
--translate-modal-translate-text-color:
--modal-dim: rgba(0, 0, 0, 0.7);
--modal-shadow: rgba(168, 168, 168, 0.3);
--modal-bg:
--modal-border:
--modal-title:
--modal-content:
--invite-popup-input-bg:
--invite-popup-input-border:
--invite-popup-input-color:
--secret-bg-color:
--secret-text-color:
--checkbox-border-color:
--checkbox-bg-color:
--user-item-border-color:
--user-item-nickname-color:
--user-item-translate-color:
--toggle-bar-color:
--toggle-bar-on-color:
--toggle-dot-color:
--toggle-dot-on-color:
--toggle-label-color:
--whisper-modal-input-text-color:
--whisper-modal-input-bg-color:
--whisper-modal-input-border-color:
--user-popup-shadow: rgba(168, 168, 168, 0.3);
--user-popup-border:
--user-popup-bg:
--user-popup-text:
--user-popup-focus-bg:
--user-popup-focus-text:
--user-popup-opacity: 1;
--user-popup-focus-opacity: 1;
--chatting-field-bg:
--chatting-field-nickname:
--chatting-field-input-text:
--chatting-field-input-placeholder:
--chatting-field-border-color:
--chatting-field-input-size-color:
--emoticon-field-border-color:
--emoticon-field-hover-bg-color: rgba(0, 0, 0, 0.1);
--emoticon-field-list-bg-color:
--emoticon-field-list-opacity: 1;
--emoticon-field-focus-border-color:
--emoticon-field-focus-box-shadow: 1px 1.7px 1px 0 rgba(207, 207, 207, 0.3);
--emoticon-field-focus-bg-color:
--scroll-down-bg:
--scroll-down-text:
--scroll-down-border:
--scroll-down-shadow: rgba(105, 105, 105, 0.25);
--chatting-header-bg:
--chatting-header-border:
--chatting-header-text:
--chatting-header-user-count:
--chatting-body-bg:
--notice-item-bg:
--notice-item-content:
--notice-item-shadow: rgba(157, 173, 184, 0.3);
--chat-base-border:
--chat-base-nickname:
--chat-base-time:
--text-chat-item-message:
--whisper-item-from:
--whisper-item-nickname-from:
--whisper-item-to:
--whisper-item-nickname-to:
--whisper-item-nickname-where:
--whisper-item-message:
--whisper-item-time:
--whisper-item-shadow: rgba(157, 173, 184, 0.3);
--join-item-message:
--exit-item-message:
--alert-item-message:
--open-graph-item-border:
--open-graph-item-shadow: rgba(157, 173, 184, 0.3);
--open-graph-item-background:
--open-graph-item-title:
--open-graph-item-desc:
--radio-group-border:
--radio-group-checked:
--radio-group-radio-bg:
--radio-group-text:
}
/* 다크 모드 */
:root .dark {
--button-primary:
--button-secondary:
--image-invert: invert(100%);
--scrollbar-bg:
--login-bg:
--login-desc:
--login-footer:
--profile-shadow: 1.5px 2.6px 5px 0 rgba(0, 0, 0, 0.3);
--profile-border:
--profile-bg:
--profile-button-bg:
--profile-img-border:
--profile-input-border:
--profile-input-color:
--profile-input-focus-border:
--notify-toast-box-shadow: 1.5px 2.6px 5px 0 rgba(0, 0, 0, 0.3);
--notify-toast-bg-color:
--notify-toast-text-color:
--drawer-color-bg:
--drawer-color-text:
--drawer-color-border:
--drawer-color-shadow: rgba(0, 0, 0, 0.3);
--drawer-color-drawer-border:
--file-drawer-border-color:
--file-drawer-header-title-color:
--file-drawer-tab-color:
--file-drawer-tab-focus-color:
--file-drawer-tab-focus-border-color:
--file-drawer-select-count-color:
--file-drawer-save-color:
--preview-item-checked-border-color:
--file-item-preview-bg:
--file-item-preview-border:
--file-item-preview-text:
--file-item-preview-sub-text:
--translate-modal-shadow: rgba(0, 0, 0, 0.3);
--translate-modal-popup-bg:
--translate-modal-border-color:
--translate-modal-title-color:
--translate-modal-translate-bg-color:
--translate-modal-translate-text-color:
--modal-dim: rgba(0, 0, 0, 0.7);
--modal-shadow: rgba(0, 0, 0, 0.3);
--modal-bg:
--modal-border:
--modal-title:
--modal-content:
--modal-button-primary:
--invite-popup-input-bg:
--invite-popup-input-border:
--invite-popup-input-color:
--secret-bg-color:
--secret-text-color:
--checkbox-border-color:
--checkbox-bg-color:
--user-item-border-color:
--user-item-nickname-color:
--user-item-translate-color:
--toggle-bar-color:
--toggle-bar-on-color:
--toggle-dot-color:
--toggle-dot-on-color:
--toggle-label-color:
--whisper-modal-input-text-color:
--whisper-modal-input-bg-color:
--whisper-modal-input-border-color:
--user-popup-shadow: rgba(0, 0, 0, 0.3);
--user-popup-border:
--user-popup-bg:
--user-popup-text:
--user-popup-focus-bg:
--user-popup-focus-text:
--user-popup-opacity: 0.7;
--user-popup-focus-opacity: 1;
--chatting-field-bg:
--chatting-field-nickname:
--chatting-field-input-text:
--chatting-field-input-placeholder:
--chatting-field-border-color:
--chatting-field-input-size-color:
--emoticon-field-border-color:
--emoticon-field-hover-bg-color: rgba(255, 255, 255, 0.1);
--emoticon-field-list-bg-color:
--emoticon-field-list-opacity: 0.5;
--emoticon-field-focus-border-color:
--emoticon-field-focus-box-shadow: 1px 1.7px 1px 0 rgba(0, 0, 0, 0.3);
--emoticon-field-focus-bg-color:
--scroll-down-bg:
--scroll-down-text:
--scroll-down-border:
--scroll-down-shadow: rgba(0, 0, 0, 0.25);
--chatting-header-bg:
--chatting-header-border:
--chatting-header-text:
--chatting-header-user-count:
--chatting-body-bg:
--notice-item-bg:
--notice-item-content:
--notice-item-shadow: rgba(0, 0, 0, 0.3);
--chat-base-border:
--chat-base-nickname:
--chat-base-time:
--text-chat-item-message:
--whisper-item-from:
--whisper-item-nickname-from:
--whisper-item-to:
--whisper-item-nickname-to:
--whisper-item-nickname-where:
--whisper-item-message:
--whisper-item-time:
--whisper-item-shadow: rgba(0, 0, 0, 0.3);
--join-item-message:
--exit-item-message:
--alert-item-message:
--open-graph-item-border:
--open-graph-item-shadow: rgba(0, 0, 0, 0.3);
--open-graph-item-background:
--open-graph-item-title:
--open-graph-item-desc:
--radio-group-border:
--radio-group-checked:
--radio-group-radio-bg:
--radio-group-text:
}
```
</details>
아래와 같이 원하는 변수를 재 지정하여 덮어쓸 수 있습니다.
```css
:root,
:root .light {
--button-primary: skyblue;
}
/* 다크모드 색상 */
:root .dark {
--button-primary: beige;
}
```
더 많은 정보와 자세한 사용법은 [공식 문서 링크](https://www.vchatcloud.com/doc/react)를 참조하세요.