计算字段使用说明

计算字段用于在数据集里补充业务分析需要的派生字段。它可以直接用表达式从当前数据集字段计算，也可以先在数据集中定义字段，再由图表绑定 Studio 脚本把结果写入。

计算字段常见于这些场景：

场景	说明
行内计算	根据当前记录或关联记录计算金额、时长、状态、分组标签
业务口径统一	把经常重复使用的计算逻辑沉淀在数据集里，图表直接使用字段
外部指标补充	图表先查询 Soln 表单聚合结果，再由脚本补充第三方系统、成员目录、审批或其他服务中的指标
图表后处理	基于图表已聚合的数据计算目标值、完成率、预测值、告警值等

使用链路

计算字段分两步使用：

在 数据集 中添加计算字段，确定字段名称、数据类型和值来源
在 字段与元数据 中设置字段身份和聚合方式
在图表中把计算字段放入字段槽位
如果值来源是 自定义脚本，还需要在图表的 绑定脚本 中选择 Studio 脚本，并配置匹配字段和赋值字段
点击 执行脚本，确认预览结果后保存图表

表达式型计算字段在数据集预览和图表查询中直接计算。脚本型计算字段在数据集里只定义字段结构，实际数值由图表查询后的绑定脚本回填。

在数据集中添加计算字段

进入 数据集 配置页后：

选择左侧 数据集属性
在中间配置区点击 自定义列 图标
填写 字段名称
选择 数据类型
选择 值来源
按值来源配置表达式，或保存为脚本型字段
点击保存

配置项	说明
字段名称	图表中展示的字段名称，建议使用业务人员能理解的名称
数据类型	计算结果的数据类型，支持文本、数字、日期、日期时间和布尔值
值来源	决定字段值由表达式直接计算，还是由图表绑定脚本写入

保存后，计算字段会出现在数据集字段列表中。你可以在 字段与元数据 中继续调整语义名称、身份、聚合方式和启用状态。

值来源

表达式

表达式适合从当前数据集行直接推导结果。它可以使用主表单字段、关联表单字段和常用函数，适合规则固定、依赖当前行数据的计算。

常见用法：

场景	示例
金额计算	实际金额 = 订单金额 - 优惠金额
时间计算	处理时长 = 完成时间 - 创建时间
状态判断	是否逾期 = 截止时间早于当前时间
分组标签	客户等级 = 根据累计金额判断 A/B/C

表达式字段可以在数据集预览中直接检查结果。配置后建议先预览数据，再保存数据集。

自定义脚本

自定义脚本适合结果不能只靠当前行表达式得到的场景。选择 自定义脚本 后，数据集保存的是一个脚本型计算字段；这个字段不会在数据集预览中直接计算，而是在图表查询时由 绑定脚本 写入结果。

脚本型计算字段适合：

场景	说明
第三方指标	根据图表分类去外部系统查询目标值、预算、汇率、库存、广告消耗等
Soln 内部补充	使用 Studio SDK 查询表单记录、成员、部门、组织、审批或权限信息后补充指标
多步骤规则	需要多次查询、条件分支、映射表、复杂权重或算法时使用脚本
聚合后计算	图表已经按地区、月份、负责人聚合后，再计算完成率、目标差额、预测值
指标卡补值	指标卡只需要一个全局结果，例如目标金额、外部余额、实时汇率

如果计算只依赖当前行字段，优先使用表达式；如果计算依赖图表聚合结果、其他系统或复杂运行时逻辑，再使用自定义脚本。

字段身份和聚合方式

计算字段保存后，需要在 字段与元数据 中设置字段身份。

身份	用途
维度	用于分类、分组、横轴、颜色或筛选
指标	用于数值统计、纵轴、大小、指标卡或目标值

脚本型计算字段通常作为指标使用，并且数据类型应选择数字。图表绑定脚本目前只会把脚本结果写入数字型计算指标。

聚合方式决定同一个图表点匹配到多条脚本结果时如何合并：

