更新自定义页面配置与组件

HAP应用密钥

HAP签名

页面组件列表，全量替换。页面采用 48 列栅格（x + w 不得超过 48）。并排在同一 y 的组件必须同高。推荐高度：section 2，filter 34，button 46，text/html 46，chart 810，carousel 68，view 1216。

组件类型 discriminator。支持：chart / section / text / html / view / carousel / button / tab / container / filtersGroup。其它值会返回 430001 参数错误。tab 与 container 为父容器，其子组件通过 parentSectionId（和 tab 子组件的 parentTabId）挂入。

componentType=section 时为分段标题（必填）；componentType=chart 时为统计图显示名（必填）。其它类型请使用 config 内的字段，不要填此字段。

[chart] 可选。顶层组件说明。

仅对 tab / container 有意义——必填，调用方生成的 UUID（如 UUIDv4），供子组件通过 parentSectionId / parentTabId 引用，本次请求内全局唯一。其它 componentType 包括 chart 一律留空：chart 一定走 config 内联新建，不支持挂载已有统计图。

仅挂到 container 容器下的子组件填：该 container 的 componentId。顶层组件 / tab 子组件 / container 自身均留空。parentSectionId 与 parentTabId 最多填一个。

仅挂到 tab 容器下的子组件填：目标子标签页的 config.tabs[].tabId（tabId 本次请求内全局唯一）。顶层组件 / container 子组件 / tab 自身均留空。parentSectionId 与 parentTabId 最多填一个。

组件在 48 列栅格中的位置。x + w 不得超过 48。

列起始位置（从 0 开始）。

行起始位置（从 0 开始）。组件按 y 值从小到大纵向排列。

宽度（列数）。推荐：section / view / carousel / button 通栏 48；chart 12（四分之一）或 24（半宽）；text / html 24（并排）。

高度（行数）。推荐：section 2，button 34，text / html 68，carousel 68，chart 810，view 10~14。并排同一 y 的组件必须同高。

组件类型专属配置。字段集合按 componentType 决定，每个字段 description 前缀[chart] / [text] / [html] / [view] / [carousel] / [button] / [tab] / [container] / [filtersGroup] 标明适用范围；只填对应类型需要的字段，其它字段留空。componentType=section 时无 config，用顶层 name 传分段标题。tab / container 的 UUID 在顶层 componentId 传入（见 componentId 说明）；tab 还必填 config.tabs[]。

[view] 可选 组件标题（默认取视图名）；[carousel] 可选 主标题字段 ID；[button] 可选 组件标题；[tab] 可选 标签页组件显示名；[container] 可选 卡片容器显示名。

[text] 必填。富文本 HTML 片段（支持基本 HTML 标签）。

[html] 必填 iframe 外链 URL，必须 http:// 或 https:// 开头；[carousel] 条件必填（action=2 时），跳转链接字段 ID。

[chart] 必填；[view] 必填；[carousel] 必填。工作表 ID 或别名。

[chart] [view] [carousel] 类型组件必填。视图 ID。

[chart] 必填；[view] 必填。页面对象 ID，必须由调用方生成 UUID（如 UUIDv4），并与 filtersGroup.filters[].objectControls[].objectId 保持一致；不要使用 chartId 或 viewId。

[chart] 必填。与 create_chart 支持值一致：columnChart / barChart / lineChart / pieChart / radarChart / funnelChart / dualAxisChart / pivotTable / regionMap / numberChart / symmetricBarChart / scatterChart / wordCloud / gaugeChart / progressChart / rankingChart / worldMap。

[chart] 必填。permission=仅可见数据；all=全部数据。

[chart] 可选。时间筛选字段 ID；不传时默认 ctime。

[chart] 可选 时间范围；不传时默认 currentMonth（本月）。取值同 create_chart。

[chart] 仅当 timeRange=customDynamicRange 时必填。结构同 create_chart。

—

—

—

—

—

—

—

—

[chart] 仅当 timeRange=customRange 时必填。

开始日期，格式 yyyy/MM/dd。

结束日期，格式 yyyy/MM/dd。

[chart] 非 pivotTable 维度字段。第 1 个为 X 轴维度，第 2 个为系列维度。对 regionMap 而言，granularity 控制数据按省/市/区县聚合；地图底图展示范围和聚焦区域由 mapScope+ mapRegionCode 控制。

—

日期：1=日,2=周,3=月,4=季度,5=年；地区：1=省,2=市,3=区/县。这里控制的是数据聚合层级，不等同于地图底图展示范围。

—

[chart] 仅 pivotTable 使用。

—

[chart] 仅 pivotTable 使用。

—

