CKEditor 5 Font 字体功能包深度指南:字体家族、字号、字体颜色与背景色全解析 CKEditor 5 Font 字体功能包深度指南字体家族、字号、字体颜色与背景色全解析【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5本篇指南围绕 CKEditor 5 官方开源仓库中的ckeditor5-font功能包展开系统讲解字体家族Font Family、字号Font Size、字体颜色Font Color与背景色Font Background Color四大特性的配置、命令 API、模型与视图的转换原理以及粘贴兼容性策略。读完本文你将能够在自己的富文本编辑器项目中完整接入并深度定制这套字体样式能力同时理解其底层是如何基于span元素与格式化属性formatting attribute实现的。包概述ckeditor5-font是什么ckeditor5-font是 CKEditor 5 中负责文本外观样式的一组功能集合其 API 参考文档位于 packages/ckeditor5-font/docs/api/font.md。该包实现了以下四个相互独立、可单独启用的插件FontFamily字体家族FontSize字号FontColor字体颜色FontBackgroundColor背景色从源码结构看这四个功能被聚合在 Font 插件 中统一对外暴露Font.requires静态属性明确声明了它的依赖组合public static get requires(): PluginDependenciesOf[ FontFamily, FontSize, FontColor, FontBackgroundColor ] { return [ FontFamily, FontSize, FontColor, FontBackgroundColor ]; }也就是说当你引入Font插件时四个子功能会一并启用如果你只需要其中某一个也可以只引入对应的独立插件例如仅引入FontSize。在 Font 功能索引文档 中官方把这一组能力描述为使用不同字体家族、控制字号以及字体颜色与背景色对应的图标分别位于 ckeditor5-icons 主题目录如font-family.svg、font-size.svg、font-color.svg、font-background.svg。安装方式由于ckeditor5-font是开源聚合包open-source aggregate package的一部分安装只需引入主包npm install ckeditor5随后在编辑器中配置即可例如import { ClassicEditor } from ckeditor5; import { Font, FontFamily, FontSize, FontColor, FontBackgroundColor } from ckeditor5; ClassicEditor.create( document.querySelector( #editor ), { plugins: [ Font ], // 或按需引入 FontFamily、FontSize、FontColor、FontBackgroundColor toolbar: [ fontFamily, fontSize, fontColor, fontBackgroundColor ] } );各子包的独立package.json与元数据文件如 packages/ckeditor5-font/ckeditor5-metadata.json也一并发布在仓库中供构建工具解析插件依赖关系。插件与功能特性详解FontFamily字体家族FontFamily插件由 fontfamilyediting.ts 实现编辑能力fontfamilyui.ts负责工具栏下拉 UI。它在模型层引入fontFamily属性并在视图层渲染为内联span stylefont-family: ...元素。默认配置默认情况下编辑器注册 8 个字体选项外加一个 default 清除项定义于源码的默认配置块中{ options: [ default, Arial, Helvetica, sans-serif, Courier New, Courier, monospace, Georgia, serif, Lucida Sans Unicode, Lucida Grande, sans-serif, Tahoma, Geneva, sans-serif, Times New Roman, Times, serif, Trebuchet MS, Helvetica, sans-serif, Verdana, Geneva, sans-serif ], supportAllValues: false }每个选项由一个或多个逗号分隔的字体名组成第一个字体名作为下拉菜单中的展示标题。这里有一个值得注意的约定含空格的字体名不要加引号与 CSS 标准不同必要引号会在视图渲染时自动补上。例如配置中的Lucida Sans Unicode最终会渲染为span stylefont-family:Lucida Sans Unicode, Lucida Grande, sans-serif.../spandefault选项比较特殊它不会设置fontFamily属性而是移除选中文本上的该属性使文本回退到网页样式中定义的默认字体。配置选项fontFamily配置支持两种形式。最简单的写法是字符串数组如上面的默认配置也可以使用FontFamilyOption对象显式声明标题、模型值与视图定义const fontFamilyConfig { options: [ default, { title: Arial, model: arial, view: { name: span, styles: { font-family: Arial, Helvetica, sans-serif } } }, { title: Georgia, model: georgia, view: { name: span, styles: { font-family: Georgia, serif } } } ] };对应接口定义见 fontconfig.tstitle是用户可读标题model是模型中的唯一属性值view是视图元素定义upcastAlso是额外的视图到模型匹配规则。命令 API通过命令 API 可以直接以编程方式应用字体// 为当前选区应用 Arial 字体 editor.execute( fontFamily, { value: Arial } ); // 不带 value 执行命令将移除选区的 fontFamily 属性 editor.execute( fontFamily );supportAllValues粘贴内容兼容策略默认supportAllValues: false时编辑器会移除任何未在配置中声明的font-family值粘贴进来、无法识别的字体会被清除并回退到默认字体。若希望保留任意粘贴的字体值可以开启const fontFamilyConfig { supportAllValues: true };从 fontfamilyediting.ts 的实现可以看到开启后编辑器注册了任意值转换器downcast 方向把所有fontFamily模型属性渲染为font-family样式upcast 方向则用正则font-family: /.*/匹配任意span stylefont-family: ...内容从而保住所有字体值。此外还有一个兼容性转换器把旧式font face...标签的face属性转换为fontFamily属性L124-L139。FontSize字号FontSize插件由 fontsizeediting.ts 实现引入fontSize模型属性。默认配置使用命名预设{ options: [ tiny, small, default, big, huge ], supportAllValues: false }它定义了tiny、small、big、huge四个字号档位default表示不带fontSize属性的普通文本。这些预设会渲染为带 class 的span例如small输出span classtext-small.../span数值型字号预设之外字号也可以用数值Number或String定义此时视图输出会变为stylefont-size: ...const fontSizeConfig { options: [ 9, 10, 11, 12, 13, 14, 15 ] };数值选项同样可以自定义下拉标签const fontSizeConfig { options: [ { title: Small, model: 8px }, default, { title: Big, model: 14px } ] };命令 API// 为当前选区应用 tiny 字号 editor.execute( fontSize, { value: tiny } ); // 不带 value 执行命令将移除选区的 fontSize 属性 editor.execute( fontSize );supportAllValues 的硬性限制与字体家族类似字号也支持supportAllValues以保留任意粘贴字号但有一个硬性约束该选项只能配合数值型字号使用。若开启supportAllValues的同时仍配置了命名预设fontsizeediting.ts 会直接抛出font-size-invalid-use-of-named-presets错误。合法示例const fontSizeConfig { options: [ 9, 10, 11, 12, default, 14, 15 ], supportAllValues: true };此外源码中定义了一个从旧式font size..映射到 CSSfont-size关键字的对照表x-small、small、medium、large、x-large、xx-large、xxx-large支持相对尺寸如1、-2以默认大小 3 为基准换算并将值钳制在合法区间内L22-L32 与 L169-L202。FontColor字体颜色FontColor插件由 fontcolorediting.ts 实现在模型层引入fontColor属性视图层渲染为span stylecolor: ...。其 UI 由fontcolorui.ts提供内部通过 utils.ts 中的addColorSelectorToDropdown辅助函数挂载ColorSelectorView颜色选择器视图支持色板网格、文档颜色与取色器。colors色板定义默认色板注册 15 种颜色定义于源码默认配置块fontcolorediting.ts#L44-L109const fontColorConfig { colors: [ { color: hsl(0, 0%, 0%), label: Black }, { color: hsl(0, 0%, 30%), label: Dim grey }, { color: hsl(0, 0%, 60%), label: Grey }, { color: hsl(0, 0%, 90%), label: Light grey }, { color: hsl(0, 0%, 100%), label: White, hasBorder: true }, { color: hsl(0, 75%, 60%), label: Red }, { color: hsl(30, 75%, 60%), label: Orange }, { color: hsl(60, 75%, 60%), label: Yellow }, { color: hsl(90, 75%, 60%), label: Light green }, { color: hsl(120, 75%, 60%), label: Green }, { color: hsl(150, 75%, 60%), label: Aquamarine }, { color: hsl(180, 75%, 60%), label: Turquoise }, { color: hsl(210, 75%, 60%), label: Light blue }, { color: hsl(240, 75%, 60%), label: Blue }, { color: hsl(270, 75%, 60%), label: Purple } ] };颜色项既可以是字符串也可以是带color、label、hasBorder等字段的对象ColorOption。默认 5 列展示columns: 5。columns / documentColors / colorPickerFontColorConfig还支持三个关键配置详见 fontconfig.tscolumns颜色下拉的列数默认5。documentColors最多可显示的文档颜色数量即文档中出现过的颜色快捷区。默认继承columns的值设为0则完全禁用文档颜色区。几个典型组合未配置任何值文档颜色数 5继承自columns的默认值columns: 8文档颜色数自动变为 8columns: 8, documentColors: 24文档颜色数为 24显式覆盖columns: 8, documentColors: 0禁用文档颜色区。colorPicker取色器color picker配置支持ColorPickerConfig对象设为false时下拉中不出现取色器。const fontColorConfig { colors: [ { color: #000, label: Black }, { color: #fff, label: White, hasBorder: true } ], columns: 6, documentColors: 12, colorPicker: { format: hex } };命令 API 与旧标签兼容editor.execute( fontColor, { value: hsl(210, 75%, 60%) } ); editor.execute( fontColor ); // 移除颜色upcast 转换同时支持现代span stylecolor: ...与旧式font color..标签正则color: /^#?\w$/匹配downcast 统一输出color样式的spanfontcolorediting.ts#L111-L141。upcast 时颜色代码会被规范化去除空白字符见 utils.ts 的 normalizeColorCode。FontBackgroundColor背景色FontBackgroundColor与FontColor结构几乎完全对称配置同样复用FontColorConfigfontBackgroundColor配置键只是最终渲染为background-color样式const fontBackgroundColorConfig { colors: [ { color: hsl(60, 75%, 60%), label: Yellow }, { color: hsl(120, 75%, 60%), label: Green } ], columns: 5, documentColors: 10, colorPicker: false };底层渲染由 utils.ts 的 renderDowncastElement 统一完成——它根据传入的styleAttrcolor或background-color生成对应的样式输出因此两个功能共用一套转换与选择器逻辑。底层实现原理统一命令与格式化属性四个特性之所以行为一致是因为它们共享同一个抽象基类 FontCommand每个具体命令围绕一个attributeKey如fontFamily、fontSize、fontColor、fontBackgroundColor工作refresh()从当前选区读取该属性值并用model.schema.checkAttributeInSelection判断命令是否可用execute( { value } )处理两类情况光标折叠collapsed selection时通过setSelectionAttribute/removeSelectionAttribute设置或移除即将输入文本的属性非折叠选区则遍历schema.getValidRanges得到的合法范围批量setAttribute/removeAttribute支持传入batch参数把多次属性修改合并到同一个 undo 批次例如取色器连续拖拽调整颜色的场景实现一次撤销。所有属性在模型 schema 中都以相同的规则注册editor.model.schema.extend( $text, { allowAttributes: fontFamily } ); editor.model.schema.setAttributeProperties( fontFamily, { isFormatting: true, copyOnEnter: true } );isFormatting: true表明这些是纯格式化属性copyOnEnter: true表示回车换行时会复制到新段落继续生效。因此整体架构遵循 CKEditor 5 的经典模式模型属性model attribute → 双向转换器conversion → 视图span元素配合官方 schema 校验与撤销机制天然兼容复制粘贴、查找替换等编辑操作。配置速查配置键类型默认值说明fontFamily.optionsArraystring \| FontFamilyOption8 个常用字体 default下拉中的字体选项fontFamily.supportAllValuesbooleanfalse为true时保留任意粘贴的font-family值fontSize.optionsArraystring \| number \| FontSizeOption[tiny,small,default,big,huge]预设或数值字号fontSize.supportAllValuesbooleanfalse仅配合数值字号使用否则抛错fontColor.colors/fontBackgroundColor.colorsArraystring \| ColorOption15 种默认颜色色板定义fontColor.columns/fontBackgroundColor.columnsnumber5颜色网格列数fontColor.documentColors/fontBackgroundColor.documentColorsnumber继承columns文档颜色数量0禁用fontColor.colorPicker/fontBackgroundColor.colorPickerfalse \| ColorPickerConfig启用取色器false关闭深入阅读功能指南与在线演示见 docs/features/index.md 中关于 font 特性的条目功能演示由 docs/_snippets 下的 snippet 驱动配置接口完整定义packages/ckeditor5-font/src/fontconfig.ts各插件入口fontfamily.ts、fontsize.ts、fontcolor.ts、fontbackgroundcolor.ts、聚合插件 font.ts编辑层实现src/fontfamily/fontfamilyediting.ts、src/fontsize/fontsizeediting.ts、src/fontcolor/fontcolorediting.ts、src/fontbackgroundcolor/fontbackgroundcolorediting.tsUI 层实现src/fontfamily/fontfamilyui.ts、src/fontsize/fontsizeui.ts、src/fontcolor/fontcolorui.ts、src/fontbackgroundcolor/fontbackgroundcolorui.ts统一命令基类packages/ckeditor5-font/src/fontcommand.ts测试用例可参考 packages/ckeditor5-font/tests 目录下各特性的.js测试文件覆盖配置解析、命令行为与转换逻辑。【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考