聚合方式	脚本回填规则
无	只允许一条结果；匹配到多条结果会报重复结果错误
求和	把多条结果相加
平均	计算多条结果的平均值
最大值	取最大值
最小值	取最小值
计数	统计可转换为数字的结果数量
去重计数	对可转换为数字的结果去重后计数

无只适合值来源为自定义脚本的计算字段，用于要求脚本结果和图表点一一对应的场景。普通字段和表达式字段不会使用无作为聚合方式。

在图表中绑定脚本

当图表使用了脚本型计算字段时，需要在图表编辑器里配置 绑定脚本。

操作步骤：

打开图表编辑器
把脚本型计算字段放入指标槽位，例如 Y 轴指标、指标卡指标或目标指标
进入左侧 绑定脚本 配置区
选择一个 Studio 脚本
按需要配置 匹配字段
在 赋值字段 中选择计算字段，并填写脚本返回结果中的字段名
点击 执行脚本
查看右侧预览，确认结果正确后保存图表

绑定脚本执行顺序是：

图表先按维度、指标、筛选条件、基础记录数查询 Soln 数据集
查询结果会整理成 chartData 传给 Studio 脚本
Studio 脚本返回数组或 { rows: [...] }
系统按匹配字段找到对应图表点
系统把脚本结果字段写入对应的脚本型计算字段
图表使用回填后的数据重新渲染预览

脚本入参

绑定脚本是 Studio 脚本，入口函数和 Soln SDK 文档中的脚本写法一致：

export default async function main(
  _payload: StudioScriptRuntimeContextPayload,
  _context: StudioScriptContext
) {
  return { rows: [] };
}

图表绑定脚本始终接收 soln.runtime-context/v1。数据集身份位于 payload.source，查询选项和图表数据位于 payload.input：

路径	说明
`payload.source.datasetId`	当前图表使用的数据集 ID
`payload.source.dimensions`	当前图表查询使用的维度字段 key
`payload.source.measures`	当前图表查询使用的指标字段 key
`payload.input.condition`	当前图表筛选条件
`payload.input.timeGrain`	时间粒度，例如 day、week、month
`payload.input.baseRecordTimeField`	基础记录取数使用的时间字段，通常是 updatedAt 或 createdAt
`payload.input.chartData`	图表聚合后的数据，包括分类、字段信息、系列和行数据

chartData 的常用结构：

type BindingChartData = {
  categories: string[];
  dimensions: Array<{
    key: string;
    name: string;
    apiName: string;
    dataType: string;
  }>;
  measures: Array<{
    key: string;
    name: string;
    apiName: string;
    dataType: string;
    aggregationType: string;
    valueSource: string | null;
  }>;
  series: Array<{
    fieldKey: string;
    fieldName: string;
    aggregationType: string;
    groupFieldKey?: string | null;
    groupValue?: string | null;
    data: Array<number | null>;
  }>;
  rows: Array<Record<string, unknown>>;
};

chartData.rows 是脚本最常用的数据。每一行代表一个图表点或一个“分类 + 分组”组合，并带有这些系统字段：

字段	说明
`__rowIndex`	图表点行号；脚本直接按行号回填时使用
`__categoryIndex`	当前分类在 `categories` 中的位置
`__category`	当前分类名称

除此之外，行里还会包含当前图表维度字段和指标字段，key 使用数据集字段 key。

脚本返回格式

脚本需要返回行数组，支持三种写法：

return [
  { __rowIndex: 0, targetAmount: 1000 },
  { __rowIndex: 1, targetAmount: 2000 },
];

return {
  rows: [
    { province: '广东省', targetAmount: 1000 },
    { province: '浙江省', targetAmount: 2000 },
  ],
};

return {
  data: [
    { month: '2026-01', targetAmount: 5000 },
  ],
};

返回对象中的数组字段可以是 rows、items 或 data。数组里的每一项都应该是普通对象。

匹配字段和赋值字段

