企业官网建设流程全解析

• 前端
• UI组件

导读

本文以仓库中 custompanelrender.md 手动测试用例为线索，剖析 CKEditor 4.16.2 中修复的 Color Button 插件面板首次打开时渲染错位问题（issue #4247）。通过还原复现步骤、梳理面板 DOM 结构、解读源码修复与回归测试，读者将掌握该 Bug 的完整成因与修复思路，并了解 CKEditor 4 手动测试（manual test）体系的组织方式与运行约定。

一、问题背景：Color Button 面板首次渲染异常

在 CKEditor 4 中，colorbutton插件为工具栏提供「Text Color（文本颜色）」与「Background Color（背景颜色）」两个下拉按钮，点击后弹出浮层面板（color panel），面板顶部是「自动颜色（Automatic）」区块，下方是色板与「More Colors」按钮。

在 4.16.2 之前的版本中，该面板首次打开时存在一个渲染缺陷：面板没有正确渲染，自动颜色框（automatic color box）与标题不在同一行，出现视觉错位。该问题由 CHANGES.md 中的 4.16.2 修复记录证实：

Fixed: [Color Button]'s incorrect rendering on the first opening.（#4247）

二、手动测试用例：复现步骤与判定标准

仓库中的手动测试文档 custompanelrender.md 专门用于验证此修复，其完整内容如下：

@bender-tags: 4.16.2, bug, 4247 @bender-ui: collapsed @bender-ckeditor-plugins: wysiwygarea, toolbar, colorbutton, colordialog, sourcearea 1. Click **Text Color** button. **Expected** * Panel is rendered correctly. Automatic color box and title are in the same line. **Unexpected** * Panel isn't rendered correctly. Automatic color box and title are not in the same line. 2. Repeat the procedure for the **Background Color** button.

该用例的核心操作只有两步：先点击Text Color按钮，再点击Background Color按钮，分别检查两个面板是否正常渲染。判定标准非常明确：

• Expected（期望）：面板渲染正确，自动颜色框与标题位于同一行；
• Unexpected（异常）：面板渲染错误，自动颜色框与标题不在同一行。

测试元数据注解

文档开头的@bender-tags与@bender-ui是 CKEditor 4 手动测试约定的元数据，含义如下：

配套 HTML 页面：定制色板配置

同目录下的 custompanelrender.html 是该手动测试的载体页面，其配置非常精简：

<textarea id="editor" name="editor">Test text.</textarea> <script> CKEDITOR.replace( 'editor', { language: 'pl', colorButton_colors: 'text-red/F00,text-blue/00F' } ); </script>

两个关键配置值得注意：

1. language: 'pl'：强制使用波兰语界面。由于「Automatic」等标签文案来自语言包，不同语言的文本宽度会直接影响「颜色框 + 标题」是否能在同一行放下，因此测试固定语言以确保复现稳定；
2. colorButton_colors: 'text-red/F00,text-blue/00F'：仅保留两个自定义色板颜色，采用colorName/colorCode格式（自 4.12.0 起，颜色名称仅用于 tooltip，输出时使用颜色代码）。精简的色板让面板尺寸更小，更容易暴露布局错位。

三、根因分析：首次渲染时的滚动条污染

面板的 DOM 结构

Color Button 面板由renderColors()函数在 plugins/colorbutton/plugin.js 中动态生成。其顶层结构如下（以 skins/moono-lisa/colorpanel.css 的 ASCII 示意图为据）：

+-- .cke_panel_block.cke_colorblock --+ | +-- a.cke_colorauto --------------+ | | | +-- .cke_colorbox --+ "Automatic" | ← 自动颜色区块 | +---------------------------------+ | | +-- table ------------------------+ | | | COLOR PALETTE | | ← 色板（每行默认 6 色） | |---------------------------------| | | | "More Colors" | | ← 更多颜色按钮 | +---------------------------------+ | +-------------------------------------+

自动颜色区块generateAutomaticButtonHtml()（plugin.js）生成的 HTML 大致为：

<a class="cke_colorauto" role="option" aria-posinset="1" aria-setsize="..."> <table><tr> <td colspan="6" align="center"> <span class="cke_colorbox" id="..._colorBox"></span>Automatic </td> </tr></table> </a>

CSS 中（moono-lisa/colorpanel.css）通过固定行高与内边距保证颜色框和文字对齐：

