交互按钮
交互按钮用于打开 Studio 页面,让用户查看上下文、补充信息或执行页面中的操作。按钮类型为 interaction,当前主动作为 studioPage;可用弹窗或抽屉打开。
业务执行、自动化和审批任务请查看 任务按钮。
配置与执行流程
- 在 按钮设计 中添加自定义按钮,类型选择 交互按钮。
- 选择已发布的 Studio 页面,设置弹窗或抽屉、标题和尺寸。
- 按需配置点击前、点击后 Studio 脚本。
| 阶段 | 行为 | 是否可中断后续动作 |
|---|---|---|
beforeClick | 执行点击前脚本,浏览器消费返回的 UI effects | 是 |
action | 打开配置的 Studio 页面 | 页面主动作不执行 Studio 脚本 |
afterClick | 页面容器打开并完成已配置的流程触发后,执行点击后脚本 | 不会撤销已打开的页面或已提交的流程 |
afterClick 不代表用户已经在页面中保存、提交或关闭。交互按钮不会统一追加任务式“执行成功”提示,页面或脚本可以按需展示反馈;执行错误仍会提示。记录场景配置了审批或自动化时,仍可能触发对应流程,交互类型不等于禁止业务写入。
下面的脚本协议用于浏览器消费结果的点击前、点击后脚本,也适用于内置按钮在系统动作前后的脚本。自定义任务脚本也可以通过前台请求返回 UI 结果,完成边界见任务按钮。
export default async function main(
payload: FormButtonRuntimePayload,
_context: StudioScriptContext,
) {
return { ok: true, effects: [] };
}
入参 Payload
type FormButtonRuntimePayload = {
schema: 'soln.runtime-context/v1';
source: {
type: 'form_button';
buttonId: string;
buttonType: 'preset' | 'custom';
placement: string;
operation: string;
phase: 'beforeClick' | 'action' | 'afterClick';
};
form: RuntimeFormRef | null;
record: RuntimeRecord | null;
draft: { data: Record<string, unknown> } | null;
selection: { records: RuntimeRecord[]; childRows: RuntimeChildRow[] };
child: RuntimeChildContext | null;
input: Record<string, unknown>;
result: unknown | null;
runtime: RuntimeMetadata;
};
基础上下文
| 字段 | 类型 | 说明 |
|---|---|---|
schema | 'soln.runtime-context/v1' | 统一运行时上下文版本 |
source.phase | 'beforeClick' | 'action' | 'afterClick' | 当前执行阶段 |
form.id | string | null | 表单 schema ID |
form.apiName | string | null | 当前表单 API 名称 |
source.buttonId | string | 按钮标识 |
source.buttonType | 'preset' | 'custom' | 预设按钮或自定义按钮 |
source.placement | string | 运行时位置,如 FORM_HEADER、LIST_ROW、LIST_BATCH |
source.operation | string | 当前动作类型,如 submit、save、saveDraft、custom |
draft.data | Record<string, unknown> | 当前草稿值,按字段 API 名称索引 |
record | { id: string } | null | 当前记录身份;新建页通常为 null;按钮绑定不会预加载记录数据 |
result | Record<string, unknown> | null | 已完成动作的结果,主要在 afterClick 使用 |
runtime.locale | string | 浏览器语言 |
runtime.timezone | string | 浏览器时区 |
当前表单值从 payload.draft.data 读取。脚本确实需要持久化值时,先确认 payload.record?.id 存在,再调用 context.form.get({ recordId: payload.record.id })。
子表上下文
| 字段 | 类型 | 说明 |
|---|---|---|
child.form | object | 子表头部、批量工具栏或行按钮点击时的子表单 |
child.row | object | null | 子表行按钮的当前行草稿数据 |
selection.childRows | RuntimeChildRow[] | 子表批量按钮选中的行 |
子表草稿也可以从 payload.draft.data.__childFormDrafts[childFormApiName] 读取,值为一组子表行对象。
| 按钮位置 | 额外上下文 |
|---|---|
FORM_LIST_HEADER | child.form |
FORM_LIST_BATCH | child.form 和 selection.childRows |
FORM_LIST_ROW | child.form 和 child.row |
返回 Response
未知字段会被忽略。
type FormButtonRuntimeResponse = {
ok?: boolean;
preventDefault?: boolean;
message?: string;
fieldErrors?: Record<string, string>;
patch?: {
draft?: Record<string, unknown>;
record?: Record<string, unknown>;
};
effects?: FormRuntimeEffect[];
notification?: RuntimeNotificationShortcut;
modal?: RuntimeModalShortcut;
};
| 字段 | 类型 | 说明 |
|---|---|---|
ok | boolean | 当前阶段是否继续;缺省按 true 处理 |
preventDefault | boolean | 为 true 时显式停止当前按钮动作 |
message | string | 展示简单消息 |
fieldErrors | Record<string, string> | 设置字段校验错误 |
patch.draft | Record<string, unknown> | 合并到当前草稿状态 |
patch.record | Record<string, unknown> | 合并到当前记录状态 |
effects | FormRuntimeEffect[] | 有序执行的运行时 effects |
notification | object | string | 顶层通知快捷写法 |
modal | object | string | 顶层弹窗快捷写法 |
当 ok 为 false、preventDefault 为 true,或带 awaitAction: true 的确认弹窗被取消时,运行时会停止当前按钮动作。
Effects
Effects 是运行时 UI 指令,不会修改字段设计配置。
本节描述的是 form_button 脚本返回协议(return { effects: [...] }),与 Studio 页面客户端用于回写新建/编辑表单草稿的 applyEffects API 不同;详见 Soln Studio。Studio 页面 API 仅支持 fieldValue、childFieldValue、childRowAdd 和 childRowRemove,不会把当前子表行隐式当作写入目标。
| Effect | 用途 |
|---|---|
fieldState | 覆盖主表字段隐藏、必填、只读或禁用状态 |
fieldOptionFilter | 按稳定选项 value 过滤主表选项字段的配置选项 |
fieldValue | 设置主表字段值 |
fieldError | 展示主表字段校验错误 |
fieldErrorClear | 清除主表字段校验错误 |
childFieldState | 覆盖子表字段隐藏、必填、只读或禁用状态 |
childRowState | 覆盖子表行状态 |
childFieldValue | 设置子表字段值 |
childFieldError | 展示子表字段校验错误 |
childFieldErrorClear | 清除子表字段校验错误 |
childRowAdd | 追加一行或多行子表草稿 |
childRowRemove | 删除一行或多行子表草稿 |
message | 展示简单消息 |
notification | 展示通知 |
modal | 展示弹窗 |
refresh | 请求运行时刷新 |
navigate | 跳转工作空间页面;新建页支持预填主表字段与子表行 |
页面跳转与新建页赋值
使用 navigate 跳转页面,并通过 data 和 childTables 给新建页赋值。
交互按钮的主动作是打开 Studio 页面。需要通过脚本跳转并预填新建表单时,使用自定义任务按钮:前台请求返回 scriptOutputs 后,浏览器会消费其中的 navigate effect。若请求返回时尚无脚本输出,之后的后台完成不会自动让浏览器跳转。
交互按钮的点击前回调成功跳转后,浏览器会停止后续按钮动作,不会再打开原来配置的 Studio 页面。
TypeScript 脚本可使用内置的 StudioScriptNavigateEffect 类型,获得补全和载荷类型检查。
return {
ok: true,
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: { description: '从当前数据带入' },
childTables: { order_lines: [{ product: '商品记录ID', quantity: 2 }] },
}],
};
| 属性 | 类型 | 说明 |
|---|---|---|
type | 'navigate' | 页面跳转指令 |
path | string | 以 / 开头的已注册工作空间路径,在当前标签页打开;不接受外部链接、查询参数、锚点 |
data | Record<string, unknown> | 可选,按目标表单字段 API 名称赋值,仅 /forms/runtime/{formApiName}/new 支持 |
childTables | Record<string, Record<string, unknown>[]> | 可选,以目标子表表单 API 名称为键、行数组为值,每行使用目标子表字段 API 名称;仅新建页支持 |
查看页需要带入已保存的主从数据时,先用 context.form.get() 读取,再显式映射到目标表单。下面的表单、字段 API 名称都需要替换为实际配置:
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
if (!payload.record?.id) {
return { ok: false, message: '请先选择来源数据。' };
}
const source = await context.form.get({ recordId: payload.record.id });
if (!source) return { ok: false, message: '来源数据不存在或无权访问。' };
const lines = source.childTables.find(
(table) => table.childFormApiName === 'source_lines',
)?.items || [];
return {
ok: true,
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: {
source_record: source.id, // 来源主表记录 ID,与 payload.record.id 相同
customer: source.data.customer,
description: source.data.description,
},
childTables: {
order_lines: lines.map((line) => ({
source_line: line.id, // 来源子表记录 ID
product: line.data.product,
quantity: line.data.quantity,
})),
},
}],
};
}
来源主表记录 ID 取 payload.record.id 或 source.id;来源子表每条记录的 ID 取对应子表 items 中的 line.id。两者都在记录顶层,不是 source.data.id 或 line.data.id。childFormApiName 是子表表单的 API 名称,不是某条子表记录的 ID。
示例中,source_record 是目标主表上关联来源主表的可写关联字段,source_line 是目标子表上关联来源子表的可写关联字段。使用前需配置这些字段并替换为实际 API 名称;不需要保留来源关联时,可删除这两项映射。
带入的数据尚未保存,用户仍需保存或提交。只会填入目标表单中已配置的可写字段;只读、自动编号和计算字段等不会复制。不要把来源 ID 作为新记录自身的 id,也不要复制来源子表行的主表归属外键;保存时会生成新记录 ID 和对应的主从归属关系。需要保留来源关联时,按上例通过关联字段传入来源记录 ID。
如果来源是尚未保存的新建/编辑页,主表当前值读取 payload.draft.data,子表当前行读取 payload.draft.data.__childFormDrafts[childFormApiName],再按目标字段 API 名称映射。
跳转携带的数据不会出现在链接中,离开或刷新后会清除。来源页有未保存修改时会先提示确认。把 navigate 放在 effects 最后。只跳转、不赋值时,可以这样写:
return { effects: [{ type: 'navigate', path: '/forms/runtime/orders' }] };
同时携带多个子表
childTables 支持同时携带多个子表,以目标子表 API 名称为键,每个子表对应独立的行数组。例如,将商品明细和费用明细一起带入订单新建页:
return {
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/new',
data: {
customer: 'customer-record-id',
},
childTables: {
order_products: [
{ product: 'product-record-id', quantity: 2 },
],
order_expenses: [
{ description: '运费', amount: 20 },
],
},
}],
};
把多个子表的行数组放在同一个 childTables 中即可,键名使用目标子表的 API 名称。
任一字段类型错误都会停止整次赋值,并提示子表、行号和字段。省略的子表按正常方式初始化,[] 表示不带入行;目标页未配置的子表会被忽略。
字段值类型
主表和子表的字段值都要符合目标字段类型。错误时会停止整次赋值,并提示路径,例如 childTables.order_lines[2].quantity(第 2 行)。必填项和访问权限仍会在提交时校验。
| 目标字段 | 应传入的值 |
|---|---|
| 文本、多行文本、自动补全、邮箱、链接 | 字符串 |
| 数字 | 有限数字,例如 2,不能传 "2" |
| 开关 | true 或 false;不接受字符串、数字和 null |
| 单选/单选按钮 | 配置中的选项 value,不能传显示名称 |
| 多选/复选框组 | 已配置选项 value 的数组 |
| 关联、外键、部门、组织 | 记录 ID 字符串;多值类型传 ID 数组 |
| 成员 | 成员 ID 字符串,或 { principalType: 'MEMBER', principalId: '...' };多成员传数组 |
| 文件、图片、视频、音频 | 文件 ID 字符串数组,不能传 URL 或文件对象 |
| 定位 | 对象;地址部分为字符串,latitude 为 -90~90 的数字、longitude 为 -180~180 的数字,provider 可选 tianditu、mapbox、google |
| 日期、周、月、季度、年 | 合法的 YYYY-MM-DD 日期;也接受草稿值中的合法 ISO 时间戳 |
| 日期时间 | 带时区偏移或 Z 的合法 ISO 日期时间,或工作空间本地时间 YYYY-MM-DD HH:mm:ss |
| 时间 | HH:mm 或 HH:mm:ss,小时为 00~23 |
| 日期/日期时间/时间区间 | 恰好两个元素 [开始, 结束];空端点可传 null,提交时仍校验是否允许留空 |
| 多日期 | 合法日期数组,不能包含无效日期或 null |
省略字段时沿用正常初始化;除开关外,null 表示清空字段,多值类型可用 [] 清空。2026-02-30、未配置的选项值、错误的数组结构或越界坐标都会被拒绝。
打开编辑页
可以跳转编辑页,但编辑页不接受携带数据预填,会按正常权限加载原记录。编辑页、查看页或列表页路径携带 data、childTables 会被拒绝。打开编辑页本身不会更新记录:
return {
effects: [{
type: 'navigate',
path: '/forms/runtime/orders/edit/record-id',
}],
};
主表字段 Effects
{
type: 'fieldState',
field: 'closeReason',
hidden: false,
required: true,
readonly: false,
disabled: false,
}
{
type: 'fieldValue',
field: 'status',
value: 'submitted',
}
{
type: 'fieldError',
field: 'amount',
message: '金额必须大于 0。',
}
| 字段 | 类型 | 适用 effect | 说明 |
|---|---|---|---|
type | string | 全部 | fieldState、fieldOptionFilter、fieldValue、fieldError 或 fieldErrorClear |
field | string | 全部 | 主表字段 API 名称 |
allowedValues | string[] | fieldOptionFilter | 允许继续选择的稳定选项 value |
clearInvalidValue | boolean | fieldOptionFilter | 清除不再允许的当前值 |
reset | boolean | fieldOptionFilter | 恢复字段原始配置选项 |
hidden | boolean | fieldState | 临时隐藏或显示字段 |
required | boolean | fieldState | 临时修改是否必填 |
readonly | boolean | fieldState | 临时修改是否只读 |
disabled | boolean | fieldState | 临时修改是否禁用 |
value | unknown | fieldValue | 新字段值 |
message | string | fieldError | 字段错误文案 |
子表字段 Effects
使用 table 指定子表单 API 名称,也可以使用 childTable、formApiName 或 childFormApiName。
使用 where 按子表字段值筛选行。省略 where 时,effect 作用于当前子表的所有行。
{
type: 'childFieldState',
table: 'orderItems',
field: 'discount',
where: {
logic: 'and',
children: [
{ field: 'productType', operator: 'eq', value: 'service' },
],
},
readonly: true,
required: false,
}
{
type: 'childFieldValue',
table: 'orderItems',
field: 'currency',
where: {
logic: 'and',
children: [
{ field: 'region', operator: 'eq', value: 'US' },
],
},
value: 'USD',
}
{
type: 'childFieldError',
table: 'orderItems',
field: 'quantity',
where: {
logic: 'and',
children: [
{ field: 'quantity', operator: 'lte', value: 0 },
],
},
message: 'Quantity must be greater than zero.',
}
{
type: 'childFieldErrorClear',
table: 'orderItems',
field: 'quantity',
where: {
logic: 'and',
children: [
{ field: 'quantity', operator: 'gt', value: 0 },
],
},
}
| 字段 | 类型 | 适用 effect | 说明 |
|---|---|---|---|
type | string | 全部 | childFieldState、childFieldValue、childFieldError 或 childFieldErrorClear |
table | string | 全部 | 子表单 API 名称 |
field | string | 全部 | 子表字段 API 名称 |
where | ApprovalFlowConditionGroup | 全部 | 行筛选条件 |
hidden | boolean | childFieldState | 隐藏或显示子表字段;隐藏字段会清空草稿值 |
required | boolean | childFieldState | 临时修改是否必填 |
readonly | boolean | childFieldState | 临时修改是否只读 |
disabled | boolean | childFieldState | 临时修改是否禁用 |
value | unknown | childFieldValue | 新子表字段值 |
message | string | childFieldError | 子表字段错误文案 |
子表行 Effects
{
type: 'childRowAdd',
table: 'orderItems',
rows: [
{
productName: 'Standard service',
quantity: 1,
currency: 'USD',
},
{
productName: 'Implementation',
quantity: 1,
currency: 'USD',
},
],
}
{
type: 'childRowRemove',
table: 'orderItems',
where: {
logic: 'and',
children: [
{ field: 'status', operator: 'eq', value: 'cancelled' },
],
},
}
| 字段 | 类型 | 适用 effect | 说明 |
|---|---|---|---|
type | string | 全部 | childRowState、childRowAdd 或 childRowRemove |
table | string | 全部 | 子表单 API 名称 |
selected | boolean | childRowState | 将匹配行标记为选中态 |
backgroundColor | string | childRowState | 匹配行的运行时背景色 |
hoverBackgroundColor | string | childRowState | 鼠标悬停时匹配行的运行时背景色 |
data | Record<string, unknown> | childRowAdd | 追加单行草稿 |
rows | Array<Record<string, unknown>> | childRowAdd | 追加多行草稿,存在时忽略 data |
where | ApprovalFlowConditionGroup | childRowState、childRowRemove | 更新或删除当前草稿中的匹配子表行 |
反馈类 Effects
{
type: 'message',
level: 'warning',
text: 'Please review the highlighted fields.',
}
{
type: 'notification',
level: 'info',
title: 'Validation completed',
description: 'The record passed the external validation.',
placement: 'topRight',
duration: 4,
closable: true,
width: 480,
maxHeight: 320,
}
{
type: 'modal',
level: 'confirm',
title: 'Continue submission?',
content: 'This amount is high. Continue submitting this record?',
okText: 'Continue',
cancelText: 'Cancel submit',
awaitAction: true,
}
| 字段 | 类型 | 适用 effect | 说明 |
|---|---|---|---|
type | string | 全部 | message、notification 或 modal |
level | string | 全部 | success、info、warning、error,modal 还支持 confirm |
text | string | message | 简单消息文本 |
title | string | notification、modal | 标题文本 |
description | string | notification | 通知说明 |
content | string | modal | 弹窗内容 |
okText | string | modal | 确认按钮文案 |
cancelText | string | modal | 确认弹窗的取消按钮文案 |
awaitAction | boolean | modal | 为 true 时等待用户选择,取消后中断动作 |
placement | string | notification | 通知位置 |
duration | number | notification | 展示秒数 |
closable | boolean | notification | 是否显示关闭入口 |
centered | boolean | modal | 是否在视口中垂直居中弹窗 |
width | number | string | notification、modal | 宽度 |
height | number | string | notification、modal | 固定高度 |
maxHeight | number | string | notification、modal | 最大高度 |
顶层 notification 和 modal 快捷写法接受同一组参数,但不需要 type。
刷新
{
type: 'refresh',
target: 'record',
}
| 字段 | 类型 | 说明 |
|---|---|---|
type | 'refresh' | 刷新请求 |
target | 'record' | 'list' | 'children' | 'all' | 刷新目标;实际支持范围取决于当前页面 |
示例
在弹窗中查看当前数据
将下面组件放入 Studio 页面并发布,再在查看页的交互按钮中选择该页面,打开方式选 弹窗。
import { getRuntimeContext } from '@soln/studio';
export default function App() {
const payload = getRuntimeContext();
return (
<pre>{JSON.stringify({
recordId: payload?.record?.id,
data: payload?.draft?.data,
childRows: payload?.selection?.childRows,
child: payload?.child,
}, null, 2)}</pre>
);
}
当前主表值在 draft.data,子表值在 draft.data.__childFormDrafts。新建页没有记录 ID;读取已保存的数据可在页面的服务端脚本中调用 context.form.get()。
打开页面前确认
放在 点击前脚本 中。用户确认后打开页面,取消则停止。
export default async function main() {
return {
ok: true,
modal: {
level: 'confirm',
title: '是否继续?',
content: '是否打开页面?',
awaitAction: true,
},
};
}
填写备注并设为必填
放在新建或编辑页按钮的 点击前脚本 中,填写备注并将其设为必填。
export default async function main() {
return {
ok: true,
patch: { draft: { description: '待核对' } },
effects: [{ type: 'fieldState', field: 'description', required: true }],
};
}
这里只改页面草稿,保存后才写入数据。
选中多条记录后打开抽屉
在列表批量操作区添加交互按钮,选择 Studio 页面,打开方式选 抽屉。以下 点击前脚本 会检查是否已选中记录。
export default async function main(payload: FormButtonRuntimePayload) {
if (payload.selection.records.length === 0) {
return { ok: false, message: '请至少选择一条记录。' };
}
return { ok: true };
}
Studio 页面中使用:
import { getRuntimeContext } from '@soln/studio';
export default function App() {
const records = getRuntimeContext()?.selection?.records || [];
return (
<ul>
{records.map((record) => <li key={record.id}>{record.id}</li>)}
</ul>
);
}
检查当前填写的金额
放在新建或编辑页按钮的 点击前脚本 中。金额无效时显示字段错误,并阻止打开页面。
export default async function main(payload: FormButtonRuntimePayload) {
const amount = payload.draft?.data?.amount;
if (typeof amount !== 'number' || !Number.isFinite(amount) || amount <= 0) {
return {
ok: false,
fieldErrors: { amount: '金额必须大于 0。' },
};
}
return {
ok: true,
effects: [{ type: 'fieldErrorClear', field: 'amount' }],
};
}
统一主表和子表的币种
放在新建或编辑页按钮的 点击前脚本 中,将主表和两个子表现有行的币种设为 CNY。
export default async function main() {
return {
ok: true,
effects: [
{ type: 'fieldValue', field: 'currency', value: 'CNY' },
{
type: 'childFieldValue',
table: 'order_products',
field: 'currency',
value: 'CNY',
},
{
type: 'childFieldValue',
table: 'order_expenses',
field: 'currency',
value: 'CNY',
},
],
};
}
将表名和字段名换成实际 API 名称。此操作只改草稿;选项字段应使用选项 value,而不是显示名称。
删除空明细并添加费用
放在新建或编辑页按钮的 点击前脚本 中,移除数量为 0 的商品明细,并追加一条运费。
export default async function main() {
return {
ok: true,
effects: [
{
type: 'childRowRemove',
table: 'order_products',
where: {
logic: 'and',
children: [{ field: 'quantity', operator: 'eq', value: 0 }],
},
},
{
type: 'childRowAdd',
table: 'order_expenses',
rows: [{ description: '运费', amount: 20 }],
},
],
};
}
这里只改草稿,保存后才生效。每次点击都会追加一条费用,按需检查是否已经存在。
打开页面后显示提示
放在 点击后脚本 中,显示一条提示。
export default async function main() {
return {
ok: true,
effects: [{
type: 'message',
level: 'info',
text: '正在打开页面。',
}],
};
}
此时只表示页面正在打开,不代表用户已保存数据。
跳转新建页并带入数据
参见 页面跳转与新建页赋值,包含 多个子表的示例。
跳转脚本作为点击主动作时,使用自定义任务按钮。脚本输出需随前台请求返回;仅后台执行完成不会自动触发浏览器跳转。
运行限制
source.buttonType是preset/custom,与设计配置的task/interaction不是同一个字段。- Effects 修改运行时 UI 或草稿,不修改字段设计;必填校验按当前运行时状态执行。
refresh目前只做协议校验和归一化,没有实际刷新处理,不要依赖它重新加载页面。- 页面跳转、草稿预填和数据库写入是不同操作;新建页预填不会保存记录。