Contribute to this guide

指南编辑器工具栏

# 主编辑器工具栏

工具栏是 CKEditor 5 最基本的用户界面元素,它使您可以方便地访问其所有功能。它具有按钮和下拉菜单,您可以使用它们来格式化、管理、插入和更改内容的元素。

# 演示

以下是一个带有基本功能集的示例工具栏。工具栏项目可以轻松地添加或删除。继续阅读以了解如何做到这一点。

缓步动物——近乎微观的超级英雄

不要让它们毛茸茸的外表欺骗了你:缓步动物是坚韧的家伙。虽然它们可爱的俗称——水熊——可能暗示了相反,但这些微小的动物是地球上最具弹性的生物之一。

缓步动物的身体呈节状,很少超过 1 毫米。通常情况下,每个个体仅由 **大约 1000 个细胞组成**,相比之下,构成人体的三万亿个细胞。

为了清楚起见,本指南中的所有演示都展示了一组有限的功能。访问 功能丰富的编辑器示例,以查看更多实际应用。

# 基本工具栏配置

工具栏配置是一个严格的与 UI 相关的设置。删除工具栏项目不会从编辑器内部删除功能。如果您使用工具栏配置的目标是删除功能,正确的解决方案是同时删除其各自的插件。有关更多信息,请查看 删除功能 指南。

工具栏提供灵活的排列,通过配置实现。请注意,使用 CKEditor 5 构建器 使这项任务变得更加容易。

以下示例可以为您提供一个大致的想法

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ]
    } )
    .catch( error => {
        console.log( error );
    } );

# 分隔工具栏项目

您可以使用 `'|'` 在工具栏项目组之间创建分隔符。这在基本和扩展配置格式中都有效。

下面您可以找到一个带有按钮分组的简单工具栏的示例。配置中设置的组分隔符 (`'|'`) 有助于组织工具栏。

一只微小野兽的简史

缓步动物是在 18 世纪后期由德国动物学家约翰·奥古斯特·艾弗拉姆·戈兹发现的。他被它们像泰迪熊一样的外表所吸引,想出了一个名字 `kleine Wasserbären`,意思是“小水熊”。

`Tardigrada`,这个群体的拉丁名字,不久后由意大利生物学家拉扎罗·斯帕兰扎尼创造。这个名字翻译成“缓慢地行走”,指的是这些生物悠闲的步态。

从那时起,**大约 1300 种缓步动物**已在不同的栖息地被发现:从深海到山顶。

# 扩展工具栏配置格式

有两种可用的工具栏配置格式

基本

toolbar: [ 'bold', 'italic', '|', 'undo', 'redo', '|', 'numberedList', 'bulletedList' ]

和扩展

toolbar: {
    items: [ 'bold', 'italic', '|', 'undo', 'redo', '|', 'numberedList', 'bulletedList' ]
}

您可以使用扩展的 工具栏配置 格式来访问更多选项

