CKEditor 生态系统文档
Search
首页/CKBox/入门

guideCKEditor 5 集成

CKBox 可以轻松地作为完整的资产管理器添加到 CKEditr 5 中。在本指南中，我们将重点介绍最简单的集成方案，其中 CKEditor 5 和 CKBox 都使用 CDN 的链接添加到网页中。

首先，将以下两个脚本添加到网页的 HTML 中

<script type="importmap">
    {
        "imports": {
            "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5.js",
            "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/42.0.0/"
        }
    }
</script>
<script src="https://cdn.ckbox.io/ckbox/2.5.1/ckbox.js"></script>

要在 CKEditor 实例中启用 CKBox，请将所有必需的配置选项添加到 ckbox 键下的对象中。在最简单的场景中，CKBox 只需要 tokenUrl 选项。

# 快速示例

在本例中，我们将使用经典编辑器类型，但还有更多编辑器类型供选择！您可以从 CKEditor 5 文档的专用指南 中了解有关从 CDN 运行 CKEditor 5 的更多信息。

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5.js",
                    "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/42.0.0/"
                }
            }
        </script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5.css" />

        <script src="https://cdn.ckbox.io/ckbox/2.5.1/ckbox.js"></script>
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.5.1/styles/themes/lark.css">
    </head>
    <body>
        <div id="editor"></div>
        <script type="module">
            import {
                ClassicEditor,
                Essentials,
                CKBox,
                CKBoxImageEdit,
                PictureEditing,
                ImageUpload,
                Heading,
                Bold,
                Italic,
                BlockQuote,
                Indent,
                Link,
                List
            } from 'ckeditor5';

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    plugins: [
                        Essentials, CKBox, CKBoxImageEdit, ImageUpload,
                        Heading, Bold, Italic, BlockQuote, Indent,
                        Link, List, PictureEditing
                    ],
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'lark'
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

以下演示示例展示了此集成的结果。尝试将剪贴板中的图像直接粘贴到编辑区域，以及拖放图像 - 文件将由 CKBox 实时保存。

您可以使用工具栏按钮打开 CKBox 对话框窗口。您可以在其中管理文件或选择要添加到编辑内容的资产。以这种方式嵌入到编辑器中的图像将生成高度优化的 <picture> 标签。如果图像在 CKBox 中的属性中设置了描述，则该描述将自动用作嵌入到编辑器中的图像的 alt 属性。

# 配置选项

使用 ckbox 属性，您可以将任何可用的 配置选项 传递给 CKBox 实例。

例如，让我们以西班牙语运行 CKEditor 5 和 CKBox，并且还将 CKBox 的主题设置为 dark。

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <script type="importmap">
            {
                "imports": {
                    "ckeditor5": "https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5.js",
                    "ckeditor5/": "https://cdn.ckeditor.com/ckeditor5/42.0.0/"
                }
            }
        </script>
        <script src="https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5/translations/es.js"></script>
        <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/42.0.0/ckeditor5.css" />

        <script src="https://cdn.ckbox.io/ckbox/2.5.1/ckbox.js"></script>
        <script src="https://cdn.ckbox.io/ckbox/2.5.1/translations/es.js"></script>
        <link rel="stylesheet" href="https://cdn.ckbox.io/ckbox/2.5.1/styles/themes/dark.css">
    </head>
    <body>
        <div id="editor"></div>
        <script type="module">
            import {
                ClassicEditor,
                Essentials,
                CKBox,
                CKBoxImageEdit,
                ImageUpload,
                Heading,
                Bold,
                Italic,
                BlockQuote,
                Indent,
                Link,
                List
            } from 'ckeditor5';

            ClassicEditor
                .create( document.querySelector( '#editor' ), {
                    language: 'es',
                    ckbox: {
                        tokenUrl: 'https://your.token.url',
                        theme: 'dark'
                    },
                    toolbar: [
                        'ckbox', 'imageUpload', '|', 'heading', '|', 'undo', 'redo', '|', 'bold', 'italic', '|',
                        'blockQuote', 'indent', 'link', '|', 'bulletedList', 'numberedList'
                    ],
                } )
                .catch( error => {
                    console.error( error );
                } );
        </script>
    </body>
</html>

如您在上面的示例中看到的，省略了 CKBox 的 language 选项。这是故意的，因为默认情况下，CKBox 的语言将与 CKEditor 5 的语言匹配，后者已设置为西班牙语。在这种情况下，在 ckbox.language 中再次设置语言将是多余的。

您可以在下面看到上面演示的配置的实时示例。

# 插件特定选项

CKEditor 5 插件为 CKBox 公开了两个插件特定选项。这些选项用于配置插件，不会传递给 CKBox 实例。

# defaultUploadCategories

将资产上传到 CKBox 时，通过将其拖放到编辑区域或粘贴到编辑区域中，资产默认情况下会进入允许该资产扩展名的第一个类别。在某些情况下，您可能希望对这种情况有更多控制权，例如，当两个或多个类别配置为允许相同的扩展名时（有关在管理面板中配置类别选项的更多信息，请参阅 类别管理 指南）。defaultUploadCategories 选项允许显式定义应用于上传特定扩展名的类别。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            defaultUploadCategories: {
                // Category referenced by name
                Files: ['pdf', 'txt', 'zip'],
                // Category referenced by ID
                'fdf2a647-b67f-4a6c-b692-5ba1dc1ed87b': ['jpg', 'png']
            }
        }
    } )
    .catch( error => {
        console.error( error );
    } );

如您在上面的示例中看到的，可以通过名称或 ID 引用类别。当通过名称引用类别时，如果类别名称发生更改，您将需要更新此配置。通过 ID 引用类别是一种更可靠的解决方案，因为类别 ID 始终保持不变。类别 ID 可以在管理面板的 资产类别 部分 中找到。

Administration panel - category ID.

请注意，分配给 defaultUploadCategories 中类别的扩展名必须与管理面板的 资产类别 部分 中允许的类别扩展名同步。如果扩展名在管理面板中的类别配置中不被允许，则该文件将不会上传。

# ignoreDataId

当资产插入到编辑器内容中时，CKEditor 的 CKBox 插件默认情况下会添加一个 data-ckbox-resource-id。此标签的目的是将内容绑定到 CKBox 资产并允许基本资产使用跟踪（例如，检查哪些 CKBox 资产在您的内容中使用）。

例如

<a href="..." data-ckbox-resource-id="hAza1FIb2YIV">link</a>

如果要禁用此功能，请将 ignoreDataId 选项设置为 true。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        ckbox: {
            tokenUrl: 'https://your.token.url',
            ignoreDataId: true
        }
    } )
    .catch( error => {
        console.error( error );
    } );

# 高级集成

要了解有关更高级集成方案的信息，请参阅 CKEditor 5 文档中的 CKBox 文件管理器 文章。