(旧版) 自定义安装

⚠️ 我们更改了安装方法，此旧版指南仅供用户参考。如果您想了解有关这些更改的更多信息，请参阅从自定义构建迁移指南。

# 简介

本指南将教您如何运行自己的 CKEditor 5 实例。下面您可以找到两个描述安装过程的独特路径。选择一个（或两个！）并开始您的 CKEditor 5 之旅！

可用路径

在线构建器路径 – 最适合初学者，也是最快的路径。
从源代码构建路径 – 一个高级路径，包括使用 npm 和 webpack。

# 使用在线构建器创建自定义构建

旧的在线构建器已被弃用，取而代之的是新的构建器，它具有实时预览和新的安装方法设置。我们鼓励您迁移到新方法。
如果您仍然想使用旧的设置，请查看更新包部分，了解如何在您从旧的在线构建器中获得的设置中更新包。

# 构建结构

每个构建包含以下文件

build/ckeditor.js – 可即用编辑器捆绑包，包含编辑器和所有插件。
src/ckeditor.ts – 构建的源代码入口点。build/ckeditor.js 文件由 webpack 基于此文件创建。它定义了编辑器创建器、插件列表和构建的默认配置。
sample/index.html – 附加编辑器脚本的页面。
webpack-config.js – 用于构建编辑器的 webpack 配置。
tsconfig.json – TypeScript 编译器使用的配置。

要自定义构建，您需要

安装缺少的依赖项。
更新 src/ckeditor.ts 文件。
更新构建（build/ 中的编辑器捆绑包）。

# 安装依赖项

首先，您需要安装构建的 package.json 中已指定的依赖项

npm install

然后，您可以添加缺少的依赖项（即您要添加到构建中的包）。最简单的方法是键入

npm install @ckeditor/ckeditor5-alignment

# 更新包

打开旧的在线构建器中的文件夹。
打开 package.json 文件。
将 dependencies (@ckeditor/ckeditor5-*) 中的所有 CKEditor 包更新到最新版本。例如
```
- "@ckeditor/ckeditor5-basic-styles": "39.0.2",
+ "@ckeditor/ckeditor5-basic-styles": "42.0.0",
```
确保所有包都具有相同的版本，否则您将在运行时遇到错误。
在根目录中运行 npm update。
在根目录中运行 npm run build。

更新后的构建文件已准备好位于 build/ckeditor.js 中。

# 更新构建配置

如果您安装或卸载了依赖项，您还需要修改 src/ckeditor.ts 文件。在此阶段，您应该拥有捆绑包的完整插件列表。您也可以更改编辑器创建器并指定默认的编辑器配置。例如，您的 webpack 入口文件 (src/ckeditor.ts) 可能如下所示

// The editor creator to use.
import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';

import { Alignment } from '@ckeditor/ckeditor5-alignment';
import { Autoformat } from '@ckeditor/ckeditor5-autoformat';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';
import { BlockQuote } from '@ckeditor/ckeditor5-block-quote';
import { CloudServices } from '@ckeditor/ckeditor5-cloud-services';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Heading } from '@ckeditor/ckeditor5-heading';
import {
    Image,
    ImageCaption,
    ImageStyle,
    ImageToolbar,
    ImageUpload
} from '@ckeditor/ckeditor5-image';
import { Indent } from '@ckeditor/ckeditor5-indent';
import { Link } from '@ckeditor/ckeditor5-link';
import { List } from '@ckeditor/ckeditor5-list';
import { MediaEmbed } from '@ckeditor/ckeditor5-media-embed';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { PasteFromOffice } from '@ckeditor/ckeditor5-paste-from-office';
import { Table, TableToolbar } from '@ckeditor/ckeditor5-table';
import { TextTransformation } from '@ckeditor/ckeditor5-typing';



class Editor extends ClassicEditor {
    // Plugins to include in the build.
    public static override builtinPlugins = [
        Alignment,
        Autoformat,
        BlockQuote,
        Bold,
        CloudServices,
        Essentials,
        Heading,
        Image,
        ImageCaption,
        ImageStyle,
        ImageToolbar,
        ImageUpload,
        Indent,
        Italic,
        Link,
        List,
        MediaEmbed,
        Paragraph,
        PasteFromOffice,
        Table,
        TableToolbar,
        TextTransformation
    ];

