JitWord SDK API 使用文档

1. 文档概览

JitWord SDK 的目标很明确：让客户可以更简单地将协同文档编辑器集成到自己的 Web 应用中，并通过统一的可配置参数和开放 API，对编辑器行为进行精细控制。

能力范围

支持本地文件方式引入 SDK
支持 Vue、React、Angular 与原生 HTML
提供内容级、实例级、REST 级三层 API
支持快速上手，也支持深度定制

2. 快速开始

如果您希望最快把编辑器运行起来，按照下面 3 步即可完成基础接入。建议优先通过本地静态服务器调试，而不是直接双击 HTML 文件。

2.1 引入 SDK

您可以通过本地文件方式引入 SDK 及依赖。下面是最基础的资源结构。

              
              
              
              index.html
            

<!-- 1. 引入样式 -->
<link rel="stylesheet" href="path/to/arco.css">
<link rel="stylesheet" href="path/to/px-editor.css">

<!-- 2. 引入依赖库 -->
<script src="path/to/vue.global.prod.js"></script>
<script src="path/to/arco-vue.min.js"></script>
<script src="path/to/arco-vue-icon.min.js"></script>
<script src="path/to/echarts.min.js"></script>
<script src="path/to/mind-elixir.js"></script>

<!-- 3. 引入 JitWord SDK -->
<script src="path/to/px-editor.standalone.js"></script>
            

2.2 初始化编辑器

准备一个容器节点，然后使用 Jitword 类完成实例化。为了避免依赖尚未加载完成，建议在 window.onload 中执行。

              
              
              
              standalone.js
            

<div id="col-editor" style="height: 100vh;"></div>

window.onload = function () {
  const { Jitword } = window.PxEditor;

  const editor = new Jitword({
    hold: "col-editor",
    appTitle: "JitWord 协作文档",
    logo: "https://jitword.com/logo.png",
    enableAI: true,
    baseApiUrl: "/api/v1",
    wsServer: "wss://your-server.com/ws",
    enableCollaboration: true
  });
};
            

2.3 本地测试与部署

不要直接使用 file:// 协议打开 HTML 文件。

直接双击 HTML 往往会触发 CORS 错误、401 认证失败或资源加载异常。请使用本地静态服务器来调试。

方法 1: Python HTTP Server

bash
cd /path/to/your/project
python3 -m http.server 8080

方法 2: Node.js http-server

bash
npx http-server -p 8080

方法 3: VS Code Live Server

安装 Live Server 扩展后，右键 HTML 文件，选择 “Open with Live Server” 即可。

方法 4: PHP 内置服务器

bash
php -S localhost:8080

测试检查清单

浏览器地址栏为 http://localhost:8080/...，而不是 file://
浏览器控制台没有 CORS 报错
编辑器可正常加载与编辑
如启用协同，WebSocket 连接成功

3. 配置项

初始化 new Jitword(config) 时，可通过配置项控制标题、只读模式、协同开关、上传回调、页面设置、AI 按钮等行为。下面按能力进行分组说明。

3.1 基础配置

参数名	类型	必填	默认值	说明
`hold`	string \| HTMLElement	是	-	编辑器挂载节点 ID 或 DOM 元素。
`appTitle`	string	否	JitWord 协同文档	显示在编辑器头部的应用标题。
`appTitleShort`	string	否	JitWord	移动端简短标题。
`documentTitle`	string	否	未命名文档	当前文档标题。
`logo` / `logoSrc`	string	否	-	Logo 图片 URL。
`logoHref`	string	否	/	点击 Logo 的跳转地址。
`locale`	'zh' \| 'en'	否	zh	界面语言。
`theme`	'light' \| 'dark'	否	light	主题模式。
`placeholder`	string	否	请输入文档内容...	编辑器空状态占位文本。

3.2 编辑器功能配置

参数名	类型	默认值	说明
`editable`	boolean	true	是否可编辑。
`readMode`	boolean	false	只读模式，优先级高于 `editable`。
`showScrollNav`	boolean	true	显示右下角滚动导航。
`showFloatToolBar` / `showRightToolbar`	boolean	true	显示右侧浮动工具栏。
`hideToc`	boolean	false	隐藏目录 TOC。
`hideFooter`	boolean	false	隐藏底部状态栏。
`hideBubbleMenu`	boolean	false	隐藏气泡菜单。
`showPageSettings`	boolean	true	显示页面设置按钮。

