npmapps 1.0.25 → 1.0.26

package/app/src/views/element/lazyCascader/data.js

@@ -0,0 +1,205 @@
+/**
+ * 懒加载级联 - 模拟数据 & 工具
+ *
+ * 数据约定:扁平数组 [{ id, parentId, label }]
+ *   - parentId 为空字符串 / null / undefined 即根
+ *   - 实际工程里这是后端一次性给到的原始数据
+ */
+
+// 1. 扁平原始数据(3 省 × 3~4 市 × 2~3 区 ≈ 30 节点)
+// eslint-disable-next-line max-lines
+export const flatRegions = [
+  // ---- 河北省 ----
+  { id: 'hebei', parentId: '', label: '河北省' },
+
+  { id: 'hebei-sjz', parentId: 'hebei', label: '石家庄市' },
+  { id: 'hebei-cd', parentId: 'hebei-sjz', label: '长安区' },
+  { id: 'hebei-qx', parentId: 'hebei-sjz', label: '桥西区' },
+  { id: 'hebei-yh', parentId: 'hebei-sjz', label: '裕华区' },
+
+  { id: 'hebei-ts', parentId: 'hebei', label: '唐山市' },
+  { id: 'hebei-ln', parentId: 'hebei-ts', label: '路北区' },
+  { id: 'hebei-gy', parentId: 'hebei-ts', label: '古冶区' },
+  { id: 'hebei-ka', parentId: 'hebei-ts', label: '开平区' },
+
+  { id: 'hebei-hd', parentId: 'hebei', label: '邯郸市' },
+  { id: 'hebei-hsh', parentId: 'hebei-hd', label: '邯山区' },
+  { id: 'hebei-cf', parentId: 'hebei-hd', label: '丛台区' },
+
+  // ---- 山东省 ----
+  { id: 'shandong', parentId: '', label: '山东省' },
+
+  { id: 'shandong-jn', parentId: 'shandong', label: '济南市' },
+  { id: 'shandong-lx', parentId: 'shandong-jn', label: '历下区' },
+  { id: 'shandong-shz', parentId: 'shandong-jn', label: '市中区' },
+  { id: 'shandong-hy', parentId: 'shandong-jn', label: '槐荫区' },
+
+  { id: 'shandong-qd', parentId: 'shandong', label: '青岛市' },
+  { id: 'shandong-shan', parentId: 'shandong-qd', label: '市南区' },
+  { id: 'shandong-shib', parentId: 'shandong-qd', label: '市北区' },
+  { id: 'shandong-ly', parentId: 'shandong-qd', label: '李沧区' },
+
+  { id: 'shandong-yk', parentId: 'shandong', label: '烟台市' },
+  { id: 'shandong-zs', parentId: 'shandong-yk', label: '芝罘区' },
+  { id: 'shandong-fs', parentId: 'shandong-yk', label: '福山区' },
+
+  // ---- 江苏省 ----
+  { id: 'jiangsu', parentId: '', label: '江苏省' },
+
+  { id: 'jiangsu-nj', parentId: 'jiangsu', label: '南京市' },
+  { id: 'jiangsu-xw', parentId: 'jiangsu-nj', label: '玄武区' },
+  { id: 'jiangsu-qh', parentId: 'jiangsu-nj', label: '秦淮区' },
+  { id: 'jiangsu-jb', parentId: 'jiangsu-nj', label: '建邺区' },
+
+  { id: 'jiangsu-sz', parentId: 'jiangsu', label: '苏州市' },
+  { id: 'jiangsu-gyq', parentId: 'jiangsu-sz', label: '姑苏区' },
+  { id: 'jiangsu-wzq', parentId: 'jiangsu-sz', label: '吴中区' },
+  { id: 'jiangsu-icq', parentId: 'jiangsu-sz', label: '相城区' },
+
+  { id: 'jiangsu-wx', parentId: 'jiangsu', label: '无锡市' },
+  { id: 'jiangsu-cs', parentId: 'jiangsu-wx', label: '梁溪区' },
+  { id: 'jiangsu-bh', parentId: 'jiangsu-wx', label: '滨湖区' },
+]
+
+// 2. 树形数据(同一份数据,只是嵌套形式;用于演示"后端返树形"的情况)
+export const treeRegions = [
+  {
+    id: 'hebei',
+    label: '河北省',
+    children: [
+      {
+        id: 'hebei-sjz',
+        label: '石家庄市',
+        children: [
+          { id: 'hebei-cd', label: '长安区' },
+          { id: 'hebei-qx', label: '桥西区' },
+          { id: 'hebei-yh', label: '裕华区' },
+        ],
+      },
+      {
+        id: 'hebei-ts',
+        label: '唐山市',
+        children: [
+          { id: 'hebei-ln', label: '路北区' },
+          { id: 'hebei-gy', label: '古冶区' },
+          { id: 'hebei-ka', label: '开平区' },
+        ],
+      },
+      {
+        id: 'hebei-hd',
+        label: '邯郸市',
+        children: [
+          { id: 'hebei-hsh', label: '邯山区' },
+          { id: 'hebei-cf', label: '丛台区' },
+        ],
+      },
+    ],
+  },
+  {
+    id: 'shandong',
+    label: '山东省',
+    children: [
+      {
+        id: 'shandong-jn',
+        label: '济南市',
+        children: [
+          { id: 'shandong-lx', label: '历下区' },
+          { id: 'shandong-shz', label: '市中区' },
+          { id: 'shandong-hy', label: '槐荫区' },
+        ],
+      },
+      {
+        id: 'shandong-qd',
+        label: '青岛市',
+        children: [
+          { id: 'shandong-shan', label: '市南区' },
+          { id: 'shandong-shib', label: '市北区' },
+          { id: 'shandong-ly', label: '李沧区' },
+        ],
+      },
+      {
+        id: 'shandong-yk',
+        label: '烟台市',
+        children: [
+          { id: 'shandong-zs', label: '芝罘区' },
+          { id: 'shandong-fs', label: '福山区' },
+        ],
+      },
+    ],
+  },
+  {
+    id: 'jiangsu',
+    label: '江苏省',
+    children: [
+      {
+        id: 'jiangsu-nj',
+        label: '南京市',
+        children: [
+          { id: 'jiangsu-xw', label: '玄武区' },
+          { id: 'jiangsu-qh', label: '秦淮区' },
+          { id: 'jiangsu-jb', label: '建邺区' },
+        ],
+      },
+      {
+        id: 'jiangsu-sz',
+        label: '苏州市',
+        children: [
+          { id: 'jiangsu-gyq', label: '姑苏区' },
+          { id: 'jiangsu-wzq', label: '吴中区' },
+          { id: 'jiangsu-icq', label: '相城区' },
+        ],
+      },
+      {
+        id: 'jiangsu-wx',
+        label: '无锡市',
+        children: [
+          { id: 'jiangsu-cs', label: '梁溪区' },
+          { id: 'jiangsu-bh', label: '滨湖区' },
+        ],
+      },
+    ],
+  },
+]
+
+/**
+ * 树 → 扁平
+ * @param {Array<{ id, label, children? }>} tree
+ * @returns {Array<{ id: string, parentId: string, label: string }>}
+ */
+export function flattenTree(tree) {
+  const out = []
+  const walk = (nodes, parentId) => {
+    if (!Array.isArray(nodes)) return
+    nodes.forEach(n => {
+      if (!n || !n.id) return
+      out.push({ id: n.id, parentId: parentId || '', label: n.label })
+      if (Array.isArray(n.children) && n.children.length) {
+        walk(n.children, n.id)
+      }
+    })
+  }
+  walk(tree, '')
+  return out
+}
+
+/**
+ * 模拟接口:返回某个 parentId 的子节点
+ * - 真实工程里这会走 axios 请求后端
+ * - 这里直接查 flat,加 0~50ms 延时让 loading 状态可见
+ */
+export function fetchChildren(parentId, flat = flatRegions) {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      const list = flat.filter(i => (i.parentId || '') === (parentId || ''))
+      resolve(list)
+    }, Math.random() * 50)
+  })
+}
+
+// 一些"默认值回显"用的预设叶子 id
+// (新设计:v-model 是单字符串,所以存叶子 id 即可)
+export const DEFAULT_LEAF_QINGDAO_SHIBEI = 'shandong-shib'
+export const DEFAULT_LEAF_JINAN_LIXIA = 'shandong-lx'
+export const DEFAULT_LEAF_SUZHOU_WUZHONG = 'jiangsu-wzq'
+export const DEFAULT_LEAF_NANJING_QINHUAI = 'jiangsu-qh'
+export const DEFAULT_LEAF_HANDAN_CONGTAI = 'hebei-cf'

