在本仓库运行 pnpm run build:editor 会生成 dist-editor/：入口 JS、doco-text-editor.d.ts、style.css 以及 Mermaid 的按需分块都在该目录中。复制或发布时必须保留整个目录；React 和 React DOM 由使用方提供。

最小用法

import { useRef } from 'react'
import { DocoTextEditor, type DocoTextEditorRef } from 'doco-text-editor'
import 'doco-text-editor/style.css'

export function DescriptionEditor() {
  const editorRef = useRef<DocoTextEditorRef>(null)

  return (
    <DocoTextEditor
      ref={editorRef}
      defaultValue="# 任务说明"
      format="markdown"
      onChange={(change) => {
        // 高频回调只包含本次 ProseMirror 增量步骤。
        enqueueChanges(change.steps)
      }}
    />
  )
}

不传 uploadImage 时，图片会作为 data URL 嵌入文档，因此组件不需要后端也能工作。业务项目有附件服务时，应注入自己的上传函数：

<DocoTextEditor
  defaultValue={{ type: 'doc', content: [] }}
  uploadImage={async (file) => {
    const result = await myAttachmentApi.upload(file)
    return { id: result.id, src: result.publicUrl }
  }}
/>

传入 uploadImage={null} 会关闭文件选择、图片拖放和图片粘贴。

纯组件默认不会请求任何 PlantUML 服务。需要该能力时，可以显式使用内置的公共服务适配器，或注入自己的渲染服务：

import { DocoTextEditor, renderPlantUMLWithPublicServer } from './editor/standalone'

<DocoTextEditor renderPlantUML={renderPlantUMLWithPublicServer} />

涉及私密文档时应传入自托管实现，不要使用公共渲染服务。仓库中的独立 Demo 为了展示完整能力，显式启用了上述公共服务适配器；正文内容仍只保存在浏览器 IndexedDB。

内容与保存

format="tiptap-json"：无损保留全部 Doco 节点，适合作为编辑态主格式。
format="markdown"：适合 ClickUp 等只接收 Markdown 的后端。
format="html"：适合普通富文本接口。
onChange({ steps }) 只返回本次事务的 ProseMirror JSON 增量步骤，不在每次输入时生成整篇文档。
ref.getContent(format) 按需取得完整内容，支持 tiptap-json、markdown、html 和 text。
ref.getRootElement() 可取得对应 DOM。

const json = editorRef.current?.getContent('tiptap-json')
const markdown = editorRef.current?.getContent('markdown')
const html = editorRef.current?.getContent('html')
const text = editorRef.current?.getContent('text')

如果后端只接受完整文档，可以在 onChange 中仅安排一次防抖保存，定时器真正执行时再调用 getContent('tiptap-json')；如果后端支持增量同步，则可以直接保存或传输 steps。

未来对接 ClickUp 时，建议以 Tiptap JSON 作为本地编辑态，通过 ref.getContent('tiptap-json') 找出 ClickUp 不支持的节点，再用节点的 data-block-id 在 ref.getRootElement() 中定位 DOM、渲染成图片、上传后替换成 Markdown 图片。这个转换属于 ClickUp Adapter，不应写进编辑器核心。