新建统计图

HAP应用密钥

HAP签名

统计图名称。必填。

统计图描述

锚点统计图 ID，新创建的统计图将有序排在此图表前面；不传或者传空放最后。

视图 ID。必填。

图表类型。支持值与约束：
• columnChart/barChart 用于分类对比（1 个维度 + 1~N 个指标，或 2 个维度 + 1 个指标；不用于时间趋势）
• lineChart 用于趋势分析（必须/优先使用时间维度）
• pieChart 用于占比（1 个维度 + 1 个指标，分类多时配合 limit，不用于趋势）
• radarChart 用于多指标对比（指标数量不宜过多）
• funnelChart 用于阶段转化（阶段维度 + 1 个指标）
• dualAxisChart 用于两个不同量纲或量级的指标对比（1 个维度 + values 恰好 1 个指标 + rightValues 恰好 1 个指标）
• pivotTable 用于多维分析（必须 rows + columns + values，不使用 dimension）
• regionMap/worldMap 仅用于地理分布（地区/定位维度 + 1 个指标）
• numberChart 用于 KPI 卡片（0 个维度 + 1 个指标）
• symmetricBarChart 用于镜像双指标对比（1 个维度 + values 恰好 1 个指标 + rightValues 恰好 1 个指标）
• scatterChart 用于相关性分析（2 个数值指标，可选 1 个维度作为点）
• wordCloud 用于文本频次（文本维度 + 1 个频次指标 + limit）
• gaugeChart 用于单指标状态（0 个维度 + 1 个指标 + gaugeMin/gaugeMax）
• progressChart 用于实际值与目标值对比（values + targetValues，条目数和顺序一致）
• rankingChart 用于 TopN（1 个维度 + 1 个指标 + sorts + limit）。

数据权限范围。必填。permission=仅统计当前用户可见的数据；all=统计全部数据。

时间筛选字段 ID。必填。

时间范围类型。必填。固定范围：all（全部）、today（今天）、yesterday（昨天）、tomorrow（明天）、currentWeek（本周）、lastWeek（上周）、nextWeek（下周）、currentMonth（本月）、lastMonth（上月）、nextMonth（下月）、currentQuarter（本季度）、lastQuarter（上季度）、nextQuarter（下季度）、currentYear（本年）、lastYear（上一年）、nextYear（下一年）、firstHalfYear（上半年）、secondHalfYear（下半年）。快捷动态范围：last7Days（过去 7 天）、last30Days（过去 30 天）、last365Days（过去 365 天）、next7Days（将来 7 天）、next30Days（将来 30 天）、next365Days（将来 365 天）。自定义：customDynamicRange（需配合 customDynamicRange 参数）、customRange（需配合 customRange 参数）。

自定义动态时间范围。仅当 timeRange=customDynamicRange 时传入。

起始时间点。

时间点类型。支持：today（今天）、currentMonth（本月）、currentYear（本年）、past（过去，需传 value+unit）、future（将来，需传 value+unit）。

偏移值。当 type=past 或 type=future 时必填。

偏移单位。当 type=past 或 type=future 时必填。支持：day（天）、week（周）、month（月）、year（年）。

结束时间点。结构与 from 相同。

—

—

—

指定时间范围。仅当 timeRange=customRange 时传入。

开始日期，格式 yyyy/MM/dd，如 '2026/01/01'。

结束日期，格式 yyyy/MM/dd，如 '2026/12/31'。

维度字段列表，适用于非 pivotTable 图表类型。第 1 个字段为 X 轴/类目维度，第 2 个字段（可选）为拆分/系列维度。优先选择分类、时间或地区字段，避免纯数值字段作为维度。趋势图应使用时间字段。地图图表必须使用真实地区/定位字段，不要使用普通文本。适用时用 granularity 指定时间/地区归组粒度。对 regionMap 而言，granularity 控制数据按省/市/区县聚合；地图底图展示范围和聚焦区域由 mapScope + mapRegionCode 控制。

字段 ID 或别名。

显示名称覆盖。可选。

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

是否统计空值，默认为 false 不统计。

行维度字段。仅 pivotTable 图表类型使用。

字段 ID 或别名。

显示名称覆盖。可选。

日期或地区字段的归组粒度。

—

列维度字段。仅 pivotTable 图表类型使用。

字段 ID 或别名。

显示名称覆盖。可选。

日期或地区字段的归组粒度。

—

值字段列表（指标）。指标必须是数值型字段或记录数。聚合方式：COUNT（计数）、DISTINCTCOUNT（去重计数）、SUM（求和）、MIN（最小值）、MAX（最大值）、AVG（平均值）。计数时 field 可传 rowid。用户未指定聚合方式时，数值字段默认 SUM，rowid 默认 COUNT。大多数图表为可读性建议使用 1~2 个指标；pie/funnel/ranking/wordCloud/regionMap/worldMap/gaugeChart 通常恰好 1 个指标。

字段 ID 或别名。计算记录数时传 rowid。

聚合方式（不区分大小写）：COUNT、DISTINCTCOUNT、SUM、MIN、MAX、AVG。

显示名称覆盖。可选。

副 Y 轴值字段。仅 dualAxisChart（双轴图）和 symmetricBarChart（对称条形图）使用。结构与 values 相同。这两类图表应在 values 中恰好传 1 个指标，并在 rightValues 中恰好传 1 个指标；指标量纲或量级差异较大时优先用 dualAxisChart，两个指标具备直接可比性时可用 symmetricBarChart。

字段 ID 或别名。

聚合方式：COUNT、DISTINCTCOUNT、SUM、MIN、MAX、AVG。

显示名称覆盖。可选。

进度目标值字段。progressChart（进度条）必填。条目数和顺序必须与 values 一致；values 表示实际值指标，targetValues 表示目标值指标。

字段 ID 或别名。

聚合方式：COUNT、DISTINCTCOUNT、SUM、MIN、MAX、AVG。

显示名称覆盖。可选。

仪表盘最小值，如 '0'。仅 gaugeChart 使用，必填。

仪表盘最大值，如 '100'。仅 gaugeChart 使用，必填。

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

行政区划代码。仅 chartType=regionMap 时使用，需与 mapScope 配合：mapScope=country 时不传或传空字符串；mapScope=province 时必填，传 6 位省级代码且后 4 位为 0000，例如 440000=广东省、110000=北京市；mapScope=city 时必填，传 6 位市级代码且后 2 位为 00，例如 440100=广州市。直辖市及特别行政区（110000 北京、120000 天津、310000 上海、500000 重庆、810000 香港、820000 澳门）即使传在 mapScope=province 下，也按城市级范围处理。

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

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"]
        }
      ]
    }
  ]
}

—

—

—

子节点类型。

分组节点的条件组合方式。

子分组中的条件列表；最多两层 group 嵌套。

条件节点。

筛选字段 ID。

筛选运算符，取值见 filter.operator。

筛选值，类型由运算符决定；为空运算符不传。

条件节点的字段 ID。

条件节点的运算符，取值见 filter.operator。

条件节点的筛选值，类型由运算符决定；为空运算符不传。

必须传入 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

排序配置。可选。

排序字段 ID 或别名。

排序方向。true=升序，false=降序（默认）。

返回数据条数上限。rankingChart、wordCloud 以及分类数量较多的图表建议传入，用于保持可读性并表达 TopN 分析。