(遗留) Vue.js 2.x 富文本编辑器组件

⚠️ 我们更改了安装方法，此遗留指南保留供用户参考。如果您正在寻找当前的 CKEditor 5 Vue 2 集成，请参阅最新的 CKEditor 5 集成指南。

CKEditor 5 由即用型编辑器构建和 CKEditor 5 框架组成，构建基于该框架。

在 Vue.js 应用程序中使用 CKEditor 5 的最简单方法是选择其中一个富文本编辑器构建，并将其传递给 Vue.js 组件的配置。在快速入门部分阅读有关此解决方案的更多信息。

此外，您可以从源代码集成 CKEditor 5，这是一个更灵活、更强大的解决方案，但需要一些额外的配置。

看门狗功能可用于 React 和 Angular 集成，但尚不支持 Vue。

# 快速入门

安装 CKEditor 5 WYSIWYG 编辑器组件 for Vue.js 和您选择的编辑器构建。

假设您选择了 @ckeditor/ckeditor5-build-classic

npm install --save @ckeditor/ckeditor5-vue2 @ckeditor/ckeditor5-build-classic

现在您需要在您的应用程序中启用 CKEditor 组件。有两种方法可以做到这一点

通过直接脚本包含,
通过使用 ES6 模块导入.

可选地，您可以在本地使用组件。

# 直接脚本包含

这是在您的项目中开始使用 CKEditor 的最快方法。假设 Vue 已安装，请包含 WYSIWYG 编辑器组件和构建的 <script> 标记

<script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js"></script>
<script src="../node_modules/@ckeditor/ckeditor5-vue2/dist/ckeditor.js"></script>

使用 Vue.use() 方法在您的应用程序中启用该组件

Vue.use( CKEditor );

除了调用 Vue.use()，您也可以始终在本地使用组件。

在您的模板中使用 <ckeditor> 组件

editor 指令指定编辑器构建。
v-model 指令启用开箱即用的双向数据绑定。
config 指令可帮助您将配置传递给编辑器实例。

<div id="app">
    <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
</div>

const app = new Vue( {
    el: '#app',
    data: {
        editor: ClassicEditor,
        editorData: '<p>Content of the editor.</p>',
        editorConfig: {
            // The configuration of the editor.
        }
    }
} );

瞧！您应该看到 CKEditor 5 在您的 Vue.js 应用程序中运行。

请参阅支持的指令和事件列表，这些将帮助您配置组件。

# 使用 ES6 模块

编辑器组件作为一个 UMD 模块，使其可以在各种环境中使用，例如，由 Vue CLI 3 生成的应用程序，使用 webpack 构建的应用程序等。

要创建编辑器实例，您必须首先将编辑器构建和组件模块导入到您的应用程序的根文件（例如，由 Vue CLI 生成的 main.js）。然后，使用 Vue.use() 方法启用该组件

import Vue from 'vue';
import CKEditor from '@ckeditor/ckeditor5-vue2';

Vue.use( CKEditor );

除了调用 Vue.use()，您也可以始终在本地使用组件。

以下示例展示了应用程序的单文件组件。在您的模板中使用 <ckeditor> 组件

editor 指令指定编辑器构建（编辑器构造函数）。
v-model 指令启用开箱即用的双向数据绑定。
config 指令可帮助您将配置传递给编辑器实例。

<template>
    <div id="app">
        <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>',
                editorConfig: {
                    // The configuration of the editor.
                }
            };
        }
    }
</script>

请参阅支持的指令和事件列表，这些将帮助您配置组件。

# 在本地使用组件

如果您不希望 CKEditor 组件在全局范围内启用，则可以完全跳过 Vue.use( CKEditor ) 部分。相反，在您视图的 components 属性中对其进行配置。

确保 CKEditor 和 ClassicEditor 可访问，具体取决于集成方案：作为直接脚本包含或 ES6 模块导入。

<template>
    <div id="app">
        <ckeditor :editor="editor" ... ></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        components: {
            // Use the <ckeditor> component in this view.
            ckeditor: CKEditor.component
        },
        data() {
            return {
                editor: ClassicEditor,

                // ...
            };
        }
    }
