跳到主要内容

任务按钮

任务按钮用于执行业务操作、提交配置的流程或运行自定义服务端脚本。按钮类型为 task,自定义按钮主动作是 action.type: 'script';内置按钮保留系统动作。

需要用弹窗或抽屉打开 Studio 页面时,使用 交互按钮。

如何选择​

需求按钮类型
更新记录、调用第三方接口、执行服务端业务逻辑自定义任务按钮
提交配置的审批或自动化流程任务按钮;提交成功与流程最终完成是两个阶段
打开 Studio 页面供用户操作交互按钮
修改当前页面 UI 或跳转后预填表单前台请求返回脚本输出的自定义任务按钮,或浏览器消费结果的 UI 回调

配置方式​

  1. 在 按钮设计 中添加自定义按钮,类型选择 任务按钮。
  2. 为点击主动作选择 Studio 脚本及入口文件。
  3. 按需配置点击前、点击后脚本。
  4. 需要触发审批或自动化时,配置对应的流程绑定。

只触发流程的自定义任务按钮,主脚本可直接返回 { ok: true },流程在按钮设计中绑定。除非明确需要另发起一次审批,否则不要在脚本中重复调用审批提交 SDK。

执行流程​

主表自定义脚本任务按钮提交到服务端执行任务链路:

阶段行为
beforeClick校验入参,可以中断执行
action执行主 Studio 服务端脚本
提交流程主动作成功后,提交按钮绑定的流程
afterClick主动作和流程提交后执行,可读取主动作结果

点击后脚本失败不会回滚已经完成的业务写入。多个写入操作应在领域操作中明确事务边界;按钮生命周期不为所有外部调用提供整体事务。

保存、提交等内置按钮保留原有系统执行链路,其浏览器侧点击前后脚本可以消费 UI effects。不能把所有内置按钮都理解为后台自定义任务。

脚本入参​

export default async function main(
payload: FormButtonRuntimePayload,
context: StudioScriptContext,
) {
return { ok: true };
}
字段含义
schemasoln.runtime-context/v1
source.typeform_button
source.phasebeforeClick、action、afterClick
source.buttonId按钮标识
source.buttonTypepreset 或 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 页面。