{"_id":"@huyooo/vue-tiptap","_rev":"67-af569fe9528c5d75bd70ef37ec4ec504","name":"@huyooo/vue-tiptap","dist-tags":{"latest":"1.0.5"},"versions":{"0.0.7":{"name":"@huyooo/vue-tiptap","version":"0.0.7","_id":"@huyooo/vue-tiptap@0.0.7","maintainers":[{"name":"grasilife","email":"434543162@qq.com"}],"dist":{"shasum":"336f469f80436fe589d0f6a14a5df145509b7a38","tarball":"https://registry.npmjs.org/@huyooo/vue-tiptap/-/vue-tiptap-0.0.7.tgz","fileCount":8,"integrity":"sha512-pqs2C6P2EwByXahK+AZwCfz6TeZnjgs9WkuLtGpCIgNWYRPrhhnX6HU7jnmSA9RPmj7asAyui0K25CdLQ1am1w==","signatures":[{"sig":"MEUCIHFM4JRAQ422o2S4fEE8ZI1zIQMWKVlViBV6Xjekmm6cAiEAl6gZc/SdvorpPhvBgBe02ojHFm+MF5HO9/SWCk6dxpI=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":7184},"type":"module","gitHead":"6ff89ee81b0cdd11baeacadbf303c01c57d39ce3","private":false,"scripts":{"dev":"vite","pub":"npm version patch --force && npm publish --access public","build":"vue-tsc -b && vite build","preview":"vite preview"},"_npmUser":{"name":"grasilife","email":"434543162@qq.com"},"_npmVersion":"10.7.0","description":"This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `\n```\n\n必须引入样式：\n\n```ts\nimport '@huyooo/vue-tiptap/style.css'\n```\n\n## 组件 API\n\n### `TiptapEditor`\n\n| 属性 | 类型 | 默认值 | 说明 |\n| --- | --- | --- | --- |\n| `v-model` | `JSONContent \\| null` | `null` | 编辑器内容，TipTap JSON 格式。 |\n| `editable` | `boolean` | `true` | 是否可编辑。只读模式下不显示工具栏、图片缩放点和图片菜单。 |\n| `autofocus` | `boolean` | `true` | 是否自动聚焦。弹窗中建议传 `false`。 |\n| `limit` | `number \\| null` | `null` | 字数限制。 |\n| `tiptapEditorContentClass` | `string` | `''` | 追加到编辑器根容器上的 class。 |\n| `uploadImage` | `(file: File) => Promise` | `undefined` | 图片上传回调，返回可访问图片 URL。可编辑模式下建议必传。 |\n\n### 事件\n\n| 事件 | 参数 | 说明 |\n| --- | --- | --- |\n| `tableOfContentsUpdate` | `unknown` | 目录数据更新。 |\n\n### 暴露方法\n\n`TiptapEditor` 通过 `defineExpose` 暴露：\n\n| 方法 | 说明 |\n| --- | --- |\n| `getEditor()` | 获取 TipTap Editor 实例。 |\n| `scrollView(id: string)` | 根据 `data-toc-id` 滚动到对应标题。 |\n\n## 内容格式\n\n编辑器读写 TipTap JSON，不是 HTML 或 Markdown。推荐数据库字段直接存储 JSON：\n\n```json\n{\n \"type\": \"doc\",\n \"content\": [\n {\n \"type\": \"paragraph\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Hello\"\n }\n ]\n }\n ]\n}\n```\n\n空文档建议使用：\n\n```ts\nconst emptyDoc = {\n type: 'doc',\n content: [{ type: 'paragraph' }],\n}\n```\n\n## 图片上传\n\n### 上传流程\n\n1. 用户粘贴或拖拽图片到编辑器。\n2. 编辑器先插入图片占位节点，显示“图片上传中”。\n3. 调用 `uploadImage(file)`。\n4. 上传成功后，将占位节点替换成真实图片 URL，并显示“图片加载中”直到图片资源加载完成。\n5. 上传失败时移除占位图。\n\n`uploadImage` 只负责上传并返回 URL：\n\n```ts\ntype UploadImageFn = (file: File) => Promise\n```\n\n返回值必须是浏览器可以访问的图片地址，例如 CDN URL、签名 URL 或公开 URL。\n\n### 撤销行为\n\n上传完成替换 URL 不进入 undo 历史。用户粘贴图片后按撤销，会直接删除整张图片，不会退回“图片上传中”的占位状态。\n\n### 临时文件清理\n\n编辑器组件无法知道业务侧“是否最终保存文章”，因此临时文件清理由宿主业务负责。\n\n推荐做法：\n\n- 打开编辑弹窗时记录已有图片 key，作为 `baselineKeys`。\n- 本次弹窗中上传成功的图片记录到 `sessionUploadedKeys`。\n- 用户取消或关闭弹窗时，删除 `sessionUploadedKeys - baselineKeys`。\n- 保存成功后，只保留当前内容仍引用的本次上传图片，其余删除。\n- 如果弹窗关闭后上传才完成，上传回调应立即删除该文件，避免永久残留。\n- 保存前如果还有图片上传中，应阻止保存，避免把 loading 占位写入数据库。\n\n业务侧可以从 TipTap JSON 中递归收集图片节点：\n\n```ts\nfunction collectImageSrcs(node: any, result = new Set()) {\n if (node?.type === 'image' && typeof node.attrs?.src === 'string') {\n result.add(node.attrs.src)\n }\n node?.content?.forEach((child: any) => collectImageSrcs(child, result))\n return result\n}\n```\n\n如果你的系统保存的是对象存储 key，建议在保存前把临时签名 URL 归一化为稳定 key，避免过期 URL 写入数据库。\n\n## 图片交互\n\n### 缩放\n\n图片选中后显示四角 + 四边中点共 8 个缩放点。缩放规则：\n\n- 永远保持宽高比。\n- 四角和四边中点都按图片中心等比缩放。\n- 最大宽度不超过编辑器内容区域。\n- loading 状态下不显示缩放点，避免上传/加载过程中误操作。\n\n### 对齐\n\n图片是块级节点。对齐通过图片外层行容器实现：\n\n- 左对齐：图片靠左。\n- 居中：图片居中。\n- 右对齐：图片靠右。\n\n选中图片时：\n\n- 外层虚线表示图片所在行和对齐范围。\n- 图片本体实线表示真实图片边界。\n- 图片工具栏左/中/右按钮会与当前图片 `align` 属性实时同步。\n\n### 拖拽\n\n图片支持拖拽移动位置。拖拽图片本体时，编辑器会显示紫色 drop cursor，表示图片将插入的位置。\n\n注意：\n\n- loading 状态图片不可拖拽。\n- 缩放点拖拽只处理缩放，不触发移动。\n- 拖拽移动由 ProseMirror 节点拖拽机制处理。\n\n## 只读模式\n\n只读模式：\n\n```vue\n\n```\n\n只读模式不会显示：\n\n- 顶部编辑工具栏\n- 图片工具栏\n- 图片缩放点\n- 表格行列菜单\n\n## 样式说明\n\n本包发布一个独立样式文件：\n\n```ts\nimport '@huyooo/vue-tiptap/style.css'\n```\n\n如果宿主项目使用局部滚动容器或弹窗，请确保编辑器外层有明确高度或最小高度：\n\n```vue\n\n```\n\n## 导出内容\n\n```ts\nimport {\n TiptapEditor,\n Aside,\n Toc,\n RepositorieTitle,\n TiptapTitle,\n} from '@huyooo/vue-tiptap'\n\nimport type {\n UploadImageFn,\n ModelType,\n Option,\n ShouldShowProps,\n} from '@huyooo/vue-tiptap'\n```\n\n## 构建与发布\n\n### 本地构建\n\n```bash\nnpm run build\n```\n\n构建产物：\n\n- `dist/index.js`\n- `dist/style.css`\n- `dist/**/*.d.ts`\n\n### 预览 npm 包内容\n\n```bash\nnpm pack --dry-run\n```\n\n发布前建议确认：\n\n- 包中只包含 `dist`、`README.md`、`package.json` 等必要文件。\n- 不包含 `public/vite.svg`、源码临时文件、测试产物。\n- `dist/index.js` 没有把 Vue 和 TipTap 全量打包进去。\n\n### 发布\n\n```bash\nnpm run release\n```\n\n`release` 会执行版本选择并发布：\n\n```bash\nbumpp && npm publish\n```\n\n如果需要直接 patch 并发布：\n\n```bash\nnpm run pub\n```\n\n发布前必须执行：\n\n```bash\nnpm run build\nnpm pack --dry-run\n```\n\n### 依赖发布原则\n\n- 不要在 npm 尚未发布新版本前，提前把下游项目依赖改到不存在的版本。\n- 发布完成并确认 npm 上存在新版本后，下游项目再显式升级版本号。\n- 下游依赖版本要写明确的新版本，例如从 `^1.0.0` 升到 `^1.0.1`，不要只依赖旧 semver 范围自动漂移。\n\n## 依赖策略\n\n本包使用库模式构建，并 external 掉主要依赖。\n\n这表示构建 `dist/index.js` 时不会把 Vue、TipTap 等依赖源码复制进 bundle，但 npm 安装时仍会自动安装 `dependencies` 中的依赖。\n\n当前策略：\n\n- `vue`：`peerDependencies`，宿主项目必须提供，避免出现多个 Vue 实例。\n- `@tiptap/*`、`lowlight`、`vue-color-kit`、`@iconify/vue`：`dependencies`，安装本包时自动安装。\n- 构建时 external 所有上述依赖，减少产物体积并避免重复打包。\n\n## 常见问题\n\n### 为什么安装后还要引入 `style.css`？\n\n库模式会把 CSS 输出为独立文件。宿主项目需要显式引入：\n\n```ts\nimport '@huyooo/vue-tiptap/style.css'\n```\n\n### 为什么不把 TipTap 全部打进 `index.js`？\n\n不打进 bundle 可以显著减少产物体积，并让 npm 依赖树正常去重。TipTap 仍在 `dependencies` 里，使用方安装本包时会自动安装。\n\n### 为什么 Vue 是 peer dependency？\n\nVue 必须由宿主项目提供，确保应用中只有一套 Vue 实例，避免响应式、插件上下文和组件渲染异常。\n\n### 图片上传后关闭弹窗会自动删除吗？\n\n组件本身不知道业务弹窗是否保存成功，不会自动删除远端文件。宿主业务必须按“临时上传会话”清理未保存文件。\n\n### 数据库存 HTML 还是 JSON？\n\n推荐存 TipTap JSON。HTML 可以用于渲染导出，但不建议作为主存储格式。\n","readmeFilename":"README.md"}