CKEditor 5 字数统计与字符统计（Word Count）功能全解析：配置、容器注入与实时监听实战

CKEditor 5 字数统计与字符统计（Word Count）功能全解析：配置、容器注入与实时监听实战

【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5

Word Count（字数统计）是 CKEditor 5 中用于实时追踪编辑器内单词数与字符数的功能插件，它通过监听文档模型（Model）数据变化，将内容转为纯文本后按特定规则统计字数，帮助开发者控制内容篇幅、实现类似"120 字限制"的输入校验等场景。读完本文你将掌握该插件的完整配置项、两种容器注入方式、update事件与按需精确取值 API，并能用一套可运行的代码实现带字符上限的进度环效果。

功能概览与统计原理

Word Count 插件会统计编辑器中所有模型文本节点（ModelText）内的单词与字符数量，并提供两个可随时读取的响应式属性与一个自更新的 HTML 输出容器。其统计流程分为三步（实现位于 packages/ckeditor5-word-count/src/wordcount.ts）：

1. 通过_getText()遍历所有文档根（root），调用工具函数modelElementToPlainText()将模型数据转换为纯文本（实现见 packages/ckeditor5-word-count/src/utils.ts）。
2. 用正则表达式识别单词，得到words计数。
3. 去除纯文本中的换行符后按长度得到characters计数。

该功能在@ckeditor/ckeditor5-word-count包中实现，版本对应仓库当前发布版本（见 packages/ckeditor5-word-count/package.json）。从源码中的统计示例可以看出其精确规则：

单词识别依赖 Unicode 属性正则：当运行环境支持\p{L}（任意语言的字母）与\p{N}（任意脚本的数字）时使用/([\p{L}\p{N}]+\S?)+/gu，否则回退到/([a-zA-Z0-9À-ž]+\S?)+/gu（wordcount.ts），因此中文、日文、阿拉伯文等多语言内容也能被正确统计。

快速开始：安装与基础接入

首先按照 安装指南 完成编辑器集成，然后将WordCount加入插件列表（它不需要工具栏按钮，属无 UI 功能）：

