# 搜索式查找选择器

在采购、服务等表单中按中文关键词查找供应商、客户或物料，并按需录入新的名称。

## 放置与配置

在易企办审批表单、数据列表表单或支持临时变量的自定义页面添加自定义代码控件，将下载的 TSX 完整粘贴到编辑器。先在测试应用核对字段类型与读写权限，再配置下表。

| 参数标识 | 类型 | 标准场景 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `dataListId` | 变量或表达式 | 需要 | 数据列表 ID。提供候选记录的易企办数据列表 ID。 | `目标供应商列表 ID` |
| `displayField` | 变量或表达式 | 需要 | 查找显示字段。用于关键词匹配和显示选项的字段标识。 | `Title` |
| `valueField` | 变量或表达式 | 需要 | 保存值字段。用于写入已选值的字段标识。 | `ListDataID` |
| `saveToField` | 变量或表达式 | 需要 | 完整结果保存目标。从变量选择器绑定可写表单字段或页面临时变量，保存完整 JSON。 | `SupplierLookupJson` |
| `selectedItemsField` | 变量或表达式 | 按需 | 匹配结果保存目标。从选择器绑定可写目标，仅保存已匹配记录的值。 | `SelectedSupplierIds` |
| `newItemsField` | 变量或表达式 | 按需 | 手工值保存目标。从选择器绑定可写目标，仅保存手工录入的值。 | `NewSupplierNames` |
| `multiSelect` | 变量或表达式 | 按需 | 允许多选。使用 true 或 false 控制能否选多项。 | `true` |
| `allowManualEntry` | 变量或表达式 | 按需 | 允许手工录入。使用 true 或 false 控制能否添加手工输入的文字。 | `true` |
| `maxResults` | 文本 | 按需 | 候选条数上限。候选列表最多显示的匹配记录数。 | `8` |
| `placeholderText` | 文本 | 按需 | 输入提示。搜索框中的提示文字。 | `输入供应商名称` |
| `labelText` | 文本 | 按需 | 控件标题。控件上方的可选标题。 | `供应商` |
| `noResultText` | 文本 | 按需 | 无匹配提示。未找到匹配记录时的提示。 | `未找到供应商` |
| `manualTagText` | 文本 | 按需 | 手工录入标记。用于标记手工录入的标签文字。 | `新录入` |
| `minSearchChars` | 文本 | 按需 | 最少搜索字符。发起查询所需的最少字符数，默认为 1。 | `1` |
| `debounceMs` | 文本 | 按需 | 搜索等待毫秒数。停止输入后等待多少毫秒再发起查询，默认为 260。 | `260` |

示例字段和列表 ID 请替换为目标应用的实际值。表达式请在编辑器中绑定。

1. 绑定来源列表和显示值。
2. 配置可写输出目标。
3. 验证匹配、手工录入和回显。

## 业务示例与结果

在采购申请中查找「上海」并选择一个已登记供应商。开启手工录入后，可添加「苏州设备服务商」，供采购组后续审核。

完整结果保存 JSON 数组，例如 [{"display":"上海供应商","value":"supplier-1","isManual":false,"source":"selected"}]。匹配与手工值分别写入字符串数组，如 ["supplier-1"] 和 ["苏州设备服务商"]。控件只写入明确配置的目标，打开表单时回显已有选项。手工值保存在配置的输出中，创建主数据需由后续业务流程完成。

来源列表需授予使用者读取权限。控件处理查询返回的记录。列表量较大时，请按目标租户的 SDK 筛选格式缩小查询范围，并核对查询条数上限。

## 预览验收

用中文输入法检查选词、搜索、空结果、查询失败、移除、多选和只读回显。若放在自定义页面，验证页面临时变量实际收到值。

出现空结果时，先核对参数值、来源数据、字段标识和使用者权限。涉及写回时，再检查可写目标类型、当前页面权限及保存后的实际值。

模板已做本地源码与交互检查。发布到业务环境前，请在目标易企办租户验证当前版本的控件编辑器、数据权限和实际读写。

源模板 CCT4FF83。 [Yeeflow 原站控件](https://www.yeeflow.com/templates/custom-code/smart-lookup-picker)