跳转到主要内容

​
内容写入

​
如何将 Markdown 格式的内容写入钉钉文档？

  • 方式一：插入内容（追加，不影响已有内容） 调用插入内容接口，将 Markdown 内容插入到文档指定位置： 
    curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{documentId}/content?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "content": {
    "type": "markdown",
    "content": "# 一级标题\n\n这是一段正文内容。"
  }
}'
  • 方式二：覆写文档（清空后重写） 调用覆写文档（应用授权）接口，以 Markdown 格式覆写文档全部内容： 
    curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/overwriteContent?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "content": "# 文档标题\n\n正文内容。",
  "dataType": "markdown"
}'
    覆写文档会清空文档现有全部内容，属于破坏性操作，请谨慎使用。如果只需追加内容，请使用插入内容接口。

​
块元素操作

​
如何插入带内容的段落

调用插入块元素接口，在文档中插入一个段落块，并通过children字段指定段落内的行内元素： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{dentryUuid}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "paragraph",
    "paragraph": {},
    "children": [
      {
        "text": "这是一段加粗的红色文字",
        "bold": true,
        "color": "#FF5733"
      },
      {
        "elementType": "sticker",
        "properties": { "code": "大笑" }
      }
    ]
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "result": {
    "data": {
      "paragraph": { "text": "这是一段加粗的红色文字" },
      "blockType": "paragraph",
      "index": 0,
      "id": "......"
    }
  },
  "success": true
}
paragraph对象不能被省略，即使段落无特殊属性，也需要传入空对象{}。

​
如何在文档指定位置（而非末尾）插入块元素

调用插入块元素接口时，通过blockId或index指定目标位置，并通过where参数控制插入到目标位置之前还是之后： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "paragraph",
    "paragraph": {}
  },
  "blockId": "lc4si5p3n84zwqxxx",
  "where": "before"
}'
参数说明
blockId目标块的唯一标识，插入到该块之前或之后
index当blockId不存在时，使用文档第index个一级块作为目标位置（从 0 开始）
where"before"表示插入到目标位置之前，"after"表示之后（默认为"after"）

​
如何插入标题

调用插入块元素接口，将blockType设置为heading，并在heading对象中通过level指定标题级别（1~6）： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "heading",
    "heading": {
      "level": 2,
      "text": "这是一个二级标题"
    }
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "success": true
}
heading.level 与标题级别的对应关系：
level 值对应标题
1一级标题（H1）
2二级标题（H2）
3三级标题（H3）
4四级标题（H4）
5五级标题（H5）
6六级标题（H6）

​
如何插入引用块

调用插入块元素接口，将blockType设置为blockquote，并在blockquote对象中传入引用内容： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "blockquote",
    "blockquote": {
      "text": "这是一段引用内容"
    }
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "result": {
    "data": {
      "blockType": "blockquote",
      "index": 4,
      "id": "......"
    }
  },
  "success": true
}

​
如何插入高亮块并在其中嵌套段落

高亮块的children只能是BlockElement数组。调用插入块元素接口时，在children中传入子段落： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "callout",
    "callout": {
      "sticker": "灯泡",
      "showstk": true,
      "bgcolor": "#FFF9C4",
      "border": "#FFD700"
    },
    "children": [
      {
        "blockType": "paragraph",
        "paragraph": { "text": "这是高亮块内的段落内容" }
      }
    ]
  }
}'
不同类型块元素的children类型不同：段落块的children只能是行内元素；高亮块的children只能是块元素。

​
如何插入分栏

调用插入块元素接口，将blockType设置为columns，通过columns.size指定分栏数量，并在children中传入各栏的块元素内容： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "columns",
    "columns": {
      "size": 2,
      "noFill": false
    },
    "children": [
      {
        "blockType": "paragraph",
        "paragraph": { "text": "左栏内容" }
      },
      {
        "blockType": "paragraph",
        "paragraph": { "text": "右栏内容" }
      }
    ]
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "result": {
    "data": {
      "columns": { "size": 2 },
      "blockType": "columns",
      "index": 7,
      "id": "......"
    }
  },
  "success": true
}
columns 对象的字段说明：
字段类型说明
sizeNumber分栏数量
noFillBoolean是否自动填充背景色，默认false
columns的children只能是 BlockElement 数组，不能是行内元素。

​
如何插入有序列表

调用插入块元素接口，将blockType设置为orderedList，并在orderedList对象中传入列表属性，在children中传入列表项文本： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "orderedList",
    "orderedList": {
      "list": {
        "listId": "my-ordered-list-001",
        "level": 0,
        "listStyleType": "decimal",
        "listStyle": {
          "format": "decimal",
          "text": "%1.",
          "align": "left"
        }
      }
    },
    "children": [
      { "text": "有序列表第一项" }
    ]
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "result": {
    "data": {
      "blockType": "orderedList",
      "index": 6,
      "id": "......"
    }
  },
  "success": true
}
list 对象的常用字段说明：
字段类型说明
listIdString列表的唯一标识，同一列表的多个列表项应使用相同的listId
levelNumber列表缩进层级，从0开始
listStyleTypeString列表样式类型，有序列表使用"decimal"

​
如何插入无序列表

调用插入块元素接口，将blockType设置为unorderedList，并在unorderedList对象中传入列表属性，在children中传入列表项文本： 
curl --location --request POST 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
  "element": {
    "blockType": "unorderedList",
    "unorderedList": {
      "list": {
        "listId": "my-unordered-list-001",
        "level": 0,
        "listStyleType": "disc",
        "listStyle": {
          "format": "disc",
          "text": "%1",
          "align": "left"
        }
      }
    },
    "children": [
      { "text": "无序列表第一项" }
    ]
  }
}'
如果调用成功，预计将返回以下格式数据： 
{
  "result": {
    "data": {
      "blockType": "unorderedList",
      "index": 8,
      "id": "......"
    }
  },
  "success": true
}
有序列表和无序列表的listId用于将多个列表项关联为同一个列表。若要插入同一列表的多个列表项，每个列表项应使用相同的listId，可通过 BatchOperate 批量接口一次性插入。

​
查询操作

​
如何获取文档中所有块元素的 blockId？

调用查询块元素接口，获取文档根节点下的一级块元素列表，每个元素包含其id（即blockId）： 
curl --location --request GET 'https://api.dingtalk.io/v1.0/doc/suites/documents/{docKey}/blocks?operatorId={operatorId}' \
--header 'x-acs-dingtalk-access-token: {ACCESS_TOKEN}'
如果调用成功，预计将返回以下格式数据： 
{
  "success": true,
  "result": {
    "data": [
      {
        "heading": { "level": "heading-1", "text": "文档标题" },
        "blockType": "heading",
        "index": 0,
        "id": "......"
      },
      {
        "paragraph": { "text": "正文内容。" },
        "blockType": "paragraph",
        "index": 1,
        "id": "......"
      }
    ]
  }
}
目前查询块元素接口仅支持查询文档根节点下的一级块元素，不支持递归查询嵌套在高亮块等容器内的子块元素。