Vue.js 3+ 富文本编辑器组件 - 传统指南
⚠️ 我们更改了安装方法,此传统指南保留供用户参考。如果您正在寻找最新的 CKEditor 5 Vue 集成,请参阅 CKEditor 5 集成 指南的最新版本。
CKEditor 5 包含 可立即使用的编辑器构建 和 CKEditor 5 框架,构建基于此框架。
在您的 Vue.js 应用程序中使用 CKEditor 5 最简单的方法是选择 富文本编辑器构建 之一,并将其简单地传递给 Vue.js 组件的配置。在本指南的 快速入门 部分中,您可以详细了解此解决方案。
此外,您可以 从源代码集成 CKEditor 5,这是一个更加灵活和强大的解决方案,但需要一些额外的配置。
watchdog 功能 可用于 React 和 Angular 集成,但目前尚不支持 Vue。
从该软件包的 5.0.0 版本开始,您可以使用 CKEditor 5 提供的原生类型定义。查看有关 TypeScript 支持 的详细信息。
# 快速入门
⚠️ 此指南仅适用于 @ckeditor/ckeditor5-vue
软件包的 6.0.0 版本,因为 7.0.0 版本中引入了 API 更改。如果您正在寻找最新的 CKEditor 5 Vue 集成,请参阅 CKEditor 5 集成 指南的最新版本。
安装 适用于 Vue.js 的 CKEditor 5 WYSIWYG 编辑器组件 和您选择的 编辑器构建。
假设您选择了 @ckeditor/ckeditor5-build-classic
npm install --save @ckeditor/ckeditor5-vue @ckeditor/ckeditor5-build-classic
您现在需要在您的应用程序中启用 CKEditor 5 组件。有两种方法可以做到这一点:
可选地,您可以 在本地使用组件。
# 直接脚本包含
这是在您的项目中开始使用 CKEditor 5 的最快方法。假设 Vue 已安装,请包含 WYSIWYG 编辑器组件和构建的 <script>
标签
<script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js"></script>
<script src="../node_modules/@ckeditor/ckeditor5-vue/dist/ckeditor.js"></script>
使用 应用程序实例 在您的应用程序中全局启用该组件
Vue.createApp( { /* options */ } ).use( CKEditor ).mount( /* DOM element */ );
您不必调用 use()
方法来全局安装 CKEditor 5 组件,也可以始终 在本地使用组件。
在您的模板中使用 <ckeditor>
组件
<div id="app">
<ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
</div>
Vue.createApp( {
data() {
editor: ClassicEditor,
editorData: '<p>Content of the editor.</p>',
editorConfig: {
// The configuration of the editor.
}
}
} ).use( CKEditor ).mount( '#app' );
瞧!您应该看到 CKEditor 5 在您的 Vue.js 应用程序中运行。
# 使用 ES6 模块
编辑器组件作为 UMD 模块 提供,这使其能够在各种环境中使用,例如,由 Vue CLI 生成的应用程序,使用 webpack 构建的应用程序等等。
要创建编辑器实例,您必须首先将编辑器构建和组件模块导入到应用程序的根文件(例如,由 Vue CLI 生成的 main.js
)。然后,使用 应用程序实例 启用该组件
import { createApp } from 'vue';
import CKEditor from '@ckeditor/ckeditor5-vue';
createApp( { /* options */ } ).use( CKEditor ).mount( /* DOM element */ );
您不必调用 use()
方法来全局安装 CKEditor 5 组件,也可以始终 在本地使用组件。
以下示例展示了应用程序的单文件组件。在您的模板中使用 <ckeditor>
组件
<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 5 组件,可以完全跳过 use()
部分。相反,在视图的 components
属性中进行配置。
<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 5
从源代码集成富文本编辑器允许您使用 CKEditor 5 框架 的全部功能。您在构建应用程序方面有两个选择:Vite 或 webpack。
# Vite
本指南假设您使用 create-vue
作为您的样板。要开始使用 Vite 和 Vue,请运行以下命令。
npm init vue@latest ckeditor5-vue-example
此命令将安装并执行 create-vue
,它是 Vue 的官方项目脚手架工具。它还允许您自定义项目,例如,通过添加 TypeScript。选择您喜欢的选项。
# 安装必要的包
您需要两个包才能将 CKEditor 5 与 Vue 和 Vite 从源代码使用:官方 Vue 组件和 Vite 插件。
使用 Vite 插件从 Vite 中的源代码构建 CKEditor 5 仍处于实验阶段。我们鼓励您进行测试并向我们提供反馈。要详细了解与 Vite 的集成或其局限性,请查看 使用 Vite 从源代码集成 指南。
使用以下命令安装必要的包。
npm install --save @ckeditor/vite-plugin-ckeditor5 @ckeditor/ckeditor5-vue
# 配置 vite.config.js
/ vite.config.ts
使用 Vue 和 Vite 配置 CKEditor 很简单。通过导入 ckeditor5
并将其添加到插件列表中,修改现有配置。在 TypeScript 的情况下,配置可以保持不变。唯一的区别是扩展名 - .ts
。
// vite.config.js / vite.config.ts
import { fileURLToPath, URL } from 'node:url';
import { defineconfiguration } from 'vite';
import vue from '@vitejs/plugin-vue';
import ckeditor5 from '@ckeditor/vite-plugin-ckeditor5';
export default defineConfig( {
plugins: [
vue(),
ckeditor5( { theme: require.resolve( '@ckeditor/ckeditor5-theme-lark' ) } )
],
resolve: {
alias: {
'@': fileURLToPath( new URL( './src', import.meta.url ) )
}
}
} );
ESM 项目的配置略有不同。如果您尝试使用 npm run dev
命令启动开发服务器,您可能会遇到错误:require.resolve is not a function
。在这种情况下,您需要一些额外的代码行。
// vite.config.js / vite.config.ts
import { createRequire } from 'node:module';
const require = createRequire( import.meta.url );
现在,您使用 Vite 和 Vue 的设置已完成。您也可以查看下一节中的 webpack 配置方法,或直接转到 安装插件。
# Webpack
本指南假设您使用的是 Vue CLI 4.5.0+ 作为您的样板,并且您的应用程序是使用 vue create
命令创建的。您可以使用以下命令安装 Vue CLI。
npm install -g @vue/cli
详细了解在 从源代码集成编辑器 指南中从源代码构建 CKEditor 5。
要创建一个新项目,请运行
vue create ckeditor5-vue-example
您可以选择默认预设进行快速设置。您也可以“手动选择功能”以选择您需要的功能,例如 TypeScript。
# 配置 vue.config.js
要使用您的应用程序构建 CKEditor 5,必须对默认项目配置进行某些更改。
首先,安装必要的依赖项
npm install --save \
@ckeditor/ckeditor5-vue \
@ckeditor/ckeditor5-dev-translations@43 \
@ckeditor/ckeditor5-dev-utils@43 \
postcss-loader@4 \
raw-loader@4
编辑 vue.config.js
文件并使用以下配置。如果文件不存在,请在应用程序的根目录(靠近 package.json
)中创建它。如果您使用的是 TypeScript,则配置可以保持不变。
// 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 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 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 5 must be loaded using raw-loader,
// 2. The CSS used by CKEditor 5 must be transpiled using PostCSS to load properly.
chainWebpack: configuration => {
// (1.) To handle the 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 加载器规则。
# 安装插件
项目配置完成后,您可以选择编辑器的构建块。安装集成所需的软件包,但请记住,所有软件包(不包括 @ckeditor/ckeditor5-dev-*
、@ckeditor/ckeditor5-vue
和 @ckeditor/vite-plugin-ckeditor5
)必须与基础编辑器软件包具有相同的版本。
npm install --save \
@ckeditor/ckeditor5-editor-classic \
@ckeditor/ckeditor5-essentials \
@ckeditor/ckeditor5-basic-styles \
@ckeditor/ckeditor5-link \
@ckeditor/ckeditor5-paragraph \
@ckeditor/ckeditor5-theme-lark
# JavaScript
您可以根据应用程序中需要的功能使用更多软件包。
// main.js
import { createApp } from 'vue';
import App from './App.vue';
import CKEditor from '@ckeditor/ckeditor5-vue';
createApp( App ).use( CKEditor ).mount( '#app' );
您不必调用 use()
方法来全局安装 CKEditor 5 组件,也可以始终 在本地使用组件。
现在,您需要做的就是指定富文本编辑器选项列表(**包括插件**)在 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 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>
# TypeScript
如果您在项目初始化期间选择了 TypeScript,则需要进行一些调整。首先,将主文件扩展名更改为 .ts
。
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import CKEditor from '@ckeditor/ckeditor5-vue';
createApp( App ).use( CKEditor ).mount( '#app' );
然后,除了指定富文本编辑器选项列表外,还要将 lang
属性添加到 Vue 组件中。
<!-- App.vue -->
<template>
<div id="app">
<ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
</div>
</template>
<script lang="ts">
// ⚠️ NOTE: We don't use @ckeditor/ckeditor5-build-classic any more!
// Since we're building CKEditor 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-vue/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 5 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 中表单输入的 标准指令。与 model-value
不同,它创建了一个双向数据绑定,它
- 设置初始编辑器内容,
- 在编辑器内容发生变化时(例如,用户键入时)自动更新应用程序的状态,
- 可用于在必要时设置编辑器内容。
<template>
<div id="app">
<ckeditor :editor="editor" v-model="editorData"></ckeditor>
<button @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
事件。
# model-value
允许单向数据绑定,它设置编辑器的内容。与 v-model
不同,当编辑器内容发生变化时,值不会更新。
<template>
<div id="app">
<ckeditor :editor="editor" :model-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>
# disableTwoWayDataBinding
允许禁用双向数据绑定机制。默认值为 false
。
引入此选项的原因是大型文档中存在性能问题。启用此标志后,v-model
指令将不再在编辑器数据发生变化时更新连接的值。
此选项允许集成程序禁用默认行为,并且仅在需要时调用 editor.getData()
方法,从而防止速度下降。您可以在 相关问题 中了解更多信息。
<ckeditor :editor="editor" :disableTwoWayDataBinding="true"></ckeditor>
# 组件事件
# 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
编辑器事件。
<ckeditor :editor="editor" @input="onEditorInput"></ckeditor>
# destroy
对应于 destroy
编辑器事件。
注意:由于编辑器的销毁是基于承诺的,因此此事件可能在实际承诺解析之前被触发。
<ckeditor :editor="editor" @destroy="onEditorDestroy"></ckeditor>
# 贡献和报告问题
此组件的源代码可在 GitHub 上的 https://github.com/ckeditor/ckeditor5-vue 中找到。
我们每天都在努力使我们的文档保持完整。您是否发现了过时的信息?缺少了什么?请通过我们的 问题跟踪器 报告它。
随着 42.0.0 版本的发布,我们已经重新编写了大部分文档,以反映新的导入路径和功能。我们感谢您的反馈,以帮助我们确保其准确性和完整性。