import { ClassicEditor, WordCount } from 'ckeditor5'; ClassicEditor .create( { licenseKey: '<YOUR_LICENSE_KEY>', // 或 'GPL'。 plugins: [ WordCount, /* ... */ ], wordCount: { // 配置项见下文。 } } ) .then( /* ... */ ) .catch( /* ... */ );

提示：WordCount在源码中标为 premium 插件（isPremiumPlugin返回true，见 wordcount.ts），需要有效的商业许可证；评估或个人使用时也可使用'GPL'作为licenseKey。

官方 Demo 使用的页面结构非常简单——编辑器与统计容器是两个相互独立的div：

<div id="editor"> <p>Hello world.</p> </div> <div id="word-count"></div>

通过插件暴露的wordCountContainer属性拿到自更新容器并挂载到页面上：

ClassicEditor .create( { // 配置细节。 } ) .then( editor => { const wordCountPlugin = editor.plugins.get( 'WordCount' ); const wordCountWrapper = document.getElementById( 'word-count' ); wordCountWrapper.appendChild( wordCountPlugin.wordCountContainer ); } );

当你在编辑器中增删内容时，#word-count容器内的数字会实时变化。

配置容器：两种注入方式

wordCountContainer属性在首次访问时才会创建视图（View），多次访问返回同一个元素（源码见 wordcount.ts）。插件生成的默认输出结构如下：

<div class="ck ck-word-count"> <div class="ck-word-count__words">Words: %%</div> <div class="ck-word-count__characters">Characters: %%</div> </div>

除手动appendChild外，第二种方式是在初始化配置中通过config.wordCount.container指定一个页面元素，插件会在init()阶段自动把容器追加进去（见 wordcount.ts）：

ClassicEditor .create( { wordCount: { container: document.getElementById( 'container-for-word-count' ) } } );

如果你的页面布局不允许直接使用默认的Words:/Characters:文案结构，可以通过监听update事件完全自定义渲染方式（详见下文"实时监听"小节）。

配置项详解

插件的全部配置定义在 packages/ckeditor5-word-count/src/wordcountconfig.ts 的WordCountConfig接口中，并通过类型增强（augmentation.ts）注册到编辑器全局配置wordCount键下。

displayWords / displayCharacters：隐藏单个计数器

• config.wordCount.displayWords设为false时隐藏单词计数器，容器只保留字符部分：

<div class="ck ck-word-count"> <div class="ck-word-count__characters">Characters: 28</div> </div>

• config.wordCount.displayCharacters设为false时隐藏字符计数器，容器只保留单词部分：

<div class="ck ck-word-count"> <div class="ck-word-count__words">Words: 4</div> </div>

两个选项均默认开启（配置未定义时按显示处理）。注意容器视图在首次访问时构建，因此该配置需在创建编辑器时确定；隐藏选项只会影响wordCountContainer输出的 HTML，不影响words/characters属性与update事件的数值。

onUpdate：内容统计变化时执行回调

ClassicEditor .create( { // ... 其他配置 ... wordCount: { onUpdate: stats => { // 打印当前内容统计。 console.log( `Characters: ${ stats.characters }\nWords: ${ stats.words }` ); } } } ) .then( /* ... */ ) .catch( /* ... */ );

回调收到{ words, characters }对象。源码中该回调是通过监听插件自身的update事件转发的（wordcount.ts）。

注意：出于性能考虑，回调会被节流（throttle）触发，因此其中拿到的数值可能不是最新的。如果需要精确值，请直接访问WordCount#characters和WordCount#words属性——这两个属性在构造器中被定义为 getter，每次访问都会实时重新计算，不依赖节流事件（wordcount.ts），适合用于表单校验、提交前检查等场景。

实时监听：update 事件与按需精确取值

除config.wordCount.onUpdate外，也可以直接订阅插件的update事件：

editor.plugins.get( 'WordCount' ).on( 'update', ( evt, stats ) => { // 打印当前内容统计。 console.log( `Characters: ${ stats.characters }\nWords: ${ stats.words }` ); } );

从源码看，统计的刷新链路为：模型change:data事件 → 250ms 节流（throttle( ..., 250 )，见 wordcount.ts）→_refreshStats()重算words/characters并触发update事件。测试用例 packages/ckeditor5-word-count/tests/wordcount.js 中对此有明确验证：连续两次修改内容后等待约 300ms，update事件只触发一次（节流合并），且words、characters均为可观察（observable）属性，可通过change:words/change:characters事件订阅。

两者的适用场景：

• 节流后的update事件 /onUpdate：适合驱动进度环、字数提示等 UI，减少高频重绘。
• 直接访问words/characters属性：适合需要"此刻绝对准确"的判断，如发布前校验、后端提交。

另外，_getText()会遍历所有文档根并用换行分隔（wordcount.ts），这意味着该插件天然支持 多根编辑器（MultiRootEditor） 场景，多个根的内容会被合并统计。

实战：带 120 字符软限制的"发帖编辑器"

官方 Demo 展示了如何组合onUpdate、SVG 进度环与 CSS 类实现一个带字符上限的帖子编辑器。当内容接近或超过 120 字符时，进度环和背景会变色提示，超过上限时"发送"按钮被禁用。核心 JS 逻辑：

const maxCharacters = 120; const container = document.querySelector( '.demo-update' ); const progressCircle = document.querySelector( '.demo-update__chart__circle' ); const charactersBox = document.querySelector( '.demo-update__chart__characters' ); const wordsBox = document.querySelector( '.demo-update__words' ); const circleCircumference = Math.floor( 2 * Math.PI * progressCircle.getAttribute( 'r' ) ); const sendButton = document.querySelector( '.demo-update__send' ); BalloonEditor .create( { root: { element: document.querySelector( '#demo-update__editor' ) }, // 编辑器配置。 wordCount: { onUpdate: stats => { const charactersProgress = stats.characters / maxCharacters * circleCircumference; const isLimitExceeded = stats.characters > maxCharacters; const isCloseToLimit = !isLimitExceeded && stats.characters > maxCharacters * .8; const circleDashArray = Math.min( charactersProgress, circleCircumference ); // 根据已输入字符数设置进度环的描边长度。 progressCircle.setAttribute( 'stroke-dasharray', `${ circleDashArray },${ circleCircumference }` ); // 显示当前字符数；超限时显示"还需删掉多少个字符"。 if ( isLimitExceeded ) { charactersBox.textContent = `-${ stats.characters - maxCharacters }`; } else { charactersBox.textContent = stats.characters; } wordsBox.textContent = `Words in the post: ${ stats.words }`; // 接近上限时添加告警样式类。 container.classList.toggle( 'demo-update__limit-close', isCloseToLimit ); // 超过上限时添加超限样式类（背景变红）。 container.classList.toggle( 'demo-update__limit-exceeded', isLimitExceeded ); // 超过上限时禁用发送按钮。 sendButton.toggleAttribute( 'disabled', isLimitExceeded ); } } } );

配套的 HTML 结构与样式（进度环通过stroke-dasharray呈现比例，.demo-update__limit-close将环变为橙色，.demo-update__limit-exceeded将编辑区背景与环变为红色）：

<style> .demo-update { border: 1px solid var(--ck-color-base-border); border-radius: var(--ck-border-radius); box-shadow: 2px 2px 0px hsla( 0, 0%, 0%, 0.1 ); margin: 1.5em 0; padding: 1em; } .demo-update h3 { font-size: 18px; font-weight: bold; margin: 0 0 .5em; padding: 0; } .demo-update .ck.ck-editor__editable_inline { border: 1px solid hsla( 0, 0%, 0%, 0.15 ); transition: background .5s ease-out; min-height: 6em; margin-bottom: 1em; } .demo-update__controls { display: flex; flex-direction: row; align-items: center; } .demo-update__chart { margin-right: 1em; } .demo-update__chart__circle { transform: rotate(-90deg); transform-origin: center; } .demo-update__chart__characters { font-size: 13px; font-weight: bold; } .demo-update__words { flex-grow: 1; opacity: .5; } .demo-update__limit-close .demo-update__chart__circle { stroke: hsl( 30, 100%, 52% ); } .demo-update__limit-exceeded .ck.ck-editor__editable_inline { background: hsl( 0, 100%, 97% ); } .demo-update__limit-exceeded .demo-update__chart__circle { stroke: hsl( 0, 100%, 52% ); } .demo-update__limit-exceeded .demo-update__chart__characters { fill: hsl( 0, 100%, 52% ); } </style> <div class="demo-update"> <h3>Post editor with word count</h3> <div id="demo-update__editor"> <p>Tourists frequently admit that <a href="https://en.wikipedia.org/wiki/Taj_Mahal">Taj Mahal</a> "simply cannot be described with words".</p> </div> <div class="demo-update__controls"> <span class="demo-update__words"></span> <svg class="demo-update__chart" viewbox="0 0 40 40" width="40" height="40" xmlns="http://www.w3.org/2000/svg"> <circle stroke="hsl(0, 0%, 93%)" stroke-width="3" fill="none" cx="20" cy="20" r="17" /> <circle class="demo-update__chart__circle" stroke="hsl(202, 92%, 59%)" stroke-width="3" stroke-dasharray="134,534" stroke-linecap="round" fill="none" cx="20" cy="20" r="17" /> <text class="demo-update__chart__characters" x="50%" y="50%" dominant-baseline="central" text-anchor="middle"></text> </svg> <button type="button" class="demo-update__send">Send post</button> </div> </div>

这段代码可直接复用到你的项目中，将BalloonEditor换成其他编辑器类型（如ClassicEditor）同样适用。

Common API 速查

WordCount插件对外提供的核心 API 汇总如下（详见 packages/ckeditor5-word-count/src/wordcount.ts）：

此外，插件还导出了内部工具modelElementToPlainText()（以_modelElementToPlainText名义导出，见 packages/ckeditor5-word-count/src/index.ts），如需在自定义逻辑中复用"模型转纯文本"能力可以参考它。

相关功能

CKEditor 5 中与字数统计搭配使用效果更佳的生产力功能还包括：

• 拼写与语法检查：在输入过程中追踪并纠正可能的错误；
• 自动保存（Autosave）：自动保存内容，避免意外丢失；
• 自动格式化（Autoformat）：使用 Markdown 语法加速编辑流程；
• 自动文本替换（Autocorrect）：将预定义的输入片段自动转换为改进形式。

开发调试时，官方推荐使用 CKEditor 5 Inspector 查看编辑器内部数据模型、选区与命令状态，配合本文的update事件观察统计更新时机，可以更直观地理解节流行为。

小结

Word Count 是 CKEditor 5 中实现内容篇幅控制的基础功能：模型层统计逻辑（纯文本转换 + Unicode 正则分词 + 换行分隔）保证了多语言与多根文档场景下的准确性；wordCountContainer与config.wordCount.container两种注入方式覆盖了不同页面布局需求；update事件（250ms 节流）适合驱动 UI 反馈，而words/characters属性提供按需的精确取值。结合本文的 120 字符限制示例，你可以直接构建字数提示、字符上限校验、发布按钮禁用等完整的写作辅助体验。

【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5