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

guideJavaScript 包内容

本指南介绍了由 包生成器 生成的 JavaScript 包的内容。

# 项目结构

项目目录结构概述

├─ lang
│  └─ contexts.json        # Entries used for creating translations.
├─ sample
│  ├─ (*) dll.html         # The editor initialized using the DLL builds.
│  ├─ index.html           # The sample file.
│  └─ ckeditor.js          # The editor initialization script.
├─ scripts
│  └─ build-dist.mjs       # Script creates `npm` and browser builds for your plugin.
├─ src
│  ├─ pluginname.js        # The plugin with example functionality.
│  ├─ index.js             # The modules exported by the package.
│  └─ **/*.js              # All JavaScript source files should be saved here.
├─ tests
│  ├─ pluginname.js
│  ├─ index.js             # Tests for the plugin.
│  └─ **/*.js              # All tests should be saved here.
├─ theme
│  ├─ icons
│  │  ├─ ckeditor.svg      # The CKEditor 5 icon displayed in the toolbar.
│  │  └─ **/*.svg          # All icon files should be saved here.
│  └─ **/*.css             # All CSS files should be saved here.
│
├─ .editorconfig           # See link below for details.
├─ .eslintrc.cjs           # ESLint configuration file.
├─ .gitattributes          # See link below for details.
├─ .gitignore              # See link below for details.
├─ .stylelintrc            # Stylelint configuration file.
├─ ckeditor5-metadata.json # See link below for details.
├─ LICENSE.md              # All created packages fall under the MIT license.
├─ package.json            # See link below for details.
└─ README.md               # Description of your project and usage instructions.

(*) 如果插件是在 --installation-methods 标志值为 current 的情况下生成的，则此文件不可用。

一些文件的开发指南

# Npm 脚本

Npm 脚本是为项目提供命令的便捷方式。它们在 package.json 文件中定义，并与其他参与该项目的人共享。它确保开发人员使用相同命令和相同选项（标志）。

您可以通过运行 npm run <script> 来执行所有脚本。对于那些脚本，具有匹配名称的预命令和后命令也会执行。

以下脚本在包中可用。

# start

启动一个具有实时重新加载机制的 HTTP 服务器，该机制允许预览和测试包中可用的插件。

服务器启动后，默认浏览器将打开开发人员示例。您可以通过将 --no-open 选项传递给该命令来关闭它。

您还可以通过指定 --language [LANG] 选项来定义将翻译创建的编辑器的语言。默认值为 'en'。

示例

# Starts the server and opens the browser.
npm run start

# Disable auto-opening the browser.
npm run start -- --no-open

# Create the editor with the interface in German.
npm run start -- --language=de

# test

允许执行包的单元测试，这些测试在 tests/ 目录中指定。该命令接受以下修饰符

  • --coverage – 创建代码覆盖率报告。
  • --watch – 观察源文件（命令在执行完测试后不会结束）。
  • --source-map – 生成源代码的源映射。
  • --verbose – 打印额外的 webpack 日志。

示例

# Execute tests.
npm run test

# Generate code coverage report after each change in the sources.
npm run test -- --coverage --test

# lint

运行 ESLint，它分析代码（所有 *.js 文件）以快速找到问题。

示例

# Execute ESLint.
npm run lint

# stylelint

类似于 lint 任务，stylelint 分析包中 CSS 代码（theme/ 目录中的 *.css 文件）。

示例

# Execute stylelint.
npm run stylelint

# build:dist

创建插件的 npm 和浏览器构建版本。这些构建版本可以通过遵循 配置 CKEditor 5 功能 指南添加到编辑器中。

示例

# Builds the `npm` and browser files thats are ready to publish.
npm run build:dist

# dll:build (*)

如果插件是在 --installation-methods 标志值为 current 的情况下生成的，则此脚本不可用。

创建一个 DLL 兼容的包构建版本，该版本可以使用 DLL 构建版本 加载到编辑器中。

示例

# Build the DLL file that is ready to publish.
npm run dll:build

# Build the DLL file and listen to changes in its sources.
npm run dll:build -- --watch

# dll:serve (*)

