React

如果您想在 React 应用程序中使用 CKBox，您可以直接使用 @ckbox/core 包导出的 CKBox React 组件。首先使用 NPM 或类似工具安装以下包

npm install @ckbox/core @ckbox/components

如果您使用 CKBox 的 CKEditor 插件，则另外安装 ckbox 包

npm install ckbox

下面显示的是一个示例 React 组件文件的示例内容

import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

// CKEditor plugin for CKBox has an implicit dependency on `ckbox` package.
// Therefore, make sure to install and import it if you use the plugin.
//
// If you don't use CKEditor plugin for CKBox, then `ckbox` package can be omitted.
import "ckbox";

function App() {
    return <CKBox tokenUrl="https://your.token.url" />;
}

export default App;

# 类别图标作为 React 组件

使用 React 时，除了使用 简单的字符串作为图标之外，您还可以轻松地使用自定义 React 组件覆盖类别图标。CKBox 样式通过 className 属性注入。

import * as React from "react";
import { CKBox } from "@ckbox/core";
import "@ckbox/components/dist/styles/ckbox.css";

function App() {
    return (
        <CKBox
            categories={{
                icons: {
                    Files: ({ className }) => (
                        <svg
                            xmlns="http://www.w3.org/2000/svg"
                            className={className}
                            viewBox="0 0 20 20"
                        >
                            <path d="M6 6V5a3 3 0 013-3h2a3 3 0 013 3v1h2a2 2 0 012 2v3.57A22.952 22.952 0 0110 13a22.95 22.95 0 01-8-1.43V8a2 2 0 012-2h2zm2-1a1 1 0 011-1h2a1 1 0 011 1v1H8V5zm1 5a1 1 0 011-1h.01a1 1 0 110 2H10a1 1 0 01-1-1z" />
                            <path d="M2 13.692V16a2 2 0 002 2h12a2 2 0 002-2v-2.308A24.974 24.974 0 0110 15c-2.796 0-5.487-.46-8-1.308z" />
                        </svg>
                    ),
                },
            }}
            tokenUrl="https://your.token.url"
        />
    );
}

export default App;

# React 的旧版本

如上所述，@ckbox/core 包需要 React 18 才能正常工作，它不能直接用于 React 的旧版本。

因此，如果您的应用程序使用的是 18 之前的版本的 React，我们建议您改用 ckbox 包。由于 react 和 react-dom 是 ckbox 包的传递依赖项，因此其 UMD 版本应用于避免在同一应用程序中运行多个版本的 React 时出现问题。

首先在应用程序的入口文件中导入 ckbox UMD 构建版本

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";

// Import UMD build only once in your app.
// `CKBox` object will be exposed globally.
import "ckbox/dist/ckbox.js";

const app = document.getElementById("app");

ReactDOM.render(
    <React.StrictMode>
        <App />
    </React.StrictMode>,
    app
);

CKBox 对象将全局公开，因此可以在组件中通过直接导入的方式进行引用

import React from "react";

function App() {
    const ref = React.useRef(null);

    React.useEffect(() => {
        const root = ref.current;

        if (!root) {
            return;
        }

        const { unmount } = CKBox.mount(root, {
            dialog: true,
            tokenUrl: "https://your.token.url",
        });

        return () => {
            unmount();
        };
    }, []);

    return <div ref={ref} />;
}

export default App;

# 服务器端渲染

虽然理论上 CKBox 可以进行服务器端渲染，但它仍然依赖于客户端功能，例如 localStorage 作为实例化的一部分。这可能会导致服务器端渲染的 HTML 与客户端渲染的 HTML 之间出现不匹配，从而导致用户体验变差。因此，如果您的应用程序默认使用服务器端渲染，我们建议您为 CKBox 选择退出该功能。

# Next.js

Next.js 是最流行的 React 框架之一，它默认使用服务器端渲染。您可以通过动态导入 CKBox 并在 禁用 SSR 的情况下进行集成，如下所示

import React from "react";
import dynamic from "next/dynamic";
import "@ckbox/components/dist/styles/ckbox.css";

const CKBox = dynamic(() => import("@ckbox/core").then((e) => e.CKBox), {
    ssr: false,
});

export default function Home() {
    return <CKBox dialog={true} tokenUrl="https://your.token.url" />;
}