rongshu/.agents/skills/lark-okr/references/lark-okr-contentblock.md

OKR ContentBlock 富文本格式

OKR 的 Objective、KeyResult 中的 content/notes 字段使用 ContentBlock 富文本格式。本文档描述其结构和使用方式。

ContentBlock 结构概览

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0,
            "number": 1
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "Hello World",
              "style": {
                "bold": true,
                "strike_through": false,
                "back_color": {
                  "red": 255,
                  "green": 0,
                  "blue": 0,
                  "alpha": 1
                },
                "text_color": {
                  "red": 0,
                  "green": 255,
                  "blue": 0,
                  "alpha": 1
                },
                "link": {
                  "url": "https://example.com"
                }
              }
            }
          },
          {
            "paragraph_element_type": "docsLink",
            "docs_link": {
              "url": "https://larkoffice.com/docx/xxx",
              "title": "Lark Document"
            }
          },
          {
            "paragraph_element_type": "mention",
            "mention": {
              "user_id": "ou_xxx"
            }
          }
        ]
      }
    },
    {
      "block_element_type": "gallery",
      "gallery": {
        "images": [
          {
            "file_token": "file_xxx",
            "src": "https://...",
            "width": 800,
            "height": 600
          }
        ]
      }
    }
  ]
}

类型定义

ContentBlock

根级别内容块。

字段	类型	说明
blocks	ContentBlockElement[]	内容块元素数组

ContentBlockElement

内容块元素，支持段落或图库。

字段	类型	说明
block_element_type	BlockElementType	块类型：paragraph | gallery
paragraph	ContentParagraph	段落内容（当 block_element_type="paragraph" 时）
gallery	ContentGallery	图库内容（当 block_element_type="gallery" 时）

ContentParagraph

段落内容。

字段	类型	说明
style	ContentParagraphStyle	段落样式（列表类型等）
elements	ContentParagraphElement[]	段落内元素数组

ContentParagraphElement

段落内元素，支持文本、文档链接、提及。

字段	类型	说明
paragraph_element_type	ParagraphElementType	元素类型：textRun | docsLink | mention
text_run	ContentTextRun	文本内容
docs_link	ContentDocsLink	飞书文档链接
mention	ContentMention	用户提及

ContentTextRun

文本块。

字段	类型	说明
text	string	文本内容
style	ContentTextStyle	文本样式

ContentTextStyle

文本样式。

字段	类型	说明
bold	boolean	是否粗体
strike_through	boolean	是否删除线
back_color	ContentColor	背景颜色
text_color	ContentColor	文字颜色
link	ContentLink	链接

ContentColor

颜色。

字段	类型	说明
red	int32	红色通道 (0-255)
green	int32	绿色通道 (0-255)
blue	int32	蓝色通道 (0-255)
alpha	float64	透明度 (0-1)

ContentParagraphStyle

段落样式。

字段	类型	说明
list	ContentList	列表样式

ContentList

列表样式。

字段	类型	说明
list_type	ListType	列表类型：bullet | number | checkBox | checkedBox | indent
indent_level	int32	缩进层级
number	int32	序号（当 list_type="number" 时）

ContentGallery

图库。

字段	类型	说明
images	ContentImageItem[]	图片项数组

ContentImageItem

图片项。

字段	类型	说明
file_token	string	文件 token
src	string	图片 URL
width	float64	宽度
height	float64	高度

ContentDocsLink

飞书文档链接。

字段	类型	说明
url	string	链接 URL
title	string	链接标题

ContentMention

提及。

字段	类型	说明
user_id	string	用户 ID

ContentLink

链接。

字段	类型	说明
url	string	链接 URL

使用示例

示例 1：简单文本段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "提升用户满意度"
            }
          }
        ]
      }
    }
  ]
}

示例 2：带格式的文本段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "Q2 目标",
              "style": {
                "bold": true
              }
            }
          },
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": " - 提升产品质量"
            }
          }
        ]
      }
    }
  ]
}

示例 3：带列表的段落

{
  "blocks": [
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "完成功能开发"
            }
          }
        ]
      }
    },
    {
      "block_element_type": "paragraph",
      "paragraph": {
        "style": {
          "list": {
            "list_type": "bullet",
            "indent_level": 0
          }
        },
        "elements": [
          {
            "paragraph_element_type": "textRun",
            "text_run": {
              "text": "进行用户测试"
            }
          }
        ]
      }
    }
  ]
}