CKEditor 4 Text Match 与填充字符冲突:WebKit 下自动补全多出 @ 的根因、修复与验证

原创2026-10-16 12:44:051,865 阅读
文章标签:前端UI组件

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 测试步骤非常简单:

  1. 打开浏览器控制台(便于观察报错);
  2. 聚焦编辑器;
  3. 按下 Bold 样式按钮;
  4. 输入 @;
  5. 按下 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

(见 core/selection.js)

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 )
    };
};

这段代码的关键点:

  1. 只检查字符串开头:indexOf( fillingCharSequence ) == 0。原因是 WebKit 的填充字符总是被插在文本节点的起始位置(它要为光标「开路」),因此只需在开头剥离一次即可得到干净的查询文本。
  2. 同步修正偏移量:剥离填充字符后,字符串变短,所以 textAndOffset.offset -= fillingSequenceOffset,保证回调拿到的 offset 仍然指向真实的光标位置。
  3. 回填 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;返回的 range endOffset 则变为 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 在输入时的完整数据流:

  1. 用户按下 Bold 后输入 @,WebKit 在行内元素中注入 7 个 U+200B 填充字符;
  2. CKEDITOR.plugins.textWatcher 监听输入,调用配置的 textTestCallback(range)(plugins/autocomplete/plugin.js);
  3. textTestCallback 调用 CKEDITOR.plugins.textMatch.match( range, matchCallback )(plugins/autocomplete/plugin.js);
  4. match() 内先由 getTextAndOffset() 拼接相邻文本节点得到含填充字符的字符串,再执行 #2038 的剥离逻辑,得到干净文本后交给 matchCallback;
  5. 匹配成功返回 { range, text },autocomplete 的 onTextMatched 触发 model.setQuery( evt.data.text, evt.data.range )(plugins/autocomplete/plugin.js),随后 dataCallback 依据 matchInfo.query 拉取建议;
  6. 用户回车或点击接受建议,编辑器依据匹配 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)桌面浏览器中复现;其他内核浏览器不受此机制影响,测试亦无需覆盖。

登录后查看全文
ckeditor4