跳到主要内容

交互按钮

交互按钮用于打开 Studio 页面,让用户查看上下文、补充信息或执行页面中的操作。按钮类型为 interaction,当前主动作为 studioPage;可用弹窗或抽屉打开。

业务执行、自动化和审批任务请查看 任务按钮。

配置与执行流程​

  1. 在 按钮设计 中添加自定义按钮,类型选择 交互按钮。
  2. 选择已发布的 Studio 页面,设置弹窗或抽屉、标题和尺寸。
  3. 按需配置点击前、点击后 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.idstring | null表单 schema ID
form.apiNamestring | null当前表单 API 名称
source.buttonIdstring按钮标识
source.buttonType'preset' | 'custom'预设按钮或自定义按钮
source.placementstring运行时位置,如 FORM_HEADER、LIST_ROW、LIST_BATCH
source.operationstring当前动作类型,如 submit、save、saveDraft、custom
draft.dataRecord<string, unknown>当前草稿值,按字段 API 名称索引
record{ id: string } | null当前记录身份;新建页通常为 null;按钮绑定不会预加载记录数据
resultRecord<string, unknown> | null已完成动作的结果,主要在 afterClick 使用
runtime.localestring浏览器语言
runtime.timezonestring浏览器时区

当前表单值从 payload.draft.data 读取。脚本确实需要持久化值时,先确认 payload.record?.id 存在,再调用 context.form.get({ recordId: payload.record.id })。

子表上下文​

字段类型说明
child.formobject子表头部、批量工具栏或行按钮点击时的子表单
child.rowobject | null子表行按钮的当前行草稿数据
selection.childRowsRuntimeChildRow[]子表批量按钮选中的行

子表草稿也可以从 payload.draft.data.__childFormDrafts[childFormApiName] 读取,值为一组子表行对象。

按钮位置额外上下文
FORM_LIST_HEADERchild.form
FORM_LIST_BATCHchild.form 和 selection.childRows
FORM_LIST_ROWchild.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;
};
字段类型说明
okboolean当前阶段是否继续;缺省按 true 处理
preventDefaultboolean为 true 时显式停止当前按钮动作
messagestring展示简单消息
fieldErrorsRecord<string, string>设置字段校验错误
patch.draftRecord<string, unknown>合并到当前草稿状态
patch.recordRecord<string, unknown>合并到当前记录状态
effectsFormRuntimeEffect[]有序执行的运行时 effects
notificationobject | string顶层通知快捷写法
modalobject | 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'页面跳转指令
pathstring以 / 开头的已注册工作空间路径,在当前标签页打开;不接受外部链接、查询参数、锚点
dataRecord<string, unknown>可选,按目标表单字段 API 名称赋值,仅 /forms/runtime/{formApiName}/new 支持
childTablesRecord<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说明
typestring全部fieldState、fieldOptionFilter、fieldValue、fieldError 或 fieldErrorClear
fieldstring全部主表字段 API 名称
allowedValuesstring[]fieldOptionFilter允许继续选择的稳定选项 value
clearInvalidValuebooleanfieldOptionFilter清除不再允许的当前值
resetbooleanfieldOptionFilter恢复字段原始配置选项
hiddenbooleanfieldState临时隐藏或显示字段
requiredbooleanfieldState临时修改是否必填
readonlybooleanfieldState临时修改是否只读
disabledbooleanfieldState临时修改是否禁用
valueunknownfieldValue新字段值
messagestringfieldError字段错误文案

子表字段 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说明
typestring全部childFieldState、childFieldValue、childFieldError 或 childFieldErrorClear
tablestring全部子表单 API 名称
fieldstring全部子表字段 API 名称
whereApprovalFlowConditionGroup全部行筛选条件
hiddenbooleanchildFieldState隐藏或显示子表字段;隐藏字段会清空草稿值
requiredbooleanchildFieldState临时修改是否必填
readonlybooleanchildFieldState临时修改是否只读
disabledbooleanchildFieldState临时修改是否禁用
valueunknownchildFieldValue新子表字段值
messagestringchildFieldError子表字段错误文案

子表行 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说明
typestring全部childRowState、childRowAdd 或 childRowRemove
tablestring全部子表单 API 名称
selectedbooleanchildRowState将匹配行标记为选中态
backgroundColorstringchildRowState匹配行的运行时背景色
hoverBackgroundColorstringchildRowState鼠标悬停时匹配行的运行时背景色
dataRecord<string, unknown>childRowAdd追加单行草稿
rowsArray<Record<string, unknown>>childRowAdd追加多行草稿,存在时忽略 data
whereApprovalFlowConditionGroupchildRowState、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说明
typestring全部message、notification 或 modal
levelstring全部success、info、warning、error,modal 还支持 confirm
textstringmessage简单消息文本
titlestringnotification、modal标题文本
descriptionstringnotification通知说明
contentstringmodal弹窗内容
okTextstringmodal确认按钮文案
cancelTextstringmodal确认弹窗的取消按钮文案
awaitActionbooleanmodal为 true 时等待用户选择,取消后中断动作
placementstringnotification通知位置
durationnumbernotification展示秒数
closablebooleannotification是否显示关闭入口
centeredbooleanmodal是否在视口中垂直居中弹窗
widthnumber | stringnotification、modal宽度
heightnumber | stringnotification、modal固定高度
maxHeightnumber | stringnotification、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 目前只做协议校验和归一化,没有实际刷新处理,不要依赖它重新加载页面。
  • 页面跳转、草稿预填和数据库写入是不同操作;新建页预填不会保存记录。