</script>

# 集成在线构建器中的自定义构建

本指南假设您已使用 CKEditor 5 在线构建器创建了一个包含编辑器的 zip 存档。

将其解压缩到您的应用程序主目录中。包含编辑器构建的目录不能放置在 src/ 目录中，因为 Node 将返回错误。因此，我们建议将该目录放在 src/ 和 node_modules/ 文件夹旁边

├── ckeditor5
│   ├── build
│   ├── sample
│   ├── src
│   ├── ...
│   ├── package.json
│   └── webpack.config.js
├── node_modules
├── public
├── src
├── ...
└── package.json

然后，将位于 ckeditor5 目录中的包添加为项目的依赖项

yarn add file:./ckeditor5

最后，在您的应用程序中导入构建

<template>
    <div id="app">
        <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    import Editor from 'ckeditor5-custom-build/build/ckeditor';

    export default {
        name: 'app',
        data() {
            return {
                editor: Editor,
                editorData: '<p>Content of the editor.</p>',
                editorConfig: {
                    // The configuration of the editor.
                }
            };
        }
    }
</script>

# 使用协作插件的编辑器

在 Vue 应用程序中集成协作插件的最简单方法是从源代码构建编辑器，包括协作插件以及 Vue 应用程序。

# 使用源代码中的 CKEditor

从源代码集成富文本编辑器使您可以使用 CKEditor 5 框架的全部功能。

# Vite

本指南假设您使用 create-vue 作为您的样板。要开始使用 Vite 和 Vue 2，请运行以下命令。

npm init vue@2 ckeditor5-vue-example

此命令将安装并执行 create-vue，这是 Vue 的官方项目脚手架工具。它还将允许您自定义您的项目。选择您喜欢的选项。

使用 Vite 插件从源代码中构建 CKEditor 5 仍在实验阶段。我们鼓励您测试它并给我们反馈。要详细了解与 Vite 集成的内容或其局限性，请查看使用 Vite 从源代码集成指南。

您需要安装一些软件包才能使用源代码中的 CKEditor 5 与 Vue 2 和 Vite：官方的 CKEditor Vue 2 组件和 CKEditor Vite 插件。

npm install --save @ckeditor/vite-plugin-ckeditor5 @ckeditor/ckeditor5-vue2

# 配置 `vite.config.js`

使用 Vue 2 和 Vite 配置 CKEditor 相当简单。通过导入 ckeditor5 包来修改现有配置。然后将其添加到插件列表中。

// vite.config.js

import { defineconfiguration } from 'vite';
import vue from '@vitejs/plugin-vue2';
import ckeditor5 from '@ckeditor/vite-plugin-ckeditor5';

export default defineConfig( {
  plugins: [
    vue(),
    ckeditor5( { theme: require.resolve( '@ckeditor/ckeditor5-theme-lark' ) } )
  ],
} );

ESM 项目的配置略有不同。如果您尝试使用 npm run dev 命令启动开发服务器，您可能会遇到错误：require.resolve is not a function。在这种情况下，您需要一些额外的代码行。

// vite.config.js

import { createRequire } from 'node:module';
const require = createRequire( import.meta.url );

现在，您使用 Vite 和 Vue 2 的设置已完成。您也可以查看下一节中如何配置 webpack，或者直接转到安装插件。

# Webpack

本指南假设您使用 Vue CLI 3+ 作为您的样板，并且您的应用程序已使用 vue create 命令创建。您可以使用以下命令安装 Vue CLI。

npm install -g @vue/cli

详细了解如何在从源代码集成编辑器指南中从源代码构建 CKEditor 5。

要创建一个新项目，请运行

vue create ckeditor5-vue-example

要启动 Vue 2 项目，请选择 Vue 2 默认预设。

# 配置 `vue.config.js`

要使用您的应用程序构建 CKEditor 5，必须对默认项目配置进行一些更改。

首先，安装必要的依赖项