3.3 协同编辑配置

参数名	类型	默认值	说明
`enableCollaboration`	boolean	true	是否启用协同编辑。
`enableCollaborationCursor`	boolean	true	是否显示协同光标。
`wsServer`	string	-	WebSocket 服务地址，启用协同时必填。
`currentDocumentId`	string	-	推荐设置，生成稳定的协同房间名。
`roomName`	string	自动生成	不设置时自动使用 `doc-{currentDocumentId}`。
`resetCollabState`	boolean	false	是否每次刷新生成新房间。通常保持 `false`。
`user`	object	-	用户信息，如 `{ name, color }`。

重要：resetCollabState 默认为 false。若设为 true，每次刷新都会创建新房间，不适合持久协作场景。

3.4 数据与回调

参数名	类型	说明
`value`	object \| string	受控模式或已有数据回显，优先级高于 `defaultValue`。
`defaultValue`	object \| string	非受控模式的默认内容。
`enableAutoSave`	boolean	启用自动保存。
`enableAutoLoad`	boolean	启用自动加载。
`onChange`	(content) => void	内容变化回调。
`onSave`	({ content, currentDocumentId }) => void	保存回调。
`onEditorReady`	(editor) => void	编辑器就绪回调。
`uploadAPI` / `uploadFn`	(file) => Promise<string>	文件上传函数，返回 URL。
`baseApiUrl`	string	后端 API 基础路径。
`onShare` / `onAi` / `onVersion` 等	function	各类 UI 事件回调。

支持的数据格式

value 与 defaultValue 同时支持 JSON 与 HTML 格式。建议优先使用 JSON 以便与编辑器 schema 更稳定地对齐。

JSON 格式

json
{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "标题内容" }]
    }
  ]
}

HTML 格式

html
<h1>标题内容</h1>
<p>正文内容...</p>

4. 内容 API

除了传统的 setContent、getJSON、getHTML 等方法外，新版 SDK 还支持第一阶段的元素级 API，方便开发者直接操作文档顶层 block 元素。

4.1 支持的顶层元素范围

paragraph

heading

image

attachment

divider

bulletList

orderedList

columns

table

chart

mindmap

flowchart

这里的“元素”指文档顶层 block 元素。
index 表示顶层元素序号，从 0 开始。
若未传 id，SDK 会自动生成唯一 ID。
在只读模式下，所有写操作会被拒绝。

4.2 元素操作方法

插入元素

ts
insert(index?: number, element: SDKElement): SDKElement

js
const element = editor.insert(1, {
  type: 'paragraph',
  data: {
    text: '这是一段通过 insert() 插入的文本'
  }
})

console.log(element.id)

获取元素

ts
getElementById(elementId: string): SDKElement | null

删除元素

ts
deleteElementById(elementId: string): boolean

更新元素

ts
updateElement(elementId: string, patch: Partial<SDKElement>): SDKElement | null

updateElement 采用 patch 语义，只更新传入字段，不会清空未传字段。

SDKElement 结构

ts
type SDKElement = {
  id?: string
  type: 'paragraph' | 'heading' | 'image' | 'attachment' | 'divider' | 'bulletList' | 'orderedList'
  data?: Record<string, any>
  style?: Record<string, any>
  meta?: Record<string, any>
}

常见元素示例

段落与标题

js
editor.insert({
  type: 'heading',
  data: {
    level: 2,
    text: '这是一个二级标题'
  }
})

图片与附件

js
editor.insert({
  type: 'attachment',
  data: {
    url: 'https://example.com/demo.pdf',
    name: '演示附件.pdf'
  }
})

4.3 导入导出

SDK 支持在现有文档中执行替换、追加、插入式导入，也支持导出为 docx、pdf、md、json、html 等格式。

ts
importFile(
  type: 'docx' | 'md' | 'html' | 'json',
  file: File,
  options?: {
    mode?: 'replace' | 'append' | 'insert'
    index?: number
    docxEngine?: 'docx4js' | 'mammoth'
  }
): Promise<SDKImportResult>

ts
exportFile(
  type: 'docx' | 'pdf' | 'md' | 'json' | 'html',
  options?: {
    autoDownload?: boolean
    filename?: string
  }
): Promise<Blob | boolean>