[chart] 指标列表。聚合方式：COUNT / DISTINCTCOUNT / SUM / MIN / MAX / AVG。

字段 ID；计数用 rowid。

—

—

[chart] 仅 dualAxisChart / symmetricBarChart 使用。

—

—

[chart] 仅 progressChart 使用。

—

—

[chart] gaugeChart 必填，最小值字符串。

[chart] gaugeChart 必填，最大值字符串。

[chart] 仅 chartType=regionMap 时使用。地图展示范围：country=全国（默认，等同于不传）；province=聚焦单个省级区域；city=聚焦单个市级区域。

[chart] 仅 chartType=regionMap 时使用，需与 mapScope 配合：mapScope=country 时不传或传空字符串；mapScope=province 时必填，传 6 位省级代码且后 4 位为 0000；mapScope=city 时必填，传 6 位市级代码且后 2 位为 00。直辖市及特别行政区即使传在 mapScope=province 下，也按城市级范围处理。

[filtersGroup] 可选 筛选器组 ID。新建筛选器组时可传空字符串。

[filtersGroup] 可选 筛选器组名称。

[filtersGroup] 是否启用筛选按钮。

[filtersGroup] 筛选器列表。一个 filtersGroup 组件内可以配置多个筛选。

筛选项 ID。更新已有筛选时传已有 ID；新建时可传调用方生成的 UUID。

筛选器字段名称。

是否全局搜索/筛选。

筛选字段的控件/数据类型。

筛选方式。

该筛选作用的图表或视图组件。

目标对象 ID，必须使用目标 chart/view 组件 config.objectId 中传入的 UUID；不要使用 chartId 或 viewId。

目标对象类型：1=图表，2=视图。

目标对象所在工作表 ID。

目标对象中用于筛选的字段/control ID。

高级配置，例如 allowscan。

多值筛选的默认选中值。

单值筛选的默认值。

范围筛选的默认最小值。

范围筛选的默认最大值。

当前筛选来源字段/control ID。

[filtersGroup] 应用 ID。

[filtersGroup] 自定义页面 ID。

筛选器对象，用于定义统计图数据查询的过滤条件。

filter 的根节点必须始终为 group，不能直接传 condition。即使只有一个筛选条件，也必须使用 group 包裹，并通过 children 传入 condition。

Filter 结构

Filter = {
  type: 'group' | 'condition';
  // 当 type 为 'group' 时的字段
  logic?: 'AND' | 'OR';
  children?: Filter[]; // 只能全是 group 或全是 condition，不能混合；最多两层嵌套
  // 当 type 为 'condition' 时的字段
  field?: string; // 必须传入字段 ID
  operator?: FilterOperator; // 运算符
  value?: any; // 字符串、数值、数组
}

注意事项

1. 根节点要求：filter 的根节点必须始终为 group，不能直接传 condition。即使只有一个筛选条件，也必须使用 group 包裹。
2. 嵌套限制：最多支持两层嵌套（group -> group -> condition）。
3. children 类型一致性：一个 group 的 children 只能全部是 group 或全部是 condition，不能混合。
4. logic 必需：当 type 为 group 时，logic 必须指定为 AND 或 OR。
5. 为空运算符：isempty / isnotempty 运算符不需要提供 value。
6. 数组值运算符：between、in、contains、concurrent、belongsto 等运算符必须使用数组值。
7. 选项型字段：单选、多选字段的筛选 value 必须传入对应 option 的 key 数组。
8. 关联记录筛选：筛选关联记录前需先查询 record_id，再以数组形式作为 value 进行筛选。
9. Collaborator / Department / Role 字段：筛选此类字段时必须使用对应实体的 id，不能直接使用名称或其他属性。
10. 示例说明：下方示例中的 field 仅用于说明结构，实际调用时必须传入真实字段 ID。

使用示例

示例 1：单个筛选条件也必须使用 group 包裹

{
  "type": "group",
  "logic": "AND",
  "children": [
    {
      "type": "condition",
      "field": "status_field_id",
      "operator": "eq",
      "value": ["1"]
    }
  ]
}

示例 2：简单筛选条件

查询所有 1 月份入职、姓“张”的职员：

{
  "type": "group",
  "logic": "AND",
  "children": [
    {
      "type": "condition",
      "field": "name_field_id",
      "operator": "startswith",
      "value": "张"
    },
    {
      "type": "condition",
      "field": "onboard_date_field_id",
      "operator": "between",
      "value": ["2025-01-01", "2025-01-31"]
    }
  ]
}

示例 3：多层筛选组

查询华北区市场部/销售部，1 月入职且姓“张”的职员：

