CKEditor 4 Text Match 与填充字符冲突:WebKit 下自动补全多出 @ 的根因、修复与验证
CKEditor 4 Text Match 与填充字符冲突:WebKit 下自动补全多出 @ 的根因、修复与验证
本文以仓库中的 Bender 手动测试用例 tests/plugins/textmatch/manual/fillingcharsequence.md 为核心,结合 plugins/textmatch/plugin.js、core/selection.js 与配套单元测试,完整讲解 CKEditor 4 在 WebKit 浏览器中因 Filling Character(填充字符)干扰 Text Match 文本匹配,导致 autocomplete(自动补全)插入结果变成
@foo@的 Bug #2038 根因、修复实现与验证方法。读完本文,你将掌握CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE的作用机制、textMatch.match()的剥离逻辑,以及如何复现和测试此类问题。
一、这份手动测试用例在测什么
该文档是 CKEditor 4 Bender 测试框架中的一个 manual(手动)测试用例,其头部元数据给出了完整的运行上下文:
@bender-tags: 4.10.0, bug, 2038
@bender-ui: collapsed
@bender-ckeditor-plugins: wysiwygarea, toolbar, basicstyles, textmatch, autocomplete
4.10.0:用例所针对(并验证修复)的版本;bug, 2038:关联的缺陷编号 #2038,即本次测试要回归验证的 Bug;@bender-ckeditor-plugins:测试编辑器需要加载的插件清单,其中textmatch(文本匹配)与autocomplete(自动补全)是本用例的主角,basicstyles用于启用 Bold 按钮,wysiwygarea、toolbar提供经典编辑界面。
用例本身分为「测试步骤」与「预期/非预期结果」两部分:它要求在按下 Bold 按钮(开启加粗)后输入 @ 并触发 autocomplete 的下拉选择,从而复现一个只有在 WebKit 浏览器(Chrome/Safari)下才会出现的文本匹配错误。
二、Bug #2038:为什么输入 @ 回车后插入了 @foo@
文档中的 Phase 1 测试步骤非常简单:
- 打开浏览器控制台(便于观察报错);
- 聚焦编辑器;
- 按下
Bold样式按钮; - 输入
@; - 按下
enter(或改用鼠标点击下拉选项)。
对应的期望结果是 @foo 被插入编辑器——即用户输入 @,autocomplete 面板出现并建议 @foo,回车接受后正文只保留一个 @foo。
而「非预期」(即 Bug 的表现)包括任意一种:
- 下拉面板根本没有出现;
- 编辑器中被插入的是
@foo@(多出一个@,即填充字符被当作查询文本的一部分回填); - 控制台出现错误。
三、根因剖析:WebKit 的 Filling Character(填充字符)
3.1 什么是填充字符
在 WebKit 内核浏览器(Chrome、Safari)中,光标(caret)无法稳定地显示在空的块级元素或行内元素内部,例如 <strong>^</strong> 这种场景。为了修复这一问题,CKEditor 4 在 4.5.7 起引入了一套「Filling Character」机制(相关历史票据 1272、13816、7222 等),其核心实现位于 core/selection.js:
// https://dev.ckeditor.com/ticket/13816
var fillingCharSequence = CKEDITOR.tools.repeat( '\u200b', 7 ),
fillingCharSequenceRegExp = new RegExp( fillingCharSequence + '( )?', 'g' );
即 填充字符是 7 个连续的零宽空格(U+200B)。当光标处于需要「占位」的位置时,编辑器会通过 createFillingCharSequenceNode() 在可编辑区创建一个文本节点并写入这段序列(core/selection.js),并在合适的时机用 removeFillingCharSequenceNode() / removeFillingCharSequenceString() 把它清理掉(core/selection.js)。
该序列通过 CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE 对外暴露:
/**
* The sequence used in a WebKit-based browser to create a Filling Character. By default it is
* a string of 7 zero-width space characters (U+200B).
* @since 4.5.7
* @readonly
* @property {String}
*/
FILLING_CHAR_SEQUENCE: fillingCharSequence
3.2 填充字符如何混进 Text Match 的查询文本
Text Match 插件的核心能力是在 DOM 中做文本搜索:它把光标所在位置前后相邻的文本节点拼成一个纯字符串,再把光标偏移量换算到该字符串中,交给回调函数做正则匹配。拼接逻辑由 CKEDITOR.plugins.textMatch.getTextAndOffset() 完成(plugins/textmatch/plugin.js)。
问题就出在这里:当用户按下了 Bold 按钮,光标位于 <strong> 这类行内元素中时,WebKit 会先注入一段填充字符以保证光标可见。之后用户输入 @,这些不可见的 U+200B 字符仍然留在文本节点里,于是 getTextAndOffset() 拼出来的「文本」就变成了类似:
\u200b\u200b\u200b\u200b\u200b\u200b\u200b@
而真正可见的内容是 @。此时如果 autocomplete 的回调对这段字符串执行 /@\w*$/ 之类的匹配:
- 对
matchCallback来说,可见前缀里@前面多了一串「幽灵字符」; - 对接受建议后的插入逻辑来说,填充字符会被当作正文内容一并插入,最终用户看到的就是
@foo@——这正是文档中「Unexpected」列表的第二条。
同时,若 textMatch.match() 返回的 range 边界没有考虑填充字符的长度,选中/替换范围也会错位,导致下拉面板不出现或插入内容异常。
四、修复实现:textMatch.match 中的填充字符剥离
Bug #2038 的修复落在 CKEDITOR.plugins.textMatch.match() 中(plugins/textmatch/plugin.js),源码注释直接标注了问题编号:
CKEDITOR.plugins.textMatch.match = function( range, callback ) {
var textAndOffset = CKEDITOR.plugins.textMatch.getTextAndOffset( range ),
fillingCharSequence = CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE,
fillingSequenceOffset = 0;
if ( !textAndOffset ) {
return;
}
// Remove filling char sequence for clean query (#2038).
if ( textAndOffset.text.indexOf( fillingCharSequence ) == 0 ) {
fillingSequenceOffset = fillingCharSequence.length;
textAndOffset.text = textAndOffset.text.replace( fillingCharSequence, '' );
textAndOffset.offset -= fillingSequenceOffset;
}
var result = callback( textAndOffset.text, textAndOffset.offset );
if ( !result ) {
return null;
}
return {
range: CKEDITOR.plugins.textMatch.getRangeInText( range, result.start, result.end + fillingSequenceOffset ),
text: textAndOffset.text.slice( result.start, result.end )
};
};
这段代码的关键点:
- 只检查字符串开头:
indexOf( fillingCharSequence ) == 0。原因是 WebKit 的填充字符总是被插在文本节点的起始位置(它要为光标「开路」),因此只需在开头剥离一次即可得到干净的查询文本。 - 同步修正偏移量:剥离填充字符后,字符串变短,所以
textAndOffset.offset -= fillingSequenceOffset,保证回调拿到的 offset 仍然指向真实的光标位置。 - 回填 range 边界:回调返回的
result.end是在「剥离后字符串」上的偏移,而最终getRangeInText()生成的是原始 DOM 上的 range,因此结束偏移要加上fillingSequenceOffset,确保替换范围覆盖到真实的@文本,而不是漏掉或重复。这也是避免插入@foo@的关键。
五、单元测试佐证:填充字符场景的自动化验证
仓库在 tests/plugins/textmatch/staticfunctions.js 中为这次修复补充了专门的单元测试(同样标注了 #2038):
// (#2038)
tcs[ 'test textMatch with filling char sequence' ] = function() {
var html = '<p>' + CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE + 'Hel{}lo</p>',
range = bender.tools.range.setWithHtml( rangeRoot, html ),
result = CKEDITOR.plugins.textMatch.match( range, function( text, offset ) {
assert.areEqual( 'Hello', text );
assert.areEqual( 3, offset );
return {
start: 0,
end: 3
};
} );
assert.areSame( 'Hel', result.text );
assert.areSame( range.startContainer, result.range.startContainer );
assert.areSame( 0, result.range.startOffset );
assert.areSame( 10, result.range.endOffset );
};
(见 tests/plugins/textmatch/staticfunctions.js)
对照普通场景(无填充字符,见同文件 L121-L138):
- 普通场景:输入
<p>Hel{}lo</p>,回调收到text='Hello'、offset=3,匹配Hel,返回 range 的endOffset=3; - 填充字符场景:输入
<p>+ 7 个 U+200B +Hel{}lo</p>,回调收到的text依然是'Hello'(填充字符已被剥离)、offset依然是3;返回的 rangeendOffset则变为10(3 + 7,即把填充字符的长度补回原始 DOM 坐标)。
这个断言精确验证了「剥离查询文本、校正偏移、回填 range 边界」三步逻辑的正确性。同一文件里还有 getAdjacentTextNodes、getTextAndRange、getRangeInText 三组大量用例,覆盖光标位于文本节点/元素节点、跨行内元素、多文本节点等场景,是理解 Text Match 底层行为的最佳入口。
六、手动测试的复现与执行细节
手动测试的配套页面 tests/plugins/textmatch/manual/fillingcharsequence.html 揭示了复现条件的三个重要细节:
1. 仅 WebKit 且非移动端环境执行:
if ( !CKEDITOR.env.webkit || bender.tools.env.mobile ) {
bender.ignore();
}
因为填充字符机制只作用于 WebKit,非 WebKit 浏览器(Firefox、IE 等)不会注入 U+200B,测试没有意义;移动端 WebKit 行为不同,同样跳过。
2. 测试编辑器挂载 autocomplete 实例:
CKEDITOR.replace( 'editor', {
on: {
instanceReady: function( evt ) {
new CKEDITOR.plugins.autocomplete( evt.editor, {
textTestCallback: textTestCallback,
dataCallback: dataCallback
} );
}
}
} );
3. 数据源与匹配回调:
function dataCallback( matchInfo, callback ) {
callback( [ { id: 1, name: '@foo' } ] );
}
function textTestCallback( range ) {
return CKEDITOR.plugins.textMatch.match( range, matchCallback );
}
function matchCallback( text, offset ) {
var left = text.slice( 0, offset ),
match = left.match( new RegExp( '@\\w*$' ) );
if ( !match ) {
return null;
}
// 双保险:即使 match() 已剥离,回调里再防御一次。
if ( text.indexOf( CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE ) == 0 ) {
return null;
}
return { start: match.index, end: offset };
}
值得注意:matchCallback 在 textMatch.match() 已剥离填充字符的前提下,又做了一次 text.indexOf( FILLING_CHAR_SEQUENCE ) == 0 的防御性检查。这说明 autocomplete 类插件的开发者可以(也建议)在自定义回调中做双重校验——因为回调拿到的 text 理论上已被清理,但显式检查能让异常场景(例如未来填充字符出现在非开头位置)不至于被静默吞掉。
数据源 dataCallback 返回的唯一建议项就是 @foo,因此按文档步骤操作后,正常情况下编辑器应插入 @foo;若修复失效,则会出现 @foo@、面板不弹出或控制台报错。
七、从测试反推完整调用链
将手动测试与源码串联,可以得到 autocomplete 在输入时的完整数据流:
- 用户按下 Bold 后输入
@,WebKit 在行内元素中注入 7 个 U+200B 填充字符; CKEDITOR.plugins.textWatcher监听输入,调用配置的textTestCallback(range)(plugins/autocomplete/plugin.js);textTestCallback调用CKEDITOR.plugins.textMatch.match( range, matchCallback )(plugins/autocomplete/plugin.js);match()内先由getTextAndOffset()拼接相邻文本节点得到含填充字符的字符串,再执行 #2038 的剥离逻辑,得到干净文本后交给matchCallback;- 匹配成功返回
{ range, text },autocomplete 的onTextMatched触发model.setQuery( evt.data.text, evt.data.range )(plugins/autocomplete/plugin.js),随后dataCallback依据matchInfo.query拉取建议; - 用户回车或点击接受建议,编辑器依据匹配 range 用
@foo替换查询文本——因为 range 的结束偏移已补回填充字符长度,替换结果恰好是干净的@foo。
八、给插件开发者的实践建议
结合本用例与源码,在 CKEditor 4 中开发 autocomplete / mentions 类功能时,建议遵循以下几点:
- 始终通过
CKEDITOR.plugins.textMatch.match()做文本匹配,不要自行遍历 DOM 拼接文本,否则会踩中填充字符的坑; - 匹配回调中务必处理
@等触发符后跟零字符的情况:/@\w*$/会把刚输入的@也算作匹配(这正是手动测试要覆盖的边界); - 对返回的 range 做替换/插入时,信任
match()已回填的偏移(result.end + fillingSequenceOffset),不要再基于可见文本长度自行推算 DOM 坐标; - 在回调里保留对
CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE的防御检查,与 fillingcharsequence.html 的做法保持一致; - 回归测试时使用 Bender:单元测试参照 staticfunctions.js 中 #2038 用例的写法(构造
FILLING_CHAR_SEQUENCE + 文本的 HTML),手动测试则参照本用例在 WebKit 桌面浏览器上执行 Phase 1 步骤并核对 Expected 清单。
九、相关源码与测试索引
| 用途 | 路径 |
|---|---|
| 手动测试用例(本文主体) | tests/plugins/textmatch/manual/fillingcharsequence.md |
| 手动测试页面(含复现代码) | tests/plugins/textmatch/manual/fillingcharsequence.html |
| Text Match 插件实现 | plugins/textmatch/plugin.js |
| 填充字符机制定义与清理 | core/selection.js |
| 填充字符常量(FILLING_CHAR_SEQUENCE) | core/selection.js |
| #2038 单元测试 | tests/plugins/textmatch/staticfunctions.js |
| autocomplete 插件调用链 | plugins/autocomplete/plugin.js |
适用前提说明:本文描述的行为与修复均以当前仓库(CKEditor 4,含 4.10.0 以来的修复)为基准,填充字符问题仅在 WebKit 内核(Chrome/Safari)桌面浏览器中复现;其他内核浏览器不受此机制影响,测试亦无需覆盖。