CKEditor 4 编辑器无障碍朗读标签定制：applicationTitle 配置详解与屏幕阅读器测试指南-平芜编程栈

前端
UI组件

【免费下载链接】ckeditor4

The best enterprise-grade WYSIWYG editor. Fully customizable with countless features and plugins.

项目地址：https://gitcode.com/gh_mirrors/ck/ckeditor4

导读

本文围绕 CKEditor 4 在 4.19.0 版本中引入的config.applicationTitle配置项展开，讲解如何定制或禁用编辑器所在的"应用区域"（application region）朗读标签，并结合 tests/core/creators/manual/themeduicustomlabels.md 这一面向屏幕阅读器的手动测试用例，说明 iframe 与 div 两种主题化编辑器形态下朗读结果应该是什么样。读完本文，你将掌握applicationTitle的取值规则、底层 DOM 实现、与title配置的配合方式，以及如何用 Bender 手动测试验证自定义标签在 VoiceOver、NVDA、JAWS 等屏幕阅读器中的实际朗读效果。

一、背景：为什么需要"应用区域标签"

CKEditor 4 编辑器的整个 UI（工具栏、面板、可编辑区域等）在无障碍树中是一个role="application"的容器。屏幕阅读器用户需要知道"当前页面上有多个编辑器、我正在操作哪一个"，因此这个容器需要一个可朗读的标签。这一标签称为应用区域标签（application region label），它描述的是"编辑器连同其工具栏等整个 UI 所在的网站区域"，与描述编辑器本身内容的config.title是两个不同的概念。

在 4.19.0 之前，应用区域标签由语言文件中的application字符串与编辑器实例名拼接而成（例如英文语言文件中的'Rich Text Editor'，见 lang/en.js）。从 4.19.0 开始（对应 issue #2445），CKEditor 4 提供了config.applicationTitle配置项，允许开发者自定义这一标签，或通过设为false完全禁用。

二、配置项取值规则与默认行为

applicationTitle的完整定义位于 core/editor.js，取值规则如下：

取值	行为
字符串（如`'My WYSIWYG'`）	将该字符串作为应用区域标签
`false`	不添加应用区域标签（容器上不再出现`aria-labelledby`与朗读用`<span>`）
其他类型（`true`、`null`、数字、空字符串等）	视为未设置，回退到默认值

默认值为基于 editor.name，即语言文件中的application字符串与实例名拼接，形如'Rich Text Editor, editor1'。

在 core/editor.js 的loadLang函数中，配置值经过类型校验后写入只读属性editor.applicationTitle：

editor.applicationTitle = typeof configApplicationTitle == 'string' || configApplicationTitle === false ? configApplicationTitle : [ editor.lang.application, editor.name ].join( ', ' );

也就是说：只有字符串和false会被直接采纳，其余所有非法值都会自动回退为默认拼接格式。这一点在 tests/core/editor/applicationtitle.js 中有完整的测试覆盖——true、null、42等非法值在 iframe（framed）和 inline 两种创建方式下都会被当作未设置处理。

全局配置的注意点

文档明确指出一个无障碍陷阱（core/editor.js）：

注意：当config.applicationTitle被全局设置时，该值会应用到所有编辑器实例。这会损害无障碍体验，因为屏幕阅读器用户将无法区分和导航不同的编辑器实例。

同样，全局设置config.applicationTitle = false也会以类似方式损害无障碍体验。因此，如果你的页面有多个编辑器实例，应避免在全局配置中统一设置固定标签或统一禁用，而应针对每个实例单独配置，以保留"哪个编辑器是哪个"的可辨识信息。

三、配置示例

在 core/editor.js 中给出了两个最基础的用法：

// 将应用区域标签设置为 'My WYSIWYG'。 config.applicationTitle = 'My WYSIWYG'; // 不添加应用区域标签。 config.applicationTitle = false;

实际项目中按编辑器实例分别配置的推荐写法：

