任务按钮
任务按钮用于执行业务操作、提交配置的流程或运行自定义服务端脚本。按钮类型为 task,自定义按钮主动作是 action.type: 'script';内置按钮保留系统动作。
需要用弹窗或抽屉打开 Studio 页面时,使用 交互按钮。
如何选择
| 需求 | 按钮类型 |
|---|---|
| 更新记录、调用第三方接口、执行服务端业务逻辑 | 自定义任务按钮 |
| 提交配置的审批或自动化流程 | 任务按钮;提交成功与流程最终完成是两个阶段 |
| 打开 Studio 页面供用户操作 | 交互按钮 |
| 修改当前页面 UI 或跳转后预填表单 | 前台请求返回脚本输出的自定义任务按钮,或浏览器消费结果的 UI 回调 |
配置方式
- 在 按钮设计 中添加自定义按钮,类型选择 任务按钮。
- 为点击主动作选择 Studio 脚本及入口文件。
- 按需配置点击前、点击后脚本。
- 需要触发审批或自动化时,配置对应的流程绑定。
只触发流程的自定义任务按钮,主脚本可直接返回 { ok: true },流程在按钮设计中绑定。除非明确需要另发起一次审批,否则不要在脚本中重复调用审批提交 SDK。
执行流程
主表自定义脚本任务按钮提交到服务端执行任务链路:
| 阶段 | 行为 |
|---|---|
beforeClick | 校验入参,可以中断执行 |
action | 执行主 Studio 服务端脚本 |
| 提交流程 | 主动作成功后,提交按钮绑定的流程 |
afterClick | 主动作和流程提交后执行,可读取主动作结果 |
点击后脚本失败不会回滚已经完成的业务写入。多个写入操作应在领域操作中明确事务边界;按钮生命周期不为所有外部调用提供整体事务。
保存、提交等内置按钮保留原有系统执行链路,其浏览器侧点击前后脚本可以消费 UI effects。不能把所有内置按钮都理解为后台自定义任务。
脚本入参
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
return { ok: true };
}
| 字段 | 含义 |
|---|---|
schema | soln.runtime-context/v1 |
source.type | form_button |
source.phase | beforeClick、action、afterClick |
source.buttonId | 按钮标识 |
source.buttonType | preset 或 custom,不是设计配置中的 task/interaction |
form | 当前表单标识,含 id、apiName |
record | 单条选中记录;没有单记录上下文时为 null |
draft.data | 本次执行携带的数据,当前输入从这里读取 |
selection.records | 批量执行时选中的持久化记录 |
input | 调用方显式提供的附加入参 |
result | 主动作结果,供 afterClick 读取 |
runtime | 执行元数据,包括语言和工作空间时区 |
新建页可能没有持久化记录。服务端任务入参可包含记录数据,而浏览器回调可能只提供记录身份。需要持久化值时,使用 context.form.get({ recordId });不要编造记录 ID,也不要将草稿存在当成已经保存。
浏览器回调、子表行上下文及完整共享入参见 交互按钮。子表本地动作和浏览器回调不能直接等同于主表后台执行任务链路。
返回值与持久化
| 返回字段 | 服务端任务行为 |
|---|---|
ok: false / preventDefault: true | 作为执行失败中断当前阶段 |
非空 fieldErrors 对象 | 作为校验失败中断,格式为 { fieldApiName: 'message' };前台收到失败结果时会把错误设置到表单字段上 |
失败结果中的 message | 前台收到失败结果时显示给用户;errorCode 仍保留用于诊断 |
patch.draft / patch.record | 合并到服务端本次执行上下文,不自动落库;返回的草稿 patch 在前台消费时也可更新浏览器草稿 |
| 主动作的其他返回值 | 点击后脚本从 payload.result.output 读取主脚本输出 |
effects、notification、modal | 前台响应中的 scriptOutputs 可由浏览器消费;仅后台完成不会自动回放 UI effects |
持久化使用 Soln SDK 的 context.form.update() 等方法。跳转并预填使用 navigate effect。前台响应携带按阶段排序的 scriptOutputs,浏览器成功跳转后停止消费后续输出。若前台请求返回时没有输出,之后的后台完成不会自动触发跳转。服务端任务无法通过返回确认弹窗来暂停等待用户选择;UI 结果在服务端执行后到达,不能授权或撤销已经发生的写入。
示例
执行前校验金额
放在按钮的 点击前脚本 中。金额不大于 0 时,停止执行。
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,
message: '金额必须大于 0。',
fieldErrors: { amount: '金额必须大于 0。' },
};
}
return { ok: true };
}
修改当前记录
放在查看页按钮的 点击脚本 中,将当前记录的备注改为“已核对”。
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const recordId = payload.record?.id;
if (!recordId) return { ok: false };
const record = await context.form.get({ recordId });
if (!record) return { ok: false };
const updated = await context.form.update({
recordId,
data: { description: '已核对' },
});
if (!updated) throw new Error('RECORD_UPDATE_FAILED');
return { ok: true, recordId: updated.id };
}
这会直接保存修改。请将 description 换成实际字段的 API 名称。
触发审批或自动化
先给按钮绑定流程,再将以下脚本设为 点击脚本。适用于查看页和列表行、批量按钮。
export default async function main() {
return { ok: true };
}
提交成功表示流程已发起,不代表审批已通过。
批量修改选中记录
放在列表批量按钮的 点击脚本 中,一次修改选中记录的备注。
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const records = payload.selection.records;
if (records.length === 0 || records.length > 100) {
return { ok: false };
}
const result = await context.form.batchUpdate({
records: records.map((record) => ({
recordId: record.id,
data: { description: '已核对' },
})),
});
return { ok: true, updatedCount: result.total };
}
每次最多更新 100 条;任一记录更新失败,本次整批修改都会取消。
把订单明细发送给第三方
放在查看页按钮的 点击脚本 中,读取当前订单和商品明细,再发送给第三方接口。
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const recordId = payload.record?.id;
if (!recordId) return { ok: false };
const source = await context.form.get({ recordId });
if (!source) return { ok: false };
const lines = source.childTables.find(
(table) => table.childFormApiName === 'order_products',
)?.items || [];
const response = await context.http.requestJson({
url: 'https://example.com/api/order-review',
method: 'POST',
json: {
recordId: source.id,
customer: source.data.customer,
lines: lines.map((line) => ({
product: line.data.product,
quantity: line.data.quantity,
})),
},
timeoutMs: 10000,
retry: { maxAttempts: 1 },
idempotency: `order-review:${context.runtime.traceId}`,
throwOnHttpError: false,
});
if (!response.ok) {
throw new Error(`ORDER_REVIEW_HTTP_${response.status}`);
}
return { ok: true, recordId: source.id, httpStatus: response.status };
}
将接口地址、子表和字段名替换为实际配置。此例读取已保存的数据,不修改 Soln 数据;需要发送审批中数据时,参考 审批 SDK。
读取点击脚本的结果
与上面的批量修改示例配合,放在同一按钮的 点击后脚本 中,记录更新数量。
export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
const result = payload.result as { output?: { updatedCount?: number } } | null;
const count = result?.output?.updatedCount;
if (typeof count !== 'number') return { ok: false };
context.logger.info('Updated records:', count);
return { ok: true };
}
点击脚本的返回值在 payload.result.output 中。点击后脚本失败不会撤销已保存的修改。
执行反馈
任务响应含 jobId 与 waitStatus,状态为 accepted、completed、failed;错误可包含 errorCode,流程提交可包含 workflowExecution。
审批任务创建成功后,按钮可以提示本次提交成功,下游审批和人工处理仍继续运行。这不代表所有后续节点已执行完成。后台执行结束后,还可以在提醒应用中产生站内通知。
需要确认、跳转或明确的 UI 反馈时,使用交互按钮的浏览器回调或 Studio 页面。