CKEditor 5 图片缩放完整指南ImageResize 插件配置、交互方式与底层实现解析【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5图片缩放Image resize是 CKEditor 5 富文本编辑器中最常用的图片功能之一它允许用户直接在编辑器中改变图片宽度从而让图文混排更加自然。本文以ckeditor/ckeditor5-image包中的ImageResize插件为主线系统讲解其三种交互方式拖拽缩放手柄、下拉菜单、独立按钮的配置方法、百分比与像素两种单位的选择、缩放后 HTML 标记与 CSS 的配合方式并结合仓库源码剖析ImageResizeEditing、ImageResizeHandles、ImageResizeButtons以及resizeImage命令的底层实现。读完本文你将能够独立完成 CKEditor 5 图片缩放的完整配置、样式定制与命令调用。功能概览谁在实现图片缩放图片缩放功能由 imageresize.ts 中定义的ImageResize插件实现它是一个组合插件通过requires声明聚合了四个子能力ImageResizeEditing负责数据层注册resizedWidth、resizedHeight模型属性并注册resizeImage命令ImageResizeHandles负责在选中图片的四角渲染拖拽手柄resize handlesImageResizeButtons负责在图片工具栏中渲染缩放下拉菜单或独立按钮ImageCustomResizeUI当配置了value: custom的选项时提供自定义尺寸输入表单balloon。从源码看ImageResizeButtons 内部又依赖ImageResizeEditing并读取config.image.resizeOptions与config.image.resizeUnit来生成 UI 组件而 ImageResizeEditing 在init()中同时为imageBlock与imageInline两种图片模型注册转换器和resizeImage命令同时保留了旧名称imageResize作为向后兼容别名。三种图片缩放交互方式编辑器提供了三种调整图片大小的方式可以按需组合使用。使用拖拽手柄Resize Handles这是最直观的方式启用ImageResize插件后选中图片会出现四个角的方形手柄用户直接拖拽即可改变图片宽度无需任何额外配置。启用方式有两种方式一直接安装ImageResize插件它包含全部所需子能力import { ClassicEditor, Image, ImageResize } from ckeditor5; ClassicEditor .create( { // ... 其他配置 ... plugins: [ Image, ImageResize, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );方式二只安装ImageResizeEditing与ImageResizeHandles的组合这样不会加载不需要的ImageResizeButtons插件包体积更小import { ClassicEditor, Image, ImageResizeEditing, ImageResizeHandles } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // 或者 GPL。 plugins: [ Image, ImageResizeEditing, ImageResizeHandles, /* ... */ ], image: { // 配置。 } } ) .then( /* ... */ ) .catch( /* ... */ );两种方式默认都会启用拖拽手柄。拖拽到手柄后可以结合图片工具栏中的对齐选项object-center.svg 对应的对齐按钮实现图文混排效果。提示本指南中的示例为了清晰起见只启用了少量功能完整功能可参考 完整功能编辑器示例。使用缩放下拉菜单Resize Dropdown如果你希望用户从一组预定义尺寸中选择可以把这些选项放入图片工具栏的下拉菜单中。配置分为两步先在image.resizeOptions中定义可用选项再把resizeImage按钮加入图片工具栏const imageConfiguration { resizeOptions: [ { name: resizeImage:original, value: null, label: Original }, { name: resizeImage:custom, label: Custom, value: custom }, { name: resizeImage:40, value: 40, label: 40% }, { name: resizeImage:60, value: 60, label: 60% } ], toolbar: [ resizeImage, /* ... */ ] }关键点说明每个选项的name是注册到编辑器组件工厂component factory中的组件名对于下拉菜单只需在image.toolbar中写一个resizeImage即可下拉列表会自动包含resizeOptions中定义的全部选项value: null的选项用于将图片恢复为原始尺寸name中的:original后缀并非强制约定但必须与后续工具栏配置保持一致value: custom的选项配合ImageCustomResizeUI会弹出一个允许用户输入任意宽度的表单。提示如果想限定图片的宽高比例如允许插入 1:1 且宽度为 40% 的图片应使用 图片样式功能关于用 CSS 固定宽高比的示例见本文“使用像素值”一节末尾。使用独立缩放按钮Standalone Resize Buttons与下拉菜单不同独立按钮把每个缩放选项直接平铺在图片工具栏中用户一次点击即可完成缩放交互路径最短。配置时需要为每个选项额外指定icon属性可用值small、medium、large、original、customconst imageConfiguration { resizeOptions: [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ], toolbar: [ resizeImage:50, resizeImage:75, resizeImage:original, resizeImage:custom, // 更多工具栏选项。 // ... ] }注意独立按钮模式下image.toolbar中必须按名称逐一列出每个选项按钮resizeImage:50等而不是只写一个resizeImage。在源码中imageresizebuttons.ts 会对每个选项调用editor.ui.componentFactory.add( name, ... )注册独立按钮并且必须提供合法的icon否则会抛出imageresizebuttons-missing-icon错误。默认的缩放选项如果不做任何resizeOptions配置ImageResizeEditing 的构造函数会注册如下默认选项resizeOptions [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:25, value: 25, icon: small }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ];对应的resizeUnit默认为%。也就是说默认配置下用户可以通过独立按钮将图片宽度设为 25%、50%、75% 或原始尺寸。禁用拖拽手柄只保留按钮交互如果希望用户只能通过按钮下拉菜单或独立按钮缩放图片而不允许拖拽手柄只需在插件列表中省略ImageResizeHandles改为只加载ImageResizeEditing和ImageResizeButtonsimport { ClassicEditor, Image, ImageResizeButtons, ImageResizeEditing, ImageToolbar } from ckeditor5; ClassicEditor .create( { plugins: [ Image, ImageResizeEditing, ImageResizeButtons, ImageToolbar, /* ... */ ], image: { resizeOptions: [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ], toolbar: [ resizeImage:50, resizeImage:75, resizeImage:original, resizeImage:custom, // 更多工具栏选项。 // ... ] } } ) .then( /* ... */ ) .catch( /* ... */ );也就是说插件列表plugins: [ ImageResizeEditing, ImageResizeButtons, ... ]与plugins: [ ImageResize, ... ]的差别在于前者不包含手柄交互缩放功能只能通过所选 UI下拉菜单或独立按钮触发。缩放后的标记与样式Markup and Styling缩放图片时编辑器使用内联width样式记录宽度并给figure元素添加image_resized类figure classimage image_resized stylewidth: 75%; img src... alt... /figureimage_resized类的作用是禁用图片样式image styles施加的max-width。例如“侧边图片side image”样式定义如下.ck-content .image-style-side { max-width: 50%; float: right; margin-left: var(--ck-image-style-spacing); }其max-width会被下面的规则覆盖.ck-content .image.image_resized { max-width: 100%; }另一个需要注意的样式问题是默认情况下 CKEditor 5 对figure classimage使用display: table以便让figure的尺寸跟随内部img。但部分浏览器不支持在display: table的元素上同时生效max-width与width因此缩放图片时必须改用display: block.ck-content .image.image_resized { display: block; box-sizing: border-box; } .ck-content .image.image_resized img { width: 100%; } .ck-content .image.image_resized figcaption { display: block; }从源码角度看ImageResizeEditing 的下转换器 在模型属性resizedWidth变化时向视图写入width样式并增删image_resized类其上转换器upcastimageresizeediting.ts在解析既有内容时只有当width与height不同时存在时才将其还原为resizedWidth模型属性避免破坏同时设置了宽高的原始图片。使用像素值代替百分比宽度默认使用百分比宽度resizeUnit: %的最大好处是响应式图片宽度跟随内容容器宽度变化。例如用户在编辑器中把图片设为 60% 宽无论发布页面的布局宽度如何变化图片始终占据内容区的 60%而如果使用像素值一旦网站更换了新的页面布局固定像素的图片就可能过宽或过窄。但在某些场景下例如精确控制版式像素值是更好的选择。通过设置config.image.resizeUnit即可切换ClassicEditor .create( { image: { resizeUnit: px, resizeOptions: [ { name: resizeImage:original, label: Original, value: null }, { name: resizeImage:custom, label: Custom, value: custom }, { name: resizeImage:100, label: 100px, value: 100 }, { name: resizeImage:200, label: 200px, value: 200 } ] } } ) .then( /* ... */ ) .catch( /* ... */ );关于resizeUnit与resizeOptions的组合规则imageconfig.ts 中明确说明resizeUnit仅支持px或%两个取值默认%它会与resizeOptions中每个选项的value拼接成最终宽度的字符串例如value: 50resizeUnit: %渲染为50%并用于 UI 标签与命令参数。这一拼接逻辑同样体现在 imageresizebuttons.ts 中下拉菜单项会把每个选项序列化为value resizeUnit。固定宽高比示例CSS如果希望在像素模式下图片自动保持固定宽高比例如 200px 宽的图片自动获得相同的高度可以借助 CSS 让图片以绝对定位填满一个由::before撑开的方形容器.ck.ck-content .image { position: relative; } .ck.ck-content .image img { position: absolute; left: 0; top: 0; width: 100%; height: 100%; object-fit: cover; border-radius: 50%; } .ck.ck-content .image::before { content: ; padding-top: 100%; display: block; }上面的示例同时展示了把图片裁剪为圆形border-radius: 50%object-fit: cover的做法。底层实现resizeImage 命令与数据模型无论用户通过哪种 UI 触发缩放最终都会执行 ResizeImageCommand 中的resizeImage命令refresh()通过ImageUtils.getClosestSelectedImageElement()判断当前选区是否命中图片未选中图片时命令不可用isEnabled false。当图片带有resizedWidth属性时命令的value形如{ width: 50%, height: null }execute( { width } )在模型中写入resizedWidth属性、移除resizedHeight并调用imageUtils.setImageNaturalSizeAttributes()记录图片的自然尺寸。命令的典型用法// 将图片宽度设为 50% editor.execute( resizeImage, { width: 50% } ); // 移除宽度属性恢复原始尺寸 editor.execute( resizeImage, { width: null } );在模型层面ImageResizeEditing 会为imageBlock与imageInline两种元素扩展resizedWidth、resizedHeight两个可格式化属性isFormatting: true这正是“缩放属于格式化操作、可被撤销”的底层依据。与图片优化及响应式图片的结合当配合 CKBox 文件管理器使用时服务端会生成多组缩放与优化后的图片副本用户可按需选用。关于图片响应式srcset、sizes的详细用法可参考 响应式图片指南。安装与常见 API启用完整缩放功能只需安装ImageResize插件包含ImageResizeEditing、ImageResizeHandles、ImageResizeButtons全部子能力import { ClassicEditor, Image, ImageResize } from ckeditor5; ClassicEditor .create( { // ... 其他配置选项 ... plugins: [ Image, ImageResize, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );ImageResize插件注册的公共 API 包括缩放按钮供 图片上下文工具栏 使用的resizeImage下拉按钮以及各resizeImage:name独立按钮resizeImage命令旧名imageResize源码中注册了别名以向后兼容接受目标宽度作为参数详见上文命令用法。开发调试建议配合官方的 CKEditor 5 Inspector 使用它可以实时展示编辑器内部的数据结构、选区、命令状态等信息。【免费下载链接】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），仅供参考
CKEditor 5 图片缩放完整指南ImageResize 插件配置、交互方式与底层实现解析【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5图片缩放Image resize是 CKEditor 5 富文本编辑器中最常用的图片功能之一它允许用户直接在编辑器中改变图片宽度从而让图文混排更加自然。本文以ckeditor/ckeditor5-image包中的ImageResize插件为主线系统讲解其三种交互方式拖拽缩放手柄、下拉菜单、独立按钮的配置方法、百分比与像素两种单位的选择、缩放后 HTML 标记与 CSS 的配合方式并结合仓库源码剖析ImageResizeEditing、ImageResizeHandles、ImageResizeButtons以及resizeImage命令的底层实现。读完本文你将能够独立完成 CKEditor 5 图片缩放的完整配置、样式定制与命令调用。功能概览谁在实现图片缩放图片缩放功能由 imageresize.ts 中定义的ImageResize插件实现它是一个组合插件通过requires声明聚合了四个子能力ImageResizeEditing负责数据层注册resizedWidth、resizedHeight模型属性并注册resizeImage命令ImageResizeHandles负责在选中图片的四角渲染拖拽手柄resize handlesImageResizeButtons负责在图片工具栏中渲染缩放下拉菜单或独立按钮ImageCustomResizeUI当配置了value: custom的选项时提供自定义尺寸输入表单balloon。从源码看ImageResizeButtons 内部又依赖ImageResizeEditing并读取config.image.resizeOptions与config.image.resizeUnit来生成 UI 组件而 ImageResizeEditing 在init()中同时为imageBlock与imageInline两种图片模型注册转换器和resizeImage命令同时保留了旧名称imageResize作为向后兼容别名。三种图片缩放交互方式编辑器提供了三种调整图片大小的方式可以按需组合使用。使用拖拽手柄Resize Handles这是最直观的方式启用ImageResize插件后选中图片会出现四个角的方形手柄用户直接拖拽即可改变图片宽度无需任何额外配置。启用方式有两种方式一直接安装ImageResize插件它包含全部所需子能力import { ClassicEditor, Image, ImageResize } from ckeditor5; ClassicEditor .create( { // ... 其他配置 ... plugins: [ Image, ImageResize, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );方式二只安装ImageResizeEditing与ImageResizeHandles的组合这样不会加载不需要的ImageResizeButtons插件包体积更小import { ClassicEditor, Image, ImageResizeEditing, ImageResizeHandles } from ckeditor5; ClassicEditor .create( { licenseKey: YOUR_LICENSE_KEY, // 或者 GPL。 plugins: [ Image, ImageResizeEditing, ImageResizeHandles, /* ... */ ], image: { // 配置。 } } ) .then( /* ... */ ) .catch( /* ... */ );两种方式默认都会启用拖拽手柄。拖拽到手柄后可以结合图片工具栏中的对齐选项object-center.svg 对应的对齐按钮实现图文混排效果。提示本指南中的示例为了清晰起见只启用了少量功能完整功能可参考 完整功能编辑器示例。使用缩放下拉菜单Resize Dropdown如果你希望用户从一组预定义尺寸中选择可以把这些选项放入图片工具栏的下拉菜单中。配置分为两步先在image.resizeOptions中定义可用选项再把resizeImage按钮加入图片工具栏const imageConfiguration { resizeOptions: [ { name: resizeImage:original, value: null, label: Original }, { name: resizeImage:custom, label: Custom, value: custom }, { name: resizeImage:40, value: 40, label: 40% }, { name: resizeImage:60, value: 60, label: 60% } ], toolbar: [ resizeImage, /* ... */ ] }关键点说明每个选项的name是注册到编辑器组件工厂component factory中的组件名对于下拉菜单只需在image.toolbar中写一个resizeImage即可下拉列表会自动包含resizeOptions中定义的全部选项value: null的选项用于将图片恢复为原始尺寸name中的:original后缀并非强制约定但必须与后续工具栏配置保持一致value: custom的选项配合ImageCustomResizeUI会弹出一个允许用户输入任意宽度的表单。提示如果想限定图片的宽高比例如允许插入 1:1 且宽度为 40% 的图片应使用 图片样式功能关于用 CSS 固定宽高比的示例见本文“使用像素值”一节末尾。使用独立缩放按钮Standalone Resize Buttons与下拉菜单不同独立按钮把每个缩放选项直接平铺在图片工具栏中用户一次点击即可完成缩放交互路径最短。配置时需要为每个选项额外指定icon属性可用值small、medium、large、original、customconst imageConfiguration { resizeOptions: [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ], toolbar: [ resizeImage:50, resizeImage:75, resizeImage:original, resizeImage:custom, // 更多工具栏选项。 // ... ] }注意独立按钮模式下image.toolbar中必须按名称逐一列出每个选项按钮resizeImage:50等而不是只写一个resizeImage。在源码中imageresizebuttons.ts 会对每个选项调用editor.ui.componentFactory.add( name, ... )注册独立按钮并且必须提供合法的icon否则会抛出imageresizebuttons-missing-icon错误。默认的缩放选项如果不做任何resizeOptions配置ImageResizeEditing 的构造函数会注册如下默认选项resizeOptions [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:25, value: 25, icon: small }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ];对应的resizeUnit默认为%。也就是说默认配置下用户可以通过独立按钮将图片宽度设为 25%、50%、75% 或原始尺寸。禁用拖拽手柄只保留按钮交互如果希望用户只能通过按钮下拉菜单或独立按钮缩放图片而不允许拖拽手柄只需在插件列表中省略ImageResizeHandles改为只加载ImageResizeEditing和ImageResizeButtonsimport { ClassicEditor, Image, ImageResizeButtons, ImageResizeEditing, ImageToolbar } from ckeditor5; ClassicEditor .create( { plugins: [ Image, ImageResizeEditing, ImageResizeButtons, ImageToolbar, /* ... */ ], image: { resizeOptions: [ { name: resizeImage:original, value: null, icon: original }, { name: resizeImage:custom, value: custom, icon: custom }, { name: resizeImage:50, value: 50, icon: medium }, { name: resizeImage:75, value: 75, icon: large } ], toolbar: [ resizeImage:50, resizeImage:75, resizeImage:original, resizeImage:custom, // 更多工具栏选项。 // ... ] } } ) .then( /* ... */ ) .catch( /* ... */ );也就是说插件列表plugins: [ ImageResizeEditing, ImageResizeButtons, ... ]与plugins: [ ImageResize, ... ]的差别在于前者不包含手柄交互缩放功能只能通过所选 UI下拉菜单或独立按钮触发。缩放后的标记与样式Markup and Styling缩放图片时编辑器使用内联width样式记录宽度并给figure元素添加image_resized类figure classimage image_resized stylewidth: 75%; img src... alt... /figureimage_resized类的作用是禁用图片样式image styles施加的max-width。例如“侧边图片side image”样式定义如下.ck-content .image-style-side { max-width: 50%; float: right; margin-left: var(--ck-image-style-spacing); }其max-width会被下面的规则覆盖.ck-content .image.image_resized { max-width: 100%; }另一个需要注意的样式问题是默认情况下 CKEditor 5 对figure classimage使用display: table以便让figure的尺寸跟随内部img。但部分浏览器不支持在display: table的元素上同时生效max-width与width因此缩放图片时必须改用display: block.ck-content .image.image_resized { display: block; box-sizing: border-box; } .ck-content .image.image_resized img { width: 100%; } .ck-content .image.image_resized figcaption { display: block; }从源码角度看ImageResizeEditing 的下转换器 在模型属性resizedWidth变化时向视图写入width样式并增删image_resized类其上转换器upcastimageresizeediting.ts在解析既有内容时只有当width与height不同时存在时才将其还原为resizedWidth模型属性避免破坏同时设置了宽高的原始图片。使用像素值代替百分比宽度默认使用百分比宽度resizeUnit: %的最大好处是响应式图片宽度跟随内容容器宽度变化。例如用户在编辑器中把图片设为 60% 宽无论发布页面的布局宽度如何变化图片始终占据内容区的 60%而如果使用像素值一旦网站更换了新的页面布局固定像素的图片就可能过宽或过窄。但在某些场景下例如精确控制版式像素值是更好的选择。通过设置config.image.resizeUnit即可切换ClassicEditor .create( { image: { resizeUnit: px, resizeOptions: [ { name: resizeImage:original, label: Original, value: null }, { name: resizeImage:custom, label: Custom, value: custom }, { name: resizeImage:100, label: 100px, value: 100 }, { name: resizeImage:200, label: 200px, value: 200 } ] } } ) .then( /* ... */ ) .catch( /* ... */ );关于resizeUnit与resizeOptions的组合规则imageconfig.ts 中明确说明resizeUnit仅支持px或%两个取值默认%它会与resizeOptions中每个选项的value拼接成最终宽度的字符串例如value: 50resizeUnit: %渲染为50%并用于 UI 标签与命令参数。这一拼接逻辑同样体现在 imageresizebuttons.ts 中下拉菜单项会把每个选项序列化为value resizeUnit。固定宽高比示例CSS如果希望在像素模式下图片自动保持固定宽高比例如 200px 宽的图片自动获得相同的高度可以借助 CSS 让图片以绝对定位填满一个由::before撑开的方形容器.ck.ck-content .image { position: relative; } .ck.ck-content .image img { position: absolute; left: 0; top: 0; width: 100%; height: 100%; object-fit: cover; border-radius: 50%; } .ck.ck-content .image::before { content: ; padding-top: 100%; display: block; }上面的示例同时展示了把图片裁剪为圆形border-radius: 50%object-fit: cover的做法。底层实现resizeImage 命令与数据模型无论用户通过哪种 UI 触发缩放最终都会执行 ResizeImageCommand 中的resizeImage命令refresh()通过ImageUtils.getClosestSelectedImageElement()判断当前选区是否命中图片未选中图片时命令不可用isEnabled false。当图片带有resizedWidth属性时命令的value形如{ width: 50%, height: null }execute( { width } )在模型中写入resizedWidth属性、移除resizedHeight并调用imageUtils.setImageNaturalSizeAttributes()记录图片的自然尺寸。命令的典型用法// 将图片宽度设为 50% editor.execute( resizeImage, { width: 50% } ); // 移除宽度属性恢复原始尺寸 editor.execute( resizeImage, { width: null } );在模型层面ImageResizeEditing 会为imageBlock与imageInline两种元素扩展resizedWidth、resizedHeight两个可格式化属性isFormatting: true这正是“缩放属于格式化操作、可被撤销”的底层依据。与图片优化及响应式图片的结合当配合 CKBox 文件管理器使用时服务端会生成多组缩放与优化后的图片副本用户可按需选用。关于图片响应式srcset、sizes的详细用法可参考 响应式图片指南。安装与常见 API启用完整缩放功能只需安装ImageResize插件包含ImageResizeEditing、ImageResizeHandles、ImageResizeButtons全部子能力import { ClassicEditor, Image, ImageResize } from ckeditor5; ClassicEditor .create( { // ... 其他配置选项 ... plugins: [ Image, ImageResize, /* ... */ ] } ) .then( /* ... */ ) .catch( /* ... */ );ImageResize插件注册的公共 API 包括缩放按钮供 图片上下文工具栏 使用的resizeImage下拉按钮以及各resizeImage:name独立按钮resizeImage命令旧名imageResize源码中注册了别名以向后兼容接受目标宽度作为参数详见上文命令用法。开发调试建议配合官方的 CKEditor 5 Inspector 使用它可以实时展示编辑器内部的数据结构、选区、命令状态等信息。【免费下载链接】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），仅供参考