匹配字段 决定脚本结果写入哪一个图表点。

配置	说明
数据集字段	当前图表数据中的字段，例如省份、月份、负责人
脚本结果字段	脚本返回行中用于匹配的字段，例如 `province`、`month`、`ownerName`

如果配置了匹配字段，系统会把 chartData.rows 中的数据集字段值和脚本返回行中的结果字段值进行匹配。匹配成功后，脚本结果才会写入对应图表点。

赋值字段 决定脚本结果里的哪个字段写入哪个计算字段。

配置	说明
计算字段	数据集中值来源为自定义脚本的数字型计算指标
脚本结果字段	脚本返回行中要写入的字段，例如 `targetAmount`、`budget`、`rate`

如果没有配置赋值字段，系统会尝试使用计算字段 key 或 API Name 从脚本返回行中读取同名字段。为了让配置更清晰，建议在图表中显式配置赋值字段。

无匹配字段的单行结果

如果不配置匹配字段，并且脚本只返回一行结果，系统会默认把这一行写入第 0 个图表点。这适合指标卡或单行总计。

示例：

export default async function main(_payload: StudioScriptRuntimeContextPayload) {
  return {
    rows: [
      { targetAmount: 100000 },
    ],
  };
}

如果图表有多个分类，通常应该配置匹配字段，或者在返回行中显式带上 __rowIndex。

示例：按图表行计算目标值

这个示例直接读取 chartData.rows，按每个图表点当前销售额计算目标值。

type BindingInput = {
  chartData: {
    rows: Array<Record<string, unknown>>;
  };
};

export default async function main(payload: StudioScriptRuntimeContextPayload) {
  const input = payload.input as BindingInput;
  return {
    rows: input.chartData.rows.map((row) => {
      const sales = Number(row['t0.amount'] || 0);

      return {
        __rowIndex: row.__rowIndex,
        targetAmount: Math.round(sales * 1.2),
      };
    }),
  };
}

图表中配置：

配置项	值
赋值字段	计算字段：目标金额；脚本结果字段：`targetAmount`
匹配字段	不需要，因为脚本返回了 `__rowIndex`

示例：按省份匹配外部结果

这个示例适合图表按省份展示，脚本返回每个省的目标金额。

type BindingInput = {
  chartData: {
    rows: Array<Record<string, unknown>>;
  };
};

export default async function main(payload: StudioScriptRuntimeContextPayload) {
  const input = payload.input as BindingInput;
  const provinces = input.chartData.rows.map((row) => String(row['t0.province'] || ''));

  const targetByProvince: Record<string, number> = {
    广东省: 120000,
    浙江省: 90000,
    江苏省: 85000,
  };

  return {
    rows: provinces.map((province) => ({
      province,
      targetAmount: targetByProvince[province] || 0,
    })),
  };
}

图表中配置：

配置项	值
匹配字段	数据集字段：省份；脚本结果字段：`province`
赋值字段	计算字段：目标金额；脚本结果字段：`targetAmount`

如果脚本返回的粒度比图表更细，例如一个省返回多条城市目标，系统会按计算字段的聚合方式处理多条结果。目标金额一般选择求和。

示例：使用 Soln SDK 查询表单数据

脚本可以使用 studioScriptContext 调用 Soln SDK。SDK 详细能力请查看 Soln SDK。

下面示例从一个目标表单中读取省份目标，然后回填到图表。

type BindingInput = {
  chartData: {
    rows: Array<Record<string, unknown>>;
  };
};

export default async function main(
  payload: StudioScriptRuntimeContextPayload,
  context: StudioScriptContext
) {
  const input = payload.input as BindingInput;
  const provinceNames = Array.from(
    new Set(input.chartData.rows.map((row) => String(row['t0.province'] || '')))
  ).filter(Boolean);

  const targetRecords = await context.form.list({
    formApiName: 'sales_targets',
    limit: 100,
    condition: {
      logic: 'and',
      children: [
        {
          field: 'province',
          operator: 'in',
          value: provinceNames,
        },
      ],
    },
  });

  return {
    rows: targetRecords.items.map((record) => ({
      province: record.data.province,
      targetAmount: record.data.targetAmount,
    })),
  };
}