{
  "type": "group",
  "logic": "AND",
  "children": [
    {
      "type": "group",
      "logic": "AND",
      "children": [
        {
          "type": "condition",
          "field": "name_field_id",
          "operator": "startswith",
          "value": "张"
        },
        {
          "type": "condition",
          "field": "onboard_date_field_id",
          "operator": "between",
          "value": ["2025-01-01", "2025-01-31"]
        }
      ]
    },
    {
      "type": "group",
      "logic": "OR",
      "children": [
        {
          "type": "condition",
          "field": "department_field_id",
          "operator": "contains",
          "value": ["sales_department_id", "marketing_department_id"]
        },
        {
          "type": "condition",
          "field": "region_field_id",
          "operator": "belongsto",
          "value": ["north_region_id"]
        }
      ]
    }
  ]
}

—

—

—

必须传入 Field ID。注意：当字段结构来自 Markdown 格式时，如果字段 ID 中包含 "(isTitle)"，该标记仅用于表示此字段是标题字段，不属于字段 ID 的一部分。在传参时应移除 "(isTitle)"，仅保留真实字段 ID。

支持的筛选运算符：

比较运算符：

• eq：等于，例如 "Beijing" 或 ["<targetid>"]
• ne：不等于，例如 "London" 或 ["<targetid>"]
• gt：大于，例如 20 或 "2025-02-06 00:00:00"
• ge：大于等于，例如 10
• lt：小于，例如 20
• le：小于等于，例如 100
• in：是其中一个，例如 ["value1", "value2"]
• notin：不是任意一个，例如 ["value1", "value2"]
• contains：包含，例如 "Ch" 或 ["销售部", "市场部"]
• notcontains：不包含，例如 "Ch" 或 ["销售部", "市场部"]
• concurrent：同时包含，例如 ["<id1>", "<id2>"]
• belongsto：属于，例如 ["<departmentid>"]
• notbelongsto：不属于，例如 ["<departmentid>"]
• startswith：开头是，例如 "张"
• notstartswith：开头不是，例如 "李"
• endswith：结尾是，例如 "公司"
• notendswith：结尾不是，例如 "有限公司"
• between：在范围内，例如 ["2025-01-01", "2025-01-31"]
• notbetween：不在范围内，例如 ["10", "20"]

为空运算符：

• isempty：为空，不需要 value
• isnotempty：不为空，不需要 value

筛选值。根据运算符不同，可传字符串、数字或数组。

• 标量示例："Beijing"、20、"2025-02-06 00:00:00"
• 数组示例：["value1", "value2"]、["2025-01-01", "2025-01-31"]
• isempty / isnotempty：不需要传 value

[chart] 可选 排序配置。

—

—

[chart] 可选 返回条数上限（rankingChart / wordCloud 推荐）。

[carousel] 必填。图片字段 ID（附件字段）。

[carousel] 可选 副标题字段 ID。

[carousel]、[button]组件必填，未填写时不能成功创建。[carousel] 表示展示条数，默认 5；[button] 表示Web 端每行按钮数, 默认6。

[carousel] 点击动作：1=打开记录，2=打开链接（需 url），3=预览图片。

[carousel] 打开方式：1=当前页面，2=新页面，3=弹窗。action=2 时生效。

[button] 可选 说明文字，显示在按钮组上方。

[button] 按钮风格：1=实心矩形（默认），2=圆角矩形，3=虚线。

[button] 按钮宽度：1=文字自适应（默认），2=平分整行。

[button] 类型组件必填，未填写时不能成功创建。表示移动端每行按钮数，默认2。

[button] 必填。按钮列表，至少 1 个。仅支持 action=1~4 简单跳转，不支持 5（扫码）/ 6（业务流程）。

按钮文字，必填。

动作：1=新建记录（value=worksheetId），2=打开视图（value=worksheetId，需传 viewId），3=打开自定义页面（value=customPageId），4=打开链接（value=外链 URL）。必填。

语义随 action：1/2=worksheetId；3=customPageId；4=外链 URL。必填。

action=2 时必填。

1=当前页面（默认），2=新页面。

按钮颜色，必填且不能为空。必须传十六进制颜色值，如 #2196f3；不要省略或传空字符串。

按钮图标 key。

[tab] 必填。子标签页列表，至少 1 项。每项 tabId 由调用方生成 UUID，本次请求内全局唯一；子组件通过顶层 parentTabId 指向具体子标签页。

子标签页 UUID，调用方生成，本次请求内全局唯一。

子标签页显示名，必填。

[tab] 可选；[container] 可选。是否显示标题。

[tab] 可选；[container] 可选。显示方式：1=透明，2=卡片。

[tab] 可选；[container] 可选。是否显示组件边框。

[tab] 可选；[container] 可选。高度类型：1=自适应，2=固定。