文稿书签说明

概述

书签功能是传统文档中的一项重要特性，允许用户在文档中标记特定位置或内容区域，并通过 API 接口对这些标记进行读取和替换操作。该功能特别适用于模板文档、合同填空、自动化文档生成等业务场景。

什么是书签功能

书签的概念

书签是在文档中设置的标记点，每个书签包含两个核心属性：

书签名：书签的唯一标识符，用于在 API 调用中引用特定书签

框选范围：书签标记的文档内容区域（可以为空）

主要用途

模板文档处理：在文档模板中预设填空位置

合同自动化：批量填写合同中的变量内容

文档内容替换：程序化更新文档中的特定内容

内容定位：快速定位和操作文档中的关键区域

书签设置方法

书签设置

书签只能在前端编辑器中手动设置，我们不提供通过 API 接口创建或设置书签的功能。用户需要通过以下步骤在编辑器中设置书签：

在传统文档编辑器中打开文档

选择要设置书签的内容区域（可选择文本内容，也可以只设置位置点）

通过编辑器的书签功能创建书签并命名

操作示例

📋 书签属性说明

属性	说明	是否必需	示例
书签名	书签的唯一标识符，用于 API 调用	✅ 必需	`customer_name`, `contract_date`, `amount`
框选范围	书签标记的文档内容区域	❌ 可选	可以是一段文字，也可以是空的位置点

框选范围示例：

有内容的书签：选中"[客户姓名]"文字后设置书签

空位置书签：在空白位置设置书签作为插入点

API 接口说明

我们提供了两个核心的书签操作接口，支持读取和替换书签内容：

1. 读取传统文档书签内容

功能：根据书签名获取书签当前的内容

适用场景：

获取模板中的占位符内容

检查书签当前状态

内容提取和分析

基本调用流程：

输入：书签名 → API 处理 → 输出：书签内容

应用示例：

读取合同模板中"甲方名称"书签的当前内容

获取文档中所有书签的内容进行数据分析

2. 替换传统文档书签内容

功能：将指定书签的内容替换为新的内容

核心参数：

书签名：要替换的书签标识

替换内容：新的内容值

类型：替换内容的类型（text 或 document）

替换类型说明

文本替换 (type: "text")

用途：将书签内容替换为指定的文本

工作原理：

书签位置: [客户姓名] → 替换为: "张三" → 结果: 张三

应用场景：

合同中填写客户姓名、金额、日期等

模板文档中的变量替换

标准化文档的批量生成

文档替换 (type: "document")

用途：将另一个传统文档的完整内容插入到书签位置

工作原理：

书签位置: [附件内容] → 文档B的ID → 结果: 文档B的完整内容

应用场景：

合同中插入标准条款文档

报告中嵌入子报告内容

模板中插入可变的文档片段

接口调用示例

文本替换示例：

{
  "bookmark_name": "customer_name",
  "type": "text",
  "value": "XX科技有限公司"
}

文档替换示例：

{
  "bookmark_name": "contract_terms",
  "type": "document",
  "value": "doc_id_12345"
}

典型应用场景

企业合同管理

场景描述：企业有标准合同模板，需要为不同客户生成个性化合同

实现流程：

在合同模板中设置书签：customer_name、contract_amount、contract_date

通过 API 批量替换书签内容

自动生成个性化合同文档

业务价值：

提高合同生成效率

减少人工错误

标准化合同格式

报告自动化生成

场景描述：定期生成包含动态内容的业务报告

实现流程：

创建报告模板，设置数据书签

系统自动获取最新业务数据

通过 API 替换书签内容生成最终报告

业务价值：

自动化报告生成

数据实时更新

减少重复劳动

文档模块化管理

场景描述：大型文档由多个可变模块组成

实现流程：

主文档设置模块书签

各模块内容存储为独立文档

根据需求动态组合文档内容

业务价值：

内容模块化管理

灵活的文档组合

便于内容维护更新

技术特性

✅ 支持的功能

✅ 书签内容读取

✅ 文本内容替换

✅ 文档内容插入

✅ 批量书签操作

✅ 支持中文书签名

✅ 空书签位置插入

使用限制

不支持通过 API 创建书签，书签必须在前端编辑器中手动设置

书签名在同一文档中必须唯一

替换操作会覆盖原有内容

最佳实践建议

书签命名规范

使用描述性名称：customer_name 而不是 bookmark1

保持命名一致性：统一使用下划线或驼峰命名

避免特殊字符：使用字母、数字和下划线

考虑国际化：如需支持多语言，使用英文命名

操作流程优化

模板设计阶段：提前规划所有需要的书签位置

测试验证：在生产环境前充分测试书签替换效果

错误处理：处理书签不存在或替换失败的情况

版本管理：维护模板文档的版本，确保书签一致性

性能考虑

批量操作：尽可能通过同一次请求批量处理多个书签替换

内容大小：注意插入文档的大小，避免性能问题

并发控制：合理控制同时操作的文档数量

概述#

什么是书签功能#

书签的概念#

主要用途#

书签设置方法#

操作示例#

📋 书签属性说明#

API 接口说明#

1. 读取传统文档书签内容#

2. 替换传统文档书签内容#

替换类型说明#

文本替换 (type: "text")#

文档替换 (type: "document")#

接口调用示例#

典型应用场景#

企业合同管理#

报告自动化生成#

文档模块化管理#

技术特性#

✅ 支持的功能#

使用限制#

最佳实践建议#

书签命名规范#

操作流程优化#

性能考虑#

概述

什么是书签功能

书签的概念

主要用途

书签设置方法

操作示例

📋 书签属性说明

API 接口说明

1. 读取传统文档书签内容

2. 替换传统文档书签内容

替换类型说明

文本替换 (type: "text")

文档替换 (type: "document")

接口调用示例

典型应用场景

企业合同管理

报告自动化生成

文档模块化管理

技术特性

✅ 支持的功能

使用限制

最佳实践建议

书签命名规范

操作流程优化

性能考虑