npm install --save \
    @ckeditor/ckeditor5-vue2 \
    @ckeditor/ckeditor5-dev-translations@43 \
    @ckeditor/ckeditor5-dev-utils@43 \
    postcss-loader@4 \
    raw-loader@4

编辑 vue.config.js 文件并使用以下配置。如果该文件不存在，请在应用程序的根目录（位于 package.json 旁边）中创建它

// vue.config.js

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

module.exports = {
    // The source of CKEditor&nbsp;5 is encapsulated in ES6 modules. By default, the code
    // from the node_modules directory is not transpiled, so you must explicitly tell
    // the CLI tools to transpile JavaScript files in all ckeditor5-* modules.
    transpileDependencies: [
        /ckeditor5-[^/\\]+[/\\]src[/\\].+\.js$/,
    ],

    configureWebpack: {
        plugins: [
            // CKEditor&nbsp;5 needs its own plugin to be built using webpack.
            new CKEditorTranslationsPlugin( {
                // See https://ckeditor.npmjs.net.cn/docs/ckeditor5/latest/features/ui-language.html
                language: 'en',

                // Append translations to the file matching the `app` name.
                translationsOutputFile: /app/
            } )
        ]
    },

    // Vue CLI would normally use its own loader to load .svg and .css files, however:
    //	1. The icons used by CKEditor&nbsp;5 must be loaded using raw-loader,
    //	2. The CSS used by CKEditor&nbsp;5 must be transpiled using PostCSS to load properly.
    chainWebpack: configuration => {
        // (1.) To handle editor icons, get the default rule for *.svg files first:
        const svgRule = config.module.rule( 'svg' );

        // Then you can either:
        //
        // * clear all loaders for existing 'svg' rule:
        //
        //		svgRule.uses.clear();
        //
        // * or exclude ckeditor directory from node_modules:
        svgRule.exclude.add( path.join( __dirname, 'node_modules', '@ckeditor' ) );

        // Add an entry for *.svg files belonging to CKEditor. You can either:
        //
        // * modify the existing 'svg' rule:
        //
        //		svgRule.use( 'raw-loader' ).loader( 'raw-loader' );
        //
        // * or add a new one:
        config.module
            .rule( 'cke-svg' )
            .test( /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/ )
            .use( 'raw-loader' )
            .loader( 'raw-loader' );

        // (2.) Transpile the .css files imported by the editor using PostCSS.
        // Make sure only the CSS belonging to ckeditor5-* packages is processed this way.
        config.module
            .rule( 'cke-css' )
            .test( /ckeditor5-[^/\\]+[/\\].+\.css$/ )
            .use( 'postcss-loader' )
            .loader( 'postcss-loader' )
            .tap( () => {
                return {
                    postcssOptions: styles.getPostCssConfig( {
                        themeImporter: {
                            themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
                        },
                        minify: true
                    } )
                };
            } );
    }
};

默认情况下，Vue CLI 对所有 SVG 文件使用 file-loader。file-loader 将文件复制到输出目录并将导入解析为 URL。CKEditor 的 UI 组件直接使用 SVG 源代码，因此必须使用 raw-loader 加载主题图标。如果您的项目使用与 CKEditor 的 UI 库不同的方法，则必须为您的项目 SVG 文件和 CKEditor 的 SVG 文件创建不同的 webpack 加载程序规则。

# 安装插件

配置完 vue.config.js 后，您可以选择编辑器的构建块。安装您的集成所需的软件包，但请记住所有软件包（不包括 @ckeditor/ckeditor5-dev-* 和 @ckeditor/ckeditor5-vue2）必须与基本编辑器包具有相同的版本。

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

您可以使用更多软件包，具体取决于您的应用程序中需要哪些功能。

// main.js

import Vue from 'vue';
import App from './App.vue';
import CKEditor from '@ckeditor/ckeditor5-vue2';

Vue.use( CKEditor );

new Vue( {
  render: ( h ) => h( App )
} ).$mount( '#app' );

除了调用 Vue.use()，您也可以始终在本地使用组件。

现在您需要做的就是使用 editorConfig 数据属性指定富文本编辑器选项（包括插件）的列表