如果插件是在 --installation-methods 标志值为 current 的情况下生成的，则此脚本不可用。

创建一个简单的 HTTP 服务器（没有实时重新加载机制），它允许验证包的 DLL 构建版本是否与 CKEditor 5 的 DLL 构建版本 兼容。

示例

# Starts the HTTP server and opens the browser.
npm run dll:serve

您可以在两个单独的命令终端中运行 npm run dll:build -- --watch 和 npm run dll:serve。这样，在保存更改并重新加载页面后，内容将更新。

# translations:collect

收集翻译消息（t() 函数的参数）和上下文文件。然后验证提供的值是否与在 @ckeditor/ckeditor5-core 包中指定的 value 冲突。

如果满足以下条件之一，该任务可能会以错误结束

  • 发现 Unused context 错误 – 在 lang/contexts.json 文件中指定的条目未在源文件中使用。它们应该被删除。
  • 发现 Context is duplicated for the id 错误 – 一些条目重复。考虑从 lang/contexts.json 文件中删除它们，或重写它们。
  • 发现 Context for the message id is missing 错误 – 在源文件中指定的条目未在 lang/contexts.json 文件中描述。它们应该被添加。

示例

npm run translations:collect

# translations:download

从 Transifex 服务器下载翻译。根据用户在项目中的活动，它会创建用于构建编辑器的翻译文件。

该任务需要传递组织和项目名称。通常，它与以下格式匹配：https://www.transifex.com/[ORGANIZATION]/[PROJECT]。

为了避免每次调用命令时都传递这些选项，您可以在 package.json 中存储它，紧挨着 ckeditor5-package-tools translations:download 命令。

"scripts": {
  "translations:download": "ckeditor5-package-tools translations:upload --organization=[ORGANIZATION] --project=[PROJECT]"
},

示例

npm run translations:download -- --organization [ORGANIZATION] --project [PROJECT]

# translations:upload

将翻译消息上传到 Transifex 服务器。它允许用户使用 Transifex 平台创建其他语言的翻译。

该任务需要传递组织和项目名称。通常，它与以下格式匹配：https://www.transifex.com/[ORGANIZATION]/[PROJECT]。

为了避免每次调用命令时都传递这些选项，您可以在 package.json 中存储它，紧挨着 ckeditor5-package-tools translations:upload 命令。

"scripts": {
  "translations:upload": "ckeditor5-package-tools translations:upload --organization=[ORGANIZATION] --project=[PROJECT]"
},

示例

npm run translations:upload -- --organization [ORGANIZATION] --project [PROJECT]

# prepare

Npm 支持一些特殊的 生命周期脚本。它们允许在某些情况下自动执行操作

  • prepare – 在创建包和发布之前触发。

此脚本创建插件的 npm 和浏览器构建版本。

如果在创建包期间 --installation-methods 标志的值设置为 current，则该脚本只创建 npm 和浏览器构建版本，而不创建 CKEditor 5 的传统安装方法。

# 如何更改 ESLint 配置

要更改 ESLint 配置，请编辑 .eslintrc.js 文件。查看 ESLint 文档 也是一个好主意。

为了使 CKEditor 5 插件彼此兼容，我们需要在从包中导入文件时引入一些限制。要了解更多信息，请访问 DLL 指南 并 查看有关限制的详细说明。

# 翻译

由该工具创建的包，与整个 CKEditor 5 生态系统一样，包含对本地化的完全支持。如果您希望在包中包含翻译，请访问 专门的翻译指南 以了解更多信息。

包生成器提供了几个用于处理创建包中的翻译的工具。我们建议在处理翻译时遵循以下流程

  1. 调用 npm run translations:download – 下载最新版本的翻译。
    • 如果 lang/translations/* 文件有更改，请提交它们，因为它们代表新的或更新的翻译文件。
  2. 调用 npm run translations:collect – 验证上下文是否是最新的。
  3. 调用 npm run translations:upload – 上传新的翻译。
  4. 调用 npm run translations:download – 如果上传了新的上下文，它将更新包中的 en.po 文件。不要忘记提交更改。

# 报告问题

如果您在 CKEditor 5 或包生成器中发现问题，请报告问题