如何自定义 ckeditor 内容模板？-网站模板-锦华智联科技

CKEditor 5 提供了两种主要的模板解决方案：

（图片来源网络，侵删）

官方推荐的模板插件：这是最现代、最灵活的方案，通过 @ckeditor/ckeditor5-template 插件实现。
第三方插件：如 ckeditor5-template，功能类似,但可能不是由官方维护。

下面我将重点介绍官方推荐的模板插件,并提供完整的配置和使用示例。

使用官方推荐的 `@ckeditor/ckeditor5-template` 插件

这是目前 CKEditor 5 官方文档中推荐的方法，它允许你在编辑器工具栏中添加一个“模板”按钮,点击后从预设的模板中选择内容插入。

第 1 步：安装插件

你需要将模板插件添加到你的 CKEditor 5 项目中。

npm install --save @ckeditor/ckeditor5-template

第 2 步：配置编辑器

在你的 CKEditor 5 构建配置文件中（通常是 src/ckeditor.js 或 ckeditor-config.js）,你需要做两件事：

（图片来源网络，侵删）

注册插件：将 TemplateEditing 和 TemplateUI 添加到 plugins 列表中。
配置模板列表：在 config.template 中定义你的模板。

示例配置 (ckeditor-config.js):

import { ClassicEditor } from '@ckeditor/ckeditor5-editor-classic';
import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';
import HeadingPlugin from '@ckeditor/ckeditor5-heading/src/heading';
import ListPlugin from '@ckeditor/ckeditor5-list/src/list';
import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
import ImagePlugin from '@ckeditor/ckeditor5-image/src/image';
import TablePlugin from '@ckeditor/ckeditor5-table/src/table';
import TemplateEditing from '@ckeditor/ckeditor5-template/src/templateediting';
import TemplateUI from '@ckeditor/ckeditor5-template/src/templateui';
// 定义你的模板
const myTemplates = [
    // 模板 1: 新闻稿
    {
        title: '新闻稿模板',
        description: '用于发布公司新闻的标准格式。',
        // 使用 HTML 字符串定义模板内容
        content: `
            <h2>新闻标题</h2>
            <p><strong>发布日期：</strong><span class="date-placeholder">YYYY-MM-DD</span></p>
            <p><strong>作者：</strong><span class="author-placeholder">请输入作者</span></p>
            <hr />
            <p>这里是新闻稿的正文内容，你可以在这里详细介绍事件的经过、背景和意义。</p>
            <p>我们很高兴地宣布...</p>
            <blockquote>
                <p>这是一段重要的引述，可以突出文章的核心观点。</p>
            </blockquote>
            <p>新闻稿的结尾部分。</p>
        `
    },
    // 模板 2: 产品简介
    {
        title: '产品简介模板',
        description: '快速创建产品介绍卡片。',
        content: `
            <h3>产品名称</h3>
            <p><strong>产品编号：</strong><span class="product-id-placeholder">PROD-001</span></p>
            <p><strong>价格：</strong><span class="price-placeholder">¥0.00</span></p>
            <p>这里是产品的详细描述，包括其特点、优势和使用方法。</p>
            <ul>
                <li>特点一</li>
                <li>特点二</li>
                <li>特点三</li>
            </ul>
        `
    }
];
ClassicEditor
    .create(document.querySelector('#editor'), {
        // 1. 注册插件
        plugins: [
            EssentialsPlugin,
            ParagraphPlugin,
            HeadingPlugin,
            ListPlugin,
            BoldPlugin,
            ItalicPlugin,
            LinkPlugin,
            ImagePlugin,
            TablePlugin,
            TemplateEditing, // 必需：处理模板内容的插件
            TemplateUI       // 必需：提供UI界面的插件
        ],
        toolbar: {
            items: [
                'heading',
                '|',
                'bold',
                'italic',
                'link',
                'bulletedList',
                'numberedList',
                'insertTable',
                '|',
                'undo',
                'redo',
                'template' // 2. 将 'template' 按钮添加到工具栏
            ]
        },
        // 3. 配置模板列表
        template: {
            items: myTemplates
        }
    })
    .then(editor => {
        console.log('Editor was initialized', editor);
    })
    .catch(error => {
        console.error(error.stack);
    });

第 3 步：在 HTML 中放置编辑器

在你的 HTML 文件中，创建一个 div 元素作为编辑器的容器。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">CKEditor 5 模板示例</title>
    <link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/39.0.1/classic/ckeditor.css">