图表中配置省份匹配字段，并把 targetAmount 写入目标金额计算字段。

示例：调用第三方数据

如果当前 Studio 脚本运行环境允许外部请求，可以在脚本中使用运行时支持的 HTTP 能力调用第三方系统。常见做法是先从 chartData.rows 取出当前图表分类，再批量请求外部服务。

type BindingInput = {
  chartData: {
    rows: Array<Record<string, unknown>>;
  };
};

export default async function main(
  payload: StudioScriptRuntimeContextPayload,
  context: StudioScriptContext
) {
  const input = payload.input as BindingInput;
  const months = input.chartData.rows.map((row) => String(row['t0.month'] || ''));

  const response = await context.http.requestJson({
    url: 'https://example.com/api/monthly-targets',
    method: 'POST',
    json: { months },
  });

  if (!response.ok) {
    throw new Error('MONTHLY_TARGET_REQUEST_FAILED');
  }

  const result = response.data as {
    rows: Array<{ month: string; targetAmount: number }>;
  };

  return {
    rows: result.rows,
  };
}

外部请求失败时，可以抛出错误让图表预览显示失败，也可以用 try/catch 转成空结果或默认值。错误处理方式可参考 Soln SDK 中关于脚本错误的说明。

常见问题

数据集预览里看不到脚本字段结果

这是正常现象。脚本型计算字段由图表绑定脚本回填，数据集预览不会执行图表绑定脚本。请在图表编辑器中点击 执行脚本 查看结果。

图表里脚本字段没有值

可以按顺序检查：

图表是否选择了包含脚本型计算字段的数据集
计算字段是否是数字类型，并作为指标放入图表槽位
图表是否选择了 Studio 脚本
赋值字段中的脚本结果字段名是否和脚本返回一致
匹配字段是否能在 chartData.rows 和脚本返回行中找到相同值
脚本返回是否是数组、{ rows: [...] }、{ items: [...] } 或 { data: [...] }

匹配到多条脚本结果时报错

如果聚合方式是无，同一个图表点只能匹配一条脚本结果。需要一对多合并时，把计算字段聚合方式改为求和、平均、最大值、最小值、计数或 去重计数。

应该用表达式还是自定义脚本

优先判断数据来源：

判断	建议
只依赖当前行字段	使用表达式
需要主表和关联表字段做固定计算	使用表达式
需要图表聚合后的分类、分组或指标	使用自定义脚本
需要查询其他 Soln 数据、成员、部门、审批或权限信息	使用自定义脚本，并参考 Soln SDK
需要第三方系统数据	使用自定义脚本

最佳实践

字段名称使用业务语言，例如“目标金额”“完成率”“外部库存”
脚本型指标的数据类型选择数字
能用表达式解决的计算，不要改成脚本
脚本返回字段名保持稳定，例如 targetAmount、budgetAmount、completionRate
图表里显式配置赋值字段，避免依赖同名字段自动匹配
多行结果需要合并时，提前设置好计算字段聚合方式
脚本中优先批量查询，避免按每个图表点单独请求
涉及外部系统时，处理请求失败、空值和超时，避免图表预览不可用

使用链路​

在数据集中添加计算字段​

值来源​

表达式​

自定义脚本​

字段身份和聚合方式​

在图表中绑定脚本​

脚本入参​

脚本返回格式​

匹配字段和赋值字段​

无匹配字段的单行结果​

示例：按图表行计算目标值​

示例：按省份匹配外部结果​

示例：使用 Soln SDK 查询表单数据​

示例：调用第三方数据​

常见问题​

数据集预览里看不到脚本字段结果​

图表里脚本字段没有值​

匹配到多条脚本结果时报错​

应该用表达式还是自定义脚本​

最佳实践​