<textarea id="editor1">...</textarea> <textarea id="editor2">...</textarea> <script> CKEDITOR.replace( 'editor1', { applicationTitle: '文章发布编辑器' } ); CKEDITOR.replace( 'editor2', { applicationTitle: '评论回复编辑器' } ); </script>

如果确实需要在全局config.js中设置，请确认页面中只有一个编辑器实例，或所有实例确实不需要被区分。仓库根目录的 config.js 是全局配置文件的示例位置。

四、底层实现：标签如何进入 DOM

applicationTitle的实际生效路径由主题加载函数loadTheme完成，见 core/creators/themedui.js。编辑器容器模板中与标签相关的片段为（themedui.js）：

role="application" ( editor.applicationTitle ? ' aria-labelledby="cke_{name}_arialbl"' : '' ) ( editor.applicationTitle ? '<span id="cke_{name}_arialbl" class="cke_voice_label">{voiceLabel}</span>' : '' )

模板渲染时把voiceLabel填为editor.applicationTitle（themedui.js）。最终生成的 DOM 结构是：

<div id="cke_editor1" class="cke cke_reset ..." role="application" aria-labelledby="cke_editor1_arialbl"> <span id="cke_editor1_arialbl" class="cke_voice_label">My WYSIWYG</span> ... </div>

其中：

role="application"声明容器角色；
aria-labelledby="cke_{name}_arialbl"引用隐藏的朗读标签；
<span id="cke_{name}_arialbl" class="cke_voice_label">是仅供屏幕阅读器朗读、视觉上不可见的标签元素，其中的文本就是editor.applicationTitle。

floatingspace 插件的对应实现

当编辑器使用floatingspace插件（inline 编辑器的浮动工具栏、或通过config.floatSpace启用的浮动 UI）时，同样的标签逻辑在 plugins/floatingspace/plugin.js 中被重复实现：浮动容器同样带role="application"、条件性的aria-labelledby与cke_voice_label朗读 span，voiceLabel同样取自editor.applicationTitle。因此，无论是经典主题化（themed UI）还是浮动空间（floating space），应用区域标签的定制行为保持一致。

与编辑器自身标签（title）的配合

applicationTitle描述的是应用区域，而config.title描述的是编辑器本身。在 iframe 型编辑器（wysiwygarea）中，编辑器的自身标签会体现在 iframe 的title属性与编辑文档<body>的aria-label上；在divarea中体现为可编辑区域的aria-label。applicationTitle与title可以独立配置、独立禁用，二者共同决定了屏幕阅读器朗读的完整信息。相关断言逻辑可参考 tests/core/creators/aria.js：测试中application标签期望值为lang.application + ', ' + editor.name，编辑器标签期望值为lang.editor + ', ' + editor.name。

测试验证要点

tests/core/editor/applicationtitle.js 通过 Bender 对上述行为做了自动化验证：

'test config.applicationTitle implies editor.applicationTitle'（L114-L123）：字符串配置直接映射为editor.applicationTitle；false、空字符串同样按配置生效；
'test editor.name implies editor.applicationTitle'（L125-L137）：未配置或配置非法值时，回退为基于editor.name的默认拼接；
'test voice label have properly set application title'（L139-L143）：页面中必须存在cke_{name}_arialbl朗读节点，且其文本与editor.applicationTitle完全一致（L158-L167）。

五、手动测试：themeduicustomlabels

仓库中的手动测试 tests/core/creators/manual/themeduicustomlabels.md 专门用于配合屏幕阅读器验证自定义标签后的朗读效果，覆盖 iframe 型（wysiwygarea）与 div 型（divarea）两种主题化编辑器。

测试元数据与准备

该测试文件头部声明了 Bender 运行所需的元数据：

@bender-tags: bug, 4.19.0, 2445 @bender-ui: collapsed @bender-ckeditor-plugins: toolbar, wysiwygarea, basicstyles, floatingspace

