辅助文本建议
辅助文本字段通过 Studio 脚本提供输入建议。建议只帮助填写，用户仍可输入列表之外的文本。
配置辅助文本建议脚本
- 在 Studio 创建服务端脚本，将下方测试代码写入 TypeScript 入口文件，编译、保存并发布
- 进入 工作管理 > 表单管理，选择表单后打开 字段设计，新建或编辑 辅助文本 字段
- 将 建议来源 设为 Studio 脚本
- 选择脚本和具体入口文件，保存字段
- 打开表单新建或编辑页，聚焦该字段并输入文本
脚本绑定在辅助文本字段上。表格展示、详情和筛选条件不会执行建议脚本。
脚本函数
使用内置类型，无需导入或重新声明：
export default async function main(
payload: AutocompleteSuggestionsPayload,
context: StudioScriptContext,
): Promise<AutocompleteSuggestionsResult> {
return { suggestions: ['建议文本一', '建议文本二'] };
}
不使用服务端 SDK 时，可省略第二个参数。绑定感知编译使用 field.autocompleteSuggestions。
入参 Payload
| 字段 | 类型 | 说明 |
|---|---|---|
schema | 'soln.runtime-context/v1' | 统一运行时上下文版本 |
source.type | 'autocomplete_suggestions' | 辅助文本建议来源 |
source.scope | 'main' | 'child' | 字段属于主表或子表 |
source.fieldApiName | string | 当前字段 API 名称 |
form | RuntimeFormRef | null | 来源表单 |
draft?.data | Record<string, unknown> | 当前主表草稿值 |
child?.row?.data | Record<string, unknown> | 当前子表行草稿值 |
selection.childRows | RuntimeChildRow[] | 当前上下文中的子表行 |
input.query | string | 本次查询文本；仅在输入非空文本后触发 |
runtime.locale | string | 运行时语言 |
runtime.timezone | string | 运行时时区 |
其他字段通过 API 名称读取，例如 payload.draft?.data.department。子表场景使用 payload.child?.row?.data 读取当前行。此事件不预加载已保存记录，record 为 null。
返回 Response
type AutocompleteSuggestionsResult = {
suggestions: string[];
};
每条建议就是文本本身：下拉展示该文本，选中后将同一文本写入字段。无需提供 label、value 或 effects。
- 返回
{ suggestions: [] }表示没有建议 - 运行时去除首尾空白，丢弃空文本、非字符串和重复项，保留原顺序
- 每次最多采用 100 条有效文本；这是当前运行时的数量限制
- 不接受对象选项数组
[{ label, value }] - 输入查询有 250ms 防抖；脚本负责按
input.query筛选，前端也会按当前输入做不区分大小写的包含匹配 - 脚本执行失败时不提供建议，仍允许自由输入
完整测试脚本
下面的脚本不读写业务数据，可以直接绑定测试：
// 用途：测试辅助文本字段的动态建议。
// 约束：只返回文本列表，不读取或修改业务数据。
export default async function main(
payload: AutocompleteSuggestionsPayload,
): Promise<AutocompleteSuggestionsResult> {
const candidates = [
'产品经理',
'项目经理',
'前端工程师',
'后端工程师',
'测试工程师',
'销售经理',
];
const query = payload.input.query.trim().toLowerCase();
if (!query) return { suggestions: [] };
return {
suggestions: candidates.filter((text) =>
text.toLowerCase().includes(query),
),
};
}
测试步骤：
- 首次聚焦空输入框，不显示建议；输入文本后才匹配
- 输入“工程师”，应显示前端、后端和测试工程师
- 输入“经理”，应显示产品、项目和销售经理
- 点击“产品经理”，字段值应为“产品经理”
- 输入“设计师”，建议为空，但仍可直接保存该文本