CKEditor 4 自定义标签保留机制:从 988 修复看 htmlDataProcessor 的保护流水线与 ACF 配置
CKEditor 4 自定义标签保留机制:从 #988 修复看 htmlDataProcessor 的保护流水线与 ACF 配置
本篇文章基于 CKEditor 4 仓库中 tests/core/htmldataprocessor/manual/customtag.md 手动测试用例,深入讲解 WYSIWYG 编辑器在处理以 object、embed、param、html、head、body、title 等原生标签名为前缀的自定义标签(Custom Tags)时的保留机制。读者将掌握:该问题(issue #988)的成因与修复原理、toHtml 数据流水线中"保护—恢复"的实现细节,以及通过 Advanced Content Filter(ACF)配置让自定义标签在编辑与源码模式间往返时不被剥离的完整实战方案。
背景:ACF 环境下自定义标签为何会意外丢失
CKEditor 4 从 4.1.0 起引入了 Advanced Content Filter(ACF),默认会剥离未被允许的内容。与此同时,编辑器的 HTML 数据处理器(CKEDITOR.htmlDataProcessor,实现于 core/htmldataprocessor.js)在把源码数据送入编辑区之前,会对一批特殊元素做"占位保护",防止浏览器 DOM 操作破坏它们。
问题出现在两者交汇处:若开发者使用形如 <objectfoo>、<embedfoo>、<paramfoo> 这类以原生标签名为前缀的自定义标签(Custom Elements),即便已经在 ACF 中通过 extraAllowedContent 显式允许了它们,标签仍然会被从编辑器内容中移除。
该问题被登记为 issue #988,并在 CKEditor 4.10.1 版本中修复。仓库的 CHANGES.md 中记录如下:
Fixed: ACF-enabled custom elements prefixed with
object,embed,paramare removed from the editor content.
仓库同时提供了覆盖此问题的两套测试:手动测试用例 tests/core/htmldataprocessor/manual/customtag.md(本篇文章的主体)与自动化回归测试 tests/core/htmldataprocessor/customtag.js。
手动测试用例:验证源码模式下自定义标签的完整性
测试元信息解读
原文档开头的 Bender 元信息定义了测试的运行环境与归属:
@bender-tags: bug, 988, 4.10.1
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, sourcearea
bug:表明这是针对缺陷修复的回归验证;988:关联 issue #988,即"ACF 允许的自定义元素被错误移除";4.10.1:标记该测试对应的修复版本;@bender-ui: collapsed:手动测试页面默认折叠 UI 面板;@bender-ckeditor-plugins:编辑器实例只需wysiwygarea(编辑区域)、toolbar(工具栏)和sourcearea(源码视图)三个插件——因为测试的核心动作就是"切换源码视图并检查源码内容"。
测试步骤与期望结果
原文档定义的测试过程极简但指向明确:
- 点击编辑器的 Source(源码) 按钮,切换到源码视图。
期望结果(Expected):编辑器源码中应完整保留以下全部自定义标签:
objectfooembedfooparamfoohtmlfooheadfoobodyfootitlefoo
每个标签都必须携带 data-foo="bar" 属性,并且标签内文本与标签名一致,例如:
<objectfoo data-foo="bar">objectfoo</objectfoo>
非期望结果(Unexpected):上述任意一个标签缺失,即视为测试失败。
该手动用例的实际页面由 tests/core/htmldataprocessor/manual/customtag.html 提供:页面在 <textarea id="editor"> 中预置了这 7 个自定义标签,并以内联脚本创建编辑器实例:
<script>
var elements = [
'object', 'embed', 'param',
'html', 'head', 'body', 'title'
];
CKEDITOR.replace( 'editor', {
extraAllowedContent: elements.join( 'foo[*]{*}(*);' ) + 'foo[*]{*}(*);',
autoParagraph: false
} );
</script>
这里的关键配置 extraAllowedContent 展开后为 objectfoo[*]{*}(*); embedfoo[*]{*}(*); paramfoo[*]{*}(*); htmlfoo[*]{*}(*); headfoo[*]{*}(*); bodyfoo[*]{*}(*); titlefoo[*]{*}(*); foo[*]{*}(*);,其含义将在后文"ACF 规则"一节详细拆解。
根源剖析:htmlDataProcessor 的"保护—恢复"机制与 #988 修复点
toHtml 流水线中的保护步骤
在 core/htmldataprocessor.js 中,编辑器触发 toHtml 事件(优先级 5 的监听器)处理输入数据时,会依次执行一系列正则保护,将易被浏览器 DOM 破坏的内容临时替换为安全占位:
protectSource:保护<script>、<noscript>、<meta>及用户通过config.protectedSource指定的内容;protectElements( protectTextareaRegex ):保护<textarea>内容(issue 9995);protectAttributes:保护href、src、name等 URL 类属性;protectElements( protectElementsRegex ):保护<style>、<link>、<meta>、<base>(IE 会从 innerHTML 中移除它们,issue 3710);protectElementsNames:给特定元素名添加cke:命名空间前缀(issue 3591);protectSelfClosingElements:把非 IE 浏览器忽略的自闭合元素改写成开闭标签对(issue 3591);protectPreFormatted:补偿<pre>后首行换行(issue 5789);protectInsecureAttributes:编码可能执行脚本的属性(issue 10)。
数据随后被塞入浏览器创建的 "fixBin" 元素,借由 DOM 修复非法结构,再经 CKEDITOR.htmlParser.fragment.fromHtml 解析,并通过 dataFilter 过滤(优先级 10)。输出方向(toDataFormat)则由 htmlFilter 反向处理。
#988 的根因与修复:protectElementNamesRegex
自定义标签丢失的根因位于第 5 步 protectElementsNames 及其正则 protectElementNamesRegex:
// Element name should be followed by space or closing angle bracket '>' to not protect custom tags (#988).
var protectElementNamesRegex = /(<\/?)((?:object|embed|param|html|body|head|title)([\s][^>]*)?>)/gi,
unprotectElementNamesRegex = /(<\/?)cke:((?:html|body|head|title)[^>]*>)/gi;
代码中的注释(#988)点明了修复意图:元素名之后必须紧跟空白字符或闭合的 > 才匹配,从而把 objectfoo 这类"名字更长"的自定义标签排除在保护范围之外。
修复前,该正则不加边界约束,会把 <objectfoo>、<embedfoo> 等也错误地匹配并改写成 <cke:objectfoo>;由于 unprotectElementNamesRegex 只还原 cke:html、cke:body、cke:head、cke:title 四个名称,其余被误加前缀的标签在后续流程中无法恢复,最终导致标签名损坏乃至被 ACF 判定为未知元素而整体剥离。修复后:
<objectfoo data-foo="bar">objectfoo</objectfoo>不再命中保护正则,保持原样进入解析与过滤阶段;- 真正的
<object>、<embed>、<param>仍会被保护为cke:object等,在浏览器 fixBin 中安全通过 DOM 处理后再由unprotectElementNames与htmlFilter的elementNames规则([ /^cke:/, '' ])还原。
与此同时,自闭合处理正则 protectSelfClosingRegex 也只在 param/embed 后紧跟 /> 或空白时改写:
var protectSelfClosingRegex = /<cke:(param|embed)([^>]*?)\/?>(?!\s*<\/cke:\1)/gi;
protectElementsNames 与 protectSelfClosingElements 两个函数的完整实现位于 core/htmldataprocessor.js。
ACF 配置:让自定义标签真正"被允许"
保护机制修复只是保证自定义标签不被误伤;要让它们最终存活,还必须让 ACF 认识它们。这正是手动测试用例与自动化测试共同使用的 extraAllowedContent 配置的作用。
extraAllowedContent 规则语法
core/filter.js 中说明了 config.extraAllowedContent 的定位:在保留编辑器默认 allowedContent 的基础上追加额外规则。其规则采用 CKEditor 4 的 Allowed Content Rules(ACR)字符串格式,一个完整规则形如:
标签名[属性]{样式}(类名)
[*]允许该元素上的任意属性;{*}允许任意内联样式;(*)允许任意 class;- 多个规则用
;分隔。
对应到 tests/core/htmldataprocessor/customtag.js:
bender.editor = {
config: {
extraAllowedContent: elements.join( 'foo[*]{*}(*);' ) + 'foo[*]{*}(*);',
autoParagraph: false
}
};
即依次允许 objectfoo、embedfoo、paramfoo、htmlfoo、headfoo、bodyfoo、titlefoo 七个标签携带任意属性、样式和类名,并额外放行一个兜底的 foo 规则。autoParagraph: false 则关闭自动段落包装,避免输入内容被包进 <p> 后干扰断言。
在 core/filter.js 的 convertValidatorToHash 中可以看到 '*' 通配符的底层语义:字符串校验器为 '*' 时直接返回 true,即"不做属性名限制"。
相关配置项对照
| 配置项 | 作用 | 源码依据 |
|---|---|---|
config.allowedContent |
整体替换过滤规则;设为 true 则完全禁用 ACF |
core/filter.js |
config.extraAllowedContent |
在默认规则基础上追加允许规则(本用例采用) | core/filter.js |
config.disallowedContent |
禁止规则,优先级高于允许规则 | core/filter.js |
另外可通过 editor.filter.check( 'objectfoo' ) 在运行时验证某个标签是否已被允许,editor.filter.allow() / disallow() 则用于运行时动态调整规则(core/filter.js)。
自动化回归测试:允许与不允许两种情形的断言
除了手动用例,仓库还提供了完全自动化的回归测试 tests/core/htmldataprocessor/customtag.js,把 #988 的两种情形固化为断言:
用例一(允许的自定义标签必须保留):输入 7 个自定义标签(objectfoo … titlefoo,均带 data-foo="bar" 与同名文本),断言 editor.getData() 输出与输入完全一致——标签、属性、文本一个都不能少。
用例二(未允许的自定义标签必须被剥离):输入 objectbar、embedbar、parambar、htmlbar、headbar、bodybar、titlebar(后缀改为 bar,未出现在 extraAllowedContent 中),断言输出仅为拼接后的纯文本 objectbarembedbarparambarhtmlbarheadbarbodybartitlebar——即标签外壳被 ACF 剥除,仅剩文本内容。
两个用例共同验证了同一机制的两个侧面:修复后的保护正则不会误伤自定义标签,而 ACF 依然忠实执行白名单过滤。测试断言通过 bender.editor 实例与 editorBot.setData()/editor.getData() 完成数据往返验证(tests/core/htmldataprocessor/customtag.js)。
边界条件与实践要点
基于源码实现,可归纳出以下实践要点:
- 修复只针对"前缀撞名"的自定义标签:
protectElementNamesRegex要求原生元素名后紧跟空白或>,因此<objectfoo>、<embedfoo>等不会被误保护;而真正匹配<object …>、<embed>、<param>、<html>、<head>、<body>、<title>的内容仍走原保护路径。 - 保留自定义标签必须双管齐下:一方面依赖 4.10.1+ 的保护正则修复,另一方面必须在 ACF 中显式放行这些标签(
extraAllowedContent或allowedContent),否则标签仍会被过滤剥离——这正是自动化测试用例二展示的行为。 param与embed有额外的自闭合处理:protectSelfClosingRegex会把它们的自闭合形式展开为开闭标签对以兼容非 IE 浏览器,自定义的paramfoo、embedfoo不受此规则影响。- 验证手段:手动场景可在源码视图检查标签完整性(本用例做法);自动场景可用
editor.getData()断言往返输出;运行时可用editor.filter.check()快速确认某标签是否在白名单内。