a.cke_colorauto { padding: 0; border: 1px solid transparent; margin-bottom: 6px; height: 26px; line-height: 26px; } .cke_colorauto span.cke_colorbox { width: 18px; height: 18px; border: 1px solid #808080; margin-left: 1px; margin-top: 3px; }

Bug 成因：html元素溢出导致首次渲染错位

在面板创建逻辑onBlock回调中（plugin.js），原有代码只处理了body的溢出：

// The block should not have scrollbars (https://dev.ckeditor.com/ticket/5933, https://dev.ckeditor.com/ticket/6056) block.element.getDocument().getBody().setStyle( 'overflow', 'hidden' ); // First render of panel have a scrollbar, but it shouldn't (#4247). block.element.getAscendant( { html: 1 } ).setStyle( 'overflow', 'hidden' );

其中最后一行正是 #4247 的修复：首次渲染面板时，滚动条本不该出现却出现了。面板首次打开时，浏览器会在<html>元素上产生滚动条，滚动条的出现改变了可用视口宽度，触发面板重新排版，进而导致自动颜色框与标题不在同一行。修复方式是找到面板块元素的html祖先节点，同样将其overflow显式设置为hidden，从根源上消除首次渲染时的滚动条干扰。

四、回归测试：防止滚动条再现

该修复同时配有自动化回归测试，位于 tests/plugins/colorbutton/colorbutton.js：

// (#4247) 'test panel should have styles that prevent scrollbar apperance': function() { bender.editorBot.create( { name: 'editorScrollbar', config: { colorButton_colors: 'text-red/F00,text-blue/00F', language: 'pl' } }, function( bot ) { var editor = bot.editor, bgColorBtn = editor.ui.get( 'TextColor' ), textColorBtn = editor.ui.get( 'BGColor' ); bgColorBtn.click( editor ); assert.areEqual( bgColorBtn._.panel.getBlock( bgColorBtn._.id ).element.getAscendant( { html: 1 } ).getStyle( 'overflow' ), 'hidden' ); textColorBtn.click( editor ); assert.areEqual( textColorBtn._.panel.getBlock( textColorBtn._.id ).element.getAscendant( { html: 1 } ).getStyle( 'overflow' ), 'hidden' ); } ); }

该测试与手动用例使用完全相同的配置（text-red/F00,text-blue/00F+language: 'pl'），并逐一验证：

1. 分别点击TextColor与BGColor按钮打开面板；
2. 通过getAscendant( { html: 1 } )找到面板块的html祖先节点；
3. 断言其overflow样式必须为hidden。

值得注意的是，手动测试验证的是视觉结果（颜色框与标题同排），而自动化测试验证的是成因修复（html 元素 overflow 被隐藏）——二者互为补充，共同锁定了回归风险。

五、手动测试的运行方式

CKEditor 4 的手动测试由 Bender 测试框架驱动，配置见仓库根目录的 bender.js：

• 框架声明为yui（framework: 'yui'）；
• 测试通过@bender-tags中的bug、4.16.2等标签可被筛选检索；
• 配置文件中预留了manualBrowsers（允许执行手动测试的浏览器列表）与manualTestTimeout（手动测试超时阈值，超时即标记失败）等参数。

执行手动测试时，先启动 Bender 服务器并打开测试列表，筛选@bender-tags中包含4247的用例，在浏览器中按文档步骤操作并依据 Expected/Unexpected 判定结果即可。自动化回归用例则可通过 Bender 的自动化测试入口运行colorbutton测试组。

六、延伸：面板渲染相关的可配置项

从该用例延伸出去，Color Button 面板渲染还受以下配置影响（均定义于 plugins/colorbutton/plugin.js 底部）：

其中colorButton_contentsCss正是手动用例中@bender-ckeditor-plugins清单里sourcearea等插件之外，影响面板外观的扩展入口——开发者可通过追加自定义 CSS 进一步定制自动颜色区块等面板内容的样式。

七、小结

#4247 是一个典型的「首次渲染时序」问题：面板首次打开时html元素产生滚动条，间接破坏了自动颜色区块「颜色框 + 标题同排」的布局。修复仅需一行代码（将面板块的html祖先overflow置为hidden），却同时配套了手动视觉用例与自动化样式断言两类测试。该案例既展示了 CKEditor 4 如何处理浏览器滚动条对浮层面板的干扰，也完整呈现了其「手动用例 + 自动化回归 + CHANGES 记录」三层质量保障体系，值得在自研富文本编辑器组件时借鉴。

• 前端
• UI组件