package/app/src/views/element/lazyCascader/index.vue

@@ -0,0 +1,315 @@
+<template>
+  <div class="lazy-cascader-demo">
+    <PageHeader
+      title="级联懒加载(前端拆分)"
+      description="模拟后端一次性返回大量扁平数据,前端按层拆分成懒加载体验;v-model 绑定叶子 id 字符串(单值);支持默认值回显、v-if 销毁重建、先有值后到数据、树形转扁平等场景"
+      usage="&lt;LazyCascader v-model=&quot;leafId&quot; :data=&quot;flat&quot; :check-strictly=&quot;false&quot; :lazy-delay=&quot;50&quot; /&gt; data 必传扁平数组;checkStrictly 控制是否可选任意级;lazyDelay 是模拟接口延时(ms),0 即同步"
+    />
+
+    <!-- 案例 1: 基础 - 可选任意级 -->
+    <el-card class="case" header="案例 1: 基础 - 可选任意级(checkStrictly=true)">
+      <LazyCascader
+        v-model="case1.value"
+        :data="flatRegions"
+        :check-strictly="true"
+        :lazy-delay="50"
+        placeholder="请选择(任意级)"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case1')">查看当前值</el-button>
+        <el-button size="mini" @click="reset('case1')">重置</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case1')">
+          重置为默认(青岛市市北区)
+        </el-button>
+      </div>
+      <div class="hint">checkStrictly=true 时,可选省/市/区任意一级;v-model 仍是单个 id 字符串</div>
+      <pre v-if="case1.display">{{ JSON.stringify(case1.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 2: 基础 - 只选最后一级(默认) -->
+    <el-card class="case" header="案例 2: 基础 - 只选最后一级(默认 checkStrictly=false)">
+      <LazyCascader
+        v-model="case2.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :lazy-delay="50"
+        placeholder="请选择(只选叶子)"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case2')">查看当前值</el-button>
+        <el-button size="mini" @click="reset('case2')">重置</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case2')">
+          重置为默认(青岛市市北区)
+        </el-button>
+      </div>
+      <div class="hint">只能选叶子级;v-model 是叶子 id 字符串;输入框只显示叶子 label</div>
+      <pre v-if="case2.display">{{ JSON.stringify(case2.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 3: 默认值回显 -->
+    <el-card class="case" header="案例 3: 默认值回显(组件挂载时即展开)">
+      <LazyCascader
+        v-model="case3.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :lazy-delay="50"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case3')">查看当前值</el-button>
+        <el-button size="mini" @click="reset('case3')">重置</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case3')">
+          重置为默认(济南市历下区)
+        </el-button>
+      </div>
+      <div class="hint">组件挂载后,应自动展开到"山东省 / 济南市 / 历下区",输入框显示"历下区",可继续点开重选</div>
+      <pre v-if="case3.display">{{ JSON.stringify(case3.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 4: v-if 销毁/重建 -->
+    <el-card class="case" header="案例 4: v-if 控制显示/隐藏(销毁重建后仍能回显)">
+      <div class="ops">
+        <el-button size="mini" :type="case4.visible ? 'danger' : 'primary'" @click="case4.visible = !case4.visible">
+          {{ case4.visible ? '隐藏组件' : '显示组件' }}
+        </el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case4')">
+          重置为默认(苏州市吴中区)
+        </el-button>
+      </div>
+      <LazyCascader
+        v-if="case4.visible"
+        v-model="case4.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :lazy-delay="50"
+      />
+      <div class="hint">点"隐藏"再点"显示",默认值仍能正确回显(说明 v-if 销毁重建不影响)</div>
+      <pre v-if="case4.display">{{ JSON.stringify(case4.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 5: 先有默认值,后到数据 -->
+    <el-card class="case" header="案例 5: 先有默认值,后到数据(模拟接口延迟)">
+      <LazyCascader
+        ref="case5Ref"
+        v-model="case5.value"
+        :data="case5.data"
+        :check-strictly="false"
+        :lazy-delay="50"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case5')">查看当前值</el-button>
+        <el-button size="mini" @click="reset('case5')">重置</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case5')">
+          重置为默认(青岛市市北区)
+        </el-button>
+        <el-button size="mini" type="success" :loading="case5.loading" @click="loadCase5Data">
+          模拟接口返回(1s 后)
+        </el-button>
+      </div>
+      <div class="hint">初始 data=[] 渲染 → 默认值暂时不显示 → 点"模拟接口返回" → data 填上 + 触发组件 reload() → 默认值正确回显</div>
+      <pre v-if="case5.display">{{ JSON.stringify(case5.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 6: 后端返回的是树形结构 -->
+    <el-card class="case" header="案例 6: 后端返的是树形结构(用 flattenTree 转扁平)">
+      <LazyCascader
+        v-model="case6.value"
+        :data="case6.flatData"
+        :check-strictly="false"
+        :lazy-delay="50"
+      />
+      <div class="ops">
+        <el-button size="mini" @click="showValue('case6')">查看当前值</el-button>
+        <el-button size="mini" @click="reset('case6')">重置</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case6')">
+          重置为默认(南京市秦淮区)
+        </el-button>
+        <el-button size="mini" type="warning" @click="rebuildCase6FromTree">
+          重新调用 flattenTree(演示树 → 扁平)
+        </el-button>
+      </div>
+      <div class="hint">case6.flatData 初始是 flattenTree(treeRegions) 的结果;点"重新调用"再走一遍,组件无感知,继续工作</div>
+      <pre v-if="case6.display">{{ JSON.stringify(case6.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 7: lazyDelay 控制 -->
+    <el-card class="case" header="案例 7: lazyDelay 控制模拟接口延时(默认 50ms)">
+      <div class="ops">
+        <el-button size="mini" @click="case7.delay = 0">同步(lazyDelay=0)</el-button>
+        <el-button size="mini" @click="case7.delay = 200">慢(lazyDelay=200)</el-button>
+        <el-button size="mini" @click="case7.delay = 1000">很慢(lazyDelay=1000)</el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case7')">
+          重置为默认(邯郸市丛台区)
+        </el-button>
+      </div>
+      <LazyCascader
+        v-model="case7.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :lazy-delay="case7.delay"
+      />
+      <div class="hint">点击不同按钮感受 loading 效果差异;lazyDelay=0 时完全同步无 loading</div>
+      <pre v-if="case7.display">{{ JSON.stringify(case7.value, null, 2) }}</pre>
+    </el-card>
+
+    <!-- 案例 8: showAllLevels 控制输入框显示内容 -->
+    <el-card class="case" header="案例 8: showAllLevels 控制输入框显示内容">
+      <div class="ops">
+        <el-button size="mini" :type="!case8.showAllLevels ? 'primary' : ''" @click="case8.showAllLevels = false">
+          只显示叶子(默认)
+        </el-button>
+        <el-button size="mini" :type="case8.showAllLevels ? 'primary' : ''" @click="case8.showAllLevels = true">
+          显示完整路径
+        </el-button>
+        <el-button size="mini" type="primary" @click="setDefault('case8')">
+          重置为默认(唐山市开平区)
+        </el-button>
+      </div>
+      <LazyCascader
+        v-model="case8.value"
+        :data="flatRegions"
+        :check-strictly="false"
+        :show-all-levels="case8.showAllLevels"
+        :separator="case8.separator"
+      />
+      <div class="hint">切换按钮,看输入框显示"开平区"还是"河北省 / 唐山市 / 开平区";separator 可自定义分隔符</div>
+      <pre v-if="case8.display">{{ JSON.stringify({ value: case8.value, showAllLevels: case8.showAllLevels }, null, 2) }}</pre>
+    </el-card>
+  </div>
+</template>
+
+<script>
+import PageHeader from '@/components/PageHeader/index.vue'
+import LazyCascader from './LazyCascader.vue'
+import {
+  flatRegions,
+  treeRegions,
+  flattenTree,
+  DEFAULT_LEAF_JINAN_LIXIA,
+  DEFAULT_LEAF_QINGDAO_SHIBEI,
+  DEFAULT_LEAF_SUZHOU_WUZHONG,
+  DEFAULT_LEAF_NANJING_QINHUAI,
+  DEFAULT_LEAF_HANDAN_CONGTAI,
+} from './data.js'
+
+const newCase = (leafId) => ({
+  value: leafId || '',
+  display: false,
+})
+
+const newCaseEmpty = () => ({
+  value: '',
+  data: [],
+  loading: false,
+  display: false,
+})
+
+const newCaseFlat = (initialFlat, defaultLeaf) => ({
+  value: defaultLeaf,
+  flatData: initialFlat,
+  display: false,
+})
+
+export default {
+  name: 'LazyCascaderDemo',
+
+  components: { PageHeader, LazyCascader },
+
+  data() {
+    return {
+      flatRegions,
+      case1: newCase(DEFAULT_LEAF_QINGDAO_SHIBEI),
+      case2: newCase(DEFAULT_LEAF_QINGDAO_SHIBEI),
+      case3: newCase(DEFAULT_LEAF_JINAN_LIXIA),
+      case4: { ...newCase(DEFAULT_LEAF_SUZHOU_WUZHONG), visible: true },
+      case5: newCaseEmpty(),
+      case6: newCaseFlat(flattenTree(treeRegions), DEFAULT_LEAF_NANJING_QINHUAI),
+      case7: { value: DEFAULT_LEAF_HANDAN_CONGTAI, delay: 50, display: false },
+      case8: { value: 'hebei-ka', showAllLevels: false, separator: ' / ', display: false },
+    }
+  },
+
+  methods: {
+    showValue(key) {
+      this[key].display = !this[key].display
+    },
+    reset(key) {
+      this[key].value = ''
+    },
+    setDefault(key) {
+      switch (key) {
+        case 'case1':
+          this.case1.value = DEFAULT_LEAF_QINGDAO_SHIBEI
+          break
+        case 'case2':
+          this.case2.value = DEFAULT_LEAF_QINGDAO_SHIBEI
+          break
+        case 'case3':
+          this.case3.value = DEFAULT_LEAF_JINAN_LIXIA
+          break
+        case 'case4':
+          this.case4.value = DEFAULT_LEAF_SUZHOU_WUZHONG
+          break
+        case 'case5':
+          this.case5.value = DEFAULT_LEAF_QINGDAO_SHIBEI
+          break
+        case 'case6':
+          this.case6.value = DEFAULT_LEAF_NANJING_QINHUAI
+          break
+        case 'case7':
+          this.case7.value = DEFAULT_LEAF_HANDAN_CONGTAI
+          break
+        case 'case8':
+          this.case8.value = 'hebei-ka'
+          break
+        default:
+          break
+      }
+    },
+    loadCase5Data() {
+      this.case5.loading = true
+      setTimeout(() => {
+        this.case5.data = flatRegions
+        this.case5.loading = false
+        this.$nextTick(() => {
+          const ref = this.$refs.case5Ref
+          if (ref && typeof ref.reload === 'function') ref.reload()
+        })
+      }, 1000)
+    },
+    rebuildCase6FromTree() {
+      this.case6.flatData = flattenTree(treeRegions)
+      this.$message.success('已重新调用 flattenTree,数据条数 = ' + this.case6.flatData.length)
+    },
+  },
+}
+</script>
+
+<style lang="less" scoped>
+.lazy-cascader-demo {
+  padding: 16px;
+  .case {
+    margin-bottom: 16px;
+  }
+  .ops {
+    margin-top: 12px;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+  .hint {
+    margin-top: 8px;
+    color: #909399;
+    font-size: 12px;
+    line-height: 1.5;
+  }
+  pre {
+    margin-top: 8px;
+    padding: 8px 12px;
+    background: #f5f7fa;
+    border-radius: 4px;
+    font-size: 12px;
+    color: #303133;
+    line-height: 1.6;
+  }
+}
+</style>

package/app/src/views/element/quillEditor/README.md

@@ -0,0 +1,163 @@
+# QuillEditor
+
+基于 Quill2.x + quill-table-better 的 Vue2 富文本编辑器组件,支持表格、图片、全部基础格式。
+
+## 安装依赖
+
+依赖已添加到 `package.json`,首次使用需安装:
+
+```bash
+npm install
+```
+
+依赖列表:
+- `quill@2.0.2`
+- `quill-table-better@1.2.3`
+
+##快速使用
+
+```vue
+<template>
+ <QuillEditor v-model="content" :height="400" />
+</template>
+
+<script>
+import QuillEditor from '@/views/element/quillEditor/index.vue';
+
+export default {
+ components: { QuillEditor },
+ data() {
+ return { content: '<p>Hello Quill!</p>' };
+ },
+};
+</script>
+```
+
+## Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | String | `''` | 编辑器 HTML 内容,支持 v-model |
+| `placeholder` | String | `'请输入内容...'` | 占位文字 |
+| `readonly` | Boolean | `false` | 是否只读(可看不可改) |
+| `disabled` | Boolean | `false` | 是否禁用(工具栏灰掉,不可编辑) |
+| `height` | String \| Number | `300` | 编辑区高度,数字按 px,字符串按原值 |
+| `toolbarPreset` | String | `'default'` | 工具栏预设:`'simple'`(精简)/ `'default'`(默认)/ `'full'`(全部) |
+| `toolbar` | Array \| Object | `null` | 自定义工具栏配置;传了则**覆盖** `toolbarPreset` |
+| `imageHandler` | Function | `null` | 自定义图片处理函数;不传则走 base64 内联 |
+| `theme` | String | `'snow'` |主题,目前只支持 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 实例(高级用法) |
+
+## 自定义图片上传示例
+
+```vue
+<QuillEditor
+ v-model="content"
+ :image-handler="uploadImage"
+/>
+
+<script>
+methods: {
+ async uploadImage(file, range, quill) {
+ const form = new FormData();
+ form.append('file', file);
+ const res = await fetch('/api/upload', { method: 'POST', body: form });
+ const { url } = await res.json();
+ quill.insertEmbed(range.index, 'image', url);
+ return true; // 返回 true 表示已处理,跳过 base64 回退
+ },
+}
+</script>
+```
+
+## 工具栏预设(toolbarPreset)
+
+通过 `toolbarPreset` 选择内置工具栏,三档从简到全:
+
+| 预设 | 适用场景 | 包含按钮 |
+|------|---------|----------|
+| `simple` 精简 | 评论、备注等轻量输入 | 加粗/斜体/下划线、标题(1-3)、有序/无序列表、链接、清除格式 |
+| `default` 默认 | 大多数业务表单(默认值) | 标题/字号、基础格式+删除线、颜色/背景、引用/代码、列表、缩进、对齐、链接/图片、清除、撤销/重做 |
+| `full` 全部 | 文档/文章等富内容 | 在默认基础上再加 上标/下标、视频、表格 |
+
+```vue
+<QuillEditor :toolbar-preset="'simple'" />   <!-- 精简 -->
+<QuillEditor />                               <!-- 默认 -->
+<QuillEditor :toolbar-preset="'full'" />      <!-- 全部 -->
+```
+
+> 运行时切换 `toolbarPreset` 需重新挂载组件(给组件加 `:key="preset"`),因为 Quill 工具栏在初始化时一次性构建。
+
+各按钮 token 的功能对照、以及为何预设不含 `font` 字体下拉,见 `toolbar.js` 顶部注释。
+
+### 完全自定义工具栏
+
+传 `toolbar` 数组(优先级高于 `toolbarPreset`):
+
+```javascript
+[
+ [{ header: [1, 2, 3, false] }],
+ ['bold', 'italic', 'underline'],
+ [{ list: 'ordered' }, { list: 'bullet' }],
+ ['link', 'clean'],
+]
+```
+
+## HTML 源码双向联动
+
+内容用 v-model 双向绑定,可同时在一个 textarea 里编辑 HTML 源码并写回编辑器:
+
+```vue
+<template>
+  <QuillEditor v-model="html" />
+  <textarea v-model="source" />
+  <button @click="html = source">应用源码到编辑器</button>
+</template>
+
+<script>
+export default {
+  data() {
+    return { html: '<p>hello</p>', source: '<p>hello</p>' };
+  },
+  watch: {
+    html(val) { this.source = val; }, // 编辑器变化实时同步到源码框
+  },
+};
+</script>
+```
+
+> 写回时 `html = source` 会触发编辑器 `setHtml`,Quill 会对 HTML 做规范化。完整示例见 `example.vue` 卡片②。
+
+##表格功能
+
+点击工具栏的 `table-better`按钮可插入表格,右键单元格可弹出操作菜单(增删行列、合并/拆分、单元格背景色、复制/删除)。
+
+表格配置见 `toolbar.js` 中 `defaultTableBetterConfig`:
+- `language: 'zh_CN'` 中文界面
+- `toolbarTable: true` 显示表格工具栏
+- `menus`包含 column/row/merge/table/cell/wrap/copy/delete全部操作
+
+##主题与样式
+
+组件内部已 `import 'quill/dist/quill.snow.css'` 和 `quill-table-better/dist/quill-table-better.css`,
+**不需要在 main.js 全局引入**。外层容器样式 scoped,不污染全局。