</head>
<body>
    <h1>CKEditor 5 内容模板示例</h1>
    <div id="editor">
        <!-- 编辑器初始化后，内容将出现在这里 -->
    </div>
    <!-- 引入 CKEditor 5 核心文件 -->
    <script src="https://cdn.ckeditor.com/ckeditor5/39.0.1/classic/ckeditor.js"></script>
    <!-- 引入你的配置文件 -->
    <script src="ckeditor-config.js"></script>
</body>
</html>

效果

配置完成后，打开页面，你会看到一个包含“模板”按钮的工具栏，点击“模板”按钮，会弹出一个对话框，列出你定义的所有模板，选择一个模板并点击“插入”，该模板的 HTML 内容就会被填充到编辑器中。

高级用法与最佳实践

使用占位符

中使用 <span> 元素并添加 data-placeholder 属性（或自定义类名）是一个很好的实践,这样用户就知道哪些地方需要修改。

content: `
    <h2>新闻标题</h2>
    <p><strong>作者：</strong><span class="author-placeholder">请输入作者</span></p>
`

使用模板片段

如果你的模板非常复杂，或者想在多个地方复用模板的一部分，你可以将模板拆分为“片段”，这需要更高级的配置，通常涉及到自定义插件，但对于简单场景，直接复制粘贴 HTML 片段到模板定义中是最直接的方法。

从服务器动态加载模板

如果你有很多模板，或者模板内容需要根据用户权限动态变化，最好从服务器 API 加载模板,而不是硬编码在配置文件中。

你可以先创建一个空的 template 配置，然后在编辑器初始化完成后，通过 API 获取模板数据并动态设置。

// 初始化时留空
ClassicEditor.create(document.querySelector('#editor'), {
    // ... 其他配置
    template: {
        items: [] // 初始为空
    }
}).then(editor => {
    // 从服务器获取模板
    fetch('/api/templates')
        .then(response => response.json())
        .then(serverTemplates => {
            // 动态设置模板
            editor.config.template.items = serverTemplates;
        });
});

保存模板内容

当用户编辑完模板内容并点击“保存”时，你需要获取编辑器中的完整 HTML，CKEditor 5 提供了简单的方法来获取内容。

// 假设你已经初始化了 editor 实例
const editor = await ClassicEditor.create(...);
// 获取编辑器内容为 HTML 字符串
const fullHtmlContent = editor.getData();
// fullHtmlContent 就包含了用户编辑后的完整内容，你可以将其发送到服务器保存
console.log(fullHtmlContent);

使用第三方插件（旧版或替代方案）

如果你使用的是 CKEditor 4，或者更早版本的 CKEditor 5，你可能接触过 ckeditor5-template 这个第三方插件，它的使用方法与官方插件类似,但安装和配置的包名不同。

对于 CKEditor 4:

CKEditor 4 有一个内置的模板功能，主要通过 templates 插件实现。

确保插件已加载：config.js 中需要包含 templates。
配置模板路径：在 config.js 中设置 templates_files，指向一个包含模板定义的 JSON 文件。

示例 config.js (CKEditor 4):

CKEDITOR.editorConfig = function( config ) {
    // ... 其他配置
    config.templates_files = [
        '/path/to/your/templates.js' // 模板定义文件
    ];
    config.templates_replaceContent = false; // 是否替换整个内容，默认为 true
};

示例 templates.js (CKEditor 4):

CKEDITOR.addTemplates( 'default', {
    imagesPath: '/ckeditor/plugins/templates/icons/',
    templates: [
        {
            title: '图片和文本',
            image: 'template1.gif',
            description: '左侧一张图片，右侧是文本',
            html: '<div style="float: left; width: 175px; margin-right: 10px;">' +
                  '<img src="/path/to/image.jpg" width="175" height="150" style="width: 100%; height: auto;" /></div>' +
                  '<p>这里是文本内容，图片在左边，文字在右边。</p>'
        },
        // ... 更多模板
    ]
});

特性	官方 `@ckeditor/ckeditor5-template` (推荐)	CKEditor 4 内置模板
适用版本	CKEditor 5	CKEditor 4
安装方式	`npm install`	内置，需配置
配置方式	在 `config.template.items` 中定义 HTML 字符串	在 `templates_files` 中指向 JSON 文件
灵活性	高，直接使用 HTML，支持 CKEditor 5 的所有特性	较高，但基于 JSON，功能相对受限
维护状态	官方维护，持续更新	已停止更新，但稳定

建议：

新项目：请务必使用 官方推荐的 @ckeditor/ckeditor5-template 插件。
旧项目 (CKEditor 4)：继续使用其内置的模板功能。
从 CKEditor 4 迁移：请按照方案一进行配置，将旧的模板定义转换为新的 HTML 字符串格式。

如何自定义 ckeditor 内容模板？

使用官方推荐的 @ckeditor/ckeditor5-template 插件