明道云开放平台

正在加载页面

鉴权方式

AppKey + Sign 是应用密钥鉴权，由管理员创建，用于以应用管理员身份访问应用数据。

版本

请求地址

GET

Path 参数

名称	类型	必填	描述
`worksheet_id`	`string`	是	工作表ID 示例值：`"worksheet_id"`

Header 参数

名称	类型	必填	描述
`HAP-Appkey`	`string`	是	HAP应用密钥
`HAP-Sign`	`string`	是	HAP签名

Query 参数

名称	类型	必填	描述
`responseFormat`	`string`	否	json：返回 JSON，md：返回 md 文本(更省 token, 仅返回部分重要字段)。默认为 json dsl：返回与 V3 创建、编辑一致的字段 DSL，适用于建表和修改结构；json 为旧格式，主要用于兼容或调试。当前后端仍默认 json，参数可选示例值：`"json"` 可选值： `"json""md""dsl"`

响应参数

200成功获取工作表结构

名称	类型	描述
`success`	`boolean`	是否调用成功
`error_code`	`integer`	错误代码
`error_msg`	`string`	错误消息
`data`	`object`	—
`data.worksheetId`	`string`	工作表 ID
`data.name`	`string`	工作表名称
`data.alias`	`string`	工作表别名
`data.desc`	`string`	说明
`data.remark`	`string`	工作表描述
`data.fields`	`object[]`	工作表字段列表
`data.fields.id`	`string`	字段 ID
`data.fields.name`	`string`	字段名称
`data.fields.alias`	`string`	字段别名
`data.fields.type`	`string`	字段类型；新增支持 Signature（签名，无需额外配置）、Concatenate（文本组合）、Barcode（条码）、Lookup（他表字段）、Rollup（汇总）、CascadingSelect（级联选择）和 CustomField（纯展示自定义字段）。字段创建后不可变更类型
`data.fields.required`	`boolean`	是否必填
`data.fields.isReadOnly`	`boolean`	是否只读
`data.fields.precision`	`integer`	数值或汇总等字段保留的小数位数
`data.fields.dataSource`	`string`	关联或级联选择的目标工作表 ID；表达式通过 config.expression 返回
`data.fields.sourceField`	`string`	Lookup 或 Rollup 引用的目标表字段 ID 或别名；count 时可省略
`data.fields.relationField`	`string`	Lookup 或 Rollup 引用的本表关联字段 ID 或别名；Lookup 仅支持单条关联，Rollup 也支持子表。Lookup 创建后不可修改来源
`data.fields.viewId`	`string`	CascadingSelect 使用的层级视图 ID
`data.fields.config`	`object`	语义化字段配置；DSL 返回与创建、编辑使用相同的属性位置
`data.fields.config.textMode`	`string`	文本显示模式，对应旧 subType 可选值： `"singleLine""multiLine""markdown"`
`data.fields.config.isMultiple`	`boolean`	是否允许多选或多条，适用于下拉、成员、关联等字段
`data.fields.config.code`	`string`	货币代码，如 CNY、USD，对应旧 unit
`data.fields.config.format`	`string`	日期或时间的语义格式，对应旧 subType 或 unit；具体格式取决于字段类型
`data.fields.config.expression`	`string`	文本组合或条码等字段的表达式，使用 $字段ID或别名$ 引用字段；兼容旧 dataSource，优先使用本属性
`data.fields.config.displayMode`	`string`	条码：code128 或 qrCode；级联选择：cascader 或 tree；关联记录可使用 dropdown、card、inlineTable、tabTable
`data.fields.config.storeData`	`boolean`	Lookup 是否存储数据副本；创建时不传默认 false，仅显示来源值；读取历史字段时返回其实际存储配置
`data.fields.config.calcType`	`string`	Rollup 聚合类型，本次补充 sum、count、avg、max、min；count 时可省略 sourceField
`data.fields.config.isColorOptions`	`boolean`	是否启用彩色选项
`data.fields.config.bidirectional`	`boolean`	是否双向关联，DSL 与创建、编辑均在 config 中返回或设置
`data.fields.config.showFields`	`string[]`	关联记录展示字段 ID 或别名列表
`data.fields.layout`	`object`	字段排版布局
`data.fields.layout.rowIndex`	`integer`	字段所在行，从 0 开始
`data.fields.layout.span`	`integer`	字段所占宽度可选值： `346812`
`data.fields.defaultValue`	`object[]`	字段默认值配置，DSL 返回完整来源信息，无配置时为空数组
`data.fields.defaultValue.source`	`string`	值来源：静态值、系统值、当前表字段或关联字段可选值： `"static""system""field""relation"`
`data.fields.defaultValue.value`	`string`	source 为 static 或 system 时的值
`data.fields.defaultValue.field`	`string`	source 为 field 或 relation 时的字段 ID 或别名
`data.fields.defaultValue.relationField`	`string`	source 为 relation 时的关联字段 ID 或别名
`data.fields.customWidget`	`object`	字段自定义前端展示配置；存储值沿用 Text、Number、Date、DateTime、Time、SingleSelect、MultipleSelect、Relation 等原字段类型，纯展示使用 CustomField
`data.fields.customWidget.height`	`integer`	组件展示高度，单位像素
`data.fields.customWidget.script`	`string`	React 函数组件脚本
`data.fields.customWidget.reference`	`object[]`	纯展示组件引用的字段变量
`data.fields.customWidget.reference.name`	`string`	脚本中的变量名
`data.fields.customWidget.reference.field`	`string`	引用字段 ID 或别名
`data.fields.options`	`object[]`	选项定义，DSL 补充返回颜色
`data.fields.options.key`	`string`	选项标识
`data.fields.options.value`	`string`	选项名称
`data.fields.options.index`	`integer`	选项排序
`data.fields.options.color`	`string`	选项颜色，使用 HEX 色值，例如 #F52222
`data.fields.options.isDeleted`	`boolean`	选项是否已删除
`data.fields.sourceWorksheetName`	`string`	关联目标工作表名称；关联字段始终返回，失效且无法获取名称时为空字符串
`data.fields.isCrossApp`	`boolean`	是否跨应用关联，仅跨应用时返回 true
`data.fields.targetAppId`	`string`	目标应用 ID，仅跨应用时返回
`data.fields.targetAppName`	`string`	目标应用名称，仅跨应用时返回
`data.fields.relation`	`object`	关联字段补充信息，语义配置同时位于 config 中
`data.fields.relation.bidirectional`	`boolean`	是否双向关联，DSL 与创建、编辑均在 config 中返回或设置
`data.fields.relation.showFields`	`string[]`	关联记录展示字段 ID 或别名列表
`data.views`	`object[]`	视图列表
`data.views.id`	`string`	视图 ID
`data.views.name`	`string`	视图名称
`data.views.type`	`string`	视图类型

