# 数据结构
# 1 资源

| **资源名称** | **描述**                                                     |
| ------------ | ------------------------------------------------------------ |
| Block        | 文档块。作为内容的结构化组成元素，Block 有多种形态，可以是一段文字、一张表格或一张图片等。 |
| Document     | 一篇新版文档。多个 Block 间可以形成树状关系的层级内容，从结构来看新版文档就是一颗 Block 树，在 OpenAPI 中将这颗树称为 Document。|

# 2 数据模型

## 2.1 Document

Document 表示一篇新版文档。

```json
"document": {
    "document_id": string,
    "revision_id": int,
    "title": string
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- |  :-:   |  :-: | --------- |
|`document_id` | `string` | required |`-`| **文档唯一标识**，其也是文档根 `Block` 的 ID。 |
|`revision_id` | `int` | required |`-`| **文档版本 ID**，用以指定要查询或更新的文档版本。<br>如果多次调用接口，其返回版本 ID 未更改，则表示文档未更改。相反，版本 ID 发生更改通常意味着文档已更新， 但需要注意的是 ID 变更并非一定是文档内容发生变化，比如也有可能是文档被他人评论所致。 |
|`title` | `string` | required |`-`| **文档标题**，`Document` 只支持返回纯文本。 |

## 2.2 Block
Block 是文档最小构建块，其有多种 BlockData（内容实体），比如 `Text`、`Image` 以及 `Table` 等。对于一个具体的 Block，其有如下属性：
```json
{
    "block_id": string, 
    "block_type": enum(BlockType),
    "parent_id": string,
    "children": [](string),
    "comment_ids": [](string),
    // BlockData 只能是以下其中一种，并且需与 BlockType 相对应:
    "page": object(Text),
    "text": object(Text),
    "heading1": object(Text),
    "heading2": object(Text),
    "heading3": object(Text),
    "heading4": object(Text),
    "heading5": object(Text),
    "heading6": object(Text),
    "heading7": object(Text),
    "heading8": object(Text),
    "heading9": object(Text),
    "bullet": object(Text),
    "ordered": object(Text),
    "code": object(Text),
    "quote": object(Text),
    "todo": object(Text),
    "bitable": object(Bitable),
    "callout": object(Callout),
    "chat_card": object(ChatCard),
    "diagram": object(Diagram),
    "divider": object(Divider),
    "file": object(File),
    "grid": object(Grid),
    "grid_column": object(GridColumn),
    "iframe": object(Iframe),
    "image": object(Image),
    "isv": object(ISV),
    "mindnote": object(Mindnote),
    "sheet": object(Sheet),
    "table": object(Table),
    "table_cell": object(TableCell),
    "view": object(View),
    "undefined": object(Undefined),
    "quote_container": object(QuoteContainer),
    "task": object(Task),
    "okr": object(OKR),
    "okr_objective": object(OkrObjective),
    "okr_key_result": object(OkrKeyResult),
    "okr_progress": object(OkrProgress)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`block_id` | `string` | required | `-` | Block 全局唯一标识，创建 Block 时会自动生成 |
|`block_type` | `enum(BlockType)` | required | `-` | Block 类型，枚举类型 |
|`parent_id` | `string` | optional | `-` | 父 BlockID，除了根节点 `PageBlock` 外，其余 Block 均有 ParentBlock |
|`children` | `array(string)` | optional | `-` | 子 BlockID 列表 |
| `comment_ids` | `array(string)` | optional | `-` | 评论 ID 列表。查询评论内容请阅览「[获取评论](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/drive-v1/file-comment/get)」。 |
| `page`      | `object(Text）` |  optional | `-` | 页面（根） Block  |
| `text`      | `object(Text）` | optional  | `-` | 文本 Block        |
| `heading1`  | `object(Text）` | optional | `-` | 一级标题 Block      |
| `heading2`  | `object(Text）` | optional | `-`  | 二级标题 Block      |
| `heading3`  | `object(Text）` | optional  | `-` | 三级标题 Block      |
| `heading4`  | `object(Text）` | optional | `-`  | 四级标题 Block      |
| `heading5`  | `object(Text）` | optional | `-`  | 五级标题 Block      |
| `heading6`  | `object(Text）` | optional | `-`  | 六级标题 Block      |
| `heading7`  | `object(Text）` | optional | `-`  | 七级标题 Block      |
| `heading8`  | `object(Text）` | optional | `-`  | 八级标题 Block      |
| `heading9`  | `object(Text）` | optional | `-`  | 九级标题 Block      |
| `bullet`    | `object(Text）` | optional | `-`  | 无序列表 Block      |
| `ordered`   | `object(Text）` | optional | `-`  | 有序列表 Block      |
| `code`      | `object(Text）` | optional | `-`  | 代码块 Block       |
| `quote`     | `object(Text）` |  optional| `-`  | 引用 Block        |
| `todo`      | `object(Text）` | optional | `-`  | 待办事项 Block      |
| `bitable`   | `object(Bitable）` |  optional | `-` | 多维表格 Block      |
| `callout`   | `object(Callout）` | optional  | `-` | 高亮块 Block       |
| `chat_card` | `object(ChatCard）` |optional  | `-`  | 会话卡片 Block      |
| `diagram`   | `object(Diagram）` | optional  | `-` | 流程图 & UML 图 Block |
| `divider`   | `object(Divider）` | optional  | `-` | 分割线 Block       |
| `file`      | `object(File）` |  optional | `-` | 文件 Block        |
| `grid`      | `object(Grid）` | optional  | `-` | 分栏 Block        |
| `grid_column`| `object(GridColumn）` | optional | `-` | 分栏列 Block       |
| `iframe`    | `object(Iframe）` | optional | `-`  | 内嵌 Block  |
| `image`     | `object(Image）` |  optional | `-` | 图片 Block        |
| `isv`       | `object(ISV）` |  optional | `-` | 开放平台小组件 Block   |
| `mindnote`  | `object(Mindnote）` | optional  | `-` | 思维笔记 Block      |
| `sheet`     | `object(Sheet）` |  optional | `-` | 电子表格 Block      |
| `table`     | `object(Table）` |  optional | `-` | 表格 Block        |
| `table_cell`| `object(TableCell）` |optional  | `-`  | 表格单元格 Block     |
| `view`      | `object(View）` | optional  | `-` | 视图 Block        |
| `undefined` | `object(Undefined）` |optional  | `-`  | 未定义 Block|
| `quote_container` | `object(QuoteContainer）` |optional  | `-`  | 引用容器 Block|
| `task`      | `object(Task)` | optional | `-` | 任务 Block|
| `okr` | `object(OKR)` | optional | `-` | OKR Block |
| `okr_objective` | `object(OkrObjective)` | optional| `-` | OKR Objective Block |
| `okr_key_result` | `object(OkrKeyResult` | optional| `-` | OKR Key Result Block|
| `okr_progress` |  `object(OkrProgress)`  | optional| `-` | OKR 进展 Block|

截止目前新版文档已支持 ==30+== 种 Block，其中有些 Block 具有容纳能力，比如 `GridColumn` 可以容纳 `Image`；有些 Block 的内容实体都是 `Text`，比如 `heading1~9`、`ordered` 及 `code` 等。

## 2.3 BlockData

每种类型的 Block 都有其对应的内容实体，这些内容实体统称为 **BlockData**。

### Bitable
多维表格 Block。目前支持通过指定 `view_type` 创建空 Bitable。
```json
{
    "token": string,
    "view_type": enum(BitableViewType)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`token` | `string` | required | `-` |多维表格文档 Token，只读属性。<br>格式为==BitableToken==**_**==TableID==，其中，==BitableToken==是一篇多维表格唯一标识，==TableID==是一张数据表的唯一标识，使用时请注意拆分。|
|`view_type` | `enum(BitableViewType)` | required | `-` | 视图类型	 |

### Callout

高亮块 Block
```json
{
    "background_color": enum(BackgroundColor),
    "border_color": enum(BorderColor),
    "text_color": enum(FontColor),
    "emoji_id": string
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`background_color` | `enum(BackgroundColor)` | optional | `-` | 背景色 |
|`border_color` | `enum(BorderColor)` | optional | `-` | 边框色 |
|`text_color` | `enum(FontColor)` | optional | `-` | 字体色 |
|`emoji_id` | `enum(string)` | optional | `-` | EmojiID |

### ChatCard

会话卡片 Block
```json
{
    "chat_id": string,
    "align": enum(Align)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`chat_id` | `string` | required | `-` | 群聊天会话 OpenID，其值以 ‘oc_’ 开头，表示专为开放能力接口定义的群组 ID。对于写操作，如果用户不在该群则返回无权限错误。 |
|`align` | `enum(Align)` | optional | `-` | 对齐方式 |

### Diagram

流程图 & UML 图 Block。
```json
{
    "diagram_type": enum(DiagramType)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`diagram_type` | `enum(DiagramType)` | optional | `-` | 绘图类型 |

### Divider

分割线 Block，空结构体
```
{}
```
| **属性** | **类型** | **描述** | **示例** | **参数校验** |
| ------ | ------ | ------ | ------ | -------- |

### File

文件 Block。文件 Block 不能独立存在，须与视图 Block 一同出现，并且文件视图是通过控制视图 Block 的 `view_type` 实现的，比如卡片视图、预览视图等。在创建文件 Block 时，系统会自动生成默认的视图 Block。

```json
{
    "token": string,
    "name": string
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`token` | `string` | optional | `-` | 附件 Token，只读属性 |
|`name` | `string` | optional | `-` | 附件文件名，只读属性 |

### Grid

分栏 Block
```json
{
    "column_size": int
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`column_size` | `int` | required | `-` | 分栏列数量，取值范围 [2,5) |

### Grid Column
分栏列 Block。
```json
{
    "width_ratio": int
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`width_ratio` | `int` | optional | `-` | 当前分栏列占整个分栏的比例，取值范围 [1,99] |

### Iframe
内嵌 Block
```json
{
    "component": {
      "type": enum(IframeComponentType),
      "url": string
    }
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`component` | `object(IframeComponent)` | required | `-` | Iframe 组件 |
|`component.type` | `enum(IframeComponentType)` | required | `-` | Iframe 组件类型 |
|`component.url` | `string` | required | `-` | 目标网页 URL，读写均需要进行 URL Encode |

### Image
图片 Block。

```json
{
    "token": string,
    "width": int,
    "height": int
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`token` | `string` | optional | `-` | 图片 Token，只读属性 |
|`width` | `int` | optional | `100` | 图片宽度，单位 px，只读属性 |
|`height` | `int` | optional | `100` | 图片高度，单位 px，只读属性|

### ISV
开放平台小组件 Block
```json
{
    "component_id": string,
    "component_type_id": string
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`component_id` | `string` | optional | `-` | 团队互动应用唯一ID |
|`component_type_id` | `string` | optional | `-` | 团队互动应用类型，比如信息收集 |

### Mindnote
思维笔记 Block。==目前只支持查询返回占位信息，不支持创建及编辑。==
```json
{
    "token": string
}
```
| **属性** | **类型** | **描述**     | **示例**                        | **参数校验** |
| ------ | ------ | ---------- | ----------------------------- | -------- |
| token  | string | 思维笔记 Token | `bmnbcJ7X9yUiNbuG8DfkgqxOtlf` | `仅输出`    |

### Sheet

电子表格 Block。目前只指定 `row_size` 和 `column_size` 创建空 Sheet。
```json
{
    "token": string,
    "row_size": int,
    "column_size": int
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`token` | `string` | optional | `-` |电子表格文档 Token，只读属性。<br>格式为 ==SpreadsheetToken==**_**==SheetID==。其中，==SpreadsheetToken==是一篇电子表格的唯一标识，==SheetID==是一张工作表的唯一标识，使用时请注意拆分。|
|`row_size` | `int` | optional | `-` | 电子表格列数量。创建空电子表格时使用，最大值 9。 |
|`column_size` | `int` | optional | `-` | 电子表格列数量。创建空电子表格时使用，最大值 9。 |

### Table
表格 Block。支持指定 `property` 创建空表格。
```json
{
    "cells":  [](string),
    "property": {
        "row_size": int,
        "column_size": int,
        "column_width":[](int),
        "merge_info": [](TableMergeInfo)
    }
}
// TableMergeInfo 单元格合并信息
{
    "row_span": int,
    "col_span": int
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
|`cells` | `array(string)` | optional | `-` | 单元格数组，数组元素为 Table Cell Block 的 ID。 |
|`property` | `object(TableProperty)` | required | `-` | 表格属性。 |
|`property.row_size` | `int` | required | `-` | 行数。 |
|`property.column_size` | `int` | required | `-` | 列数。 |
|`property.column_width` | `array(int)` | optional | `-` | 列宽，单位px。 |
|`property.merge_info` | `object(TableMergeInfo)` | optional | `-` | 单元格合并信息, 只读属性。 |
|`property.merge_info.row_span` | `int` | optional | `-` | 从当前行索引起被合并的连续行数。 |
|`property.merge_info.col_span` | `int` | optional | `-` | 从当前列索引起被合并的连续列数。 |

### Table Cell
单元格 Block。
```json
{}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |

### View
视图 Block，承载 card / preview 视图。
```json
{
    "view_type": enum(ViewType)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `view_type` | `enum(ViewType)` | optional | `-` | 视图类型   |

### Undefined
未支持的 Block Type Object，只支持读，不支持写。

### QuoteContainer
引用容器 Block。
```json
{}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |

### Text
文本 Block，其有多种 type
```json
{
    "style": object(TextStyle),
    "elements": [](TextElement)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `style` | `object(TextStyle)` | optional | `-` | 文本样式|
| `elements` | `array(TextElement)` | required | `-` | 文本元素|

### TextStyle
```json
{
    "align": enum(Align),
    "done": boolean,
    "folded": boolean,
    "language": enum(CodeLanguage),
    "wrap": boolean
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `align` | `enum(Align)` | optional | `1` | 对齐方式|
| `done` | `boolean` | optional | `false` | Todo 的完成状态|
| `folded` | `boolean` | optional | `false` | 文本的折叠状态|
| `language` | `enum(CodeLanguage)` | optional | `-` | 代码块语言|
| `wrap` | `boolean` | optional | `false` | 代码块是否自动换行|

### TextElement
文本元素，支持多种类型。
```json
{
    "text_run": object(TextRun),
    "mention_user": object(MentionUser),
    "mention_doc": object(MentionDoc),
    "reminder": object(Reminder),
    "file": object(InlineFile),
    "inline_block": object(InlineBlock),
    "equation": object(Equation),
    "undefined_element": object(UndefinedElement),
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `text_run` | `object(TextRun)` | optional | `-` |文字|
| `mention_user` | `object(MentionUser)` | optional | `-` |@用户|
| `mention_doc` | `object(MentionDoc)` | optional | `-` |@文档|
| `reminder` | `object(Reminder)` | optional | `-` |日期提醒|
| `file` | `object(InlineFile)` | optional | `-` |内联附件|
| `inline_block` | `object(InlineBlock)` |optional |`-`|  内联 Block |
| `equation` | `object(Equation)` | optional | `-` | 公式 |
| `undefined_element` | `object(UndefinedElement)` | optional | `-` |未支持的 TextElement|

### TextElementStyle
文本局部样式
```json
{
    "bold": boolean,
    "italic": boolean,
    "strikethrough": boolean,
    "underline": boolean,
    "inline_code": boolean,
    "text_color": enum(FontColor),
    "background_color": enum(BackgroundColor),
    "link": object(Link),
    "comment_ids": [](string)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `bold` | `boolean` | optional | `false` |加粗|
| `italic` | `boolean` | optional | `false` |斜体|
| `strikethrough` | `boolean` | optional | `false` |删除线|
| `underline` | `boolean` | optional | `false` |下划线|
| `inline_code` | `boolean` | optional | `false` |inline 代码|
| `text_color` | `enum(FontColor)` | optional | `-` |字体颜色|
| `background_color` | `enum(BackgroundColor)` | optional | `-` |背景色|
| `link` | `object(Link)` | optional | `-` |链接|
| `comment_ids` | `array(string)` | optional | `-` | 评论 ID 列表|

### TextElementData
文本元素
#### TextRun
文字
```json
{
    "content": string,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `content` | `string` | required | `-` |文本|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### MentionUser
@用户
```json
{
    "user_id": string,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `user_id` | `string` | required | `-` |用户 OpenID|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|
#### MentionDoc
@文档
```json
{
    "token": string,
    "obj_type": enum(MentionObjType),
    "url": string,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `token` | `string` | required | `-` |云文档 Token|
| `obj_type` | `enum(MentionObjType)` | required | `-` |云文档类型|
| `url` | `string` | required | `-` |云文档链接（需要 URL Encode)|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### Reminder
日期提醒
```json
{
    "create_user_id": string,
    "is_notify": boolean,
    "is_whole_day": boolean,
    "expire_time": int,
    "notify_time": int,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `create_user_id` | `string` | required | `-` |创建者用户 ID|
| `is_notify` | `boolean` | optional | `false` |是否通知|
| `is_whole_day` | `boolean` | optional | `false` |是日期还是整点小时|
| `expire_time` | `int` | required | `-` |事件发生的时间（毫秒级事件戳）|
| `notify_time` | `int` | required | `-` |触发通知的时间（毫秒级时间戳）|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### InlineFile （仅输出）
内联附件
```json
{
    "file_token": string,
    "source_block_id": string,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `file_token` | `string` | optional | `-` |附件 Token|
| `source_block_id` | `string` | optional | `-` |当前文档中该附件所处的 BlockID|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### InlineBlock (仅输出)
内联 Block
```json
{
	"block_id": string,
	"text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `block_id` | `string` | optional | `-` |当前 Block 关联的内联状态的 Block 的 BlockID|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### Equation
公式
```json
{
    "content": string,
    "text_element_style": object(TextElementStyle)
}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `content` | `string` | required | `-` |符合 KaTeX 语法的公式内容。语法规则请参考：https://katex.org/docs/supported.html|
| `text_element_style` | `object(TextElementStyle)` | optional | `-` |文本局部样式|

#### UndefinedElement （仅输出）
未支持的 TextElement
```json
{}
```
| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |

### Task
任务 Block。 ==只支持返回任务 ID，不支持创建及编辑。==
```json
{
    "task_id": string
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `task_id` | `string` | required | `-` |任务 ID|

### OKR
OKR Block, 仅可在使用 `user_access_token` 时创建

**创建**

```json
{
    "okr_id": string,
    "objectives": [](Objective)
}
// Objective
{
    "objective_id": string,
    "kr_ids": [](string)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `okr_id`  | `string`  | required | `-` | OKR ID
| `objectives` | `array(Objective)` | optional | `-` | OKR Block 中的 Objective ID 和 Key Result ID。<br>此值为空时插入 OKR 下所有的 Objective 和 Key Result。|
| `objectives.objective_id`| `string` | required | `-` | OKR 中 Objective 的 ID。 |
| `objectives.kr_ids`| `array(string)` | optional | `-` | Key Result 的 ID 列表。<br>此值为空时插入当前 Objective 下的所有 Key Result。 |

**查询**

```json
{
    "okr_id": string,
    "period_display_status": enum(OkrPeriodDisplayStatus),
    "period_name_zh": string,
    "period_name_en": string,
    "user_id": string,
    "visible_setting": {
        "progress_fill_area_visible": boolean,
        "progress_status_visible": boolean,
        "score_visible": boolean
    }
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `okr_id`  | `string`  | optional | `-` | OKR ID |
| `period_display_status` | `enum(OkrPeriodDisplayStatus)` | optional | `-` | 周期的状态 |
| `period_name_zh` | `string` | optional | `-` | 周期名 - 中文 |
| `period_name_en` | `string` | optional | `-` | 周期名 - 英文 |
| `user_id`        | `string` | optional | `-` | OKR 所属的用户 ID |
| `visible_setting` | `object(VisibleSetting)` | optional | `-` | 可见性设置 |
| `visible_setting.progress_fill_area_visible` | `boolean` | optional | `true` | 进展编辑区域是否可见 |
| `visible_setting.progress_status_visible` | `boolean` | optional | `true` | 进展状态是否可见 |
| `visible_setting.score_visible` | `boolean` | optional | `true` | 分数是否可见 |

### OkrObjective
OKR Objective Block

```json
{
    "objective_id": string,
    "confidential": boolean,
    "position": int,
    "score": int,
    "visible": int,
    "weight": float,
    "progress_rate": object(ProgressRate),
    "content": object(Text)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `objective_id`  | `string`  | optional | `-` | OKR Objective ID |
| `confidential` | `boolean` | optional | `-` | 是否在 OKR 平台设置了私密权限 |
| `position` | `int` | optional | `-` | Objective 的位置编号，对应 Block 中 O1、O2 的 1、2 |
| `score` | `int` | optional | `-` | 打分信息 |
| `visible` | `boolean` | optional | `true` | OKR Block 中是否展示该 Objective |
| `weight` | `float` | optional | `-` | Objective 的权重 |
| `progress_rate` | `object(ProgressRate)` | optional | `-` | 进展信息 |
| `content` | `object(Text)` | optional | `-` | Objective 的文本内容 |

### OkrKeyResult
OKR Key Result Block

```json
{
    "kr_id": string,
    "confidential": boolean,
    "position": int,
    "score": int,
    "visible": int,
    "weight": float,
    "progress_rate": object(ProgressRate),
    "content": object(Text)
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `kr_id`  | `string`  | optional | `-` | OKR Key Result ID |
| `confidential` | `boolean` | optional | `-` | 是否在 OKR 平台设置了私密权限 |
| `position` | `int` | optional | `-` | Key Result 的位置编号，对应 Block 中 KR1、KR2 的 1、2 |
| `score` | `int` | optional | `-` | 打分信息 |
| `visible` | `boolean` | optional | `true` | OKR Block 中是否展示该 Key Result |
| `weight` | `float` | optional | `-` | Key Result 的权重 |
| `progress_rate` | `object(ProgressRate)` | optional | `-` | 进展信息 |
| `content` | `object(Text)` | optional | `-` | Key Result 的文本内容 |

### ProgressRate
OKR 进展信息

```json
{
    "mode": enum(OkrProgressRateMode),
    "current": float,
    "percent": float,
    "progress_status": enum(OkrProgressStatus),
    "status_type": enum(OkrProgressStatusType),
    "start": float,
    "target": float
}
```

| 名称         | 数据类型           | 属性        | 默认值         | 描述        |
| --------- | --------------- | -------   | ----------- | --------- |
| `mode`  | `enum(OkrProgressRateMode)`  | optional | `-` | 状态模式，分 simple 和 advanced 两种|
| `status_type` | `enum(OkrProgressStatusType)` | optional | `-` | 进展状态计算类型 |
| `progress_status` | `enum(OkrProgressStatus)` | optional | `-` | 进展状态 |
| `percent` | `float` | optional | `-` | 当前进度百分比，simple 模式下使用 |
| `start`   | `float` | optional | `-` | 进度起始值，advanced 模式使用 |
| `current` | `float` | optional | `-` | 当前进度, advanced 模式使用 |
| `target`  | `float` | optional | `-` | 进度目标值，advanced 模式使用 |

### Progress
OKR 进展 Block

```json
{}
```

# 3 枚举

## BlockType
| **Enums**  |             |
| ---------- | ----------- | 
|1|页面 Block|
|2|文本 Block|
|3|标题 1 Block|
|4|标题 2 Block|
|5|标题 3 Block|
|6|标题 4 Block|
|7|标题 5 Block|
|8|标题 6 Block|
|9|标题 7 Block|
|10|标题 8 Block|
|11|标题 9 Block|
|12|无序列表 Block|
|13|有序列表 Block|
|14|代码块 Block|
|15|引用 Block|
|17|待办事项 Block|
|18|多维表格 Block|
|19|高亮块 Block|
|20|会话卡片 Block|
|21|流程图 & UML Block|
|22|分割线 Block|
|23|文件 Block|
|24|分栏 Block|
|25|分栏列 Block|
|26|内嵌 Block Block|
|27|图片 Block|
|28|开放平台小组件 Block|
|29|思维笔记 Block|
|30|电子表格 Block|
|31|表格 Block|
|32|表格单元格 Block|
|33|视图 Block|
|34|引用容器 Block|
|35|任务 Block|
|36|OKR Block|
|37|OKR Objective Block|
|38|OKR Key Result Block|
|39|OKR Progress Block|
|999|未支持 Block|

## TextElementType
| **Enums**   |              |
| ------------ | ----- |
| text_run     | 文字  |
| mention_user | @用户  |
| mention_doc  | @文档 |
| file         | @文件  |
| reminder     | 日期提醒  |
| undefined    | 未支持元素 |
| equation    | 公式 |

## Align
Block 的排版方式，比如居左等
| **Enums** |        |
| --------- | ------ |
|1|居左排版|
|2|居中排版|
|3|居右排版|

## CalloutBackgroundColor
高亮块背景色（分为深色系和浅色系）
| **Enums** |        |
| --------- | ------ |
|1|浅红色|
|2|浅橙色|
|3|浅黄色|
|4|浅绿色|
|5|浅蓝色|
|6|浅紫色|
|7|浅灰色|
|8|暗红色|
|9|暗橙色|
|10|暗黄色|
|11|暗绿色|
|12|暗蓝色|
|13|暗紫色|
|14|暗灰色|

## CalloutBorderColor
高亮块边框色（色系与高亮块背景色色系一致）
| **Enums** |        |
| --------- | ------ |
|1|红色|
|2|橙色|
|3|黄色|
|4|绿色|
|5|蓝色|
|6|紫色|
|7|灰色|

## FontBackgroundColor
字体背景色（分为深色系和浅色系）
| **Enums** |        |
| --------- | ------ |
|1|浅粉红色|
|2|浅橙色|
|3|浅黄色|
|4|浅绿色|
|5|浅蓝色|
|6|浅紫色|
|7|浅灰色|
|8|暗粉红色|
|9|暗橙色|
|10|暗黄色|
|11|暗绿色|
|12|暗蓝色|
|13|暗紫色|
|14|暗灰色|

## FontColor
字体色
| **Enums** |        |
| --------- | ------ |
|1|粉红色|
|2|橙色|
|3|黄色|
|4|绿色|
|5|蓝色|
|6|紫色|
|7|灰色|

## ViewType
View Block 的视图类型
| **Enums** |        |
| --------- | ------ |
|1|卡片视图，独占一行的一种视图，在 Card 上可有一些简单交互|
|2|预览视图，在当前页面直接预览插入的 Block 内容，而不需要打开新的页面|
|3|内联试图|

## BitableViewType
Bitable Block 的视图类型
| **Enums** |        |
| --------- | ------ |
|1|数据表|
|2|看板|

## DiagramType
绘图类型
| **Enums** |        |
| --------- | ------ |
|1|流程图|
|2|UML 图|

## IframeComponentType
内嵌 Block 支持的类型
| **Enums** |        |
| --------- | ------ |
|1|哔哩哔哩|
|2|西瓜视频|
|3|优酷|
|4|Airtable|
|5|百度地图|
|6|高德地图|
|7|Undefined|
|8|Figma|
|9|墨刀|
|10|Canva|
|11|CodePen|
|12|Lark 问卷|
|13|金数据|
|14|Undefined|
|15|Undefined|

## MentionObjType
Mention 云文档类型
| **Enums** |        |
| --------- | ------ |
|1|Doc|
|3|Sheet|
|8|Bitable|
|11|MindNote|
|12|File|
|15|Slide|
|16|Wiki|
|22|Docx|
## CodeLanguage
代码块语言
| **Enums** |        |
| --------- | ------ |
|1|PlainText
|2|ABAP
|3|Ada
|4|Apache|
|5|Apex|
|6|Assembly| Language|
|7|Bash|
|8|CSharp|
|9|C++|
|10|C|
|11|COBOL|
|12|CSS
|13|CoffeeScript|
|14|D|
|15|Dart|
|16|Delphi|
|17|Django|
|18|Dockerfile|
|19|Erlang|
|20|Fortran|
|21|FoxPro|
|22|Go|
|23|Groovy|
|24|HTML|
|25|HTMLBars|
|26|HTTP|
|27|Haskell|
|28|JSON|
|29|Java|
|30|JavaScript|
|31|Julia|
|32|Kotlin|
|33|LateX|
|34|Lisp|
|35|Logo|
|36|Lua|
|37|MATLAB|
|38|Makefile|
|39|Markdown|
|40|Nginx|
|41|Objective|-C|
|42|OpenEdgeABL|
|43|PHP|
|44|Perl
|45|PostScript|
|46|Power| Shell|
|47|Prolog|
|48|ProtoBuf|
|49|Python
|50|R|
|51|RPG|
|52|Ruby|
|53|Rust|
|54|SAS|
|55|SCSS|
|56|SQL|
|57|Scala|
|58|Scheme|
|59|Scratch|
|60|Shell|
|61|Swift|
|62|Thrift|
|63|TypeScript|
|64|VBScript|
|65|Visual| Basic|
|66|XML|
|67|YAML|

## OkrPeriodDisplayStatus
周期的状态
| **Enums** |        |
| --------- | ------ |
|default|默认|
|normal|正常|
|invalid|失效|
|hidden|隐藏|

## OkrProgressRateMode
OKR 进展状态模式
| **Enums** |        |
| --------- | ------ |
|simple|简单模式|
|advanced|高级模式|

## OkrProgressStatus
OKR 进展状态
| **Enums** |        |
| --------- | ------ |
|unset|未设置|
|normal|正常|
|risk|有风险|
|extended|已延期|

## OkrProgressStatusType
OKR 进展所展示的状态计算类型
| **Enums** |        |
| --------- | ------ |
|default|以风险最高的 Key Result 状态展示|
|custom|自定义|