wangEditor 5 编辑器包wangeditor/editor实战指南开箱即用的 Web 富文本编辑器【免费下载链接】wangEditorwangEditor, open-source Web rich text editor 开源 Web 富文本编辑器项目地址: https://gitcode.com/gh_mirrors/wa/wangEditor导读本文以 wangEditor 仓库中 packages/editor 包npm 名wangeditor/editor为核心讲解这个开箱即用、配置简单的 Web 富文本编辑器在 JS / Vue / React 项目中的接入方式、createEditor/createToolbar核心 API、Boot全局注册机制以及内置模块、默认配置、多语言、示例与测试的组织方式。读完本文你将掌握如何在任意前端技术栈中快速创建带工具栏的编辑器、如何切换默认/简洁两种模式、如何通过全局配置定制菜单与行为以及如何在源码层面深入二次开发。一、包定位从源码包到开箱即用的编辑器在 wangEditor 的 monorepolerna 管理结构中packages/editor是面向最终使用者的聚合入口包。它不重复实现编辑器内核而是把底层能力组装成开箱即用的完整产品。它的名字和产物如下见 packages/editor/package.json包名wangeditor/editor当前版本5.1.23描述Web rich text editor, Web 富文本编辑器入口main: dist/index.jsCommonJS、module: dist/index.esm.jsES Module类型声明dist/editor/src/index.d.ts依赖wangeditor/core内核、wangeditor/basic-modules基础模块、wangeditor/list-module、wangeditor/table-module、wangeditor/video-module、wangeditor/upload-image-module、wangeditor/code-highlight等全部功能模块以及slate、snabbdom、dom7等底层库许可证MIT官方定位的一句话在 packages/editor/README.md 中写得很明确开源 Web 富文本编辑器开箱即用配置简单支持 JS / Vue / React。也就是说无论你用的是原生 JS、Vue 2/3 还是 React安装这一个包即可获得完整编辑能力无需手动组装各个模块。从 packages/editor/src/index.ts 的入口代码可以看到它做了四件关键的事引入样式自身assets/index.less与内核wangeditor/core/dist/css/style.css执行浏览器/Node 环境的 polyfill./utils/browser-polyfill、./utils/node-polyfill保证兼容性加载多语言资源、注册内置模块、初始化默认配置导出Boot、core API、slate API 以及createEditor/createToolbar工厂函数。正是这种入口即装配的设计让使用者只需几行代码就能跑起来。二、快速上手两个核心 API 完成编辑器搭建wangeditor/editor对外暴露的创建入口是createEditor与createToolbar见 packages/editor/src/create.ts仓库内置示例 packages/editor/examples/default-mode.html 展示了完整用法。最小步骤如下div ideditor-toolbar classeditor-toolbar/div div ideditor-text-area classeditor-text-area/div script src.../dist/index.js/script script const E window.wangEditor const editorConfig { placeholder: 请输入内容, MENU_CONF: {}, onChange: (editor) { // 每次内容变化时触发 console.log(editor.getHtml()) }, } const toolbarConfig {} // 1. 创建编辑器绑定内容区域 const editor E.createEditor({ selector: #editor-text-area, // 也支持传 DOM 元素 config: editorConfig, // content: [...], // slate JSON 内容 // html: phello/p, // 或直接传 html // mode: default, // default | simple }) // 2. 创建工具栏绑定工具栏区域传入 editor 实例 const toolbar E.createToolbar({ editor, selector: #editor-toolbar, config: toolbarConfig, }) /scriptcreateEditor 参数详解ICreateEditorOption源码同文件顶部定义支持以下字段参数类型说明selectorstring \| DOMElement编辑器挂载点支持 CSS 选择器字符串或 DOM 元素缺省为空字符串configPartialIEditorConfig编辑器配置与全局配置浅合并contentDescendant[]slate 数据结构的内容JSON 数组缺省为[]htmlstring可选直接以 HTML 字符串作为初始内容modedefault \| simple模式缺省defaultsimple为简洁模式createToolbar 参数详解ICreateToolbarOption支持参数类型说明editorIDomEditor \| null已创建的编辑器实例必须传入selectorstring \| DOMElement工具栏挂载点必填缺失会抛错Cannot find selector when create toolbarconfigPartialIToolbarConfig工具栏配置modestring模式与编辑器保持一致一个值得注意的实现细节createEditor在合并配置时会单独处理hoverbarKeys选中文字弹出的悬浮工具条配置对全局配置与实例配置做浅合并后再传给内核coreCreateEditor而createToolbar同样会把全局工具栏配置与实例配置合并后传给coreCreateToolbar。这意味着实例配置优先于全局配置后合并者覆盖前者hoverbarKeys采用并集策略实例配置可以增量扩展全局悬浮菜单而不丢失默认项。三、两种模式default 与 simple 的默认配置差异mode参数决定编辑器采用哪套默认配置。在 packages/editor/src/init-default-config/index.ts 中编辑器会分别在Boot上注册四套默认配置default模式getDefaultEditorConfig()含genDefaultHoverbarKeys()悬浮工具条getDefaultToolbarConfig()含genDefaultToolbarKeys()完整工具栏simple模式getSimpleEditorConfig()getSimpleToolbarConfig()。createEditor中通过mode simple ? Boot.simpleEditorConfig : Boot.editorConfig选择对应配置createToolbar同理选择simpleToolbarConfig/toolbarConfig。默认模式的工具栏键序列定义在 packages/editor/src/init-default-config/config/toolbar.ts 的genDefaultToolbarKeys()顺序为标题选择headerSelect、引用blockquote、加粗/下划线/斜体、更多样式分组删除线/行内代码/上标/下标/清除格式、颜色/背景色、字号/字体/行高、无序列表/有序列表/待办、对齐分组、缩进分组、表情/插入链接、图片分组插入/上传、视频分组插入/上传、插入表格、代码块、分割线、撤销/重做、全屏。简洁模式的genSimpleToolbarKeys()则只保留高频能力blockquote、header1/2/3、加粗/下划线/斜体/删除线、颜色/背景色/清除格式、三种列表、三种对齐、插入链接、图片分组、插入视频/表格/代码块、撤销/重做、全屏。工具栏键序列支持两种元素字符串键直接引用已注册菜单的 key如bold、headerSelect、|分隔线分组对象以group开头的key如group-more-style配合title使用t(editor.more)做国际化和iconSvg图标、menuKeys子菜单列表可把多个菜单折叠进一个下拉分组按钮。默认配置文件中大量注释掉的键如header1、editLink、deleteImage、deleteVideo、codeSelectLang等说明这些菜单已注册、只是默认不展示——开发者在自定义toolbarKeys时可以直接启用它们。四、Boot全局注册机制与自定义扩展Boot是 wangEditor 5 的灵魂类实现见 packages/editor/src/Boot.ts它的设计思想是在创建编辑器之前把一切能力配置、插件、菜单、渲染、HTML 转换统一注册到静态容器创建实例时自动携带。构造函数被禁止实例化直接抛错全部成员为静态。全局配置静态成员说明editorConfig/setEditorConfig(config)默认模式编辑器全局配置合并式写入simpleEditorConfig/setSimpleEditorConfig(config)简洁模式编辑器全局配置toolbarConfig/setToolbarConfig(config)默认模式工具栏全局配置simpleToolbarConfig/setSimpleToolbarConfig(config)简洁模式工具栏全局配置能力注册Boot提供了完整的一套registerXxx静态方法分别对接内核的注册机制registerPlugin(plugin)注册 editor 插件slate 插件registerMenu(menuConf, customConfig?)注册菜单registerRenderElem(renderElemConf)注册元素渲染registerRenderStyle(fn)注册文本样式渲染registerElemToHtml(elemToHtmlConf)注册元素转 HTMLregisterStyleToHtml(fn)注册样式转 HTMLregisterPreParseHtml(preParseHtmlConf)注册 HTML 预解析registerParseElemHtml(parseElemHtmlConf)注册 HTML 解析为元素registerParseStyleHtml(fn)注册 HTML 样式解析registerModule(module)一键注册一个完整模块内部会依次调用上面的注册方法见 packages/editor/src/register-builtin-modules/register.ts。一个模块IModuleConf可以包含menus、renderElems、renderStyle、elemsToHtml、styleToHtml、preParseHtml、parseElemsHtml、parseStyleHtml、editorPlugin这些字段registerModule会按字段逐个分发注册——这正是各功能包basic-modules、list-module、table-module 等被wangeditor/editor聚合的方式。例如新增自定义菜单时只需在创建编辑器前const E window.wangEditor E.Boot.registerMenu({ key: myMenu, // 菜单唯一 key可写进 toolbarKeys title: 我的菜单, iconSvg: svg.../svg, // 其他菜单配置... })内置模块自动装配packages/editor/src/register-builtin-modules/index.ts 在包加载时自动完成内置模块注册basic-modules基础模块标题、引用、颜色、字体、对齐、缩进、行高、图片、链接、段落、文本样式、待办、撤销重做、分割线等、list-module列表、table-module表格、video-module视频、upload-image-module图片上传、code-highlight代码高亮同时导入各模块的 CSS。这也是开箱即用的底层保证——你不需要手动注册任何内置能力。五、默认配置初始化hoverbar 与代码高亮packages/editor/src/init-default-config/index.ts 在模块加载时执行默认配置初始化两个关键点hoverbarKeys默认编辑器和简洁编辑器的配置都来自genDefaultHoverbarKeys()/genSimpleHoverbarKeys()见 packages/editor/src/init-default-config/config/index.ts它们定义了选中不同元素时如段落、标题、图片、链接、表格等弹出的悬浮工具条按钮代码高亮默认配置和简洁配置都会附加decorate: wangEditorCodeHighLightDecorate来自wangeditor/code-highlight即开箱即带代码高亮装饰能力。这说明即使不写任何配置编辑器也自带悬浮工具条与代码高亮进一步印证了开箱即用的定位。六、入口导出core API、slate API 与扩展接口wangeditor/editor不仅是一个成品还是二次开发的工具箱。packages/editor/src/index.ts 按需导出了以下内容不可用*全量导出核心 API 与接口DomEditor、IDomEditor、IEditorConfig、IToolbarConfig、Toolbar、IModuleConf、IButtonMenu、ISelectMenu、IDropPanelMenu、IModalMenu多语言i18nChangeLanguage、i18nAddResources、i18nGetResources、tModal 辅助genModalTextareaElems、genModalInputElems、genModalButtonElems自定义弹窗菜单时生成表单元素上传createUploader、IUploadConfig底层基于 Uppyslate API为区分命名空间统一加Slate前缀导出如SlateTransforms、SlateEditor、SlateNode、SlateElement、SlateText、SlatePath、SlateRange、SlatePoint、SlateLocation、SlateDescendant工厂函数createEditor、createToolbarBoot全局注册入口。对于需要深度定制新元素类型、新菜单、自定义粘贴、自定义解析的开发者这些导出就是官方提供的插件 SDK。七、内置示例与测试理解用法的捷径示例目录packages/editor/examples/index.html 是一个示例导航页覆盖了绝大多数使用场景是学习配置的最佳素材default-mode.html默认模式完整示例包含placeholder、MENU_CONF如uploadImage的fieldName、base64LimitSize、onCreated/onChange/onDestroyed/onFocus/onBlur回调、getHtml()/getText()/getSelectionText()/isFocused()等方法、editor.disable()/editor.enable()/editor.destroy()生命周期操作simple-mode.html简洁模式示例parse-html.html使用 HTML 回显menu.html菜单toolbarKeys/excludeKeys配置like-yuque.html仿腾讯文档风格定制maxlength.html最大字数限制upload-image.html / upload-video.html图片、视频上传check.html资源校验、回调与自定义 alertmulti-editors.html单页多个编辑器headers.html获取标题 / 滚动到标题huge-doc.html几万字大文档性能i18n.html国际化theme.html主题定制code-highlight.html代码高亮shadow-dom.htmlShadow DOM 支持batch-destroy.html批量销毁与内存泄漏测试content-to-html.html内容转 HTMLnew-menu.html注册新菜单。以 default-mode.html 为例其中展示了一些容易踩坑的细节btn-toggle-enable按钮需监听mousedown并preventDefault()否则点击会先触发编辑器blur导致无法正确focusonChange里可以实时把editor.getHtml()渲染到其他容器做内容预览。测试与验证packages/editor的自动化测试位于 packages/editor/tests/create.test.ts围绕创建流程做回归验证。此外仓库根目录还有cypress/端到端测试cypress/integration/editor.spec.ts以及各功能模块的 jest 单测如 packages/basic-modules/tests下的菜单、elem-to-html、parse-html、plugin、render-elem测试。运行测试的方式# 在 packages/editor 目录下 yarn test # jest 单测 yarn test-c # jest 覆盖率测试构建与调试packages/editor/package.json 提供了完整脚本yarn dev # 开发模式构建rollup yarn dev-watch # 开发模式监听构建 yarn build # 生产构建 yarn example # 启动示例监听构建 http-server -p 8881 yarn size-stats # 产物体积统计八、扩展阅读在 monorepo 中继续深入packages/editor是整个 wangEditor 产品化的最后一公里向上游深入可以完整理解编辑器架构内核wangeditor/core 提供编辑器/工具栏实例、slate 封装、DOM 绑定、选区同步、渲染管线render、HTML 转换to-html、parse-html、上传upload等底层能力基础模块wangeditor/basic-modules 实现标题、引用、代码块、颜色、分割线、表情、字号字体、全屏、图片、缩进、对齐、行高、链接、段落、文本样式、待办、撤销重做等菜单与解析列表/表格/视频/图片上传/代码高亮wangeditor/list-module、wangeditor/table-module、wangeditor/video-module、wangeditor/upload-image-module、wangeditor/code-highlight开发文档仓库 docs/dev.md 与 docs/README.md 说明了模块开发规范各功能模块的__tests__目录是理解渲染 → 转 HTML → 解析 HTML闭环的最佳范本。结语wangeditor/editor通过入口聚合 Boot 全局注册 默认配置初始化三层设计把 wangEditor 5 的模块化内核包装成了对使用者极其友好的产品安装一个包、调用两个函数、传两行配置即可获得功能完整的富文本编辑器。同时Boot.registerModule等机制又保留了充分的扩展空间——无论是新增菜单、自定义元素还是定制主题与国际化都可以在不修改源码的情况下完成。理解本文梳理的包结构与源码脉络你就同时掌握了会用和能改两种能力。【免费下载链接】wangEditorwangEditor, open-source Web rich text editor 开源 Web 富文本编辑器项目地址: https://gitcode.com/gh_mirrors/wa/wangEditor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