<!-- App.vue -->

<template>
    <div id="app">
        <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    // ⚠️ NOTE: We don't use @ckeditor/ckeditor5-build-classic any more!
    // Since we're building CKEditor&nbsp;5 from source, we use the source version of ClassicEditor.
    import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';

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

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>',
                editorConfig: {
                    plugins: [
                        Essentials,
                        Bold,
                        Italic,
                        Link,
                        Paragraph
                    ],

                    toolbar: {
                        items: [
                            'bold',
                            'italic',
                            'link',
                            'undo',
                            'redo'
                        ]
                    }
                }
            };
        }
    };
</script>

最后，您可以构建您的项目。命令可能因包管理器而异，因此请检查您的 package.json 文件的脚本部分。

# 使用文档编辑器构建

如果您的应用程序使用了文档编辑器，您需要手动将编辑器工具栏添加到 DOM。

由于在编辑器实例就绪之前无法访问编辑器工具栏，因此请将工具栏插入代码放在组件的 ready 事件执行的方法中，如下例所示。

<template>
        <div id="app">
            <ckeditor :editor="editor" @ready="onReady" ... ></ckeditor>
        </div>
</template>

<script>
    import DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';

    export default {
        name: 'app',
        data() {
            return {
                editor: DecoupledEditor,

                // ...
            };
        },
        methods: {
            onReady( editor )  {
                // Insert the toolbar before the editable area.
                editor.ui.getEditableElement().parentElement.insertBefore(
                    editor.ui.view.toolbar.element,
                    editor.ui.getEditableElement()
                );
            }
        }
    }
</script>

# 本地化

CKEditor 5 支持多种 UI 语言，官方的 Vue.js 组件也是如此。请按照以下说明在您的 Vue.js 应用程序中翻译 CKEditor 5。

# 预定义构建

使用预定义构建之一，您需要先导入翻译。

使用直接脚本包含时

<!-- Import translations for the German language. -->
<script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/translations/de.js"></script>
<script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js"></script>
<script src="../node_modules/@ckeditor/ckeditor5-vue2/dist/ckeditor.js"></script>

使用 ES6 模块时

import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

// Import translations for the German language.
import '@ckeditor/ckeditor5-build-classic/build/translations/de';

然后，在组件中配置编辑器的语言

<ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>

export default {
    name: 'app',
    data() {
        return {
            editor: ClassicEditor,
            editorData: '<p>Content of the editor.</p>',
            editorConfig: {
                // Run the editor with the German UI.
                language: 'de'
            }
        };
    }
}

有关更多信息，请参阅设置 UI 语言指南。

# 从源代码构建的 CKEditor 5

使用从源代码构建的编辑器需要您修改 webpack 配置。将 language（以及 additionalLanguages）传递给 CKEditorTranslationsPlugin 的构造函数以本地化您的编辑器。

// vue.config.js
// ...

const { CKEditorTranslationsPlugin } = require( '@ckeditor/ckeditor5-dev-translations' );

// ...

module.exports = {
    // ...

    configureWebpack: {
        plugins: [
            // CKEditor needs its own plugin to be built using webpack.
            new CKEditorTranslationsPlugin( {
                // The UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
                language: 'de',

                // Append translations to the file matching the `app` name.
                translationsOutputFile: /app/
            } )
        ]
    },

    // ...
}

构建应用程序后，CKEditor 5 将以 UI 翻译成指定语言运行。

有关更多信息，请参阅 “设置 UI 语言” 指南。

# 组件指令

# `editor`

此指令指定组件要使用的编辑器。它必须直接引用要在模板中使用的编辑器构造函数。

<template>
        <div id="app">
            <ckeditor :editor="editor" ... ></ckeditor>
        </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,

                // ...
            };
        }
    }
</script>

要在应用程序中使用多个富文本编辑器构建，您需要从源代码配置或使用 “超级构建”。

# `tag-name`

默认情况下，编辑器组件创建一个 <div> 容器，该容器用作传递给编辑器的元素（例如，ClassicEditor#element）。元素可以配置，因此例如要创建一个 <textarea>，请使用以下指令

