关联数据范围

关联数据范围脚本用于限制 search、multi_search 或 foreign_key 字段在选择弹窗中可以选择哪些目标记录。

当可选记录依赖来源字段、当前表单、当前子表行、当前用户或业务规则时，使用这个交互事件。例如只允许选择启用中的产品、当前部门客户，或当前子表行分类下的物料。

配置关联数据范围脚本

进入 工作管理 > 表单管理
打开包含来源关联字段的表单
进入 字段设计
选择一个 search、multi_search 或 foreign_key 字段
在字段属性面板中打开 关联数据范围
选择 Studio 脚本；如果脚本包含多个文件，可以继续选择入口文件
保存字段

脚本绑定在来源字段上。不要把这类过滤规则配置到目标表单的页面事件里。

脚本函数

type RelationDataRangePayload = {
  schema: 'soln.runtime-context/v1';
  source: {
    type: 'relation_data_range';
    scope: 'main' | 'child';
    fieldApiName: string | null;
    targetForm: RuntimeFormRef;
  };
  form: RuntimeFormRef | null;
  record: RuntimeRecord | null;
  draft: { data: Record<string, unknown> } | null;
  selection: { records: RuntimeRecord[]; childRows: RuntimeChildRow[] };
  child: RuntimeChildContext | null;
  input: { search: { keyword: string; batchKeywords: string[]; field: string } };
  result: unknown | null;
  runtime: RuntimeMetadata;
};

export default async function main(payload: RelationDataRangePayload) {
  return {
    ok: true,
    effects: [
      {
        type: 'relationDataFilter',
        condition: {
          logic: 'and',
          children: [
            {
              field: 'status',
              operator: 'eq',
              value: 'active',
            },
          ],
        },
      },
    ],
  };
}

入参 Payload

字段	类型	说明
`schema`	`'soln.runtime-context/v1'`	统一运行时上下文版本
`source.type`	`'relation_data_range'`	关联数据范围来源
`source.scope`	`'main' \| 'child'`	来源字段属于主表还是子表
`source.fieldApiName`	`string \| null`	来源关联字段 API 名称
`source.targetForm`	`RuntimeFormRef`	目标表单
`form`	`RuntimeFormRef \| null`	来源表单
`record`	`RuntimeRecord \| null`	当前已保存记录
`draft.data`	`Record<string, unknown>`	当前主表草稿值
`child.row.data`	`Record<string, unknown>`	子表范围内的当前行草稿值
`selection.childRows`	`RuntimeChildRow[]`	当前执行可用的子表行
`input.search.keyword`	`string`	选择弹窗中的当前搜索关键词
`input.search.batchKeywords`	`string[]`	选择器执行批量查找时的关键词列表
`input.search.field`	`string`	选择器使用的目标搜索字段

返回 Response

返回 relationDataFilter 条件。条件中的 field 必须使用目标表单字段 API 名称，不要使用来源表单字段名或展示名称。

运行时会把这个条件和用户在选择弹窗中的当前筛选条件用 and 合并。

Effect 返回

return {
  ok: true,
  effects: [
    {
      type: 'relationDataFilter',
      condition: {
        logic: 'and',
        children: [
          { field: 'so_product_type', operator: 'eq', value: 'standard' },
        ],
      },
    },
  ],
};

直接返回

当脚本只需要返回条件时，运行时也接受直接返回形式：

return {
  relationDataFilter: {
    condition: {
      logic: 'and',
      children: [
        { field: 'so_product_type', operator: 'eq', value: 'standard' },
      ],
    },
  },
};

return {
  condition: {
    logic: 'and',
    children: [
      { field: 'so_product_type', operator: 'eq', value: 'standard' },
    ],
  },
};

示例：仅启用产品

export default async function main(payload) {
  if (
    payload?.schema !== 'soln.runtime-context/v1' ||
    payload?.source?.type !== 'relation_data_range'
  ) {
    return { ok: true };
  }

  return {
    ok: true,
    effects: [
      {
        type: 'relationDataFilter',
        condition: {
          logic: 'and',
          children: [
            {
              field: 'so_status',
              operator: 'eq',
              value: 'active',
            },
          ],
        },
      },
    ],
  };
}

注意事项

脚本绑定在来源 search、multi_search 或 foreign_key 字段上
condition.children 中使用目标表单字段 API 名称
主表值使用 payload.draft.data，当前子表行值使用 payload.child.row.data
选择器输入从 payload.input.search 读取，不要增加自定义顶层字段
不要把这类规则放到目标表单的页面加载事件里

配置关联数据范围脚本​

脚本函数​

入参 Payload​

返回 Response​

Effect 返回​

直接返回​

示例：仅启用产品​

注意事项​