CKEditor 生态系统文档
Search
Contribute to this guide
首页/CKEditor 5/框架

guide包元数据

包元数据是一组与 CKEditor 5 相关的描述插件的数据。它允许外部构建器自动检测插件并构建它们。

对于官方的 CKEditor 5 包（以及一些合作伙伴的包），此数据由 CKEditor 5 Builder 使用，并允许构建 功能的 HTML 输出 页面，该页面列出了所有官方 CKEditor 5 插件。

包元数据应保存在 npm 上发布的包根目录下的特殊 ckeditor5-metadata.json 文件中。

只有提供主要功能的插件才应在元数据文件中描述。例如，@ckeditor/ckeditor5-mention 包的元数据文件 只描述了 Mention 插件，它是一个“胶水插件”，可以加载提及功能的编辑和 UI 部分。此包不会公开 MentionEditing 和 MentionUI 插件，它们不能单独使用。

# 插件元数据的格式

ckeditor5-metadata.json 文件是一个 JSON 对象，它包含 plugins 数组。此数组的每个元素都应是一个对象，包含有关包提供的不同插件的信息。以下是可用于描述插件的所有元数据属性的列表

  • name – 插件的人类可读名称。
  • description – 插件的人类可读简短描述。
  • docs – 插件文档的绝对或相对 URL。如果此 URL 是相对的，它将指向 https://ckeditor.npmjs.net.cn/docs/ckeditor5/latest/ 中的 CKEditor 5 文档。
  • path – 相对于导出插件的元数据文件的路径。
  • className – 用于创建插件的类的名称。此类应使用 export default 语法从文件中导出。
  • requires – 插件的软需求和其他非显式需求的数组。它应包含应在添加此插件时包含的插件的类名。如果此数组的元素是包含插件类名的另一个（嵌套）数组，则意味着至少需要此嵌套数组中列出的一个插件，但并非所有插件都需要。
  • registeredToolbars – 插件注册的所有工具栏名称的数组。这些名称需要表示配置路径（例如，table.contentToolbar 代表 editorConfig.table.contentToolbar，table.tableToolbar 代表 editorConfig.table.tableToolbar，它们由 Table 插件注册）。
  • uiComponents – 描述插件导出的 UI 组件的对象数组。此数组中的每个对象都可以包含
    • name – 插件导出的组件的名称。它应与插件注册的实际 UI 名称匹配。
    • type – 组件类型：Button、SplitButton 或 Dropdown。
    • iconPath – Button 或 SplitButton 的 SVG 图标的路径。路径可以是相对于包的，也可以是绝对的 - 链接到来自另一个包的资源。
    • label – Dropdown 组件的文本内容。
    • toolbars – 可以向其添加给定 UI 组件的工具栏名称的数组。一些 UI 组件可以添加到多个工具栏中。
  • htmlOutput – 定义给定插件可以创建的所有可能的 HTML 元素的对象数组。此对象中的主要属性是 elements。其他属性（如 classes、styles、attributes）仅适用于给定对象中 elements 属性中定义的项。通配符字符 * 用于标记任何值。所有这些属性的完整列表包括
    • elements – 插件创建或修改的 HTML 元素（单个元素或这些元素的数组）。伪元素 $block 表示给定插件为所有块元素应用类、样式或属性（在相应的属性中定义）。
    • classes – 可能应用于 elements 属性中定义的 HTML 元素的 CSS 类名（单个类名或这些类名的数组）。
    • styles – 可能应用于 elements 属性中定义的 HTML 元素的内联 CSS 样式（单个样式或这些样式的数组）。
    • attributes – 除了 class 和 styles（单独处理）之外的 HTML 属性（单个属性或这些属性的数组），这些属性可能应用于 elements 属性中定义的 HTML 元素。
    • implements – 元素或伪元素的名称，指示 elements 属性中定义的 HTML 元素可能包含由其他插件创建的类、样式或属性。例如，implements 等于 $block 意味着 HTML 元素可能包含由另一个插件定义的类、样式或属性，该插件的 elements 等于 $block。
    • isAlternative – 如果插件输出取决于其配置，则应将此值设置为 true 以标记非默认配置产生的输出。如果此值缺失或为 false，则输出将被视为默认输出。
    • _comment – 人类可读的描述，以解释更复杂的情况，例如：给定元素、类或样式何时创建的条件。

以下是一个使用此格式文档 Bold 插件的示例

{
    "name": "Bold",
    "className": "Bold",
    "description": "Implements bold formatting support. It is a part of the basic text styles package.",
    "docs": "features/basic-styles.html",
    "path": "src/bold.js",
    "uiComponents": [
        {
            "type": "Button",
            "name": "bold",
            "iconPath": "theme/icons/bold.svg"
        }
    ],
    "htmlOutput": [
        {
            "elements": "strong"
        }
    ]
}

如果您想检查其他包中的插件是如何文档化的，请访问 GitHub 上的 CKEditor 5 包 部分，并在您感兴趣的包中找到 ckeditor5-metadata.json 文件。