    public static override defaultConfig = {
        toolbar: {
            items: [
                'alignment',
                'heading',
                '|',
                'bold',
                'italic',
                'link',
                'bulletedList',
                'numberedList',
                '|',
                'outdent',
                'indent',
                '|',
                'imageUpload',
                'blockQuote',
                'insertTable',
                'mediaEmbed',
                'undo',
                'redo'
            ]
        },

        // This value must be kept in sync with the language defined in webpack.config.js.
        language: 'en',
        image: {
            toolbar: [
                'imageTextAlternative',
                'toggleImageCaption',
                'imageStyle:inline',
                'imageStyle:block',
                'imageStyle:side'
            ]
        },
        table: {
            contentToolbar: [
                'tableColumn',
                'tableRow',
                'mergeTableCells'
            ]
        }
    };
}

export default Editor;

# 重新构建捆绑包

修改配置或源代码后，您可以重建项目以应用更改。您很可能已经在 package.json 中有一个构建脚本。要运行它，请执行以下命令

npm run build

# 运行编辑器

您可以通过在浏览器中打开 sample/index.html 文件（通过 HTTP，而不是作为本地文件）来验证您的新构建是否有效。确保清除缓存。

# 从源代码构建编辑器

这种情况使您可以完全控制 CKEditor 5 的构建过程。这意味着您实际上不会使用之前路径中介绍的构建，而是直接从源代码构建 CKEditor 到您的项目中。这种集成方法使您可以完全控制将包含哪些功能以及如何配置 webpack。

这是一条高级路径，假设您熟悉 npm 并且您的项目已经使用 npm。如果没有，请参阅 npm 文档或在空目录中调用 npm init 并检查结果。

# 设置环境

在迁移到集成之前，您需要准备三个将用本指南中提供的代码填充的文件。创建 webpack.config.js、app.js 和 index.html 文件。

然后，安装构建 CKEditor 5 所需的包

npm install --save \
    css-loader@5 \
    postcss-loader@4 \
    raw-loader@4 \
    style-loader@2 \
    webpack@5 \
    webpack-cli@4

启用构建 CKEditor 5 所需的最小 webpack 配置为

// webpack.config.js

'use strict';

const path = require( 'path' );
const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

module.exports = {
    // https://webpack.js.cn/configuration/entry-context/
    entry: './app.js',

    // https://webpack.js.cn/configuration/output/
    output: {
        path: path.resolve( __dirname, 'dist' ),
        filename: 'bundle.js'
    },

    module: {
        rules: [
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,

                use: [ 'raw-loader' ]
            },
            {
                test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,

                use: [
                    {
                        loader: 'style-loader',
                        options: {
                            injectType: 'singletonStyleTag',
                            attributes: {
                                'data-cke': true
                            }
                        }
                    },
                    'css-loader',
                    {
                        loader: 'postcss-loader',
                        options: {
                            postcssOptions: styles.getPostCssConfig( {
                                themeImporter: {
                                    themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                                },
                                minify: true
                            } )
                        }
                    }
                ]
            }
        ]
    },

    // Useful for debugging.
    devtool: 'source-map',

    // By default webpack logs warnings if the bundle is bigger than 200kb.
    performance: { hints: false }
};

如果您不能使用最新的 webpack（在撰写本指南时，它是 5），提供的配置也适用于 webpack 4。还有一个专门针对使用 Vite 从源代码集成的完整指南。

# 创建编辑器

您现在可以安装一些 CKEditor 5 框架包，这些包将允许您初始化一个简单的富文本编辑器。但是请记住，所有包（除了 @ckeditor/ckeditor5-dev-*）都必须与基本编辑器包具有相同的版本。

您可以从具有少量功能的经典编辑器开始。

