Soln SDK

当 Studio 脚本需要查询或写入记录、读取表单元数据、创建文件资产、查询组织目录数据、处理审批运行时数据，或从已挂载的工作空间应用发送消息时，可以使用 studioScriptContext。

这组 SDK 可用于按钮设计、布局设计、审批服务调用、集成流程等位置配置的 Studio 脚本。

基础用法

export default async function main(payload: StudioScriptRuntimeContextPayload, context: StudioScriptContext) {
  const created = await context.form.create({
    formApiName: 'orders',
    title: 'SO-1001',
    data: {
      orderNo: 'SO-1001',
      amount: 1200,
    },
  });

  return {
    ok: true,
    recordId: created.id,
  };
}

payload 始终使用 soln.runtime-context/v1，调用方传入的值位于 payload.input。每个远程 SDK 方法都以一个对象承载文档声明的输入；输入标记为可选的方法可以不传参数。禁止使用位置参数或多个参数。面向表单的 API 使用 formApiName，面向已有记录的 API 使用 recordId；例如更新记录应调用 context.form.update({ recordId, data })。脚本中不要硬编码表单 ID。

SDK 返回会按表单字段元数据格式化表单数据：date 字段返回 YYYY-MM-DD，datetime 字段返回 YYYY-MM-DD HH:mm:ss。

所有需要分页的 SDK 方法只使用游标分页。首次请求省略 cursor，下一次请求传入上一次返回的 nextCursor，并保持其他查询条件和 limit 不变。旧的 page、pageSize 参数不再接受。当 hasMore 为 false 且 nextCursor 为 null 时，表示已经读取完毕。

Client

interface StudioScriptContext {
  runtime: StudioScriptRuntimeInfo;
  logger: StudioScriptLogger;
  http: StudioScriptHttpClient;
  file: StudioScriptFileClient;
  form: StudioScriptFormClient;
  formSavedFilter: StudioScriptFormSavedFilterClient;
  formSchema: StudioScriptFormSchemaClient;
  formTableView: StudioScriptFormTableViewClient;
  approval: StudioScriptApprovalClient;
  organization: StudioScriptOrganizationClient;
  department: StudioScriptDepartmentClient;
  member: StudioScriptMemberClient;
  iam: StudioScriptIamClient;
}

type StudioScriptRuntimeInfo = {
  tenantId: string;
  assetId: string;
  assetCode: string;
  workspaceAppCode: string | null;
  executionId: string;
  startedAt: string;
  traceId: string;
};

type StudioScriptLogger = {
  log: (...args: unknown[]) => void;
  info: (...args: unknown[]) => void;
  warn: (...args: unknown[]) => void;
  error: (...args: unknown[]) => void;
  debug: (...args: unknown[]) => void;
};

interface StudioScriptHttpClient {
  request(input: StudioScriptHttpRequestInput): Promise<StudioScriptHttpResponse>;
  requestJson<TData = unknown>(input: StudioScriptHttpRequestInput): Promise<StudioScriptHttpJsonResponse<TData>>;
}

interface StudioScriptFormClient {
  list(input: StudioScriptFormListInput): Promise<StudioScriptFormRecordList>;
  find(input: StudioScriptFormFindInput): Promise<StudioScriptFormRecord | null>;
  get(input: { recordId: string }): Promise<StudioScriptFormRecord | null>;
  batchGet(input: { recordIds: string[] }): Promise<StudioScriptFormBatchGetResult>;
  create(input: StudioScriptFormCreateInput): Promise<StudioScriptFormRecord | StudioScriptFormCreateResult>;
  createWithChildTables(input: StudioScriptFormCreateWithChildTablesInput): Promise<StudioScriptFormCreateWithChildTablesResult>;
  batchCreate(input: StudioScriptFormBatchCreateInput): Promise<StudioScriptFormBatchCreateResult>;
  batchCreateWithChildTables(input: StudioScriptFormBatchCreateWithChildTablesInput): Promise<StudioScriptFormBatchCreateWithChildTablesResult>;
  batchUpdate(input: StudioScriptFormBatchUpdateInput): Promise<StudioScriptFormBatchUpdateResult>;
  updateWithChildTables(input: StudioScriptFormUpdateWithChildTablesInput): Promise<StudioScriptFormUpdateWithChildTablesResult | null>;
  batchUpdateWithChildTables(input: StudioScriptFormBatchUpdateWithChildTablesInput): Promise<StudioScriptFormBatchUpdateWithChildTablesResult>;
  update(input: StudioScriptFormUpdateInput): Promise<StudioScriptFormRecord | null>;
  trash(input: StudioScriptFormDeleteInput): Promise<{ trashed: boolean }>;
  batchTrash(input: StudioScriptFormBatchDeleteInput): Promise<StudioScriptFormBatchTrashResult>;
  restore(input: StudioScriptFormRestoreInput): Promise<StudioScriptFormRecord | null>;
  batchDelete(input: StudioScriptFormBatchDeleteInput): Promise<StudioScriptFormBatchDeleteResult>;
  delete(input: StudioScriptFormDeleteInput): Promise<{ deleted: boolean }>;
}

interface StudioScriptFormSavedFilterClient {
  list(input: { formApiName: string }): Promise<{ items: StudioScriptFormSavedFilter[] }>;
  save(input: { formApiName: string; id?: string | null; name: string; condition: Record<string, unknown> }): Promise<StudioScriptFormSavedFilter>;
  delete(input: { filterId: string }): Promise<{ id: string }>;
}

interface StudioScriptFormTableViewClient {
  list(input: { formApiName: string }): Promise<{ items: StudioScriptFormTableView[] }>;
  save(input: { formApiName: string; id?: string | null; name: string; layoutIds?: string[] | null; groupFieldIds?: string[] | null; scopes?: string[] | null; bordered?: boolean | null; showRowNumber?: boolean | null; groups?: StudioScriptFormTableViewGroup[] | null }): Promise<StudioScriptFormTableView>;
  delete(input: { viewId: string }): Promise<{ id: string }>;
}

