标题：Vue3 深度实践：基于 Hook 封装 WangEditor 富文本编辑器

2025年11月22日 互联网

Vue3 二次封装 WangEditor 富文本编辑器-Hook：从基础到进阶的完整实践

在 Vue3 项目中，富文本编辑器是内容管理系统（CMS）、博客平台等场景的核心组件。WangEditor 作为一款轻量级、高可扩展的开源富文本编辑器，因其简洁的 API 和灵活的配置深受开发者喜爱。然而，直接集成到 Vue3 项目中可能面临状态管理分散、功能复用性差等问题。本文将详细阐述如何通过 Vue3 的 Composition API 和 Hook 模式，封装一个可复用、易扩展的 WangEditor 组件，覆盖从基础封装到高级功能扩展的全流程。

一、为什么选择 Hook 模式封装？

1.1 传统封装方式的痛点

在 Vue2 时代，富文本编辑器的封装通常基于 Options API，通过 data、methods 等选项管理编辑器实例和状态。这种方式存在以下问题：

  • 状态与逻辑耦合：编辑器配置、内容、事件处理等逻辑分散在多个选项中，难以维护。
  • 复用性差：不同组件需要重复编写相似的初始化、销毁逻辑。
  • TypeScript 支持弱：Options API 的类型推断依赖手动声明，容易出错。

1.2 Hook 模式的优势

Vue3 的 Composition API 通过 setup 函数和 Hook（如 ref、reactive、computed）将逻辑按功能组织，而非按选项分类。封装 WangEditor 时，Hook 模式能带来以下收益：

  • 逻辑复用：将编辑器初始化、事件监听、内容同步等逻辑提取为独立 Hook，可在多个组件中共享。
  • 类型安全：结合 TypeScript，可精准定义编辑器配置、事件参数的类型，减少运行时错误。
  • 响应式集成：通过 ref 或 reactive 轻松实现编辑器内容与 Vue 响应式系统的双向绑定。

二、核心封装实现：从零构建 useWangEditor Hook

2.1 基础 Hook 结构

封装的核心是创建一个 useWangEditor Hook，返回编辑器实例、内容、方法等。以下是基础实现：

  1. import { ref, onMounted, onBeforeUnmount } from 'vue';
  2. import E from 'wangeditor';
  4. export function useWangEditor(containerId: string, initialContent?: string) {
  5.   const editorRef = ref<E | null>(null);
  6.   const content = ref<string>(initialContent || '');
  8.   const initEditor = () => {
  9.     const editor = new E(`#${containerId}`);
  10.     editor.config.onchange = (html: string) => {
  11.       content.value = html;
  12.     };
  13.     editor.create();
  14.     editorRef.value = editor;
  15.   };
  17.   onMounted(() => {
  18.     initEditor();
  19.   });
  21.   onBeforeUnmount(() => {
  22.     if (editorRef.value) {
  23.       editorRef.value.destroy();
  24.       editorRef.value = null;
  25.     }
  26.   });
  28.   return {
  29.     editor: editorRef,
  30.     content,
  31.     getContent: () => content.value,
  32.     setContent: (html: string) => {
  33.       if (editorRef.value) {
  34.         editorRef.value.txt.html(html);
  35.         content.value = html;
  36.       }
  37.     },
  38.   };
  39. }

2.2 关键点解析

  • 容器绑定：通过 containerId 动态绑定 DOM 元素，避免硬编码。
  • 响应式内容：使用 ref 管理编辑器内容，确保与 Vue 响应式系统同步。
  • 生命周期管理：在 onMounted 中初始化编辑器，onBeforeUnmount 中销毁，防止内存泄漏。
  • 类型定义：通过 TypeScript 明确 editorRef 的类型为 E | null（E 是 WangEditor 的类型）。

三、功能扩展：增强 Hook 的实用性

3.1 配置参数化

将编辑器配置（如工具栏菜单、上传图片接口）通过参数传入，提升灵活性：

  1. interface EditorConfig {
  2.   menus?: string[];
  3.   uploadImgServer?: string;
  4.   uploadFileName?: string;
  5. }
  7. export function useWangEditor(containerId: string, initialContent?: string, config?: EditorConfig) {
  8.   // ...其他代码
  9.   const initEditor = () => {
  10.     const editor = new E(`#${containerId}`);
  11.     if (config?.menus) {
  12.       editor.config.menus = config.menus;
  13.     }
  14.     if (config?.uploadImgServer) {
  15.       editor.config.uploadImgServer = config.uploadImgServer;
  16.       editor.config.uploadFileName = config.uploadFileName || 'file';
  17.     }
  18.     // ...剩余配置
  19.   };
  20.   // ...返回逻辑
  21. }