replace 会替换当前内容。
append 会把导入内容追加到文末。
insert 会把导入内容插入到指定顶层位置。
autoDownload = true 时自动下载，返回 true。
autoDownload = false 时返回 Blob。

5. 实例 API

除元素级 API 外，Jitword 实例还保留了一组更通用的编辑器方法，适合内容回显、只读切换、文档切换与生命周期管理。

方法名	参数	返回值	说明
`getJData()`	-	object	获取文档 JSON 数据。
`getHtml()`	-	string	获取 HTML 内容。
`setData(data)`	object \| string	void	设置文档内容，支持 JSON 或 HTML。
`setEditable(editable)`	boolean	void	设置编辑器是否可编辑。
`getEditor()`	-	Editor	获取底层 TipTap Editor 实例。
`setCurrentDocumentId(docId)`	string	void	切换当前文档 ID，并触发协同房间切换。
`destroy()`	-	void	销毁实例并释放资源。

返回值与错误约定

getElementById 找不到元素时返回 null。
deleteElementById 删除成功返回 true，找不到返回 false。
insert 与 updateElement 失败时抛出异常。

常见错误场景

编辑器尚未 ready 即调用实例方法
当前实例处于只读模式
传入了不支持的元素类型
元素结构与目标 schema 不匹配

js
const editor = new Jitword({ hold: 'editor-container' });

const json = editor.getJData();
const html = editor.getHtml();

editor.setData({ type: 'doc', content: [] });
editor.setEditable(false);
editor.setCurrentDocumentId('new-doc-id');

6. REST API

JitWordSDK 还提供完整的后端 REST API 调用能力，适合在业务系统中统一管理登录、文档、评论、版本与 AI 接口。

6.1 初始化 SDK

js
const { JitWordSDK } = window.PxEditor;

JitWordSDK.init({
  baseUrl: 'https://your-api-server.com/api/v1',
  tokenKey: 'jwt_token',
  onError: (err) => console.error('SDK Error:', err)
});

6.2 核心模块总览

模块	核心方法	说明
`auth`	`register` / `login` / `setToken` / `getToken`	用户注册与登录态管理。
`documents`	`list` / `get` / `create` / `rename` / `delete`	文档列表、详情、权限、页面设置等。
`comments`	`list` / `create` / `update` / `delete`	评论管理。
`versions`	`list` / `create` / `get` / `compare`	版本快照与版本对比。
`ai`	`trialStats` / `streamTrial`	AI 试用统计与流式生成。
`files`	`uploadApi` / `uploadDoc` / `uploadPdf`	文件上传与文档解析。

6.3 示例调用

js
const docs = await JitWordSDK.documents.list({
  filter: 'active',
  scope: 'mine'
});

const newDoc = await JitWordSDK.documents.create('我的新文档');

await JitWordSDK.comments.create({
  id: 'comment-123',
  documentId: 'doc-456',
  content: '这里需要修改'
});

7. 后端路由定义

如果您准备自行实现后端服务，可以直接参考以下路由定义。所有接口响应建议遵循统一的 { code, message, data } 格式。

7.1 认证路由

方法	路径	说明	请求体
POST	`/user/register`	用户注册	`{ username, password }`
POST	`/user/login`	用户登录	`{ username, password }`

7.2 文档路由

方法	路径	说明
GET	`/documents`	获取文档列表
GET	`/documents/stats`	获取文档统计
GET	`/documents/:id`	获取文档详情
POST	`/documents`	创建文档
PUT	`/documents/:id`	重命名文档
DELETE	`/documents/:id`	删除文档
PUT	`/documents/:id/restore`	恢复文档
DELETE	`/documents/:id/permanent`	永久删除
PUT	`/documents/:id/page-settings`	更新页面设置
PUT	`/documents/:id/permission`	更新权限

7.3 评论、版本、AI 与上传路由

方法	路径	说明
GET	`/comments?documentId=xxx`	获取评论列表
POST	`/comments`	创建评论
PUT	`/comments/:id`	更新评论
DELETE	`/comments/:id`	删除评论
GET	`/documents/:docId/versions`	获取版本列表
POST	`/documents/:docId/versions`	创建版本
GET	`/documents/:docId/versions/:versionId`	获取版本详情
GET	`/ai/trial/stats`	AI 试用统计
POST	`/ai/trial/stream`	AI 流式生成
POST	`/upload/free`	通用文件上传
POST	`/parse/doc2html2`	Word 文档解析
POST	`/parse/pdf2html`	PDF 文档解析

