npmapps 1.1.4 → 1.1.6

package/app/wujie-wk/wujie-vue2-child/docs/superpowers/specs/2026-05-29-quill-editor-design.md

@@ -0,0 +1,210 @@
+# QuillEditor组件封装设计
+
+**日期**:2026-05-29
+**作者**: wk-7500f
+**状态**: Approved
+
+##背景
+
+`src/views/element/index.vue` 已经预留了 "Quill编辑器" tab 并 import 了
+`./quillEditor/example.vue`,但 `src/views/element/quillEditor/`目录为空,
+example.vue也不存在。需要:
+
+1.封装一个功能齐全的 Quill 富文本编辑器 Vue2组件
+2. 必须包含表格(table)功能
+3. 在 element tab 下展示多实例对比案例
+
+##决策记录
+
+|维度 | 选择 |理由 |
+|------|------|------|
+| Quill 版本 |2.0.2 | quill-table-better@1.2.3明确要求 quill.js >= v2.0.0;Quill 是框架无关的,Vue2也能用2.x;生态最新最活跃 |
+|表格模块 | quill-table-better1.2.3 |唯一活跃维护的 Quill表格模块,功能齐全(增删/合并/拆分/样式),官方要求 Quill2.x |
+| 图片上传 | base64 内联 | 无后端依赖、零配置、适合 demo场景 |
+|主题 | snow | Quill 默认浅色主题,和现有 element tab风格一致 |
+|放置位置 | `src/views/element/quillEditor/` | 仅给 element tab 用,不放全局 components |
+|案例形式 | 多实例对比 | 同时展示基础/只读/禁用三种配置 |
+
+##架构
+
+```
+src/views/element/index.vue (el-tabs)
+ └─ <el-tab-pane name="quillEditor">
+ └─ <QuillEditorDemo /> (example.vue)
+ ├─ <QuillEditor v-model="..." /> 实例1:基础
+ ├─ <QuillEditor v-model="..." :readonly="true"/> 实例2:只读
+ └─ <QuillEditor v-model="..." :disabled="true"/> 实例3:禁用
+
+src/views/element/quillEditor/
+├── index.vue QuillEditor 主组件
+├── example.vue Demo页面(已存在 tab引用)
+├── toolbar.js 默认工具栏配置
+└── README.md 使用文档
+```
+
+外部依赖:
+
+- `quill@2.0.2` 富文本核心
+- `quill-table-better@1.2.3`表格模块(明确要求 Quill >=2.0.0)
+- `quill-image-drop-module` 图片拖拽上传(兼容 Quill2.x)
+- `quill-image-resize-module` (兼容 Quill2.x 版本) 图片缩放
+- `quill/dist/quill.snow.css` snow主题样式
+- `quill-table-better/dist/quill-table-better.css`表格样式
+
+> **修订记录**:2026-05-29实施前发现 quill-table-better实际依赖 Quill2.x,
+>升级方案由 "Quill1.x + quill-table-better"改为 "Quill2.x + quill-table-better1.2.3"。
+
+##组件 API
+
+### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | String | `''` | 编辑器 HTML 内容,支持 v-model |
+| `placeholder` | String | `'请输入内容...'` | 占位文字 |
+| `readonly` | Boolean | `false` | 是否只读 |
+| `disabled` | Boolean | `false` | 是否禁用工具栏 |
+| `height` | String \| Number | `300` | 编辑区高度,数字按 px,字符串按原值 |
+| `toolbar` | Array \| Object | 见下方"默认工具栏" | 自定义工具栏配置;不传则用默认全量 |
+| `imageHandler` | Function | `null` | 自定义图片处理;不传则走 base64 内联 |
+| `theme` | String | `'snow'` |主题 |
+
+### Events
+
+|事件 |触发时机 | 参数 |
+|------|---------|------|
+| `input` | 内容变化 | `(html: String)` |
+| `change` | 内容变化(去抖300ms) | `(html: String)` |
+| `ready` | Quill初始化完成 | `(quill: Quill)` |
+| `focus` | 编辑器获得焦点 | `()` |
+| `blur` | 编辑器失去焦点 | `()` |
+
+### Methods(ref 调用)
+
+| 方法 | 返回值 | 说明 |
+|------|--------|------|
+| `getHtml()` | String | 获取当前 HTML |
+| `getText()` | String | 获取纯文本 |
+| `setHtml(html)` | - | 设置内容 |
+| `clear()` | - | 清空内容 |
+| `focus()` | - |聚焦 |
+| `getQuill()` | Quill | 获取底层 Quill 实例 |
+
+### 默认工具栏(全量)
+
+```
+[
+ [{ header: [1,2,3,4,5,6, false] }],
+ [{ font: [] }],
+ [{ size: ['small', false, 'large', 'huge'] }],
+ ['bold', 'italic', 'underline', 'strike'],
+ [{ color: [] }, { background: [] }],
+ [{ script: 'sub' }, { script: 'super' }],
+ ['blockquote', 'code-block'],
+ [{ list: 'ordered' }, { list: 'bullet' }],
+ [{ indent: '-1' }, { indent: '+1' }],
+ [{ align: [] }],
+ ['link', 'image', 'video'],
+ ['table-better'],
+ ['clean'],
+ ['undo', 'redo'],
+]
+```
+
+## 文件内部实现要点
+
+### toolbar.js
+
+导出:
+
+- `defaultToolbar`:默认工具栏数组(上述全量配置)
+- `defaultHandlers`:`{ image, 'table-better' }`,image handler触发组件内的 file input;
+ table-better 由 quill-table-better 模块自身注册
+
+### index.vue关键实现
+
+1. **生命周期**
+ - `mounted`(nextTick):创建 Quill 实例,挂载到 `ref="editor"` div
+ - `beforeDestroy`:销毁 Quill 实例、清理事件、移除 file input
+ - 用 `this._quill`缓存实例,避免 hot reload重复挂载
+
+2. **v-model双向同步**
+ - `watch.value`(immediate):外部值变化 → `quill.clipboard.dangerouslyPasteHTML(value)`
+ - 用 `isInternalChange`标志位避免 watch循环
+ - Quill `text-change`事件 →触发 `input` +300ms 去抖触发 `change`
+
+3. **图片处理(base64 内联)**
+ - 自定义 image handler:创建隐藏 `<input type="file" accept="image/*">`,点击触发选择
+ - FileReader读 File → onload 转 base64 → `quill.insertEmbed(range.index, 'image', dataUrl)`
+ - 若 `imageHandler` prop传入,优先调用 prop;失败回退 base64
+
+4. **表格模块**
+ - 通过 Quill `theme.include`机制注册 quill-table-better
+ - 在 `index.vue` 中 import quill-table-better CSS
+
+5. **样式**
+ - scoped容器,只控制外层高度和 disabled态样式
+ - Quill内部样式通过 `index.vue` 中 `import 'quill/dist/quill.snow.css'`
+
+### example.vue 内容
+
+```vue
+<template>
+ <div class="quill-demo">
+ <h3>实例1:基础编辑器(v-model双向绑定)</h3>
+ <QuillEditor v-model="content1" @change="onChange" />
+
+ <h3>实例2:只读模式(readonly)</h3>
+ <QuillEditor v-model="content2" :readonly="true" />
+
+ <h3>实例3:禁用模式(disabled,工具栏灰掉)</h3>
+ <QuillEditor v-model="content3" :disabled="true" :height="200" />
+
+ <h3>当前实例1 的 v-model 内容:</h3>
+ <pre>{{ content1 }}</pre>
+ </div>
+</template>
+```
+
+实例1预填一段带表格的 HTML,演示表格功能;实例2、3共享同一份初始内容,
+便于对比 readonly 和 disabled 的视觉差异。
+
+##错误处理与边界
+
+|场景 | 处理 |
+|------|------|
+|依赖未安装(window.Quill 不存在) |渲染 `<div class="quill-editor-error">请先安装 quill依赖</div>` + console.error |
+| value 非字符串 |强制 `String(value)` |
+|重复创建 | 用 `this._quill`缓存,hot reload 不重复挂载 |
+| watch循环 | `isInternalChange`标志位 |
+|组件销毁 |销毁 Quill 实例、清理事件、移除 file input |
+| 图片 >5MB | ElMessage.warning提示但仍允许插入(base64 内联策略) |
+
+## 测试策略
+
+项目无现成测试框架(jest/vitest 未安装),通过 example演示 +人工验证:
+
+-三个实例能否正常渲染
+- v-model双向同步是否正确
+-工具栏按钮(尤其 table-better、image)是否可用
+- readonly / disabled切换是否生效
+-组件销毁后无控制台报错
+
+## 实现步骤
+
+1. 安装依赖:`quill@2.0.2`、`quill-table-better@1.2.3`、`quill-image-drop-module`、
+ `quill-image-resize-module`(注意选兼容 Quill2.x 的版本)
+2.写 `toolbar.js`(默认工具栏 + handlers)
+3.写 `index.vue`(QuillEditor 主组件,实现上述所有要点)
+4.写 `example.vue`(三实例对比 demo)
+5.写 `README.md`(用法 + Props/Events/Methods 说明)
+6. `index.vue` (element tab) 已经 import 该组件,无需修改
+
+##范围之外(本期不做)
+
+- 图片上传到后端 API(默认 base64,后续如需可加 `imageHandler` prop)
+- 自定义主题(只用 snow)
+-暗黑模式
+-协同编辑
+- 字数限制(可在调用方通过 `change`事件自行截断)
+-移动端适配

package/app/wujie-wk/wujie-vue2-child/jsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "module": "esnext",
+    "baseUrl": "./",
+    "moduleResolution": "node",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    },
+    "lib": [
+      "esnext",
+      "dom",
+      "dom.iterable",
+      "scripthost"
+    ]
+  }
+}