@mario9/tiptap-editor 1.0.2 → 1.0.4

package/README.md

@@ -2,6 +2,14 @@
 
 基于 Tiptap + Vue 3 的富文本编辑器组件，支持 Feature Plugin 架构，消费方可按需引入功能模块实现 tree-shaking。
 
+## 效果预览
+
+![编辑器全貌](docs/screenshots/screenshot-overview.png)
+
+![代码块与表格](docs/screenshots/screenshot-features.png)
+
+![数学公式](docs/screenshots/screenshot-math.png)
+
 ## 安装
 
 ```bash
@@ -57,6 +65,59 @@ const content = ref('')
 </template>
 ```
 
+## 常见场景
+
+### 最小化配置
+
+只引入用到的 feature，未引入的模块不会进入消费方 bundle：
+
+```vue
+<TiptapEditor
+  v-model="content"
+  :features="[UndoRedoFeature, TextStyleFeature]"
+/>
+```
+
+![最小化配置工具栏](docs/screenshots/screenshot-minimal.png)
+
+### 只读模式
+
+```vue
+<TiptapEditor v-model="content" :readonly="true" />
+```
+
+`readonly` 时工具栏隐藏，编辑器不可编辑，图片控件仅保留下载，数学公式不可点击编辑。
+
+### 获取 / 设置内容
+
+`v-model` 绑定的是 HTML 字符串，直接读写即可：
+
+```typescript
+const content = ref('<p>初始内容</p>')
+
+// 读取当前内容
+console.log(content.value)
+
+// 程序化设置内容
+content.value = '<h1>新标题</h1><p>新内容</p>'
+```
+
+### 工具栏顺序
+
+`features` 数组的顺序即工具栏按钮的顺序，用 `SeparatorFeature` 插入分隔符：
+
+```typescript
+:features="[
+  UndoRedoFeature,     // 撤销重做
+  SeparatorFeature,    // ——
+  TextStyleFeature,    // 粗体/斜体/下划线/删除线/链接
+  TextAlignFeature,    // 对齐
+  SeparatorFeature,    // ——
+  TableFeature,        // 表格
+  ImageFeature,        // 图片
+]"
+```
+
 ## Props
 
 | 属性 | 类型 | 默认值 | 说明 |
@@ -102,7 +163,9 @@ const myUpload: UploadFn = async (file) => {
 
 ## 自定义 Feature Plugin
 
-实现 `FeaturePlugin` 接口即可创建自定义功能插件：
+实现 `FeaturePlugin` 接口即可创建自定义功能插件。
+
+### 基础示例
 
 ```typescript
 import type { FeaturePlugin } from '@mario9/tiptap-editor'
@@ -118,6 +181,55 @@ export const MyFeature: FeaturePlugin = {
 }
 ```
 
+### 含浮层和状态共享的完整示例
+
+如果 feature 需要一个持久渲染的浮层（如对话框），并且工具栏按钮需要触发它，使用 `controlComponent` + `ctx.provide`：
+
+```typescript
+import { ref, defineComponent, h } from 'vue'
+import type { FeaturePlugin } from '@mario9/tiptap-editor'
+import MyExtension from './MyExtension'
+import MyToolbarButton from './MyToolbarButton.vue'
+import MyControlPanel from './MyControlPanel.vue'
+
+export const MyFeature: FeaturePlugin = {
+  name: 'my-feature',
+
+  install(ctx) {
+    // per-instance 状态（多个编辑器实例互不干扰）
+    const isOpen = ref(false)
+    const openPanel = () => { isOpen.value = true }
+
+    // 通过 provide 共享给工具栏按钮
+    ctx.provide('openMyPanel', openPanel)
+
+    // 闭包组件，捕获 per-instance 状态
+    const ControlWrapper = defineComponent({
+      setup: () => () => h(MyControlPanel, {
+        visible: isOpen.value,
+        'onUpdate:visible': (v: boolean) => { isOpen.value = v },
+      }),
+    })
+
+    return {
+      extensions: [MyExtension],
+      controlComponent: ControlWrapper,  // 渲染在编辑器内容区之后
+    }
+  },
+
+  toolbarComponent: MyToolbarButton,
+}
+```
+
+工具栏按钮通过 `inject` 获取共享函数：
+
+```typescript
+// MyToolbarButton.vue
+import { inject } from 'vue'
+
+const openMyPanel = inject<() => void>('openMyPanel')
+```
+
 `install()` 接收 `PluginInstallContext`（含 `readonly`、`provide`、`upload`），返回 `{ extensions, controlComponent? }`。
 
 ## 内置功能（始终启用）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mario9/tiptap-editor",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "基于 Tiptap + Vue 3 的富文本编辑器组件。",
   "type": "module",
   "main": "./dist/tiptap-editor.umd.cjs",
@@ -43,6 +43,12 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "build:lib": "vue-tsc -b && vite build --mode lib",
+    "preview": "vite preview"
+  },
   "peerDependencies": {
     "@tiptap/core": "^3.22.5",
     "@tiptap/extension-bubble-menu": "^3.22.5",
@@ -67,7 +73,6 @@
     "lowlight": "^3.3.0",
     "vue": "^3.5.0"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@vitejs/plugin-vue": "^6.0.2",
@@ -79,11 +84,5 @@
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.4",
     "vue-tsc": "^3.1.5"
-  },
-  "scripts": {
-    "dev": "vite",
-    "build": "vue-tsc -b && vite build",
-    "build:lib": "vue-tsc -b && vite build --mode lib",
-    "preview": "vite preview"
   }
-}
+}