3.2 事件监听与自定义

暴露编辑器事件（如 focus、blur）的监听方法，支持自定义处理：

  1. export function useWangEditor(containerId: string, initialContent?: string) {
  2.   const editorRef = ref<E | null>(null);
  3.   // ...其他代码
  4.   const on = (event: string, callback: (...args: any[]) => void) => {
  5.     if (editorRef.value) {
  6.       editorRef.value.config.on(event, callback);
  7.     }
  8.   };
  10.   return {
  11.     // ...其他返回值
  12.     on,
  13.   };
  14. }

3.3 与表单库集成

封装一个 WangEditorFormItem 组件，结合 Element Plus 或 Ant Design Vue 的表单库使用：

  1. <template>
  2.   <div :id="containerId" class="wang-editor-container"></div>
  3. </template>
  5. <script setup lang="ts">
  6. import { useWangEditor } from './useWangEditor';
  7. import { ref, watch } from 'vue';
  9. const props = defineProps<{
  10.   modelValue: string;
  11.   config?: EditorConfig;
  12. }>();
  14. const emit = defineEmits(['update:modelValue']);
  16. const containerId = ref(`editor-${Math.random().toString(36).substr(2)}`);
  17. const { content, setContent } = useWangEditor(containerId.value, props.modelValue, props.config);
  19. watch(content, (newVal) => {
  20.   emit('update:modelValue', newVal);
  21. });
  23. watch(() => props.modelValue, (newVal) => {
  24.   setContent(newVal);
  25. });
  26. </script>

四、实际应用场景与优化建议

4.1 多编辑器实例管理

在需要多个编辑器的页面（如邮件模板编辑），可通过 Hook 封装实例管理逻辑：

  1. const editorInstances = ref<Map<string, E>>(new Map());
  3. export function useMultiWangEditor() {
  4.   const createEditor = (containerId: string, config?: EditorConfig) => {
  5.     const editor = new E(`#${containerId}`);
  6.     // 配置编辑器...
  7.     editor.create();
  8.     editorInstances.value.set(containerId, editor);
  9.     return editor;
  10.   };
  12.   const destroyEditor = (containerId: string) => {
  13.     const editor = editorInstances.value.get(containerId);
  14.     if (editor) {
  15.       editor.destroy();
  16.       editorInstances.value.delete(containerId);
  17.     }
  18.   };
  20.   return {
  21.     createEditor,
  22.     destroyEditor,
  23.   };
  24. }

4.2 性能优化

  • 按需加载菜单：通过 menus 配置仅加载必要的功能，减少初始包体积。
  • 防抖处理：对 onchange 事件添加防抖，避免高频更新导致性能问题。
  • SSR 兼容：在服务端渲染时，通过 isServer 判断跳过编辑器初始化。

4.3 错误处理

封装统一的错误处理逻辑，捕获编辑器初始化失败、上传图片错误等：

  1. export function useWangEditor(containerId: string, initialContent?: string) {
  2.   const error = ref<Error | null>(null);
  4.   const initEditor = () => {
  5.     try {
  6.       const editor = new E(`#${containerId}`);
  7.       // ...配置编辑器
  8.       editor.create();
  9.       return editor;
  10.     } catch (e) {
  11.       error.value = e instanceof Error ? e : new Error(String(e));
  12.       return null;
  13.     }
  14.   };
  16.   return {
  17.     // ...其他返回值
  18.     error,
  19.   };
  20. }

五、总结与展望

通过 Vue3 的 Composition API 和 Hook 模式封装 WangEditor，不仅解决了传统封装方式的复用性和类型安全问题，还为功能扩展提供了清晰的路径。未来可进一步探索：

  • 插件化架构：将图片上传、代码高亮等扩展功能设计为插件，通过 Hook 动态注入。
  • 跨框架兼容：基于相同的 Hook 逻辑，适配 React 或 SolidJS 等框架。
  • AI 集成：结合 NLP 能力，实现智能纠错、内容摘要等高级功能。

对于开发者而言，掌握这种封装模式不仅能提升项目开发效率，更能深入理解 Vue3 的设计哲学，为构建更复杂的组件库打下基础。

最新文章