curl -X GET "https://example.com/v3/app/worksheets/worksheet_id" \  -H "HAP-Appkey: {{HAP-Appkey}}" \  -H "HAP-Sign: {{HAP-Sign}}"

{  "data": {    "worksheetId": "65dda1a5a608a40050774c72",    "name": "会员信息",    "alias": "",    "desc": "",    "remark": "",    "fields": [      {        "id": "632444f6182c34e9180b0676",        "name": "名称",        "alias": "",        "desc": "",        "type": "2",        "required": false,        "isHidden": false,        "isReadOnly": false,        "isHiddenOnCreate": false,        "isUnique": false,        "isTitle": true,        "remark": ""      }    ],    "views": [      {        "id": "65dda1a5a608a40050774c8f",        "name": "全部",        "type": "0"      }    ]  },  "success": true}

名称

类型

必填

描述

worksheet_id

string

是

工作表ID

示例值："worksheet_id"

名称

类型

必填

描述

HAP-Appkey

string

是

HAP应用密钥

HAP-Sign

string

是

HAP签名

Query 参数

名称	类型	必填	描述
`responseFormat`	`string`	否	json：返回 JSON，md：返回 md 文本(更省 token, 仅返回部分重要字段)。默认为 json dsl：返回与 V3 创建、编辑一致的字段 DSL，适用于建表和修改结构；json 为旧格式，主要用于兼容或调试。当前后端仍默认 json，参数可选示例值：`"json"` 可选值： `"json""md""dsl"`

名称

类型

描述

success

boolean

是否调用成功

error_code

integer

错误代码

error_msg

string

错误消息

data

object

—

data.worksheetId

string

工作表 ID

data.name

string

工作表名称

data.alias

string

工作表别名

data.desc

string

说明

data.remark

string

工作表描述

data.fields

object[]

工作表字段列表

data.fields.id

string

字段 ID

data.fields.name

string

字段名称

data.fields.alias

string

字段别名

data.fields.type

string

字段类型；新增支持 Signature（签名，无需额外配置）、Concatenate（文本组合）、Barcode（条码）、Lookup（他表字段）、Rollup（汇总）、CascadingSelect（级联选择）和 CustomField（纯展示自定义字段）。字段创建后不可变更类型

data.fields.required

boolean

是否必填

data.fields.isReadOnly

boolean

是否只读

data.fields.precision

integer

数值或汇总等字段保留的小数位数

data.fields.dataSource

string

关联或级联选择的目标工作表 ID；表达式通过 config.expression 返回

data.fields.sourceField

string

Lookup 或 Rollup 引用的目标表字段 ID 或别名；count 时可省略

data.fields.relationField

string

Lookup 或 Rollup 引用的本表关联字段 ID 或别名；Lookup 仅支持单条关联，Rollup 也支持子表。Lookup 创建后不可修改来源

data.fields.viewId

string

CascadingSelect 使用的层级视图 ID

data.fields.config

object