<ckeditor :editor="editor" tag-name="textarea"></ckeditor>

# `v-model`

Vue 中表单输入的标准指令。与 value 不同，它创建了一个双向数据绑定，它

设置初始编辑器内容，
当编辑器内容发生变化时（即，用户输入时），自动更新应用程序的状态，
可以在需要时用于设置编辑器内容。

<template>
    <div id="app">
        <ckeditor :editor="editor" v-model="editorData"></ckeditor>
        <button v-on:click="emptyEditor()">Empty the editor</button>

        <h2>Editor data</h2>
        <code>{{ editorData }}</code>
    </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        },
        methods: {
            emptyEditor() {
                this.editorData = '';
            }
        }
    }
</script>

在上面的示例中，editorData 属性将在用户输入和更改内容时自动更新。它也可以用于更改（如 emptyEditor() 中）或设置编辑器的初始内容。

如果您只想在编辑器数据发生变化时执行操作，请使用 input 事件。

# `value`

允许进行单向数据绑定，该绑定设置编辑器的内容。与 v-model 不同，当编辑器的内容发生变化时，值不会更新。

<template>
    <div id="app">
        <ckeditor :editor="editor" :value="editorData"></ckeditor>
    </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorData: '<p>Content of the editor.</p>'
            };
        }
    }
</script>

要执行编辑器数据发生变化时的操作，请使用 input 事件。

# `config`

指定编辑器的配置。

<template>
    <div id="app">
        <ckeditor :editor="editor" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                editorConfig: {
                    toolbar: [ 'bold', 'italic', '|', 'link' ]
                }
            };
        }
    }
</script>

# `disabled`

此指令控制编辑器的 isReadOnly 属性。

它设置编辑器的初始只读状态，并在其生命周期内更改它。

<template>
    <div id="app">
        <ckeditor :editor="editor" :disabled="editorDisabled"></ckeditor>
    </div>
</template>

<script>
    import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

    export default {
        name: 'app',
        data() {
            return {
                editor: ClassicEditor,
                // This editor will be read–only when created.
                editorDisabled: true
            };
        }
    }
</script>

# 组件事件

# `ready`

对应于 ready 编辑器事件。

<ckeditor :editor="editor" @ready="onEditorReady"></ckeditor>

# `focus`

对应于 focus 编辑器事件。

<ckeditor :editor="editor" @focus="onEditorFocus"></ckeditor>

# `blur`

对应于 blur 编辑器事件。

<ckeditor :editor="editor" @blur="onEditorBlur"></ckeditor>

# `input`

对应于 change:data 编辑器事件。有关更多信息，请参阅 v-model 指令。

<ckeditor :editor="editor" @input="onEditorInput"></ckeditor>

# `destroy`

对应于 destroy 编辑器事件。

注意：由于编辑器的销毁是基于 Promise 的，因此此事件可能在实际的 Promise 解决之前被触发。

<ckeditor :editor="editor" @destroy="onEditorDestroy"></ckeditor>

# 贡献和报告问题

此组件的源代码在 GitHub 上的 https://github.com/ckeditor/ckeditor5-vue2 中提供。

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

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

(遗留) Vue.js 2.x 富文本编辑器组件

# 快速入门

# 直接脚本包含

# 使用 ES6 模块

# 在本地使用组件

# 集成在线构建器中的自定义构建

# 使用协作插件的编辑器

# 使用源代码中的 CKEditor

# Vite

# 配置 vite.config.js

# Webpack

# 配置 vue.config.js

# 安装插件

# 使用文档编辑器构建

# 本地化

# 预定义构建

# 从源代码构建的 CKEditor 5

# 组件指令

# editor

# tag-name

# v-model

# value

# config

# disabled

# 组件事件

# ready

# focus

# blur

# input

# destroy

# 贡献和报告问题

# 配置 `vite.config.js`

# 配置 `vue.config.js`

# `editor`

# `tag-name`

# `v-model`

# `value`

# `config`

# `disabled`

# `ready`

# `focus`

# `blur`

# `input`

# `destroy`