@bender-tags表明该测试针对 4.19.0 版本、issue #2445（即applicationTitle的引入）；
@bender-ui: collapsed表示 Bender 页面以折叠 UI 运行；
@bender-ckeditor-plugins列出测试所需的插件组合：toolbar（工具栏）、wysiwygarea（iframe 编辑器）、basicstyles（基础样式）、floatingspace（浮动空间）。

文件顶部特别标注：

NoteThis test is intended to be used with a screen reader.

即该测试必须配合真实屏幕阅读器进行人工验证，不能仅依赖自动化断言。

执行步骤与判定标准

操作步骤：

将焦点移入编辑器（Focus the editor）。

预期结果（Expected）：编辑器被正确朗读。

非预期结果（Unexpected）：编辑器被错误朗读，或完全没有被朗读。

不同编辑器形态的朗读样例

该测试针对两种主题化形态给出了主流屏幕阅读器的参考朗读结果，其中Horse / Donkey / Mouse / Snake 均为测试页面中配置的自定义标签占位值，用于验证自定义applicationTitle（与title）确实被读屏软件读出：

iframe 型编辑器（基于wysiwygarea，整个编辑器位于 iframe 中）：

屏幕阅读器组合	参考朗读样例
VoiceOver + Chrome	"Horse edit text,`<content and selection info>`. Horse, group"
NVDA + Firefox	"Mouse, Horse frame, Horse document editable"
JAWS + Firefox	"Mouse, Horse frame, Horse edit`<content>`type and text"

div 型编辑器（基于divarea，编辑区域渲染为 div）：

屏幕阅读器组合	参考朗读样例
VoiceOver + Chrome	"Donkey edit text`<content>`. Snake, application."
NVDA + Firefox	"Snake, Donkey edit multi line"
JAWS + Firefox	"Snake, Donkey edit, contains text, type and text"

可以看到，在两种形态下，自定义标签（Horse、Donkey、Snake、Mouse）都会出现在朗读结果的开头部分——这正是config.applicationTitle（对应应用区域标签，如 Snake/Mouse 所在的 role="application" 容器）与config.title（对应编辑器自身标签，如 Horse/Donkey）被屏幕阅读器实际消费的直接证据。

六、实际验证与调试建议

要复现本文档描述的行为并自行验证，可以按以下路径操作：

运行自动化测试：在仓库根目录通过 Bender 运行相关用例，重点观察applicationTitle的属性映射与cke_{name}_arialbl朗读节点的存在性：
- tests/core/editor/applicationtitle.js（属性与朗读节点断言）；
- tests/core/creators/aria.js（inline / divarea / wysiwygarea 三种创建方式下标签的启用与禁用断言）。
运行手动测试：在 Bender 中打开 tests/core/creators/manual/themeduicustomlabels.md，开启真实屏幕阅读器（VoiceOver、NVDA 或 JAWS），将焦点移入编辑器，对照上文"朗读样例"一节核验朗读文本中是否包含自定义标签。
直接检查 DOM：打开任意含编辑器的页面，在开发者工具中确认容器根节点：
- 存在role="application"；
- 设置了applicationTitle时存在aria-labelledby="cke_{name}_arialbl"与对应的.cke_voice_label隐藏 span，span 文本即应用区域标签；
- 未设置或设为false时，二者均不出现。

七、版本与兼容性说明

config.applicationTitle与editor.applicationTitle属性均为4.19.0 新增（见 core/editor.js 与 CHANGES.md）；
该配置同时作用于经典主题化 UI（core/creators/themedui.js）与浮动空间 UI（plugins/floatingspace/plugin.js）；
本仓库为 CKEditor 4 的当前源码仓库，上述实现与测试均可在仓库内直接查阅；若你的项目使用旧版本（4.19.0 之前），则该配置项不存在，需要升级后才能使用；
设置applicationTitle前请评估页面中的编辑器实例数量：多实例页面应避免全局统一标签或全局禁用，以免屏幕阅读器用户无法区分不同编辑器。