toolbar: {
    items: [
        'undo', 'redo',
        '|',
        'heading',
        '|',
        'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|',
        'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '|',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|',
        'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: false
}
  • items – 工具栏项目名称的数组。您可以在工具栏项目中使用的大多数组件(按钮、下拉菜单等)都在 功能 部分中描述。完整列表在 editor.ui.componentFactory 中定义,可以使用以下代码段列出:Array.from( editor.ui.componentFactory.names() )。除了按钮名称,您还可以使用专用的分隔符用于工具栏组 (`'|'`) 和工具栏行 (`'-'`)。

  • removeItems – 工具栏项目名称的数组。使用此设置,您可以更改默认工具栏配置,而无需定义整个列表。您可以指定要删除的几个按钮,而不是指定要保留的所有按钮。如果在删除项目后,工具栏将具有两个或多个连续的分隔符 (`'|'`),则重复项将被自动删除。

  • shouldNotGroupWhenFull – 当设置为 `true` 时,工具栏将停止对项目进行分组,并在没有足够的空间在一行中显示它们时,让它们换行。此设置默认情况下为 `false`,这将启用项目分组。

下面的演示展示了 `shouldNotGroupWhenFull` 设置为 `false` 时“常规”工具栏的外观。如果工具栏项目超过当前显示宽度中的工具栏可以容纳的项目,则某些项目会被隐藏。您可以通过点击“显示更多项目”按钮 显示更多项目 来访问它们。

凡是不能杀死我的…

除了它们的可爱之外,缓步动物最出名的是它们令人难以置信的弹性。正如 一项研究 所表明的那样,它们甚至可以在外太空生存。

以下是缓步动物可以承受的极端条件选集

  • 在 151°C 下几分钟
  • 在 -272°C(仅比绝对零度高一度!)下几分钟
  • 在脱水状态下长达十年
  • 压力范围从接近零到 1200 个大气压
  • 甚至比对人类致命剂量高 1000 倍的辐射

# 多行(换行)工具栏

扩展工具栏配置格式 中,也可以将工具栏项目排列成多行。以下是实现方法

  • 将 `shouldNotGroupWhenFull` 选项设置为 `true`,以便项目在工具栏溢出时不会进行分组。它们将换行而不是分组。
  • 此外,您可以在项目列表中使用 `'-'` 分隔符来显式地设置断点。
toolbar: {
    items: [ 'bold', 'italic', '|', 'undo', 'redo', '-', 'numberedList', 'bulletedList' ],
    shouldNotGroupWhenFull: true
}

# 自动工具栏换行

当您将 `shouldNotGroupWhenFull` 设置为 `true` 时,默认情况下,工具栏项目会自动换行,一旦它们不适合编辑器宽度。该机制是自动的,只换行多余的项目。请注意,虽然工具栏组分隔符 `'|'` 被保留,但组可能会在溢出时被拆分。

toolbar: {
    items: [
        'undo', 'redo',
        '|',
        'heading',
        '|',
        'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|',
        'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '|',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|',
        'alignment',
        '|',
        'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: true
}

查看它在实践中的运作方式。使用浏览器窗口宽度来查看按钮在工具栏换行到多行时是如何表现的。

植物界

植物界是一个多样化的生物群,包括微小的藻类和巨大的红杉。尽管存在这种多样性,但所有植物都有一些共同点。

植物是有机体,它们

  • 拥有由多个细胞组成的身体。
  • 可以在称为*光合作用*的过程中合成食物。
  • 通常无法移动
  • 具有由纤维素构成的细胞壁。

# 显式换行断点

在工具栏配置中使用 `'-'` 设置显式断点可以创建您自己的预定义多行工具栏配置。然后,工具栏项目将按配置中声明的方式进行分组并放在行中。

toolbar: {
    items: [
        'undo', 'redo',
        '|', 'heading',
        '|', 'fontfamily', 'fontsize', 'fontColor', 'fontBackgroundColor',
        '|', 'bold', 'italic', 'strikethrough', 'subscript', 'superscript', 'code',
        '-', // break point
        '|', 'alignment',
        'link', 'uploadImage', 'blockQuote', 'codeBlock',
        '|', 'bulletedList', 'numberedList', 'todoList', 'outdent', 'indent'
    ],
    shouldNotGroupWhenFull: true
}

无种子植物

这个群体中的植物,称为*隐花植物*,不产生种子。

淡水和海洋藻类

绿藻不形成真正的根、茎或叶。这个群体在数亿年前产生了所有陆地植物。

# 将工具栏项目分组到下拉菜单中(嵌套工具栏)

为了节省工具栏中的空间或按主题排列功能,您可以将多个项目分组到下拉菜单中。例如,查看以下配置

toolbar: [
    {
        label: 'More basic styles',
        icon: 'threeVerticalDots',
        items: [ 'strikethrough', 'superscript', 'subscript' ]
    },
    // More of toolbar's configuration.
    // ...
]

它将创建一个带有三个垂直点图标 三个垂直点 的“基本样式”下拉菜单,其中包含设置的额外基本文本样式按钮。您可以在下面的演示中以及其他一些工具栏下拉菜单中对其进行测试。

苔藓和地钱

苔藓和地钱是最古老的陆地植物。它们有茎和类似于叶和根的结构。与其他陆地植物不同,它们缺乏维管系统(一种专门的组织,用于在体内运输水和营养物质)。

蕨类植物和木贼

蕨类植物和木贼具有明显的茎、叶和根。它们是最古老的维管植物。这意味着,与苔藓和地钱不同,它们具有维管系统,通过其身体运输水和营养物质。

# 自定义

您可以通过配置其他属性(如图标、标签或工具提示文本)来自定义下拉菜单的外观。

# 显示标签

您可以控制 UI 元素的显示方式。例如,要隐藏图标并显示标签,可以使用以下配置

{
    label: 'Basic styles',
    // Show the textual label of the dropdown.
    // Note that the "icon" property is not configured and defaults to three dots.
    withText: true,
    items: [ 'bold', 'italic', 'strikethrough', 'superscript', 'subscript' ]
}

注意:如果 `icon` 为 `false`,标签也会自动显示(了解更多)。

种子植物

这个群体中的植物,称为*显花植物*,可以产生种子。

非开花植物

这个群体中的成员,称为*裸子植物*,是第一个产生种子的维管植物。与开花植物不同,种子没有外层覆盖物。

# 更改图标

您可以为下拉菜单使用以下列出的图标之一

图标名称 预览
'threeVerticalDots' **(默认)** Three vertical dots
'alignLeft' Align left
'bold' Bold
'importExport' Import export
'paragraph' Paragraph
'文本' Text
'加号' Plus
'拖动指示器' Drag indicator
'段落标记' Pilcrow
  • 默认图标从ckeditor5-core包中加载。
  • 如果未指定图标,则'threeVerticalDots'将用作默认图标。
  • 如果配置了icon: false,则不会显示图标,而是显示文本标签。
  • 您可以通过传递 SVG 字符串为下拉菜单设置自定义图标。

以下是一个示例

toolbar: [
    'undo', 'redo', '|',
    {
        // This dropdown uses a default icon because none was specified.
        label: 'Fonts',
        items: [ 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor' ]
    },
    '|',
    {
        label: 'A drop-down with a custom icon',
        // If you want your icon to change the color dynamically (for example, when opened)
        // avoid fill="..." and stroke="..." styling attributes.
        // Use solid shapes and avoid paths with strokes.
        // eslint-disable-next-line max-len
        icon: '<svg viewBox="0 0 68 64" xmlns="http://www.w3.org/2000/svg"><g fill="none" fill-rule="evenodd"><path d="M43.71 11.025a11.508 11.508 0 0 0-1.213 5.159c0 6.42 5.244 11.625 11.713 11.625.083 0 .167 0 .25-.002v16.282a5.464 5.464 0 0 1-2.756 4.739L30.986 60.7a5.548 5.548 0 0 1-5.512 0L4.756 48.828A5.464 5.464 0 0 1 2 44.089V20.344c0-1.955 1.05-3.76 2.756-4.738L25.474 3.733a5.548 5.548 0 0 1 5.512 0l12.724 7.292z" fill="#FFF"/><path d="M45.684 8.79a12.604 12.604 0 0 0-1.329 5.65c0 7.032 5.744 12.733 12.829 12.733.091 0 .183-.001.274-.003v17.834a5.987 5.987 0 0 1-3.019 5.19L31.747 63.196a6.076 6.076 0 0 1-6.037 0L3.02 50.193A5.984 5.984 0 0 1 0 45.003V18.997c0-2.14 1.15-4.119 3.019-5.19L25.71.804a6.076 6.076 0 0 1 6.037 0L45.684 8.79zm-29.44 11.89c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h18.479c.833 0 1.509-.67 1.509-1.498v-.715c0-.827-.676-1.498-1.51-1.498H16.244zm0 9.227c-.834 0-1.51.671-1.51 1.498v.715c0 .828.676 1.498 1.51 1.498h25.489c.833 0 1.51-.67 1.51-1.498v-.715c0-.827-.677-1.498-1.51-1.498h-25.49.001zm41.191-14.459c-5.835 0-10.565-4.695-10.565-10.486 0-5.792 4.73-10.487 10.565-10.487C63.27 3.703 68 8.398 68 14.19c0 5.791-4.73 10.486-10.565 10.486v-.001z" fill="#1EBC61" fill-rule="nonzero"/><path d="M60.857 15.995c0-.467-.084-.875-.251-1.225a2.547 2.547 0 0 0-.686-.88 2.888 2.888 0 0 0-1.026-.531 4.418 4.418 0 0 0-1.259-.175c-.134 0-.283.006-.447.018-.15.01-.3.034-.446.07l.075-1.4h3.587v-1.8h-5.462l-.214 5.06c.319-.116.682-.21 1.089-.28.406-.071.77-.107 1.088-.107.218 0 .437.021.655.063.218.041.413.114.585.218s.313.244.422.419c.109.175.163.391.163.65 0 .424-.132.745-.396.961a1.434 1.434 0 0 1-.938.325c-.352 0-.656-.1-.912-.3-.256-.2-.43-.453-.523-.762l-1.925.588c.1.35.258.664.472.943.214.279.47.514.767.706.298.191.63.339.995.443.365.104.749.156 1.151.156.437 0 .86-.064 1.272-.193.41-.13.778-.323 1.1-.581a2.8 2.8 0 0 0 .775-.981c.193-.396.29-.864.29-1.405h-.001z" fill="#FFF" fill-rule="nonzero"/></g></svg>',
        items: [ 'bold', 'italic', 'strikethrough', 'superscript', 'subscript' ]
    },
    '|',
    {
        // A "plus" sign icon works best for content insertion tools.
        label: 'Insert',
        icon: 'plus',
        items: [ 'uploadImage', 'insertTable' ]
    },
    '|',
    {
        // This dropdown has the icon disabled and a text label instead.
        label: 'Lists',
        icon: false,
        items: [ 'bulletedList', 'numberedList', 'todoList' ]
    }
],

以下是效果

针叶树

该组的大多数成员是常绿树木和灌木。它们以其针叶(特化的叶子)和球果(种子存放的地方)而闻名。

银杏和苏铁

银杏和苏铁都是非常古老的植物群。现存唯一的银杏物种是银杏树(银杏)。苏铁类似于棕榈树,但两者没有关系。后者属于开花植物。

# 自定义工具提示

默认情况下,按钮的工具提示与其标签共享文本。您可以使用tooltip属性来自定义它以更好地描述您的下拉菜单并使其更易于访问。

toolbar: [
    {
        label: 'Others',
        tooltip: 'Basic formatting features',
        items: [ 'bold', 'italic' ]
    },
    '|',
    'undo', 'redo'
]

开花植物

当您听到“植物”这个词时,您可能会想到这个组的成员。它们被称为被子植物,构成了植物界最多样化和最丰富的门。该组的植物可以开花结果,并包裹着种子。

# 列出可用项目

您可以使用以下代码段检索编辑器中可用的所有工具栏项目

Array.from( editor.ui.componentFactory.names() );

# 添加自定义按钮

请参阅分步教程,了解如何构建自定义插件、注册其按钮以及将其添加到工具栏配置中。

# 解耦编辑器

使用解耦编辑器时,您需要自己将菜单栏插入所需的位置。菜单栏 HTML 元素位于editor.ui.view.toolbar.element属性下。

    <div id="toolbarContainer"></div>
    <div id="editor"><p>Document content.</p></div>
DecoupledEditor
    .create( document.querySelector( '#editor' ), {
        toolbar: [ 'undo', 'redo', 'bold', 'italic', 'numberedList', 'bulletedList' ],
    } )
    .then( editor => {
        document.querySelector( '#toolbarContainer' ).appendChild( editor.ui.view.toolbar.element );
    } );

# 块工具栏

块工具栏在内容区域左侧提供了一个额外的可配置工具栏,当主工具栏不可用时(例如在某些布局中,如气球块编辑器)很有用。

# 演示

在下面的编辑器中,将光标移动到内容周围。您将看到块工具栏按钮拖动指示器正在跟随您的选择。单击该按钮以显示工具栏。

旅行带给你的美好

Three Monks walking on ancient temple.

就像地球上所有美好的事物一样,旅行以身作则教导我们。以下是我多年旅行中汲取的一些最宝贵的经验教训。

对多样性的欣赏

习惯一种完全不同的文化可能具有挑战性。虽然在线或从书籍中了解文化也很不错,但没有什么比亲身经历文化多样性更能令人难忘。您学会欣赏每一种差异,同时变得更具文化流动性。

此演示展示了一组有限的功能。访问功能丰富的编辑器示例以查看更多实际操作。

# 额外功能信息

要访问块工具栏,您需要单击内容区域左侧(边距)的带有盲文点图标的按钮拖动指示器。该按钮出现在选定的块元素(例如,段落)旁边,随着用户编辑内容和导航文档,它会跟随光标移动。

图标拖动指示器也是一个用于在编辑器周围拖动内容块的句柄。在上面的演示中单击标题并将其一直拖到底部,位于以下段落之间,以查看此功能的实际操作。

块工具栏是对气球编辑器类型的补充,因为它在某些情况下效果不佳,例如您必须插入某些内容(如图像),但选择已折叠,因此您无法访问工具栏。但是,它可以添加到任何类型的编辑器中并相应地配置(见下文)。

请参阅气球块编辑器示例页面。

# 块工具栏安装

请记住,首先将相关功能添加到编辑器配置中。块工具栏提供了一个按钮空间,但它不会带来实际功能。例如,heading1按钮在编辑器中没有标题功能的情况下将无法使用。

要将此功能添加到您的编辑器中,请将BlockToolbar添加到您的插件列表中,并使用blockToolbar属性配置该功能。

import { BlockToolbar, HeadingButtonsUI, ParagraphButtonUI } from 'ckeditor5';

BalloonEditor.create( document.querySelector( '#editor' ), {
    plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, /* ... */ ],
    blockToolbar: [
        'paragraph', 'heading1', 'heading2', 'heading3',
        '|',
        'bulletedList', 'numberedList',
        '|',
        'blockQuote', 'uploadImage'
    ],
    toolbar: [ /* ... */ ]
} )
.then( /* ... */ );

# 块工具栏配置

可以使用blockToolbar配置来定义块工具栏的内容。它类似于常规工具栏 UI 项目列表。

blockToolbar: {
  items: [
  	'bold',
  	'italic',
  	'link'
  ]
}

请参阅安装说明以获取更高级的示例。

由于工具栏始终与内容块连接,因此它最适合修改整个块(例如,创建标题)或插入对象(如图像表格)而不是内联样式(如粗体或斜体)的功能。

要调整块工具栏按钮的位置以匹配您网站的样式,请使用 CSStransform属性

.ck.ck-block-toolbar-button {
    transform: translateX( -10px );
}

如果您计划在从右到左 (RTL) 的语言中运行编辑器,请记住该按钮将附加到可编辑区域的右侧边界。在这种情况下,请确保通过添加以下样式来正确调整 CSS 位置。

.ck[dir="rtl"] .ck-block-toolbar-button {
    transform: translateX( 10px );
}

您可以使用shouldNotGroupWhenFull配置选项来防止块工具栏中自动项目分组

您还可以通过从图标列表中使用icon选项选择预定义图标或传递SVG字符串,来更改当前默认工具栏图标'dragIndicator'拖动指示器

blockToolbar: {
  items: [ /* ... */ ],
  icon: 'pilcrow'
  // or
  // icon: '<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24">' +
  // '<path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>'
},
toolbar: [ /* ... */ ]

您可以通过传递 SVG 字符串来提供自定义工具栏按钮图标。

# 功能特定的工具栏

某些功能也有自己的专用工具栏。在此页面上的演示中,您可以看到图像工具栏表格工具栏,当您使用相应的功能时。您将在相应的功能指南中找到有关这些工具栏的所有信息。