CKEditor 4 removeButtons 配置详解:字符串与数组两种方式移除工具栏按钮
CKEditor 4 removeButtons 配置详解:字符串与数组两种方式移除工具栏按钮
本文围绕 CKEditor 4 的 config.removeButtons 配置项展开,以仓库内对应的 Bender 手动测试(tests/plugins/toolbar/manual/removebuttons.md)为切入点,结合 toolbar 插件源码、自动化测试与变更记录,讲解如何精确移除工具栏上的指定按钮、4.20.0 起新增的数组写法,以及该配置在底层是如何参与工具栏构建的。读完本文,你将能够独立配置 CKEditor 4 的按钮显隐,并理解它与 toolbar、toolbarGroups 等其他工具栏配置的协作关系。
一、这篇手动测试在验证什么
仓库中的 removebuttons.md 是一个 Bender 手动测试用例,其核心验证目标非常明确:当通过 config.removeButtons 以数组形式传入按钮名时,编辑器工具栏不再渲染这些按钮,且控制台不产生任何错误。
该用例的 Bender 元数据标注了测试归属:
@bender-tags: 4.20.0, feature, 5122—— 对应 CKEditor 4.20.0 引入的功能,关联 issue #5122(即“允许以数组形式向removeButtons传入按钮列表”);@bender-ui: collapsed—— 以折叠 UI 的方式渲染测试页面;@bender-ckeditor-plugins: wysiwygarea, toolbar, basicstyles—— 测试环境仅加载这三个插件,保证测试聚焦于工具栏与基础样式按钮。
与 .md 说明配套的测试页面 removebuttons.html 内容如下:
<div id="editor">
<p>Lorem ipsum dolor sit amet</p>
</div>
<script>
if ( bender.tools.env.mobile ) {
bender.ignore();
}
CKEDITOR.replace( 'editor', {
removeButtons: [ 'Bold', 'Italic' ]
} );
</script>
测试页首先通过 bender.tools.env.mobile 判断运行环境,若为移动端则调用 bender.ignore() 跳过该用例(因为桌面端工具栏布局才是本用例的验证对象);随后创建一个配置了 removeButtons: [ 'Bold', 'Italic' ] 的编辑器实例。手动执行时的验证步骤为:
- 打开浏览器控制台 —— 预期结果:控制台无任何错误;
- 观察编辑器工具栏 —— 预期结果:工具栏中不存在 “Bold” 和 “Italic” 按钮。
虽然它是一份简短的手动测试说明,但其背后对应的是一个真实可用的公开配置项。下面从配置写法、源码实现到自动化测试逐一展开。
二、config.removeButtons 的两种写法
removeButtons 的完整定义位于 plugins/toolbar/plugin.js 的配置文档注释:
不得渲染的工具栏按钮名称列表。该配置同样适用于非按钮类工具栏项(例如 Font 字体下拉框)。
类型为 String/String[],支持两种写法:
写法一:字符串(逗号分隔,兼容所有版本)
config.removeButtons = 'Underline,JustifyCenter';
写法二:数组(CKEditor 4.20.0 起支持)
config.removeButtons = [ 'Underline', 'JustifyCenter' ];
数组写法由 issue #5122 引入,CHANGES.md 中的 4.20 变更记录明确记载:
[#5122]:为
config.removeButtons配置项增加了以数组形式提供按钮列表的能力。
两种写法在效果上完全等价,数组写法更适合通过编程方式动态拼接要移除的按钮列表,例如根据权限系统过滤按钮。
注意事项
- 配置中使用的按钮名是按钮的注册名(item name),而不是显示标签。例如 Bold 按钮的注册名是
Bold、粗体命令是bold,配置时必须使用前者; - 该配置只影响按钮是否渲染,并不会删除按钮对应的命令。从 basicstyles 插件 的源码结构看,命令(
editor.addCommand)与按钮(editor.ui.addButton)是分开注册的,因此移除按钮后,格式化命令仍可通过快捷键等方式触发——这正是“从工具栏移除”与“彻底禁用功能”的本质区别; - 官方注释明确建议不要过度使用该配置。更推荐的方式是使用
config.removePlugins移除整个功能插件,或直接在 CKEditor 4 Builder 中定制只包含所需功能的构建版本。removeButtons的典型适用场景是:单个插件注册了一组按钮,而你只想去掉其中少数几个——例如本文示例中 basicstyles 插件提供了六个按钮,仅需隐藏其中两个。
三、源码实现:工具栏构建时如何过滤按钮
要理解 removeButtons 的生效时机,需要看 toolbar 插件初始化时构建工具栏配置的完整链路。plugins/toolbar/plugin.js 的 getToolbarConfig 函数 是核心入口:
function getToolbarConfig( editor ) {
var removeButtons = getRemoveButtons( editor.config.removeButtons );
// (#5122)
function getRemoveButtons( config ) {
if ( config && typeof config === 'string' ) {
return config.split( ',' );
}
return config;
}
// ...
}
这里就是两种写法归一化的关键点:字符串写法按逗号 split(',') 拆成数组,数组写法则原样透传,最终都统一为数组交给后续逻辑使用。这正是 4.20.0 中为支持数组写法所做的改动(代码中 // (#5122) 注释即为对应 issue 标记)。
随后,在 fillGroup 函数(plugins/toolbar/plugin.js 的 fillGroup 实现)中,每个要放入工具栏组的 UI 项都会被逐一检查:
// Ignore items that are configured to be removed.
if ( !removeButtons || CKEDITOR.tools.indexOf( removeButtons, name ) == -1 ) {
item = editor.ui.create( name );
if ( !item )
continue;
if ( !editor.addFeature( item ) )
continue;
toolbarGroup.items.push( item );
}
逻辑清晰:只有当 removeButtons 未配置、或当前按钮名不在移除列表中时,才真正创建 UI 项并加入工具栏;命中移除列表的按钮会被直接跳过,根本不进入渲染阶段。这解释了为什么该配置“不会渲染按钮”而非“渲染后再隐藏”。
与其他工具栏配置的关系
getToolbarConfig 最终根据以下优先级产出工具栏定义:
- 若
config.toolbar为字符串,则读取对应的config.toolbar_<名称>命名配置; - 若配置了
config.toolbar(数组/字符串),走populateToolbarConfig填充; - 否则基于
config.toolbarGroups通过buildToolbarConfig自动生成。
无论走哪条路径,removeButtons 的过滤都发生在 fillGroup 这一层,因此它对显式 toolbar 定义和自动生成的工具栏同样生效。toolbar 示例页 在判断“是否为默认工具栏”时也将 removeButtons 与 toolbar、toolbarGroups 并列检查:
defaultToolbar = !( editor.config.toolbar || editor.config.toolbarGroups || editor.config.removeButtons );
这说明只要显式配置了三者中的任何一个,编辑器就会认为“用户主动定制了工具栏”,从而在示例页中展示当前配置对应的代码。
四、自动化测试如何锁定行为
除了手动测试,仓库还提供了自动化测试 tests/plugins/toolbar/config.js 对两种写法分别做了断言。
用例一:字符串写法配合自定义 toolbarGroups(config.js 第 66 行起)
'test config.toolbarGroups and config.removeButtons': function() {
bender.editorBot.create( {
name: 'editor3',
config: {
toolbarGroups: [
{ name: 'about' },
'/',
{ name: 'test', groups: [ 'basicstyles', 'list' ] }
],
removeButtons: 'Underline,Strike,Subscript,Superscript,BulletedList'
}
},
function( bot ) {
var editor = bot.editor;
// 断言:'test' 组最终只剩 bold、italic、分隔符与 numberedlist
assert.isTrue( comp( [ 'bold', 'italic', '-', 'numberedlist' ], editor.toolbar[ 2 ] ) );
// ...
} );
}
该用例通过 comp 比较函数断言最终工具栏内容:basicstyles 组的 Underline、Strike、Subscript、Superscript 以及 list 组的 BulletedList 均被移除,只保留 bold、italic 和 numberedlist。
用例二:数组写法(对应 #5122)(config.js 第 96 行起)
// (#5122)
'test config.removeButtons accepts array of buttons': function() {
bender.editorBot.create( {
name: 'editor-5122',
config: {
plugins: [ 'toolbar', 'wysiwygarea', 'basicstyles' ],
removeButtons: [ 'Bold', 'Italic' ]
}
},
function( bot ) {
var editor = bot.editor,
basicStyleGroup = getToolbarGroup( editor, 'basicstyles' );
assert.isTrue( comp( [ 'underline', 'strike', 'subscript', 'superscript' ], basicStyleGroup ) );
// ...
} );
}
该用例与手动测试页使用完全相同的配置(removeButtons: [ 'Bold', 'Italic' ]),断言 basicstyles 组中仅剩 underline、strike、subscript、superscript 四个按钮——即 Bold、Italic 已被正确移除。手动测试与自动化测试双管齐下,共同锁定该功能在字符串与数组两种写法下的行为一致性。
五、结合 basicstyles 插件理解按钮的“注册名”
示例中移除的 Bold、Italic 按钮来自 basicstyles 插件。该插件在 init 阶段通过 addButtonCommand 辅助函数统一注册按钮,其中按钮的 toolbar 属性决定了它归属于哪个工具栏组以及组内顺序(plugins/basicstyles/plugin.js 第 43 行):
if ( editor.ui.addButton ) {
editor.ui.addButton( buttonName, {
isToggle: true,
label: buttonLabel,
command: commandName,
toolbar: 'basicstyles,' + ( order += 10 )
} );
}
toolbar 属性的格式是 "组名,顺序值",order 每次递增 10,于是六个按钮依次以 basicstyles,10、basicstyles,20 … basicstyles,60 注册。结合插件顶部声明的图标列表 icons: 'bold,italic,underline,strike,subscript,superscript' 可以推断,默认顺序依次为:Bold(10)、Italic(20)、Underline(30)、Strike(40)、Subscript(50)、Superscript(60)。
这也从侧面印证了两点:
- toolbar 插件在
getItemDefinedGroups(plugins/toolbar/plugin.js 第 471 行起)中正是解析每个 UI 项的toolbar: '组名,顺序'来构建组内排序的; removeButtons中的名称必须与editor.ui.addButton注册时的buttonName完全一致(如'Bold'、'Italic'),否则过滤不生效。
六、实践建议
- 按需选择写法:静态配置用字符串即可,动态计算按钮列表(如按用户角色过滤)建议用数组,代码更清晰;
- 组合使用:
removeButtons可与toolbar/toolbarGroups自由组合——它只负责“剔除”,不负责“重排”,重排请使用toolbarGroups或显式toolbar定义; - 优先考虑
removePlugins:如果整个功能都不需要(比如完全不需要粗体格式化),移除插件比逐个移除按钮更彻底,还能减小最终构建体积; - 注意命令仍可用:如第三节所述,移除按钮不等于禁用命令,若需要彻底禁用,应使用
editor.addCommand级别的控制或removePlugins; - 运行验证:本仓库采用 Bender 测试框架,手动用例可通过 Bender 测试运行器执行(配置见 bender.js 与 bender-runner.config.json);自动化断言则直接运行
tests/plugins/toolbar/config.js对应的测试套件即可。
七、小结
一份仅十余行的手动测试说明背后,是 CKEditor 4 工具栏定制体系中一个看似简单却设计周到的配置项:removeButtons 以“构建期过滤”而非“渲染后隐藏”的方式工作,字符串与数组两种写法在 getRemoveButtons 处归一化,最终在 fillGroup 中统一过滤。理解这一链路后,你不仅能熟练配置按钮显隐,还能举一反三地理解 toolbar、toolbarGroups、removePlugins 等配置的协作边界,按需构建出符合业务场景的编辑器工具栏。