统一响应格式

json
{
  "code": 200,
  "message": "Success",
  "data": {}
}

常见状态码包括：200 成功、400 参数错误、401 未授权、403 权限不足、404 资源不存在、500 服务器内部错误。

8. 完整示例

下面给出一个独立页面 standalone.html 的最小可运行示例，适合作为 PoC、Demo 或二次封装的起点。

              
              
              
              standalone.html
            

<!DOCTYPE html>
<html lang="zh">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>JitWord - 独立构建示例</title>

  <link rel="stylesheet" href="cdn/arco.css">
  <link rel="stylesheet" href="cdn/px-editor.css">

  <script src="cdn/vue.global.prod.js"></script>
  <script src="cdn/arco-vue.min.js"></script>
  <script src="cdn/arco-vue-icon.min.js"></script>
  <script src="cdn/echarts.min.js"></script>
  <script src="cdn/mind-elixir.js"></script>
  <script src="cdn/px-editor.standalone.js"></script>

  <style>
    body { margin: 0; padding: 0; }
    #app { width: 100%; height: 100vh; }
  </style>
</head>
<body>
  <div id="app">
    <div id="col-editor" style="height: 100%"></div>
  </div>

  <script>
    window.onload = function() {
      if (!window.PxEditor) {
        console.error('PxEditor SDK 加载失败');
        return;
      }

      const { Jitword, Message } = window.PxEditor;

      const editor = new Jitword({
        hold: "col-editor",
        appTitle: "JitWord 协作文档",
        logo: "https://jitword.com/logo.png",
        logoHref: "https://jitword.com/",
        locale: "zh",
        placeholder: "在此输入内容...",
        showScrollNav: true,
        showFloatToolBar: true,
        enableAI: true,
        editable: true,
        enableCollaboration: true,
        wsServer: "wss://your-collab-server.com/ws",
        defaultValue: { type: "doc", content: [] },
        onSave: ({ content }) => {
          console.log("文档保存:", content);
          Message.success("保存成功");
        },
        onChange: () => {
          console.log("内容变更");
        },
        uploadAPI: async (file) => {
          return URL.createObjectURL(file);
        }
      });

      window.editor = editor;
    };
  </script>
</body>
</html>
            

9. 常见问题与排查

问题 1: 提示 “PxEditor SDK 加载失败”

检查 px-editor.standalone.js 文件路径是否正确。
检查 Vue、Arco、ECharts、Mind Elixir 等依赖文件是否都已加载。
打开浏览器开发者工具的 Network 面板查看失败资源。

问题 2: 编辑器功能异常

先执行硬刷新清理缓存。
确认 SDK 版本是否为最新版。
检查控制台是否存在 JavaScript 运行时错误。

问题 3: 协同功能无法连接

确认 wsServer 地址是否正确。
确认 WebSocket 服务是否可用。
检查网络环境与防火墙是否阻断 WebSocket 连接。

建议把这份文档与 SDK 示例工程一起交付给开发团队。前端可直接参考初始化与内容 API，后端可直接对照 REST API 与路由定义完成联调。

JitWord SDK API 使用文档

1. 文档概览

能力范围

推荐阅读顺序

2. 快速开始

2.1 引入 SDK

2.2 初始化编辑器

2.3 本地测试与部署

方法 1: Python HTTP Server

方法 2: Node.js http-server

方法 3: VS Code Live Server

方法 4: PHP 内置服务器

测试检查清单

3. 配置项

3.1 基础配置

3.2 编辑器功能配置

3.3 协同编辑配置

3.4 数据与回调

支持的数据格式

JSON 格式

HTML 格式

4. 内容 API

4.1 支持的顶层元素范围

4.2 元素操作方法

插入元素

获取元素

删除元素

更新元素

SDKElement 结构

常见元素示例

段落与标题

图片与附件

4.3 导入导出

5. 实例 API

返回值与错误约定

常见错误场景

6. REST API

6.1 初始化 SDK

6.2 核心模块总览

6.3 示例调用

7. 后端路由定义

7.1 认证路由

7.2 文档路由

7.3 评论、版本、AI 与上传路由

统一响应格式

8. 完整示例

9. 常见问题与排查

问题 1: 提示 “PxEditor SDK 加载失败”

问题 2: 编辑器功能异常

问题 3: 协同功能无法连接