npm install --save \
    @ckeditor/ckeditor5-dev-utils@43 \
    @ckeditor/ckeditor5-editor-classic \
    @ckeditor/ckeditor5-essentials \
    @ckeditor/ckeditor5-paragraph \
    @ckeditor/ckeditor5-basic-styles \
    @ckeditor/ckeditor5-theme-lark

基于这些包，您可以创建一个简单的应用程序。

本指南使用 ES6 模块语法。如果您不熟悉它，请查看这篇文章。

在本指南中，编辑器类被直接使用，因此您使用 @ckeditor/ckeditor5-editor-classic 而不是 @ckeditor/ckeditor5-build-classic。

不使用任何预定义的编辑器构建，因为向这些构建添加新插件无论如何都需要重建它们。

// app.js

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import { Essentials } from '@ckeditor/ckeditor5-essentials';
import { Paragraph } from '@ckeditor/ckeditor5-paragraph';
import { Bold, Italic } from '@ckeditor/ckeditor5-basic-styles';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Essentials, Paragraph, Bold, Italic ],
        toolbar: [ 'bold', 'italic' ]
    } )
    .then( editor => {
        console.log( 'Editor was initialized', editor );
    } )
    .catch( error => {
        console.error( error.stack );
    } );

您现在可以运行 webpack 来构建应用程序。为此，请调用 webpack 可执行文件

./node_modules/.bin/webpack --mode development

您也可以全局安装 webpack-cli（使用 npm install -g）并通过全局可用的 webpack 运行它。

或者，您可以将其添加为 npm 脚本

"scripts": {
    "build": "webpack --mode development"
}

并使用它与

yarn run build

npm 会自动将 ./node_modules/.bin/ 添加到 PATH 中，因此在这种情况下，您不需要全局安装 webpack-cli。

如果您想构建一个缩小且经过优化的应用程序，请使用 webpack --mode production。在 webpack 文档中了解有关它的更多信息。

注意： 在 1.2.7 版之前，uglifyjs-webpack-plugin（webpack 使用的默认缩小器）存在一个 bug，导致 webpack 崩溃并出现以下错误：TypeError: Assignment to constant variable。如果您遇到此错误，请确保您的 node_modules 包含此包的最新版本（以及 webpack 使用了此版本）。

注意： CKEditor 5 构建使用 Terser 而不是 uglifyjs-webpack-plugin，因为后者似乎不再受支持。

如果一切正常，您应该看到

p@m /workspace/quick-start> ./node_modules/.bin/webpack --mode development
Hash: c96beab038124d61568f
Version: webpack 5.58.1
Time: 3023ms
Built at: 2022-03-02 17:37:38
        Asset      Size  Chunks             Chunk Names
    bundle.js  2.45 MiB    main  [emitted]  main
bundle.js.map  2.39 MiB    main  [emitted]  main
[./app.js] 638 bytes {main} [built]
[./node_modules/webpack/buildin/global.js] (webpack)/buildin/global.js 489 bytes {main} [built]
[./node_modules/webpack/buildin/harmony-module.js] (webpack)/buildin/harmony-module.js 573 bytes {main} [built]
    + 491 hidden modules

# 运行编辑器

最后，是时候创建一个 HTML 页面了

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>CKEditor 5 Quick start guide</title>
    </head>
    <body>
        <div id="editor">
            <p>The editor content goes here.</p>
        </div>

        <script src="dist/bundle.js"></script>
    </body>
</html>

在浏览器中打开此页面，您应该看到简单的所见即所得编辑器正在运行。确保检查浏览器控制台，以防出现任何错误。

Screenshot of CKEditor 5 classic editor with bold and italic features.

我们建议您在开发和调试时使用官方的 CKEditor 5 检查器。它将为您提供大量有关编辑器状态的有用信息，例如内部数据结构、选择、命令等等。

我们每天都在努力使我们的文档保持完整。您是否发现过时的信息？是否缺少内容？请通过我们的问题跟踪器报告。

随着 42.0.0 版本的发布，我们重写了大部分文档，以反映新的导入路径和功能。我们感谢您的反馈，帮助我们确保其准确性和完整性。