★ FEATURED ARTICLE 前端UI组件【免费下载链接】ckeditor4The best enterprise-grade WYSIWYG editor. Fully customizable with countless features and plugins.项目地址https://gitcode.com/gh_mirrors/ck/ckeditor4点击查看免费下载CKEditor 4 从 4.9.0 起引入了imagebase插件它提供了一套可复用的图片部件image widget基础设施其中captionfeature 负责在图片下方渲染可编辑的figcaption说明文字。本指南围绕仓库中的手动测试用例 captiondisabled.md 展开讲解如何利用 CKEditor 4 的 Advanced Content FilterACF通过disallowedContent配置彻底禁用部件 caption并深入源码解释其底层生效机制最终给出可在真实项目中直接使用的配置方案与验证方法。读完本文你将掌握让部件永不显示 caption的标准做法并理解 ACF 对部件可编辑区域nested editable的约束方式。一、测试用例原文解读期望与验收标准仓库中的 captiondisabled.md 是一个 Bender 手动测试manual test用例它的任务定义如下测试标识bender-tags: 4.9.0, feature, 932关联 ticket #932bender-ui: collapsed测试插件集合sourcearea, wysiwygarea, toolbar, imagebase, link, htmlwriter, elementspath, basicstyles, easyimage测试主题Customizing caption existence with ACF通过 ACF 定制 caption 是否存在用例步骤与断言非常精简只有两步聚焦部件Focus widget。期望结果Expected没有任何 caption 出现。非期望结果Unexpected聚焦后 caption 显示出来。最后要求Repeat for all editors——即对页面中的每个编辑器实例classic、divarea逐一重复验证。该用例的完整配置从哪里来手动测试的步骤描述只占一半信息另一半藏在与之配套的 captiondisabled.html 中。HTML 文件才是真正给出配置的载体其核心片段如下div idclassic pWidget:/p figure img src../../../image2/_assets/foo.png altfoo /figure /divvar cfg { disallowedContent: figcaption, on: { pluginsLoaded: function( evt ) { var editor evt.editor, imageBase CKEDITOR.plugins.imagebase; imageBase.addImageWidget( editor, testWidget, imageBase.addFeature( editor, caption, {} ) ); } }, height: 270 }; CKEDITOR.replace( classic, cfg ); CKEDITOR.replace( divarea, CKEDITOR.tools.object.merge( cfg, { extraPlugins: divarea } ) );也就是说该用例故意给编辑器注入了disallowedContent: figcaption然后动态注册一个带captionfeature 的图片部件testWidget。页面中的figure原始内容没有figcaption子元素因此验收的关键点是即使部件被聚焦正常情况下聚焦一个空 caption 的图片部件会临时显示 caption 并出现占位符ACF 也应从根源上禁止figcaption使 caption 完全不出现。二、ACF 如何决定 caption 的存在性2.1 从disallowedContent说起CKEditor 4 的 Advanced Content Filter 负责控制编辑器内容中允许出现的元素与属性。disallowedContent配置用于裁剪默认允许的内容并且其优先级高于allowedContent规则。官方配置文档位于 core/filter.js原文说明为Disallowed content rules. They have precedence overallowedContentallowed content rules.因此disallowedContent: figcaption一经设置无论imagebase部件定义声明了多少关于figcaption的允许规则该元素都不会被编辑器保留或创建。2.2 caption feature 的两次 ACF 检查关键问题在于figcaption被禁后imagebase的 caption feature 在部件初始化阶段就应当自我禁用而不是等到聚焦时才去隐藏。这在 plugins/imagebase/plugin.js 的getCaptionFeature()实现中有两处明确证据第一处setUp阶段检查plugin.js L553-574setUp: function( editor ) { var listeners []; function listener( evt ) { var path evt.name blur ? editor.elementPath() : evt.data.path, sender path ? path.lastElement : null, widgets getWidgetsWithFeature( editor.widgets.instances, caption ); if ( !editor.filter.check( figcaption ) ) { return CKEDITOR.tools.array.forEach( listeners, function( listener ) { listener.removeListener(); } ); } // ... 否则为每个带 caption 的部件调用 _refreshCaption } listeners.push( editor.on( selectionChange, listener , null, null, 9 ) ); listeners.push( editor.on( blur, listener ) ); }editor.filter.check( figcaption )是 ACF 的运行时查询方法它询问当前过滤器中是否允许figcaption元素。在disallowedContent: figcaption生效的情况下该方法返回false于是监听器立即把自己从selectionChange/blur事件上全部移除——后续任何焦点变化都不会再触发 caption 的显示逻辑。第二处init阶段检查plugin.js L576-589init: function() { if ( !this.editor.filter.check( figcaption ) ) { return; } if ( !this.parts.caption ) { this.parts.caption createCaption( this ); } // ... }部件初始化时再次调用editor.filter.check( figcaption )。若返回false则直接return根本不会调用createCaption()去创建figcaption元素也不会注册 caption 这个 nested editable。这正是聚焦后 caption 永不出现的底层保证——caption 从 DOM 层面就不存在。2.3 部件基础定义中的对照什么情况下 caption 会被创建为了理解 2.2 的禁用效果有必要对照 caption 正常启用时的部件定义。createWidgetDefinition()生成的 image widget 基础定义plugin.js L643-695包含template: figure class{imageClass} img alt{alt} src{src} / figcaption{caption}/figcaption /figure, allowedContent: { img: { attributes: !src,alt,width,height }, figure: true, figcaption: true }, requiredContent: figure; img[!src], editables: { caption: { selector: figcaption, pathName: editor.lang.imagebase.pathNameCaption, allowedContent: br em strong sub sup u s; a[!href,target] } }可以看到正常状态下部件模板输出figcaptionallowedContent允许figure与figcaptioncaption 作为 nested editable 的允许内容为br em strong sub sup u s; a[!href,target]。而disallowedContent: figcaption会覆盖这一切——即使 upcast 时原始 HTML 中存在figcaptionACF 也会在数据进入编辑器时将其剥离。三、完整实战配置让图片部件彻底不显示 caption结合上文原理在真实项目中禁用 caption 有以下两种层次的做法。3.1 全局禁用直接配置disallowedContent最简单的方式是在创建编辑器时配置CKEDITOR.replace( editor1, { // 依赖 imagebase 的图片部件如 easyimage extraPlugins: imagebase, // 从 ACF 层面彻底禁止 figcaption disallowedContent: figcaption } );从源码结构看这一配置对所有依赖imagebase的图片部件都生效包括easyimage——因为 plugins/easyimage/plugin.js 在构建 easyimage 部件定义时就是通过同一套 API 装配的widgetDefinition CKEDITOR.plugins.imagebase.addFeature( editor, upload, widgetDefinition ); widgetDefinition CKEDITOR.plugins.imagebase.addFeature( editor, caption, widgetDefinition ); CKEDITOR.plugins.imagebase.addImageWidget( editor, WIDGET_NAME, widgetDefinition );因此禁用figcaption同样会让 Easy Image 部件失去 caption 能力这可以推断为该配置适用于所有基于 imagebase 的部件。3.2 动态注册部件时使用相同手法如果项目是像测试用例那样在运行时通过CKEDITOR.plugins.imagebase.addFeature( editor, caption, {} )动态注册部件只需保证注册前编辑器配置中已含disallowedContent: figcaption即可。注意addFeature的调用顺序setUp在注册阶段就会执行一次 ACF 检查所以配置必须在pluginsLoaded或更早的阶段就绪否则监听器可能已经挂上需要后续由init的检查兜底init也会直接 return部件依然不会创建 caption两种检查互为保险。3.3 可选的 UI 行为定制聚焦时显示、失焦时隐藏若需求并非彻底禁用而是希望保留figcaption但控制其可见性空 caption 时隐藏、聚焦时显示占位符则不应使用disallowedContent而应依赖 caption feature 默认的可见性切换逻辑。其行为由_refreshCaptionplugin.js L599-616与样式表 plugins/imagebase/styles/imagebase.css 配合实现[data-cke-caption-hidden] { display: none; } [data-cke-caption-placeholder]::before { display: inline; color: rgba( 0, 0, 0, .4 ); content: attr(>tests[ test integration with ACF ] function() { bender.editorBot.create( { name: acf_integration, config: { disallowedContent: figcaption } }, function( bot ) { var editor bot.editor; addTestWidget( editor ); bot.setData( getFixture( toggleOneEmpty ), function() { assert.isFalse( !!widgetTestsTools.getWidgetByDOMOffset( editor, 0 ).parts.caption, Caption presence ); } ); } ); };该测试先用disallowedContent: figcaption创建编辑器并注册带 caption feature 的testWidget然后加载一个包含空 caption 的部件作为 fixture最终断言widget.parts.caption不存在assert.isFalse。这正是caption 被 ACF 禁用后部件不再持有 caption part的直接证据与手动用例的预期行为完全一致。同文件中的其他用例caption.js L228-248还覆盖了另一种相关场景当输入 HTML本身就没有figcaption时upcast 后的部件会自动补建一个 captioncreateCaption逻辑这也反向说明只有 ACF 层面禁止figcaption才能真正阻止 caption 的无中生有。五、注意事项与边界disallowedContent优先级最高它作用于编辑器全局过滤器会覆盖部件allowedContent中关于figcaption的声明参见 core/filter.js。这与extraAllowedContent增量允许是相反方向的配置不应混用。两处 ACF 检查互为保障setUp中的检查负责拆掉监听器init中的检查负责不创建元素。即使部件注册时序稍有不同init的editor.filter.check( figcaption )依然能保证 caption 不会出现这是测试用例断言能够稳定的原因。对已有内容的剥离行为若编辑器已有内容中包含figcaption例如从其他来源粘贴或setData在disallowedContent: figcaption下该元素会被 ACF 在数据处理阶段剥离因此 caption 文字也会一并丢失。这是彻底禁用的必然代价适用于明确不需要图片说明文字的场景。占位符与隐藏逻辑不适用禁用后CSS 中的data-cke-caption-hidden/data-cke-caption-placeholder相关样式与_refreshCaption逻辑都不会再被执行因为监听器与 caption 元素均已不存在。版本前提caption feature 与addFeature/addImageWidgetAPI 自 CKEditor 4.9.0 引入见 plugins/imagebase/plugin.js 中since 4.9.0标注本文所有配置与断言均以仓库当前源码为准。六、小结围绕 captiondisabled.md 这一手动用例可以总结出一条清晰的定制链路disallowedContent: figcaption→ ACF 拒绝该元素 → caption feature 的setUp/init两处editor.filter.check( figcaption )检查全部短路 → 部件不再创建figcaption、不再挂载 caption 可编辑区、不再响应焦点事件 → 无论聚焦与否caption 都不存在。配套的自动化测试 caption.js 用widget.parts.caption是否为空给出了可机器执行的验收标准。这套机制同时适用于easyimage等所有基于imagebase的图片部件是 CKEditor 4 中控制图片说明文字存在性的标准做法。赞分享前端UI组件【免费下载链接】ckeditor4The best enterprise-grade WYSIWYG editor. Fully customizable with countless features and plugins.项目地址https://gitcode.com/gh_mirrors/ck/ckeditor4点击查看免费下载相关推荐CKEditor 4 imagebase 插件剪切粘贴后图片 caption 占位符可见性修复1592解析与验证CKEditor 4 imagebase 插件剪切粘贴后图片 caption 占位符可见性修复 1592解析与验证 本篇文章以仓库中的手工测试用例 cap前端UI组件CKEditor 4 图片小部件题注 ACF 定制实战从手动测试到源码原理CKEditor 4 图片小部件题注 ACF 定制实战从手动测试到源码原理 导读 本文围绕 CKEditor 4 仓库中 tests/plugins/imag前端UI组件CKEditor 4 禁用内置图片拖放处理clipboard_handleImages 配置与第三方插件接管实战CKEditor 4 禁用内置图片拖放处理 clipboard_handleImages 配置与第三方插件接管实战 本文围绕 CKEditor 4当前仓库前端UI组件上一篇Hologram与Docker集成如何在容器化环境中安全使用AWS凭证的完整指南下一篇swiftScan实战教程轻松实现微信/QQ风格的扫码界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
)
