页面属性模型

适用范围

本页只说明数据库 schema、页面属性值以及 property_item 返回结构之间的关系。属性如何过滤、排序或写入，放到对应接口页说明。

核心定义

字段说明或规则

数据库 schema 与页面属性值

数据库 schema 和页面属性值不是同一个东西。

• schema 定义“这个属性是什么”，例如标题、选择、日期、关联
• value 定义“这个页面当前填了什么”
• 同一个属性在 schema 和 value 中会共享 type，但承载的内容不同

数据库返回的 properties 里，每个条目通常包含 id、name、type 以及类型相关配置；页面返回的 properties 里，每个条目通常包含 id、type 和对应的值字段。

页面属性值类型

页面属性值常见的类型字段包括：

• title
• rich_text
• number
• select
• multi_select
• date
• people
• files
• checkbox
• url
• email
• phone_number
• formula
• relation
• rollup
• created_time
• created_by
• last_edited_time
• last_edited_by

property_item 的分页结构

当属性内容较大，或者属性本身就是多值集合时，接口会返回分页结构。

{
  "object": "list",
  "type": "property_item",
  "property_item": {
    "object": "property_item",
    "id": "title",
    "type": "title"
  },
  "results": [],
  "has_more": false,
  "next_cursor": null
}

• object 固定为 "list"
• type 固定为 "property_item"
• property_item 是当前属性的元信息
• results 是这一页的属性值片段
• has_more 和 next_cursor 服从统一游标分页约定

单值 property_item

对于选择、数字、布尔、日期等单值属性，接口可能直接返回单个 property_item 对象，而不是分页列表。

{
  "object": "property_item",
  "id": "status",
  "type": "select",
  "select": {
    "id": "doing",
    "name": "进行中",
    "color": "yellow"
  }
}

常见注意事项

• 不要把数据库 properties 当成页面 properties，前者是 schema，后者是值。
• property_id 通常是属性 ID，不是展示名。
• 属性分页返回的 results 只是当前页片段，不代表属性的完整内容已经一次返回完。

相关文档

相关能力

• 获取页面属性
• 查询数据库
• 创建页面
• 创建数据库

相关参考

• 对象模型
• 通用约定