interface StudioScriptFormSavedFilter {
  id: string;
  tenantId: string;
  formId: string;
  ownerType: string;
  ownerId: string;
  name: string;
  condition: unknown;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

interface StudioScriptFormTableViewGroup {
  id: string;
  name: string;
  fieldIds: string[];
  level: 1 | 2 | 3;
  parentId: string | null;
}

interface StudioScriptFormTableView {
  id: string;
  tenantId: string;
  formId: string;
  ownerType: string;
  ownerId: string;
  name: string;
  layoutIds: string[];
  groupFieldIds: string[];
  scopes: string[];
  bordered: boolean;
  showRowNumber: boolean;
  groups: StudioScriptFormTableViewGroup[];
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

Context Client：

Client	类型	说明
`runtime`	`StudioScriptRuntimeInfo`	当前执行元数据，包括租户、资产、已校验的工作空间应用、执行和 trace ID
`logger`	`StudioScriptLogger`	写入 Studio 运行日志
`http`	`StudioScriptHttpClient`	在服务端 Studio runtime 中发起外部 HTTP 请求
`file`	`StudioScriptFileClient`	解析和创建文件资产
`form`	`StudioScriptFormClient`	查询和写入表单记录
`formSavedFilter`	`StudioScriptFormSavedFilterClient`	查询和管理表单保存筛选器
`formSchema`	`StudioScriptFormSchemaClient`	查询表单和字段元数据
`formTableView`	`StudioScriptFormTableViewClient`	查询和管理表单表格视图
`approval`	`StudioScriptApprovalClient`	提交记录审批，并处理审批运行时数据
`organization`	`StudioScriptOrganizationClient`	查询组织记录和组织树
`department`	`StudioScriptDepartmentClient`	查询部门数据和部门树
`member`	`StudioScriptMemberClient`	查询成员数据
`iam`	`StudioScriptIamClient`	查询当前成员或指定成员的角色摘要

表单 Client 方法：

方法	入参	返回值	说明
`list`	`StudioScriptFormListInput`	`StudioScriptFormRecordList`	按条件批量获取记录
`find`	`StudioScriptFormFindInput`	`StudioScriptFormRecord \| null`	单条记录查询：按条件返回第一条匹配记录
`get`	`{ recordId: string }`	`StudioScriptFormRecord \| null`	按记录 ID 查询一条记录
`batchGet`	`{ recordIds: string[] }`	`{ items: StudioScriptFormRecord[]; total: number }`	按记录 ID 批量查询记录
`create`	`StudioScriptFormCreateInput`	`StudioScriptFormRecord \| StudioScriptFormCreateResult`	新建一条表单记录，可选提交审批
`createWithChildTables`	`StudioScriptFormCreateWithChildTablesInput`	`StudioScriptFormCreateWithChildTablesResult`	在一个事务中创建一条主表记录和明细表记录
`batchCreate`	`StudioScriptFormBatchCreateInput`	`StudioScriptFormBatchCreateResult`	在一个事务中创建多条表单记录
`batchCreateWithChildTables`	`StudioScriptFormBatchCreateWithChildTablesInput`	`StudioScriptFormBatchCreateWithChildTablesResult`	在一个事务中批量创建多条主表记录及各自的明细表记录
`batchUpdate`	`StudioScriptFormBatchUpdateInput`	`StudioScriptFormBatchUpdateResult`	在一个事务中更新多条表单记录
`updateWithChildTables`	`StudioScriptFormUpdateWithChildTablesInput`	`StudioScriptFormUpdateWithChildTablesResult \| null`	在一个事务中更新一条主表记录和明细表记录
`batchUpdateWithChildTables`	`StudioScriptFormBatchUpdateWithChildTablesInput`	`StudioScriptFormBatchUpdateWithChildTablesResult`	在一个事务中批量更新多条主表记录及各自的明细表记录
`update`	`StudioScriptFormUpdateInput`	`StudioScriptFormRecord \| null`	更新一条表单记录
`trash`	`StudioScriptFormDeleteInput`	`{ trashed: boolean }`	将一条表单记录移入回收站
`batchTrash`	`StudioScriptFormBatchDeleteInput`	`StudioScriptFormBatchTrashResult`	将多条表单记录移入回收站
`restore`	`StudioScriptFormRestoreInput`	`StudioScriptFormRecord \| null`	恢复一条回收站记录，并可在恢复时更新标题、数据和状态
`batchDelete`	`StudioScriptFormBatchDeleteInput`	`StudioScriptFormBatchDeleteResult`	永久删除多条表单记录
`delete`	`StudioScriptFormDeleteInput`	`{ deleted: boolean }`	永久删除一条表单记录

trash 是默认业务删除操作，会将记录移入回收站，通常可以通过产品流程恢复。delete 是硬删除，只应在脚本明确需要永久删除记录时使用。

保存筛选器和表格视图方法：

Client	方法	入参	返回值	说明
`formSavedFilter`	`list`	`{ formApiName: string }`	`{ items: StudioScriptFormSavedFilter[] }`	查询一个表单的保存筛选器
`formSavedFilter`	`save`	`{ formApiName: string; id?: string; name: string; condition: object }`	`StudioScriptFormSavedFilter`	新建或更新一个保存筛选器
`formSavedFilter`	`delete`	`{ filterId: string }`	`{ id: string }`	删除一个保存筛选器
`formTableView`	`list`	`{ formApiName: string }`	`{ items: StudioScriptFormTableView[] }`	查询一个表单的表格视图
`formTableView`	`save`	`{ formApiName: string; id?: string; name: string; layoutIds?; groupFieldIds?; scopes?; bordered?; showRowNumber?; groups? }`	`StudioScriptFormTableView`	新建或更新一个表格视图；没有 `columns` 入参
`formTableView`	`delete`	`{ viewId: string }`	`{ id: string }`	删除一个表格视图

Runtime、Logger 与 HTTP

使用 context.runtime 读取执行标识，使用 context.logger 写运行日志，使用 context.http 发起服务端外部请求。

export default async function main(payload: StudioScriptRuntimeContextPayload, context: StudioScriptContext) {
  context.logger.info('execution', context.runtime.executionId);

  const response = await context.http.requestJson({
    url: 'https://example.com/api/orders',
    method: 'POST',
    json: payload,
    timeoutMs: 10000,
    retry: {
      maxAttempts: 2,
    },
  });

  return {
    ok: response.ok,
    status: response.status,
    data: response.data,
    traceId: context.runtime.traceId,
  };
}

HTTP 请求入参：

type StudioScriptHttpRequestInput = {
  url: string;
  method?: string;
  query?: Record<string, unknown>;
  headers?: Record<string, unknown>;
  json?: unknown;
  body?: unknown;
  timeoutMs?: number;
  retry?: number | {
    maxAttempts?: number;
    baseDelayMs?: number;
    maxDelayMs?: number;
    factor?: number;
    retryableStatusCodes?: number[];
  };
  expect?: 'json' | 'text';
  throwOnHttpError?: boolean;
  idempotency?: boolean | string | {
    key?: string;
    headerName?: string;
  };
};

type StudioScriptHttpResponse = {
  ok: boolean;
  status: number;
  code: string;
  url: string;
  method: string;
  headers: Record<string, string>;
  requestId: string;
  traceId: string | null;
  idempotencyKey: string | null;
  durationMs: number;
  attempts: number;
  bodyText: string;
  bodyJson: unknown;
};

type StudioScriptHttpJsonResponse<TData = unknown> = StudioScriptHttpResponse & {
  data: TData | null;
};

requestJson 是便捷封装，会设置 expect: 'json'，并把解析后的 JSON 响应放在 data。

Logger 方法按日志级别使用：

方法	用途
`context.logger.debug`	仅用于调试执行细节
`context.logger.info` / `log`	记录正常执行阶段和关键标识
`context.logger.warn`	记录可继续执行的异常状态
`context.logger.error`	记录已经失败或即将返回失败的操作

不要记录密钥、Authorization Header、完整个人资料或文件内容。

HTTP 使用规则：

服务端脚本使用 context.http，不要直接使用 fetch
每次外部请求都设置有界的 timeoutMs
JSON 接口优先使用 requestJson；文本或自定义响应使用 request
脚本需要自行处理 4xx/5xx 时设置 throwOnHttpError: false 并检查 response.ok
会产生外部写入的请求使用稳定的 idempotency key；审批和自动化场景通常可以使用 context.runtime.traceId
不在脚本中硬编码凭证；使用 OpenLink 集成系统配置外部鉴权

记录结构

type StudioScriptFormRecord = {
  id: string;
  tenantId: string;
  formId: string;
  formName: string;
  title: string;
  data: Record<string, unknown>;
  dataStatus: 'draft' | 'active' | 'archived' | 'trashed';
  approvalStatus: 'none' | 'pending' | 'approved' | 'rejected' | 'returned' | 'canceled';
  approvalFlowInstanceId: string | null;
  createdAt: string;
  updatedAt: string;
  createdBy?: StudioScriptFormRecordPrincipal;
  updatedBy?: StudioScriptFormRecordPrincipal;
};

type StudioScriptFormCreateResult = StudioScriptFormRecord & {
  approval: {
    queued: true;
    submitted: false;
    jobId: string;
    action: 'create';
    record: {
      recordId: string;
      formId: string;
    };
  };
};

type StudioScriptFormBatchCreateResult = {
  items: Array<StudioScriptFormRecord | StudioScriptFormCreateResult>;
  total: number;
};

type StudioScriptFormCreateWithChildTablesResult = {
  record: StudioScriptFormRecord | StudioScriptFormCreateResult;
  childTables: Array<{
    childFormApiName: string;
    items: Array<StudioScriptFormRecord | StudioScriptFormCreateResult>;
    total: number;
  }>;
};

type StudioScriptFormBatchCreateWithChildTablesResult = {
  items: StudioScriptFormCreateWithChildTablesResult[];
  total: number;
};

type StudioScriptFormRecordPrincipal = {
  memberId?: string | null;
  departmentId?: string | null;
  organizationId?: string | null;
};

记录字段值在 data 中，key 为字段 API 名。

返回与失败行为

表单 SDK 方法成功时会 resolve 为文档中的返回类型。业务错误、权限错误不会返回 { ok: false }。

方法	成功返回	空结果或目标不存在	失败行为
`list`	`StudioScriptFormRecordList`	`items: []`，`hasMore: false`，`nextCursor: null`	Promise reject
`find`	`StudioScriptFormRecord`	`null`	Promise reject
`create`	`StudioScriptFormRecord` 或 `StudioScriptFormCreateResult`	不适用	Promise reject
`createWithChildTables`	`StudioScriptFormCreateWithChildTablesResult`	不适用	Promise reject
`batchCreate`	`StudioScriptFormBatchCreateResult`	不适用	Promise reject
`batchCreateWithChildTables`	`StudioScriptFormBatchCreateWithChildTablesResult`	不适用	Promise reject
`batchUpdate`	`StudioScriptFormBatchUpdateResult`	不适用	Promise reject
`updateWithChildTables`	`StudioScriptFormUpdateWithChildTablesResult`	目标主记录不存在时返回 `null`	Promise reject
`batchUpdateWithChildTables`	`StudioScriptFormBatchUpdateWithChildTablesResult`	不适用	Promise reject
`update`	`StudioScriptFormRecord`	目标记录不存在时返回 `null`	Promise reject
`trash`	`{ trashed: boolean }`	目标记录不存在时返回 `{ trashed: false }`	Promise reject
`batchTrash`	`StudioScriptFormBatchTrashResult`	不存在的目标记录会返回到 `failed`	仅在入参非法或运行时级故障时 Promise reject
`batchDelete`	`StudioScriptFormBatchDeleteResult`	不存在的目标记录会返回到 `failed`	仅在入参非法或运行时级故障时 Promise reject
`delete`	`{ deleted: boolean }`	目标记录不存在时返回 `{ deleted: false }`	Promise reject

表单 SDK 调用失败时，会在脚本 worker 内抛出 Error。如果脚本没有捕获这个错误，整次脚本执行会失败，执行结果的 errorCode 为 STUDIO_ASSET_EXECUTION_FAILED，errorMessage 是底层错误信息，例如 IAM_PERMISSION_DENIED 或 FORMS_SCHEMA_NOT_FOUND。

如果脚本希望返回可控结构，需要自行 try/catch：

export default async function main(payload: StudioScriptRuntimeContextPayload, context: StudioScriptContext) {
  try {
    const record = await context.form.create({
      formApiName: 'orders',
      title: 'SO-1002',
      data: {
        orderNo: 'SO-1002',
      },
    });

    return {
      ok: true,
      record,
    };
  } catch (error) {
    return {
      ok: false,
      error: error instanceof Error ? error.message : String(error),
    };
  }
}

记录查询

查询第一条匹配记录

const record = await context.form.find({
  formApiName: 'orders',
  sortFieldApiName: 'order_amount',
  sortDirection: 'DESC',
  condition: {
    logic: 'and',
    children: [
      {
        field: 'so_order_no',
        operator: 'eq',
        value: 'SO-1001',
      },
    ],
  },
});

需要按条件获取第一条匹配记录时，使用带条件入参的 find。它使用和 list 相同的过滤条件，并始终包含记录详细数据。

已经有记录 ID 时，使用 recordId 条件过滤：

const record = await context.form.find({
  formApiName: 'orders',
  condition: {
    logic: 'and',
    children: [
      {
        field: 'recordId',
        operator: 'eq',
        value: 'record-id',
      },
    ],
  },
});

条件查询入参：

type StudioScriptFormFindInput = Omit<
  StudioScriptFormListInput,
  'cursor' | 'limit' | 'includeDetail'
>;

const record = await context.form.find({
  formApiName: 'orders',
  condition: {
    logic: 'and',
    children: [
      {
        field: 'recordId',
        operator: 'eq',
        value: payload.record?.id,
      },
    ],
  },
});

已经有目标记录 ID 时，在 condition 中使用 field: 'recordId'。recordId 匹配记录主键 ID。

如果条件可能匹配多条记录，可以传入 sortFieldApiName 和 sortDirection 控制返回的第一条记录。排序支持 number、time、date、datetime、week、month、quarter、year 和 serial_number 字段。

参数：

参数	类型	必填	说明
`condition.children[].field`	`string`	是	使用 `recordId` 按目标表单记录 ID 过滤
`condition.children[].operator`	`'eq' \| 'in'`	是	查询单条记录 ID 用 `eq`，多个记录 ID 可用 `in`
`condition.children[].value`	`string \| string[]`	是	目标表单记录 ID
`sortFieldApiName`	`string \| null`	否	返回第一条匹配记录前使用的排序字段 API 名
`sortDirection`	`'ASC' \| 'DESC'`	否	排序方向；默认 `DESC`

按条件批量获取记录

const records = await context.form.list({
  formApiName: 'orders',
  limit: 20,
  keyword: 'SO-1001',
  includeDetail: true,
});

入参：

type StudioScriptFormListInput = {
  formApiName: string;
  cursor?: string | null;
  limit?: number;
  keyword?: string | null;
  keywords?: string[] | null;
  includeDetail?: boolean;
  sortFieldApiName?: string | null;
  sortDirection?: 'ASC' | 'DESC' | 'asc' | 'desc' | null;
  searchFieldApiName?: string | null;
  dataStatuses?: Array<'draft' | 'active' | 'archived' | 'trashed'>;
  approvalStatuses?: Array<'none' | 'pending' | 'approved' | 'rejected' | 'returned' | 'canceled'>;
  visibilityStates?: Array<{
    dataStatus: 'draft' | 'active' | 'archived' | 'trashed';
    approvalStatus: 'none' | 'pending' | 'approved' | 'rejected' | 'returned' | 'canceled';
  }>;
  condition?: StudioScriptFormConditionGroup | null;
};

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名；运行时会解析为租户侧表单 ID
`cursor`	`string \| null`	否	上一次调用返回的不透明游标 `nextCursor`；继续查询时其他条件必须保持不变
`limit`	`number`	否	单次最多返回的记录数；默认 `20`，最大 `200`
`keyword`	`string \| null`	否	单个搜索关键词
`keywords`	`string[] \| null`	否	多个搜索关键词
`includeDetail`	`boolean`	否	列表记录是否包含详细数据；默认 `false`
`sortFieldApiName`	`string \| null`	否	排序字段 API 名；支持 `number`、`time`、`date`、`datetime`、`week`、`month`、`quarter`、`year` 和 `serial_number` 字段
`sortDirection`	`'ASC' \| 'DESC'`	否	排序方向；默认 `DESC`
`searchFieldApiName`	`string \| null`	否	作为关键词搜索目标的字段 API 名
`dataStatuses`	`Array<'draft' \| 'active' \| 'archived' \| 'trashed'>`	否	按记录数据状态过滤
`approvalStatuses`	`Array<'none' \| 'pending' \| 'approved' \| 'rejected' \| 'returned' \| 'canceled'>`	否	按审批状态过滤
`visibilityStates`	`Array<object>`	否	按数据状态和审批状态组合过滤
`condition`	`StudioScriptFormConditionGroup \| null`	否	结构化字段条件

支持的操作符：

操作符	含义
`eq`	等于
`neq`	不等于
`contains`	包含
`not_contains`	不包含
`gt`	大于
`gte`	大于等于
`lt`	小于
`lte`	小于等于
`in`	在列表中
`empty`	为空
`not_empty`	不为空

type StudioScriptFormRecordList = {
  items: StudioScriptFormRecord[];
  limit: number;
  projectionAsOf: string | null;
  hasMore: boolean;
  nextCursor: string | null;
};

type StudioScriptFormBatchGetResult = {
  items: StudioScriptFormRecord[];
  total: number;
};

按记录 ID 查询

已经有记录 ID 时，直接使用 get，不要再通过 find 构造 recordId 条件：

const record = await context.form.get({
  recordId: payload.record?.id || '',
});

if (!record) {
  return { ok: false, message: 'Record not found.' };
}

get 返回完整记录或 null，并继续应用当前运行主体的表单、行和字段权限。

多个记录 ID 已知时使用 batchGet，单次最多 100 个 ID：

const result = await context.form.batchGet({
  recordIds: selectedRecordIds,
});

return {
  ok: true,
  records: result.items,
  total: result.total,
};

batchGet 只返回当前运行主体可读取的记录。不要假设返回数组与输入 ID 数组等长；需要建立对应关系时，应按返回记录的 id 建立 Map。

遍历全部游标分页

需要读取全部匹配记录时，应逐页使用 nextCursor。每次请求必须保持 formApiName、筛选条件、排序和 limit 不变：

const items: StudioScriptFormRecord[] = [];
let cursor: string | null = null;

do {
  const page = await context.form.list({
    formApiName: 'orders',
    cursor,
    limit: 200,
    includeDetail: true,
    dataStatuses: ['active'],
    sortFieldApiName: 'orderDate',
    sortDirection: 'ASC',
  });

  items.push(...page.items);
  cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);

只在确实需要全部数据且数据量有明确上限时遍历所有页面。大批量同步应使用 OpenLink 分页流程或数据处理任务，避免让一个 Studio 脚本承担无界读取。

记录创建

创建单条记录

const record = await context.form.create({
  formApiName: 'orders',
  title: 'SO-1002',
  data: {
    orderNo: 'SO-1002',
    status: 'draft',
  },
  submitApproval: true,
});

入参：

type StudioScriptFormCreateInput = {
  formApiName: string;
  title: string;
  data: Record<string, unknown>;
  buttonKey?: string | null;
  submitApproval?: boolean;
};

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名；运行时会解析为租户侧表单 ID
`title`	`string`	是	记录标题，用于运行时列表和展示
`data`	`Record<string, unknown>`	是	字段值，key 为字段 API 名；必须是对象
`buttonKey`	`string \| null`	否	可选按钮 key，会传入运行时写入链路
`submitApproval`	`boolean`	否	为 `true` 时，在同一个事务中创建记录并写入审批提交任务

submitApproval 为 true 时，返回的记录会包含 approval 字段，其中有排队中的审批提交 jobId。后台审批提交任务使用 create 动作，审批运行时只会使用已发布且开启新建触发的审批定义。如果写入任务失败，SDK 调用会 reject，并回滚本次记录新建。

批量创建记录

const result = await context.form.batchCreate({
  formApiName: 'orders',
  records: [
    {
      title: 'SO-1003',
      data: {
        orderNo: 'SO-1003',
        status: 'draft',
      },
    },
    {
      title: 'SO-1004',
      data: {
        orderNo: 'SO-1004',
        status: 'draft',
      },
      submitApproval: true,
    },
  ],
});

入参：

type StudioScriptFormBatchCreateInput = {
  formApiName: string;
  records: Array<{
    title: string;
    data: Record<string, unknown>;
    buttonKey?: string | null;
    submitApproval?: boolean;
  }>;
};

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名；运行时会解析为租户侧表单 ID
`records`	`Array<object>`	是	要创建的批次数据；每批次数据最少 1 条，最多 100 条
`records[].title`	`string`	是	记录标题，用于运行时列表和展示
`records[].data`	`Record<string, unknown>`	是	字段值，key 为字段 API 名；必须是对象
`records[].buttonKey`	`string \| null`	否	可选按钮 key，会传入运行时写入链路
`records[].submitApproval`	`boolean`	否	为 `true` 时，会在同一个事务中为该记录写入审批提交任务

type StudioScriptFormBatchCreateResult = {
  items: Array<StudioScriptFormRecord | StudioScriptFormCreateResult>;
  total: number;
};

batchCreate 会在一个事务中创建全部记录。任意一条记录在校验、权限检查、自动编号、文件引用处理、公式计算、创建后任务写入或审批任务写入过程中失败时，SDK 调用会 reject，并回滚本批次的全部记录。

创建主子表记录

const result = await context.form.createWithChildTables({
  formApiName: 'orders',
  title: 'SO-1005',
  data: {
    orderNo: 'SO-1005',
    status: 'draft',
  },
  childTables: [
    {
      childFormApiName: 'order_items',
      records: [
        {
          title: 'SO-1005-1',
          data: {
            productName: 'Keyboard',
            quantity: 2,
          },
        },
        {
          title: 'SO-1005-2',
          data: {
            productName: 'Mouse',
            quantity: 1,
          },
        },
      ],
    },
  ],
});

入参：

type StudioScriptFormCreateWithChildTablesInput = {
  formApiName: string;
  title: string;
  data: Record<string, unknown>;
  buttonKey?: string | null;
  submitApproval?: boolean;
  childTables: Array<{
    childFormApiName: string;
    records: Array<{
      title: string;
      data: Record<string, unknown>;
      buttonKey?: string | null;
      submitApproval?: boolean;
    }>;
  }>;
};

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	主表 API 名；运行时会解析为租户侧主表 ID
`title`	`string`	是	主表记录标题，用于运行时列表和展示
`data`	`Record<string, unknown>`	是	主表字段值，key 为字段 API 名；必须是对象
`childTables`	`Array<object>`	是	要创建的明细表批次数据；至少包含一个明细表
`childTables[].childFormApiName`	`string`	是	明细表 API 名；必须是当前主表的明细表
`childTables[].records`	`Array<object>`	是	明细表批次数据；每个明细表批次最少 1 条，最多 100 条
`childTables[].records[].title`	`string`	是	明细表记录标题，用于运行时列表和展示
`childTables[].records[].data`	`Record<string, unknown>`	是	明细表字段值，key 为字段 API 名；不要传主表关联字段；SDK 会自动填入创建后的主表记录 ID
`childTables[].records[].buttonKey`	`string \| null`	否	可选按钮 key，会传入运行时写入链路
`childTables[].records[].submitApproval`	`boolean`	否	为 `true` 时，会在同一个事务中为该明细记录写入审批提交任务

type StudioScriptFormCreateWithChildTablesResult = {
  record: StudioScriptFormRecord | StudioScriptFormCreateResult;
  childTables: Array<{
    childFormApiName: string;
    items: Array<StudioScriptFormRecord | StudioScriptFormCreateResult>;
    total: number;
  }>;
};

createWithChildTables 会先创建主表记录，再把创建后的主表记录 ID 自动写入每条明细表记录的主表关联字段。整个操作在一个事务中执行。主表、明细表识别、任意明细记录、创建后任务写入或审批任务写入任一环节失败时，SDK 调用会 reject，并回滚整个操作。

批量创建主子表记录

const result = await context.form.batchCreateWithChildTables({
  formApiName: 'orders',
  records: [
    {
      title: 'SO-1006',
      data: {
        orderNo: 'SO-1006',
        status: 'draft',
      },
      childTables: [
        {
          childFormApiName: 'order_items',
          records: [
            {
              title: 'SO-1006-1',
              data: {
                productName: 'Keyboard',
                quantity: 2,
              },
            },
          ],
        },
      ],
    },
    {
      title: 'SO-1007',
      data: {
        orderNo: 'SO-1007',
        status: 'draft',
      },
      childTables: [
        {
          childFormApiName: 'order_items',
          records: [
            {
              title: 'SO-1007-1',
              data: {
                productName: 'Mouse',
                quantity: 1,
              },
            },
          ],
        },
      ],
    },
  ],
});

入参：

type StudioScriptFormBatchCreateWithChildTablesInput = {
  formApiName: string;
  records: Array<{
    title: string;
    data: Record<string, unknown>;
    buttonKey?: string | null;
    submitApproval?: boolean;
    childTables: Array<{
      childFormApiName: string;
      records: Array<{
        title: string;
        data: Record<string, unknown>;
        buttonKey?: string | null;
        submitApproval?: boolean;
      }>;
    }>;
  }>;
};

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	主表 API 名；运行时会解析为租户侧主表 ID
`records`	`Array<object>`	是	要创建的主表批次数据；每批次最少 1 条主表记录，最多 100 条主表记录
`records[].title`	`string`	是	主表记录标题，用于运行时列表和展示
`records[].data`	`Record<string, unknown>`	是	主表字段值，key 为字段 API 名；必须是对象
`records[].childTables`	`Array<object>`	是	当前主表记录下要创建的明细表批次数据；至少包含一个明细表
`records[].childTables[].childFormApiName`	`string`	是	明细表 API 名；必须是当前主表的明细表
`records[].childTables[].records`	`Array<object>`	是	明细表批次数据；每个明细表批次最少 1 条，最多 100 条

type StudioScriptFormBatchCreateWithChildTablesResult = {
  items: StudioScriptFormCreateWithChildTablesResult[];
  total: number;
};

batchCreateWithChildTables 适合导入场景：每条主表数据都带自己的明细表数据。整个批次在一个事务中执行。任意主表记录、明细表识别、明细记录、创建后任务写入或审批任务写入失败时，SDK 调用会 reject，并回滚整个批次。

记录更新

更新单条记录

const updated = await context.form.update({
  recordId: record.id,
  data: {
    status: 'confirmed',
  },
});

入参：

type StudioScriptFormUpdateInput = {
  recordId: string;
  title?: string;
  data?: Record<string, unknown>;
  buttonKey?: string | null;
  submitApproval?: boolean;
};

参数：

参数	类型	必填	说明
`recordId`	`string`	是	目标表单记录 ID
`title`	`string`	否	新记录标题；不传则保持当前标题
`data`	`Record<string, unknown>`	否	要合并进现有记录数据的字段值
`buttonKey`	`string \| null`	否	可选按钮权限 key；传入时会校验按钮执行权限
`submitApproval`	`boolean`	否	为 `true` 时，会在同一个事务中为这条更新后的记录写入审批提交任务

data 会合并到现有记录数据中。汇总字段、动态公式字段等只读计算字段会由现有表单数据写入链路忽略。

批量更新记录

const result = await context.form.batchUpdate({
  records: [
    {
      recordId: 'record-id-1',
      data: {
        status: 'confirmed',
      },
    },
    {
      recordId: 'record-id-2',
      title: 'Updated Title',
      data: {
        status: 'approved',
      },
      submitApproval: true,
    },
  ],
});

入参：

type StudioScriptFormBatchUpdateInput = {
  records: StudioScriptFormUpdateInput[];
};

type StudioScriptFormBatchUpdateResult = {
  items: StudioScriptFormRecord[];
  total: number;
};

参数：

参数	类型	必填	说明
`records`	`StudioScriptFormUpdateInput[]`	是	要更新的记录；最少 1 条，最多 100 条

batchUpdate 会在一个事务中更新全部记录。任意一条记录在校验、权限检查、自动字段重算、更新后任务写入或审批任务写入过程中失败时，SDK 调用会 reject，并回滚本批次的全部更新。

更新主子表记录

const result = await context.form.updateWithChildTables({
  recordId: 'parent-record-id',
  title: 'SO-1005',
  data: {
    status: 'confirmed',
  },
  submitApproval: true,
  childTables: [
    {
      childFormApiName: 'order_items',
      records: [
        {
          recordId: 'child-record-id-1',
          data: {
            quantity: 2,
          },
        },
        {
          recordId: 'child-record-id-2',
          data: {
            quantity: 1,
          },
          submitApproval: true,
        },
      ],
    },
  ],
});

入参：

type StudioScriptFormChildTableUpdateInput = {
  childFormApiName: string;
  records: StudioScriptFormUpdateInput[];
};

type StudioScriptFormUpdateWithChildTablesInput = StudioScriptFormUpdateInput & {
  childTables: StudioScriptFormChildTableUpdateInput[];
};

type StudioScriptFormUpdateWithChildTablesResult = {
  record: StudioScriptFormRecord;
  childTables: Array<{
    childFormApiName: string;
    items: StudioScriptFormRecord[];
    total: number;
  }>;
};

updateWithChildTables 会在一个事务中更新一条主表记录和指定的明细表记录。明细记录通过 recordId 更新，这个接口不会为缺失的明细记录自动新建。主记录不存在时返回 null。任意主表更新、明细表识别、明细更新、更新后任务写入或审批任务写入失败时，SDK 调用会 reject，并回滚整个事务。

批量更新主子表记录

const result = await context.form.batchUpdateWithChildTables({
  records: [
    {
      recordId: 'parent-record-id-1',
      data: {
        status: 'confirmed',
      },
      childTables: [
        {
          childFormApiName: 'order_items',
          records: [
            {
              recordId: 'child-record-id-1',
              data: {
                quantity: 3,
              },
            },
          ],
        },
      ],
    },
    {
      recordId: 'parent-record-id-2',
      data: {
        status: 'approved',
      },
      submitApproval: true,
      childTables: [
        {
          childFormApiName: 'order_items',
          records: [
            {
              recordId: 'child-record-id-2',
              data: {
                quantity: 5,
              },
              submitApproval: true,
            },
          ],
        },
      ],
    },
  ],
});

入参：

type StudioScriptFormBatchUpdateWithChildTablesInput = {
  records: Array<StudioScriptFormUpdateInput & {
    childTables: StudioScriptFormChildTableUpdateInput[];
  }>;
};

type StudioScriptFormBatchUpdateWithChildTablesResult = {
  items: StudioScriptFormUpdateWithChildTablesResult[];
  total: number;
};

batchUpdateWithChildTables 会在一个事务中批量更新多条主表记录及各自的明细表记录。每条主记录和明细记录仍然遵循和单条更新相同的权限校验、自动字段重算、更新后任务写入与可选审批任务写入。任意主记录不存在或任意更新步骤失败时，SDK 调用会 reject，并回滚整个批次。

记录删除

删除相关 API 分为软删除和硬删除两类：

trash / batchTrash：软删除，将记录移入回收站
delete / batchDelete：硬删除

删除审批说明：

trash / batchTrash 支持显式传入 submitApproval
submitApproval 为 true 时，会按删除动作发起删除审批；如果当前表单没有命中删除审批配置，则回退为直接软删除
delete / batchDelete 也暴露了 submitApproval 入参，但当前硬删除链路不支持触发删除审批；传入 true 会报 FORM_DATA_DELETE_APPROVAL_NOT_SUPPORTED

入参：

type StudioScriptFormDeleteInput = {
  recordId: string;
  buttonKey?: string | null;
  submitApproval?: boolean;
};

type StudioScriptFormRestoreInput = {
  recordId: string;
  buttonKey?: string | null;
  title?: string;
  data?: Record<string, unknown>;
  dataStatus?: 'draft' | 'active' | 'archived';
};

type StudioScriptFormBatchDeleteInput = {
  recordIds: string[];
  buttonKey?: string | null;
  submitApproval?: boolean;
};

type StudioScriptFormBatchTrashResult = {
  requestedCount: number;
  trashedCount: number;
  trashedRecordIds: string[];
  failed: Array<{
    recordId: string;
    code: string;
  }>;
};

type StudioScriptFormBatchDeleteResult = {
  requestedCount: number;
  deletedCount: number;
  deletedRecordIds: string[];
  failed: Array<{
    recordId: string;
    code: string;
  }>;
};

软删除单条记录

const result = await context.form.trash({
  recordId: record.id,
  submitApproval: true,
});

type StudioScriptFormTrashResult = {
  trashed: boolean;
};

参数：

参数	类型	必填	说明
`recordId`	`string`	是	目标表单记录 ID
`buttonKey`	`string \| null`	否	可选按钮权限 key；传入时会校验按钮执行权限
`submitApproval`	`boolean`	否	为 `true` 时，优先按删除动作发起删除审批；如果没有命中删除审批配置，则回退为直接软删除

submitApproval 为 true 时，SDK 会优先尝试发起删除审批。审批提交成功时，返回值中的 trashed 也会是 true；未命中删除审批配置时，记录会直接移入回收站。

硬删除单条记录

const result = await context.form.delete({
  recordId: record.id,
  submitApproval: false,
});

type StudioScriptFormDeleteResult = {
  deleted: boolean;
};

参数：

参数	类型	必填	说明
`recordId`	`string`	是	目标表单记录 ID
`buttonKey`	`string \| null`	否	可选按钮权限 key；传入时会校验按钮执行权限
`submitApproval`	`boolean`	否	当前硬删除链路暂不支持触发删除审批；传入 `true` 会报 `FORM_DATA_DELETE_APPROVAL_NOT_SUPPORTED`

当前 Studio Script SDK 的 delete 链路用于硬删除，不支持通过审批驱动执行。需要删除审批时，请改用 trash / batchTrash 并传入 submitApproval: true。

批量软删除记录

const result = await context.form.batchTrash({
  recordIds: selectedRecordIds,
  submitApproval: true,
});

type StudioScriptFormBatchTrashResult = {
  requestedCount: number;
  trashedCount: number;
  trashedRecordIds: string[];
  failed: Array<{
    recordId: string;
    code: string;
  }>;
};

参数：

参数	类型	必填	说明
`recordIds`	`string[]`	是	要软删除的目标表单记录 ID；最少 1 条，最多 100 条
`buttonKey`	`string \| null`	否	可选按钮权限 key；传入时会校验按钮执行权限
`submitApproval`	`boolean`	否	为 `true` 时，逐条按删除动作尝试发起删除审批；未命中删除审批配置时，回退为直接软删除

batchTrash 返回部分成功结果。无法移入回收站的记录会带运行时错误码返回到 failed，成功记录会返回到 trashedRecordIds。传入 submitApproval: true 时，每条记录都会独立判断是否命中删除审批配置。

批量硬删除记录

const result = await context.form.batchDelete({
  recordIds: staleRecordIds,
  submitApproval: false,
});

type StudioScriptFormBatchDeleteResult = {
  requestedCount: number;
  deletedCount: number;
  deletedRecordIds: string[];
  failed: Array<{
    recordId: string;
    code: string;
  }>;
};

参数：

参数	类型	必填	说明
`recordIds`	`string[]`	是	要硬删除的目标表单记录 ID；最少 1 条，最多 100 条
`buttonKey`	`string \| null`	否	可选按钮权限 key；传入时会校验按钮执行权限
`submitApproval`	`boolean`	否	当前硬删除链路暂不支持触发删除审批；传入 `true` 会报 `FORM_DATA_DELETE_APPROVAL_NOT_SUPPORTED`

batchDelete 同样返回部分成功结果，失败记录会带错误码返回到 failed。当前硬删除不支持审批驱动执行；需要删除审批时，请改用 batchTrash 并传入 submitApproval: true。

恢复回收站记录

restore 用于恢复一条已经软删除的记录，并可同时更新标题、字段数据和恢复后的数据状态：

const restored = await context.form.restore({
  recordId: trashedRecordId,
  dataStatus: 'active',
  data: {
    restoreReason: 'Confirmed by operations',
  },
});

if (!restored) {
  return { ok: false, message: 'Record could not be restored.' };
}

参数	类型	必填	说明
`recordId`	`string`	是	回收站中的目标记录 ID
`buttonKey`	`string \| null`	否	需要复用产品按钮权限时传入按钮 key
`title`	`string`	否	恢复时更新记录标题
`data`	`Record<string, unknown>`	否	恢复时合并到记录的字段值
`dataStatus`	`'draft' \| 'active' \| 'archived'`	否	恢复后的数据状态

restore 只用于软删除记录。已经硬删除的记录不能恢复。

保存筛选器 Client

context.formSavedFilter 管理当前运行主体在指定表单下的个人保存筛选器。它不会创建全租户共享筛选器，也不会替其他成员修改筛选器。

新建或更新保存筛选器

const saved = await context.formSavedFilter.save({
  formApiName: 'orders',
  name: '待处理的大额订单',
  condition: {
    logic: 'and',
    children: [
      { field: 'status', operator: 'eq', value: 'pending' },
      { field: 'amount', operator: 'gte', value: 10000 },
    ],
  },
});

condition 必须是根条件组，字段使用目标表单的字段 API 名。创建时省略 id；更新时必须传回现有筛选器的真实 id：

const filters = await context.formSavedFilter.list({
  formApiName: 'orders',
});

const current = filters.items.find((item) => item.name === '待处理的大额订单');
if (current) {
  await context.formSavedFilter.save({
    formApiName: 'orders',
    id: current.id,
    name: current.name,
    condition: {
      logic: 'and',
      children: [{ field: 'status', operator: 'eq', value: 'pending' }],
    },
  });
}

删除时使用 filterId，返回值是 { id }，不是 { deleted }：

const deleted = await context.formSavedFilter.delete({
  filterId: saved.id,
});

表格视图 Client

context.formTableView 管理当前运行主体的个人表格视图。视图保存布局、分组和显示偏好；它不修改表单字段、布局设计或其他成员的视图。

新建或更新表格视图

const view = await context.formTableView.save({
  formApiName: 'orders',
  name: '按客户分组',
  layoutIds: [listLayoutId],
  groupFieldIds: [customerFieldId],
  scopes: ['list'],
  bordered: true,
  showRowNumber: true,
  groups: [
    {
      id: 'customer-group',
      name: '客户',
      fieldIds: [customerFieldId],
      level: 1,
      parentId: null,
    },
  ],
});

参数	说明
`formApiName`	目标表单 API 名，不传内部表单 ID
`id`	更新现有视图时传入真实视图 ID；创建时省略
`layoutIds`	视图使用的布局 ID
`groupFieldIds`	用于分组的字段 ID，不是字段 API 名
`scopes`	支持 `list`、`detail`、`new`、`edit`、`relation`；未提供有效值时使用 `list`
`bordered`	是否显示表格边框
`showRowNumber`	是否显示行号
`groups`	最多三级的分组配置，每组通过 `fieldIds` 引用字段 ID

该 API 没有 columns 入参。调用前如果不知道布局 ID 或字段 ID，应先从实际表单配置中取得，不能把 API 名当成 ID。

查询与删除：

const views = await context.formTableView.list({
  formApiName: 'orders',
});

const deleted = await context.formTableView.delete({
  viewId: view.id,
});

删除返回 { id }。list、save 和 delete 都只作用于当前运行主体拥有的视图。

表单结构 Client

当脚本在读写记录之前需要表单或字段元数据时，可以使用 studioScriptContext.formSchema。

interface StudioScriptFormSchemaClient {
  get(input: StudioScriptFormSchemaGetInput): Promise<StudioScriptFormSchema>;
  fields(input: StudioScriptFormSchemaFieldsInput): Promise<StudioScriptFormFieldList>;
  field(input: StudioScriptFormSchemaFieldInput): Promise<StudioScriptFormField | null>;
}

Client 方法：

方法	入参	返回值	说明
`get`	`StudioScriptFormSchemaGetInput`	`StudioScriptFormSchema`	通过表单 API 名查询表单元数据
`fields`	`StudioScriptFormSchemaFieldsInput`	`StudioScriptFormFieldList`	查询指定表单的字段列表，可按关键词过滤
`field`	`StudioScriptFormSchemaFieldInput`	`StudioScriptFormField \| null`	通过表单 API 名和字段 API 名查询单个字段

获取表单元数据

const form = await context.formSchema.get({
  formApiName: 'orders',
});

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名；运行时会解析并返回当前访问主体可访问的表单元数据

表单结构

type StudioScriptFormSchema = {
  id: string;
  name: string;
  apiName: string;
  type: string;
  description: string | null;
  icon: string | null;
  isDefault: boolean;
  enabled: boolean;
};

查询字段列表

const fields = await context.formSchema.fields({
  formApiName: 'orders',
  keyword: 'amount',
});

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名
`keyword`	`string \| null`	否	可选关键词，用于按字段名称或字段 API 名过滤

获取单个字段

const amountField = await context.formSchema.field({
  formApiName: 'orders',
  fieldApiName: 'amount',
});

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名
`fieldApiName`	`string`	是	要在目标表单中解析的字段 API 名

字段结构

type StudioScriptFormField = {
  id: string;
  formId: string;
  groupId: string | null;
  name: string;
  apiName: string;
  type: string;
  dataType: string;
  sortOrder: number;
  required: boolean;
  readonly: boolean;
  disabled: boolean;
  hidden: boolean;
  isDefault: boolean;
  isIdentifier: boolean;
  defaultValue: unknown;
  options: unknown;
  validation: unknown;
  display: unknown;
  specialConfig: unknown;
  config: unknown;
};

字段元数据会按当前访问主体的表单和字段元数据权限过滤。

内置表单、字段和选项标签在 Studio SDK 中会返回兜底英文展示文本。产品页面仍然使用数据库中的 i18n: key 按当前页面语言翻译。

文件 Client

当脚本需要解析表单文件字段中的文件资产，或创建新的文件资产时，可以使用 studioScriptContext.file。

interface StudioScriptFileClient {
  get(input: StudioScriptFileGetInput): Promise<StudioScriptFileAsset | null>;
  resolve(input: StudioScriptFileResolveInput): Promise<StudioScriptFileAsset[]>;
  create(input: StudioScriptFileCreateInput): Promise<StudioScriptFileAsset>;
}

Client 方法：

方法	入参	返回值	说明
`get`	`StudioScriptFileGetInput`	`StudioScriptFileAsset \| null`	通过文件 ID 查询单个文件资产
`resolve`	`StudioScriptFileResolveInput`	`StudioScriptFileAsset[]`	通过文件 ID 批量解析文件资产
`create`	`StudioScriptFileCreateInput`	`StudioScriptFileAsset`	通过 base64 文件内容创建文件资产

脚本需要文件展示地址时，可以使用 file.previewUrl || file.url。previewUrl 只会在当前预览器支持的文件类型上返回，例如常见图片、PDF、文本/代码文件、常见音视频文件。合法上传和下载的文件仍然可能返回 previewUrl: null。

获取单个文件

const file = await context.file.get({
  fileId: '6d4b0e70-8a36-4c11-a6f2-6ad1a7f6aa01',
});

参数：

参数	类型	必填	说明
`fileId`	`string`	是	文件资产 ID

批量解析文件

const files = await context.file.resolve({
  fileIds: ['file-id-1', 'file-id-2'],
});

参数：

参数	类型	必填	说明
`fileIds`	`string[]`	是	要解析的文件资产 ID

创建文件

const csv = 'orderNo,amount\\nSO-1001,1200\\n';
const file = await context.file.create({
  name: 'orders.csv',
  mimeType: 'text/csv',
  size: csv.length,
  contentBase64: btoa(csv),
});

参数：

参数	类型	必填	说明
`name`	`string`	是	文件展示名称
`originalName`	`string`	否	原始文件名；默认使用 `name`
`mimeType`	`string`	是	MIME 类型，例如 `text/csv` 或 `application/pdf`
`size`	`number`	是	预期文件大小，单位字节
`contentBase64`	`string`	是	base64 编码后的文件内容
`storagePolicyKey`	`string \| null`	否	可选存储策略 key；不传则使用默认策略

文件 API 限定在当前租户范围内。Studio 脚本不暴露硬删除文件接口。

审批 Client

当脚本需要提交记录审批、查询审批实例，或处理当前 actor 的审批任务时，可以使用 studioScriptContext.approval。

type StudioScriptApprovalRecordListInput = {
  cursor?: string | null;
  limit?: number;
  status?: StudioScriptApprovalStatus | null;
  definitionId?: string | null;
  initiatorMemberId?: string | null;
  currentApproverMemberId?: string | null;
  startedAtFrom?: string | null;
  startedAtTo?: string | null;
  keyword?: string | null;
};

type StudioScriptApprovalRecordListItem = {
  id: string;
  definitionId: string;
  definitionName: string;
  recordId: string;
  recordTitle: string;
  formApiName: string;
  formName: string;
  initiatorType: string;
  initiatorId: string;
  initiatorName: string;
  initiatorDisplayName: string | null;
  currentApproverPrincipals: Array<{ principalType: string; principalId: string; displayName: string | null }>;
  taskIds: string[];
  currentNodeName: string;
  currentApproverName: string;
  taskStatus: string;
  instanceStatus: string;
  instanceResult: string | null;
  startedAt: string;
  completedAt: string | null;
};

type StudioScriptApprovalRecordListResult = {
  items: StudioScriptApprovalRecordListItem[];
  hasMore: boolean;
  nextCursor: string | null;
  limit: number;
};

interface StudioScriptApprovalClient {
  getSubmissionConfig(input: { formApiName: string; action?: 'create' | 'update' | 'delete' }): Promise<{
    enabled: boolean;
    allowWithdraw: boolean;
    definitionId: string | null;
    definitionVersionId: string | null;
    definitionName: string | null;
  }>;
  submitRecord(input: { recordId: string; action?: 'create' | 'update' | 'delete'; beforeRecordData?: Record<string, unknown> | null }): Promise<StudioScriptApprovalSubmitRecordResult>;
  listRecords(input?: StudioScriptApprovalRecordListInput): Promise<StudioScriptApprovalRecordListResult>;
  listRecordInstances(input: { recordId: string }): Promise<StudioScriptApprovalRecordInstanceSummary[]>;
  getInstance(input: { instanceId: string }): Promise<StudioScriptApprovalInstance | null>;
  listTasks(input?: { cursor?: string | null; limit?: number; status?: string | null; memberId?: string | null; timeRange?: { from: string; to: string } | null }): Promise<{ items: StudioScriptApprovalTaskListItem[]; hasMore: boolean; nextCursor: string | null; limit: number; timeRange: { from: string; to: string } }>;
  getTask(input: { taskId: string }): Promise<StudioScriptApprovalTaskDetail | null>;
  decideTask(input: { taskId: string; decision: 'approved' | 'rejected' | 'returned'; comment?: string | null; returnTarget?: StudioScriptApprovalReturnTarget | null }): Promise<StudioScriptApprovalTaskDecisionResult>;
  withdraw(input: { instanceId: string; comment?: string | null }): Promise<{
    instance: StudioScriptApprovalInstance;
    record: {
      recordId: string;
      formId: string;
      dataStatus: string;
      approvalStatus: string;
      approvalFlowInstanceId: string | null;
    } | null;
  }>;
}

Client 方法：

方法	入参	返回值	说明
`getSubmissionConfig`	`{ formApiName: string; action?: 'create' \| 'update' \| 'delete' }`	`{ enabled; allowWithdraw; definitionId; definitionVersionId; definitionName }`	查询指定表单动作的审批提交配置
`submitRecord`	`{ recordId: string; action?: 'create' \| 'update' \| 'delete'; beforeRecordData?: Record<string, unknown> \| null }`	`StudioScriptApprovalSubmitRecordResult`	将记录提交审批，并返回精简提交摘要
`listRecords`	`StudioScriptApprovalRecordListInput`	`StudioScriptApprovalRecordListResult`	使用游标分页查询审批运行时可见的记录摘要
`listRecordInstances`	`{ recordId: string }`	`StudioScriptApprovalRecordInstanceSummary[]`	查询一条记录关联的审批实例摘要列表
`getInstance`	`{ instanceId: string }`	`StudioScriptApprovalInstance \| null`	通过实例 ID 查询单个审批实例
`listTasks`	`{ cursor?: string; limit?: number; status?: string; memberId?: string; timeRange?: { from: string; to: string } }`	`{ items: StudioScriptApprovalTaskListItem[]; hasMore: boolean; nextCursor: string \| null; limit: number; timeRange: { from: string; to: string } }`	使用游标分页查询当前 actor 或指定成员可见/可处理的审批任务摘要列表
`getTask`	`{ taskId: string }`	`StudioScriptApprovalTaskDetail \| null`	通过任务 ID 查询单个审批任务摘要
`decideTask`	`{ taskId: string; decision: 'approved' \| 'rejected' \| 'returned'; comment?: string \| null; returnTarget?: StudioScriptApprovalReturnTarget \| null }`	`StudioScriptApprovalTaskDecisionResult`	对审批任务执行通过、拒绝或退回
`withdraw`	`{ instanceId: string; comment?: string \| null }`	`{ instance: StudioScriptApprovalInstance; record: object \| null }`	当前 actor 有权限时，撤回待审批实例

获取提交配置

const config = await context.approval.getSubmissionConfig({
  formApiName: 'orders',
  action: 'update',
});

参数：

参数	类型	必填	说明
`formApiName`	`string`	是	表单 API 名；运行时内部解析 form ID
`action`	`'create' \| 'update' \| 'delete'`	否	触发动作；默认 `update`

提交记录审批

const result = await context.approval.submitRecord({
  recordId: 'record-id',
  action: 'update',
});

参数：

参数	类型	必填	说明
`recordId`	`string`	是	表单记录 ID
`action`	`'create' \| 'update' \| 'delete'`	否	触发动作；默认 `update`
`beforeRecordData`	`Record<string, unknown> \| null`	否	更新或删除审批场景下的变更前记录数据快照

返回结构：

type StudioScriptApprovalSubmitRecordResult = {
  submitted: boolean;
  config: {
    enabled: boolean;
    definitionName: string | null;
    allowWithdraw: boolean;
  };
  record: {
    recordId: string;
    dataStatus: string;
    approvalStatus: string;
    approvalFlowInstanceId: string | null;
  };
  instance: {
    instanceId: string;
    status: string;
    result: string | null;
    startedAt: string;
    completedAt: string | null;
  } | null;
  currentTask: {
    taskId: string;
    status: string;
    nodeKey: string;
    nodeName: string;
    assigneeType: string;
    assigneeId: string;
    assigneeDisplayName: string | null;
  } | null;
};

submitRecord 面向脚本返回精简摘要，不包含完整实例快照、审批主体记录、节点历史、子表数据或表单字段数据。脚本需要完整审批运行时详情时，再调用 listRecordInstances 或 getInstance。

查询审批记录列表

const records = await context.approval.listRecords({
  limit: 20,
  status: 'pending',
  currentApproverMemberId: 'member-id',
});

参数：

参数	类型	必填	说明
`cursor`	`string \| null`	否	上一次调用返回的不透明游标 `nextCursor`；继续查询时其他条件必须保持不变
`limit`	`number`	否	单次最多返回的记录数；默认 `20`，最大 `100`
`status`	`StudioScriptApprovalStatus \| null`	否	按任务状态过滤
`definitionId`	`string \| null`	否	按审批流程过滤
`initiatorMemberId`	`string \| null`	否	按发起成员过滤
`currentApproverMemberId`	`string \| null`	否	按当前审批成员过滤
`startedAtFrom` / `startedAtTo`	`string \| null`	否	按发起时间范围过滤
`keyword`	`string \| null`	否	关键词搜索

listRecords 复用审批记录页相同的审批运行时可见性和权限规则。

查询记录审批实例

const instances = await context.approval.listRecordInstances({
  recordId: 'record-id',
});

参数：

参数	类型	必填	说明
`recordId`	`string`	是	表单记录 ID

返回结构：

type StudioScriptApprovalRecordInstanceSummary = {
  instanceId: string;
  status: string;
  result: string | null;
  definitionName: string;
  allowWithdraw: boolean;
  subjectId: string;
  startedAt: string;
  completedAt: string | null;
  currentTasks: Array<{
    taskId: string;
    status: string;
    nodeKey: string;
    nodeName: string;
    assigneeType: string;
    assigneeId: string;
    assigneeDisplayName: string | null;
  }>;
};

listRecordInstances 面向脚本返回实例摘要和当前待审批任务，不包含完整实例快照、审批主体记录、节点历史、子表数据或表单字段数据。脚本需要完整审批运行时详情时，再调用 getInstance。

查询审批实例

const instance = await context.approval.getInstance({
  instanceId: 'approval-instance-id',
});

参数：

参数	类型	必填	说明
`instanceId`	`string`	是	审批实例 ID

getInstance 返回完整审批实例详情，包含实例快照、节点历史、任务列表和审批主体记录。脚本只需要摘要时，优先使用 listRecordInstances。

查询审批任务

const tasks = await context.approval.listTasks({
  status: 'pending',
});

参数：

参数	类型	必填	说明
`cursor`	`string \| null`	否	上一页返回的游标
`limit`	`number`	否	单次最多返回的任务数，默认 `20`，最大 `100`
`status`	`string \| null`	否	可选任务状态过滤
`memberId`	`string \| null`	否	指定成员 ID；不传时查询当前运行 actor
`timeRange`	`{ from: string; to: string } \| null`	否	可选的任务搜索时间范围；省略时由审批 Runtime 使用默认范围

返回结构：

type StudioScriptApprovalTaskListItem = {
  taskId: string;
  instanceId: string;
  status: string;
  nodeKey: string;
  nodeName: string;
  assigneeType: string;
  assigneeId: string;
  assigneeDisplayName: string | null;
  subjectId: string;
  instanceStatus: string;
  createdAt: string;
};

listTasks 面向脚本返回任务摘要，不包含 tenantId、审批策略字段、审批意见、完整 subjectSnapshot、子表数据或表单字段数据。脚本需要单个任务的处理结果时，再调用 getTask。

查询单个审批任务

const task = await context.approval.getTask({
  taskId: 'task-id',
});

返回结构：

type StudioScriptApprovalTaskDetail = StudioScriptApprovalTaskListItem & {
  decidedAt: string | null;
  decision: string | null;
  comment: string | null;
};

getTask 面向脚本返回任务摘要，不包含完整 subjectSnapshot、子表数据或表单字段数据。脚本需要完整业务记录数据时，请通过 subjectId 调用表单 SDK 查询对应记录。

审批任务决策

await context.approval.decideTask({
  taskId: 'task-id',
  decision: 'approved',
  comment: 'Looks good.',
});

参数：

参数	类型	必填	说明
`taskId`	`string`	是	审批任务 ID
`decision`	`'approved' \| 'rejected' \| 'returned'`	是	审批决策
`comment`	`string \| null`	否	审批意见；部分审批节点可能要求填写
`returnTarget`	`{ type: 'initiator' } \| { type: 'node'; nodeKey: string } \| null`	否	退回到发起人或指定节点时使用

返回结构：

type StudioScriptApprovalTaskDecisionResult = {
  task: {
    taskId: string;
    status: string;
    decision: string | null;
    comment: string | null;
    decidedAt: string | null;
  } | null;
  instance: {
    instanceId: string;
    status: string;
    result: string | null;
    completedAt: string | null;
    currentTasks: StudioScriptApprovalTaskSummary[];
  };
};

decideTask 复用产品 UI 相同的审批运行时权限和节点决策规则。节点可能拒绝不支持的决策、缺失的审批意见或缺失的退回目标。

撤回审批实例

const result = await context.approval.withdraw({
  instanceId: 'approval-instance-id',
  comment: 'Withdraw by script.',
});

参数：

参数	类型	必填	说明
`instanceId`	`string`	是	待撤回的审批实例 ID
`comment`	`string \| null`	否	撤回说明

只有当前 actor 有权撤回且实例仍在待审批中时，withdraw 才会成功。

组织记录 Client

当脚本需要只读访问组织表中的组织记录时，可以使用 studioScriptContext.organization。

interface StudioScriptOrganizationClient {
  get(input: StudioScriptOrganizationGetInput): Promise<StudioScriptOrganization | null>;
  list(input?: StudioScriptOrganizationListInput): Promise<StudioScriptOrganizationList>;
  tree(input?: Record<string, never>): Promise<StudioScriptOrganizationTree>;
}

Client 方法：

方法	入参	返回值	说明
`get`	`StudioScriptOrganizationGetInput`	`StudioScriptOrganization \| null`	通过组织 ID 查询单个组织
`list`	`StudioScriptOrganizationListInput`	`StudioScriptOrganizationList`	查询组织列表，可按关键词过滤
`tree`	`Record<string, never>`	`StudioScriptOrganizationTree`	查询组织树；不需要参数

查询组织列表

const organizations = await context.organization.list({
  keyword: 'Sales',
  condition: {
    logic: 'and',
    children: [{ field: 'so_status', operator: 'eq', value: 'active' }],
  },
});

参数：

参数	类型	必填	说明
`keyword`	`string \| null`	否	按组织名称或编码过滤
`condition`	`StudioScriptFormConditionGroup \| null`	否	按组织资料表单字段 API 名执行结构化条件查询；操作符与表单记录查询一致

获取组织树

const tree = await context.organization.tree();

tree 不需要参数。

获取单个组织

const organization = await context.organization.get({
  organizationId: 'organization-id',
});

参数：

参数	类型	必填	说明
`organizationId`	`string`	是	组织 ID

组织记录 Client 在 Studio 脚本中只读，不暴露组织的新建、更新、移动、停用或删除操作。

部门 Client

当脚本需要只读访问部门数据时，可以使用 studioScriptContext.department。

interface StudioScriptDepartmentClient {
  get(input: StudioScriptDepartmentGetInput): Promise<StudioScriptDepartment | null>;
  list(input?: StudioScriptDepartmentListInput): Promise<StudioScriptDepartmentList>;
  tree(input?: { organizationId?: string | null }): Promise<StudioScriptDepartmentTree>;
}

Client 方法：

方法	入参	返回值	说明
`get`	`StudioScriptDepartmentGetInput`	`StudioScriptDepartment \| null`	通过部门 ID 查询单个部门
`list`	`StudioScriptDepartmentListInput`	`StudioScriptDepartmentList`	查询部门列表，可按关键词和组织过滤
`tree`	`{ organizationId?: string \| null }`	`StudioScriptDepartmentTree`	查询部门树，可按组织 ID 过滤

查询部门列表

const departments = await context.department.list({
  keyword: 'Sales',
  condition: {
    logic: 'and',
    children: [{ field: 'so_status', operator: 'eq', value: 'active' }],
  },
});

参数：

参数	类型	必填	说明
`keyword`	`string \| null`	否	按部门名称或编码过滤
`organizationId`	`string \| null`	否	按组织 ID 过滤部门
`condition`	`StudioScriptFormConditionGroup \| null`	否	按部门资料表单字段 API 名执行结构化条件查询；操作符与表单记录查询一致

获取部门树

const tree = await context.department.tree();

参数：

参数	类型	必填	说明
`organizationId`	`string \| null`	否	按组织 ID 过滤部门树

获取单个部门

const department = await context.department.get({
  departmentId: 'department-id',
});

参数：

参数	类型	必填	说明
`departmentId`	`string`	是	部门 ID

部门 Client 在 Studio 脚本中只读，不暴露部门的新建、更新、移动、停用或删除操作。

成员 Client

当脚本需要只读访问成员数据时，可以使用 studioScriptContext.member。

interface StudioScriptMemberClient {
  current(input?: Record<string, never>): Promise<StudioScriptCurrentMember | null>;
  get(input: StudioScriptMemberGetInput): Promise<StudioScriptMemberProfileData | null>;
  list(input?: StudioScriptMemberListInput): Promise<StudioScriptMemberList>;
}

Client 方法：

方法	入参	返回值	说明
`current`	`Record<string, never>`	`StudioScriptCurrentMember \| null`	查询触发当前脚本的成员资料表单数据；不需要参数
`get`	`StudioScriptMemberGetInput`	`StudioScriptMemberProfileData \| null`	通过成员 ID 查询单个成员的资料表单数据
`list`	`StudioScriptMemberListInput`	`StudioScriptMemberList`	查询成员资料表单数据列表，可按关键词、组织、部门和分页条件过滤

获取当前成员

const member = await context.member.current();

current 不需要参数。当脚本不是由登录成员上下文触发时，返回 null。

返回结构：

type StudioScriptCurrentMember = {
  data: Record<string, unknown>;
};

data 是当前成员的资料表单数据。

查询成员列表

const members = await context.member.list({
  departmentId: 'department-id',
  includeDescendants: true,
  limit: 20,
  condition: {
    logic: 'and',
    children: [{ field: 'so_avatar', operator: 'not_empty' }],
  },
});

items 只包含成员资料表单数据：

type StudioScriptMemberList = {
  items: Array<{ data: Record<string, unknown> }>;
  hasMore: boolean;
  nextCursor: string | null;
  limit: number;
  summary: {
    active: number;
    inactive: number;
  };
};

参数：

参数	类型	必填	说明
`keyword`	`string \| null`	否	按成员姓名、邮箱、手机号或员工编号过滤
`organizationId`	`string \| null`	否	按组织 ID 过滤成员
`departmentId`	`string \| null`	否	按部门 ID 过滤成员
`includeDescendants`	`boolean`	否	传入 `departmentId` 时，是否包含子部门成员
`cursor`	`string \| null`	否	上一次调用返回的不透明游标 `nextCursor`；继续查询时其他条件必须保持不变
`limit`	`number`	否	单次最多返回的成员数；默认 `20`，最大 `100`
`condition`	`StudioScriptFormConditionGroup \| null`	否	按成员资料表单字段 API 名执行结构化条件查询；操作符与表单记录查询一致

获取单个成员

const member = await context.member.get({
  memberId: 'member-id',
});

get 返回和 current 一样的 { data } 结构。

参数：

参数	类型	必填	说明
`memberId`	`string`	是	成员 ID

成员 Client 在 Studio 脚本中只读，不暴露成员的新建、更新、停用或删除操作。

IAM Client

当脚本需要判断当前运行主体的有效角色时，可以使用 studioScriptContext.iam。这是只读运行时 SDK，不是角色管理 API。

interface StudioScriptIamClient {
  currentRoleSummary(input?: Record<string, never>): Promise<{
    roles: StudioScriptIamRole[];
    roleCodes: string[];
  }>;
  memberRoleSummary(input: { memberId: string }): Promise<{
    memberId: string;
    roles: StudioScriptIamRole[];
    roleCodes: string[];
  }>;
  memberRoleSummaries(input: { memberIds: string[] }): Promise<{
    items: Array<{
      memberId: string;
      roles: StudioScriptIamRole[];
      roleCodes: string[];
    }>;
  }>;
}

Client 方法：

方法	入参	返回值	说明
`currentRoleSummary`	`Record<string, never>`	`{ roles: StudioScriptIamRole[]; roleCodes: string[] }`	查询当前运行主体的角色摘要；不需要参数
`memberRoleSummary`	`{ memberId: string }`	`{ memberId: string; roles: StudioScriptIamRole[]; roleCodes: string[] }`	查询指定成员的角色摘要
`memberRoleSummaries`	`{ memberIds: string[] }`	`{ items: Array<MemberRoleSummary> }`	批量查询指定成员的角色摘要

查询当前角色摘要

const summary = await context.iam.currentRoleSummary();

currentRoleSummary 不需要参数。它会返回当前 actor 通过成员、部门、组织主体匹配到的有效角色，并同时返回去重后的 roleCodes，适合脚本里做简单分支判断。

查询指定成员角色摘要

const summary = await context.iam.memberRoleSummary({
  memberId: 'member-id',
});

参数：

参数	类型	必填	说明
`memberId`	`string`	是	当前租户中的成员 ID

memberRoleSummary 会返回目标成员通过成员、部门、组织主体匹配到的有效角色，并同时返回去重后的 roleCodes。

批量查询指定成员角色摘要

const summaries = await context.iam.memberRoleSummaries({
  memberIds: ['member-id-1', 'member-id-2'],
});

参数：

参数	类型	必填	说明
`memberIds`	`string[]`	是	当前租户中的成员 ID；单次最多 100 个

memberRoleSummaries 会按请求顺序返回每个成员的角色摘要。

角色结构

type StudioScriptIamRole = {
  id: string;
  code: string;
  name: string;
  description: string | null;
  builtIn: boolean;
  systemProtected: boolean;
  status: 'active';
  bindings: Array<{
    id: string;
    principalType: 'MEMBER' | 'DEPARTMENT' | 'ORGANIZATION';
    principalId: string;
    precedence: number;
    startAt: string | null;
    endAt: string | null;
  }>;
};

角色字段：

字段	类型	说明
`id`	`string`	角色 ID；需要和角色绑定或其他角色记录关联时使用
`code`	`string`	稳定的角色编码，适合脚本分支判断，例如 `space_admin` 或自定义角色编码
`name`	`string`	角色展示名称
`description`	`string \| null`	角色说明，可为空
`builtIn`	`boolean`	是否为系统内置角色
`systemProtected`	`boolean`	是否受系统保护，普通用户侧操作不能随意修改
`status`	`'active'`	角色状态；SDK 只返回启用角色
`bindings`	`StudioScriptIamRoleBinding[]`	匹配当前 actor 或指定成员的有效角色绑定列表

绑定字段：

字段	类型	说明
`id`	`string`	角色绑定 ID
`principalType`	`'MEMBER' \| 'DEPARTMENT' \| 'ORGANIZATION'`	授予该角色的主体类型
`principalId`	`string`	成员、部门或组织主体的 ID
`precedence`	`number`	匹配优先级；数字越小越具体：成员绑定为 `0`，部门绑定为 `1`，组织绑定为 `2`
`startAt`	`string \| null`	绑定开始时间；`null` 表示立即生效
`endAt`	`string \| null`	绑定结束时间；`null` 表示不自动过期

只返回启用且处于有效时间窗口内的绑定。禁用角色和无效绑定会被过滤。

安装

npm i @soln/custom-login-sdk

使用完整 demo

从 GitHub 或 GitCode 下载 demo。SDK 调用已完整接入，代码中的英文注释 SOLN INTEGRATION 1–9 标记了各接入位置。

修改 examples/config.js：

export const config = {
  issuer: 'https://console.example.com', // Your trusted Soln control-plane origin.
  workspaceLoginUrl: 'https://work.example.com/auth/start', // Your workspace login entry.
  brandName: 'Your brand',
  faviconUrl: './assets/favicon-192x192.png',
  locale: 'zh-CN',
};

将 issuer 替换为你的可信控制面地址，workspaceLoginUrl 替换为工作区的 /auth/start 地址。按需修改 examples/index.html 中的 Logo、examples/messages.js 中的文案和 examples/styles.css 中的样式。将 examples/ 和 dist/ 一起部署到 HTTPS 站点，保留相对目录关系。

在 系统管理 → 组织资料 → 编辑 中，将部署后的 /examples/ 地址填入 自定义登录页地址 并保存；留空恢复默认登录页。从工作区发起登录即可使用，配置 workspaceLoginUrl 后也可直接打开 demo，无需先登录。

接入自己的页面

页面打开时创建客户端，将对应方法绑定到自己的表单。issuer 填写可信控制面地址。

import {
  createSolnLoginClient,
  type LoginResult,
} from '@soln/custom-login-sdk';

const login = createSolnLoginClient({
  issuer: 'https://console.example.com',
  locale: 'zh-CN',
});

const context = await login.getContext();
// If context.passwordSetup is present, show the new-password form.

function finish(result: LoginResult) {
  if (result.nextStep === 'set_password') {
    // Show the new-password form for result.email.
    return;
  }
  login.complete(result);
}

// Bind to the password-login form.
async function submitPassword(email: string, password: string) {
  finish(await login.loginWithPassword({ email, password }));
}

// Bind to the send-code button.
async function sendCode(email: string) {
  await login.sendEmailCode({ email });
}

// Bind to the email-code form. The code has six digits.
async function submitCode(email: string, code: string) {
  finish(await login.verifyEmailCode({ email, code }));
}

// Bind to the new-password form. Use at least eight characters.
async function submitNewPassword(newPassword: string) {
  finish(await login.setupPassword({ newPassword }));
}

调用失败时用自己的消息组件显示错误，在 finally 中恢复按钮状态。人机验证由 SDK 按需自动打开，完整 demo 已包含这些处理。

返回 complete 时调用 complete() 完成登录并进入工作区。登录请求过期后，从工作区 /auth/start 重新发起即可。

权限与错误

Studio SDK 调用会以当前脚本运行主体执行，并复用租户侧产品运行时的权限检查。它不会绕过表单可见性、行权限、字段权限、按钮权限、审批任务权限或租户文件边界。

当 SDK 调用抛错且脚本没有捕获时，整次脚本执行会失败，执行结果的 errorCode 为 STUDIO_ASSET_EXECUTION_FAILED。执行结果的 errorMessage 会保留底层运行时错误码，例如 IAM_PERMISSION_DENIED、FORMS_SCHEMA_NOT_FOUND 或 FORM_DATA_RECORD_ID_REQUIRED。

权限规则

Client	权限行为
`form`	通过 `formApiName` 解析表单，检查表单可见性；读取时应用行权限和字段权限；写入时进入正常的新建、更新、删除运行时链路；传入 `buttonKey` 时，会应用和产品按钮一致的按钮执行权限校验
`formSchema`	只返回当前访问主体可见的表单和字段元数据；表单禁用或不可访问时会拒绝
`file`	只能解析和创建当前租户内的文件资产；其他租户的文件 ID 不可访问
`approval`	使用正常审批运行时的可见性和操作规则；任务处理和撤回必须对当前访问主体或该方法支持的成员上下文可执行
`organization` / `department` / `member`	只读；返回当前租户可见的资料表单数据；不暴露新建、更新、停用、移动或删除接口
`iam`	只读；返回当前成员或指定成员的角色摘要；不暴露角色管理或绑定修改接口

错误处理

当脚本需要把 SDK 失败转换成可控返回值或用户可见运行时效果时，使用 try/catch。

export default async function main(_payload: StudioScriptRuntimeContextPayload, context: StudioScriptContext) {
  try {
    const record = await context.form.find({
      formApiName: 'orders',
      condition: {
        logic: 'and',
        children: [
          {
            field: 'recordId',
            operator: 'eq',
            value: 'record-id',
          },
        ],
      },
    });

    return {
      ok: true,
      record,
    };
  } catch (error) {
    const code = error instanceof Error ? error.message : String(error);
    return {
      ok: false,
      message: code,
      notification: {
        type: 'error',
        title: '操作失败',
        description: code,
      },
    };
  }
}

批量方法有两类失败语义：

batchTrash 和 batchDelete 返回部分成功结果。单条记录失败会进入 failed，并带 code
事务型批量新建、批量更新方法中任意记录失败时，SDK 调用会 reject，整个事务回滚

常见错误码

通用 Studio SDK 错误：

错误码	含义
`STUDIO_ASSET_EXECUTION_FAILED`	脚本抛出未捕获错误；底层 SDK 错误会作为 `errorMessage` 返回
`STUDIO_FORM_API_INPUT_INVALID`	表单 SDK 入参必须是对象
`STUDIO_FORM_SCHEMA_API_INPUT_INVALID`	表单结构 SDK 入参必须是对象
`STUDIO_FORM_SAVED_FILTER_API_INPUT_INVALID`	保存筛选器 SDK 入参必须是对象
`STUDIO_FORM_TABLE_VIEW_API_INPUT_INVALID`	表格视图 SDK 入参必须是对象
`STUDIO_FILE_API_INPUT_INVALID`	文件 SDK 入参必须是对象
`STUDIO_APPROVAL_API_INPUT_INVALID`	审批 SDK 入参必须是对象
`STUDIO_ORG_API_INPUT_INVALID`	组织、部门或成员 SDK 入参必须是对象
`STUDIO_FORM_API_OPERATION_INVALID`	未知的表单 SDK 操作
`STUDIO_FORM_SCHEMA_API_OPERATION_INVALID`	未知的表单结构 SDK 操作
`STUDIO_FORM_SAVED_FILTER_API_OPERATION_INVALID`	未知的保存筛选器 SDK 操作
`STUDIO_FORM_TABLE_VIEW_API_OPERATION_INVALID`	未知的表格视图 SDK 操作
`STUDIO_FILE_API_OPERATION_INVALID`	未知的文件 SDK 操作
`STUDIO_APPROVAL_API_OPERATION_INVALID`	未知的审批 SDK 操作
`STUDIO_ORG_API_OPERATION_INVALID`	未知的组织、部门或成员 SDK 操作
`STUDIO_IAM_API_OPERATION_INVALID`	未知的 IAM SDK 操作

表单与表单结构错误：

错误码	含义
`FORMS_SCHEMA_API_NAME_REQUIRED`	缺少 `formApiName`
`FORMS_SCHEMA_NOT_FOUND`	表单 API 名无法解析或当前用户不可访问
`FORMS_SCHEMA_DISABLED`	目标表单已禁用
`FORMS_FIELD_API_NAME_REQUIRED`	缺少 `fieldApiName`
`FORM_DATA_RECORD_ID_REQUIRED`	缺少 `recordId`
`FORM_DATA_NOT_FOUND`	目标记录不存在或当前用户不可访问
`FORM_DATA_APPROVAL_PENDING_READ_ONLY`	记录处于审批中状态，不能直接修改
`FORM_DATA_APPROVAL_FLOW_REQUIRED`	当前操作需要审批流程实例
`FORM_DATA_APPROVAL_TRANSITION_INVALID`	请求的审批状态流转不允许
`FORM_DATA_DELETE_APPROVAL_NOT_SUPPORTED`	硬删除不支持发起审批；请使用 `trash` 或 `batchTrash` 并传入 `submitApproval: true`
`FORM_DATA_FOREIGN_KEY_RESTRICTED`	关联记录或关系受数据权限或关系规则限制
`IAM_PERMISSION_DENIED`	当前访问主体没有所需权限
`STUDIO_FORM_API_DATA_INVALID`	`data` 不是对象
`STUDIO_FORM_API_RECORDS_REQUIRED`	批量新建或批量更新至少需要一条记录
`STUDIO_FORM_API_RECORDS_LIMIT_EXCEEDED`	批量新建或批量更新超过最大记录数
`STUDIO_FORM_API_RECORD_IDS_REQUIRED`	批量删除至少需要一个记录 ID
`STUDIO_FORM_API_RECORD_IDS_LIMIT_EXCEEDED`	批量删除超过最大记录 ID 数量
`STUDIO_FORM_API_CHILD_TABLES_REQUIRED`	主子表新建或更新需要传入子表数据
`STUDIO_FORM_API_CHILD_TABLE_NOT_FOUND`	子表 API 名不是当前主表的子表
`STUDIO_FORM_API_CHILD_RECORDS_REQUIRED`	子表操作至少需要一条子表记录
`STUDIO_FORM_API_CHILD_RECORDS_LIMIT_EXCEEDED`	子表操作超过最大子表记录数
`FORM_DATA_BATCH_UPDATE_RECORD_NOT_FOUND`	批量更新的目标记录不存在或不可访问

文件错误：

错误码	含义
`FILES_ID_REQUIRED`	缺少 `fileId`
`FILES_IDS_REQUIRED`	缺少 `fileIds` 或数组为空
`FILES_NAME_REQUIRED`	缺少文件展示名
`FILES_ORIGINAL_NAME_REQUIRED`	缺少原始文件名
`FILES_MIME_TYPE_REQUIRED`	缺少 MIME 类型
`FILES_CONTENT_REQUIRED`	缺少 base64 文件内容
`FILES_NOT_FOUND`	文件资产不存在或当前用户不可访问

审批错误：

错误码	含义
`APPROVAL_TRIGGER_ACTION_INVALID`	审批动作必须是 `create`、`update` 或 `delete`
`APPROVAL_TASK_ID_REQUIRED`	缺少 `taskId`
`APPROVAL_INSTANCE_ID_REQUIRED`	缺少 `instanceId`
`APPROVAL_TASK_DECISION_INVALID`	任务决定必须是 `approved`、`rejected` 或 `returned`
`APPROVAL_TASK_NOT_FOUND`	审批任务不存在或当前用户不可见
`APPROVAL_TASK_NOT_ACTIONABLE`	当前访问主体或当前任务状态不允许处理该任务
`APPROVAL_TASK_ALREADY_DECIDED`	审批任务已经处理过
`APPROVAL_TASK_COMMENT_REQUIRED`	当前审批策略要求填写审批意见
`APPROVAL_INSTANCE_NOT_FOUND`	审批实例不存在或当前用户不可见
`APPROVAL_INSTANCE_ALREADY_PENDING`	记录已经存在审批中的实例
`APPROVAL_INSTANCE_NOT_ACTIONABLE`	当前审批实例状态不允许执行该操作
`APPROVAL_INSTANCE_WITHDRAW_DISABLED`	当前审批定义不允许撤回
`APPROVAL_INSTANCE_WITHDRAW_FORBIDDEN`	当前访问主体不能撤回该审批实例
`APPROVAL_RETURN_TARGET_INVALID`	退回目标无效
`APPROVAL_RETURN_TARGET_NODE_REQUIRED`	退回到节点时必须传入 `nodeKey`

组织、部门、成员和 IAM 错误：

错误码	含义
`ORGANIZATIONS_ID_REQUIRED`	缺少 `organizationId`
`DEPARTMENTS_ID_REQUIRED`	缺少 `departmentId`
`MEMBERS_ID_REQUIRED`	缺少 `memberId`
`STUDIO_IAM_MEMBER_ID_REQUIRED`	查询角色摘要时缺少 `memberId`
`STUDIO_IAM_MEMBER_IDS_REQUIRED`	缺少 `memberIds` 或数组为空
`STUDIO_IAM_MEMBER_IDS_LIMIT_EXCEEDED`	`memberIds` 超过最大数量 100

基础用法​

Client​

Runtime、Logger 与 HTTP​

记录结构​

返回与失败行为​

记录查询​

查询第一条匹配记录​

按条件批量获取记录​

按记录 ID 查询​

遍历全部游标分页​

记录创建​

创建单条记录​

批量创建记录​

创建主子表记录​

批量创建主子表记录​

记录更新​

更新单条记录​

批量更新记录​

更新主子表记录​

批量更新主子表记录​

记录删除​

软删除单条记录​

硬删除单条记录​

批量软删除记录​

批量硬删除记录​

恢复回收站记录​

保存筛选器 Client​

新建或更新保存筛选器​

表格视图 Client​

新建或更新表格视图​

表单结构 Client​

获取表单元数据​

表单结构​

查询字段列表​

获取单个字段​

字段结构​

文件 Client​

获取单个文件​

批量解析文件​

创建文件​

审批 Client​

获取提交配置​

提交记录审批​

查询审批记录列表​

查询记录审批实例​

查询审批实例​

查询审批任务​

查询单个审批任务​

审批任务决策​

撤回审批实例​

组织记录 Client​

查询组织列表​

获取组织树​

获取单个组织​

部门 Client​

查询部门列表​

获取部门树​

获取单个部门​

成员 Client​

获取当前成员​

查询成员列表​

获取单个成员​

IAM Client​

查询当前角色摘要​

查询指定成员角色摘要​

批量查询指定成员角色摘要​

角色结构​

自定义登录页​

安装​

使用完整 demo​

接入自己的页面​

权限与错误​

权限规则​

错误处理​

常见错误码​

基础用法

Client

Runtime、Logger 与 HTTP

记录结构

返回与失败行为

记录查询

查询第一条匹配记录

按条件批量获取记录

按记录 ID 查询

遍历全部游标分页

记录创建

创建单条记录

批量创建记录

创建主子表记录

批量创建主子表记录

记录更新

更新单条记录

批量更新记录

更新主子表记录

批量更新主子表记录

记录删除

软删除单条记录

硬删除单条记录

批量软删除记录

批量硬删除记录

恢复回收站记录

保存筛选器 Client

新建或更新保存筛选器

表格视图 Client

新建或更新表格视图

表单结构 Client

获取表单元数据

表单结构

查询字段列表

获取单个字段

字段结构

文件 Client

获取单个文件

批量解析文件

创建文件

审批 Client

获取提交配置

提交记录审批

查询审批记录列表

查询记录审批实例

查询审批实例

查询审批任务

查询单个审批任务

审批任务决策

撤回审批实例

组织记录 Client

查询组织列表

获取组织树

获取单个组织

部门 Client

查询部门列表

获取部门树

获取单个部门

成员 Client

获取当前成员

查询成员列表

获取单个成员

IAM Client

查询当前角色摘要

查询指定成员角色摘要

批量查询指定成员角色摘要

角色结构

自定义登录页

安装

使用完整 demo

接入自己的页面

权限与错误

权限规则

错误处理

常见错误码