语义化字段配置；DSL 返回与创建、编辑使用相同的属性位置

data.fields.config.textMode

string

文本显示模式，对应旧 subType

可选值：

"singleLine""multiLine""markdown"

data.fields.config.isMultiple

boolean

是否允许多选或多条，适用于下拉、成员、关联等字段

data.fields.config.code

string

货币代码，如 CNY、USD，对应旧 unit

data.fields.config.format

string

日期或时间的语义格式，对应旧 subType 或 unit；具体格式取决于字段类型

data.fields.config.expression

string

文本组合或条码等字段的表达式，使用 $字段ID或别名$ 引用字段；兼容旧 dataSource，优先使用本属性

data.fields.config.displayMode

string

条码：code128 或 qrCode；级联选择：cascader 或 tree；关联记录可使用 dropdown、card、inlineTable、tabTable

data.fields.config.storeData

boolean

Lookup 是否存储数据副本；创建时不传默认 false，仅显示来源值；读取历史字段时返回其实际存储配置

data.fields.config.calcType

string

Rollup 聚合类型，本次补充 sum、count、avg、max、min；count 时可省略 sourceField

data.fields.config.isColorOptions

boolean

是否启用彩色选项

data.fields.config.bidirectional

boolean

是否双向关联，DSL 与创建、编辑均在 config 中返回或设置

data.fields.config.showFields

string[]

关联记录展示字段 ID 或别名列表

data.fields.layout

object

字段排版布局

data.fields.layout.rowIndex

integer

字段所在行，从 0 开始

data.fields.layout.span

integer

字段所占宽度

可选值：

346812

data.fields.defaultValue

object[]

字段默认值配置，DSL 返回完整来源信息，无配置时为空数组

data.fields.defaultValue.source

string

值来源：静态值、系统值、当前表字段或关联字段

可选值：

"static""system""field""relation"

data.fields.defaultValue.value

string

source 为 static 或 system 时的值

data.fields.defaultValue.field

string

source 为 field 或 relation 时的字段 ID 或别名

data.fields.defaultValue.relationField

string

source 为 relation 时的关联字段 ID 或别名

data.fields.customWidget

object

字段自定义前端展示配置；存储值沿用 Text、Number、Date、DateTime、Time、SingleSelect、MultipleSelect、Relation 等原字段类型，纯展示使用 CustomField

data.fields.customWidget.height

integer

组件展示高度，单位像素

data.fields.customWidget.script

string

React 函数组件脚本

data.fields.customWidget.reference

object[]

纯展示组件引用的字段变量

data.fields.customWidget.reference.name

string

脚本中的变量名

data.fields.customWidget.reference.field

string

引用字段 ID 或别名

data.fields.options

object[]

选项定义，DSL 补充返回颜色

data.fields.options.key

string

选项标识

data.fields.options.value

string

选项名称

data.fields.options.index

integer

选项排序

data.fields.options.color

string

选项颜色，使用 HEX 色值，例如 #F52222

data.fields.options.isDeleted

boolean

选项是否已删除

data.fields.sourceWorksheetName

string

关联目标工作表名称；关联字段始终返回，失效且无法获取名称时为空字符串

data.fields.isCrossApp

boolean

是否跨应用关联，仅跨应用时返回 true

data.fields.targetAppId

string

目标应用 ID，仅跨应用时返回

data.fields.targetAppName

string

目标应用名称，仅跨应用时返回

data.fields.relation

object

关联字段补充信息，语义配置同时位于 config 中

data.fields.relation.bidirectional

boolean

是否双向关联，DSL 与创建、编辑均在 config 中返回或设置

data.fields.relation.showFields

string[]

关联记录展示字段 ID 或别名列表

data.views

object[]

视图列表

data.views.id

string

视图 ID

data.views.name

string

视图名称

data.views.type

string

视图类型

{ "data": { "worksheetId": "65dda1a5a608a40050774c72", "name": "会员信息", "alias": "", "desc": "", "remark": "", "fields": [ { "id": "632444f6182c34e9180b0676", "name": "名称", "alias": "", "desc": "", "type": "2", "required": false, "isHidden": false, "isReadOnly": false, "isHiddenOnCreate": false, "isUnique": false, "isTitle": true, "remark": "" } ], "views": [ { "id": "65dda1a5a608a40050774c8f", "name": "全部", "type": "0" } ] }, "success": true}

获取工作表结构信息

鉴权方式

版本

请求地址

Path 参数

Header 参数

Query 参数

响应参数

获取工作表结构信息

鉴权方式

版本

请求地址

Path 参数

Header 参数

Query 参数

响应参数

获取工作表结构信息

鉴权方式

版本

请求地址

Path 参数

Header 参数

Query 参数

响应参数

成功示例

异常示例

DSL 结构示例

获取工作表结构信息

鉴权方式

版本

请求地址

Path 参数

Header 参数

Query 参数

响应参数

成功示例

异常示例

DSL 结构示例