LookupEdit 查询选择

通用布局能力：RenderLookupEdit 实例统一支持 width、height、min/max、margin 和槽位对齐；查询 popup 的 viewport 尺寸不属于组件外部盒模型。详见组件通用布局属性。

DirectSurface UI 的查询选择组件公共类名是 RenderLookupEdit。它用于从多列候选数据中检索并选择一个值，常见于诊断、药品、检查项目、人员、科室、物资等复杂字典。

LookupEdit 的触发字段负责表单布局、已选值展示、meta 文本、焦点和清除；popup 使用内部的表格浮层展示候选行，支持搜索框、键盘导航、鼠标选择、滚动和右下角拖拽调整尺寸。

API 总览

主类：

• RenderLookupEdit

相关 public API：

• defaultLookupQueryProcessor
• LookupEditColumn
• LookupEditQueryContext
• LookupEditQueryProcessor
• LookupEditQueryResult
• LookupEditDebugState
• FormFieldStatus

导入：

import {  RenderLookupEdit,  defaultLookupQueryProcessor,  type FormFieldStatus,  type LookupEditColumn,  type LookupEditDebugState,  type LookupEditQueryContext,  type LookupEditQueryProcessor,  type LookupEditQueryResult,} from 'ds-ui'

RenderLookupEdit 的构造参数是公开 options 对象，但当前没有单独导出的 LookupEdit options 类型。业务代码直接按本文参数表传入对象。

何时使用

• 候选项需要显示多列信息，例如编码、名称、规格、科室。
• 候选项较多，需要输入关键字过滤。
• 选择结果是一个稳定值，但显示时需要 label 和附加 meta。
• 业务需要自定义查询规则、远程搜索、拼音码搜索或排序。

不适合：

• 只有少量单列枚举，使用 Dropdown。
• 需要多选，使用 MultiSelectDropdown。
• 候选项是树结构，使用 DropTreeEdit。
• 候选项是树表结构，使用 DropTreeGridEdit。
• 任意文本输入，使用 TextField。

最小示例

import { RenderLookupEdit, type LookupEditColumn } from 'ds-ui' interface DiagnosisLookupRow {  code: string  name: string  icd: string  py: string} const diagnosisColumns: LookupEditColumn[] = [  { key: 'code', title: '编码', width: 92 },  { key: 'name', title: '诊断名称' },  { key: 'icd', title: 'ICD-10', width: 104 },] const diagnosisRows: DiagnosisLookupRow[] = [  { code: 'DX001', name: '上呼吸道感染', icd: 'J06.9', py: 'shhxdgr' },  { code: 'DX002', name: '高血压病', icd: 'I10.x00', py: 'gxy' },] const diagnosisState = {  diagnosisCode: '',  diagnosisName: '',} const diagnosisLookup = new RenderLookupEdit({  columns: diagnosisColumns,  rows: diagnosisRows,  valueKey: 'code',  labelKey: 'name',  metaKey: 'icd',  queryKeys: ['code', 'name', 'icd', 'py'],  searchable: true,  clearable: true,  placeholder: '输入关键字检索诊断',  onChange: (value, row) => {    diagnosisState.diagnosisCode = value    diagnosisState.diagnosisName = row?.name ?? ''  },})

组件关系

内部 popup 基于框架的表格浮层实现，但 DropdownGridPopup 不是当前 public API 的直接文档入口。业务优先使用 RenderLookupEdit，除非后续框架明确暴露更底层的 popup API。

行数据和列定义

RenderLookupEdit<T> 的 T 必须是普通对象。valueKey 和 labelKey 指向行对象中的字段：

interface DrugRow {  code: string  name: string  spec: string  py: string} const drugRows: DrugRow[] = [  { code: 'MED001', name: '阿莫西林胶囊', spec: '0.25g*24 粒', py: 'amxl' },  { code: 'MED002', name: '布洛芬缓释胶囊', spec: '0.3g*20 粒', py: 'blf' },] const drugColumns: LookupEditColumn[] = [  { key: 'code', title: '药品编码', width: 104 },  { key: 'name', title: '药品名称' },  { key: 'spec', title: '规格', width: 132 },]

LookupEditColumn

列的 key 不要求都参与查询；实际查询字段由 queryKeys 或默认查询键决定。

RenderLookupEdit 构造参数

new RenderLookupEdit<T>(options) 的 options：

interface DrugLookupRow {  code: string  name: string  spec: string  py: string} const drugLookupRows: DrugLookupRow[] = [  { code: 'MED001', name: '阿莫西林胶囊', spec: '0.25g*24 粒', py: 'amxl' },  { code: 'MED002', name: '布洛芬缓释胶囊', spec: '0.3g*20 粒', py: 'blf' },]const drugLookupColumns: LookupEditColumn[] = [  { key: 'code', title: '药品编码', width: 104 },  { key: 'name', title: '药品名称' },  { key: 'spec', title: '规格', width: 132 },] const drugLookup = new RenderLookupEdit<DrugLookupRow>({  columns: drugLookupColumns,  rows: drugLookupRows,  valueKey: 'code',  labelKey: 'name',  metaKey: 'spec',  queryKeys: ['code', 'name', 'spec', 'py'],  clearable: true,  prefixText: '药品',  onChange: (value, row) => {    state.drugCode = value    state.drugSpec = row?.spec ?? ''  },})

RenderLookupEdit 属性

公开字段不是 setter 时，运行时修改后框架不会自动知道所有视觉变化。如果影响当前画面，应由业务触发重绘或在下一次打开 popup 前修改。

RenderLookupEdit 方法

RenderLookupEdit 没有公开 open() 方法。打开行为由点击、Enter、Space、ArrowDown 或可搜索状态下的字符输入触发。

每个 RenderLookupEdit 实例独立维护 valueKey → row 索引。已选 label 和 meta 的绘制不会重复扫描完整 rows；该索引不参与 queryProcessor，因此不会改变 popup 的查询结果、顺序或数量。替换 rows 或改变数组长度时索引会自动更新。

LookupEditDebugState

debugState() 返回：

const debugLookup = new RenderLookupEdit({  columns: [    { key: 'code', title: '编码' },    { key: 'name', title: '名称' },  ],  rows: [    { code: 'DX001', name: '上呼吸道感染' },  ],  valueKey: 'code',  labelKey: 'name',})const stateSnapshot = debugLookup.debugState()if (stateSnapshot.popupVisible) {  notificationManager.show(`当前过滤结果: ${stateSnapshot.filteredCount}`)}

查询行为

默认查询

默认查询函数是 defaultLookupQueryProcessor()。它会：

• 将 query trim 后转小写。
• query 为空时返回全部 rows。
• 在 queryKeys 指定的字段中查找。
• 匹配优先级为：完全匹配、前缀匹配、包含匹配。
• 字段优先级为：valueKey、labelKey、metaKey、其他 queryKeys。
• 同等条件下按匹配位置、长度差、原始行顺序排序。

const localResult = defaultLookupQueryProcessor({  query: 'dx',  rows: [    { code: 'DX001', name: '上呼吸道感染', icd: 'J06.9' },  ],  columns: [    { key: 'code', title: '编码' },    { key: 'name', title: '名称' },  ],  valueKey: 'code',  labelKey: 'name',  queryKeys: ['code', 'name'],  selectedValue: '',}) state.filteredRows = localResult.rows

自定义查询

queryProcessor 接收 LookupEditQueryContext<T>：

返回 LookupEditQueryResult<T>：

interface EmployeeRow {  id: string  name: string  dept: string  py: string} const employeeRows: EmployeeRow[] = [  { id: 'E001', name: '李安然', dept: '心内科', py: 'lar' },  { id: 'E002', name: '王明', dept: '呼吸科', py: 'wm' },] const employeeLookup = new RenderLookupEdit<EmployeeRow>({  columns: [    { key: 'id', title: '工号', width: 80 },    { key: 'name', title: '姓名' },    { key: 'dept', title: '科室', width: 120 },  ],  rows: employeeRows,  valueKey: 'id',  labelKey: 'name',  queryKeys: ['id', 'name', 'dept', 'py'],  queryProcessor: context => {    const query = context.query.trim().toLowerCase()    return {      rows: query        ? context.rows.filter(row =>            row.name.includes(context.query) ||            row.py.includes(query) ||            row.dept.includes(context.query),          )        : [...context.rows],    }  },  onChange: (value, row) => {    state.employeeId = value    state.employeeName = row?.name ?? ''  },})

当前 queryProcessor 是同步函数。远程检索通常应由业务层异步更新 rows：输入变化可以先返回已有缓存结果，业务异步请求完成后给 lookup.rows 重新赋值；如果 popup 仍打开，组件会按当前 query 自动同步候选行。

鼠标行为

popup 中的表格是只读候选表格，不支持在 lookup popup 内编辑单元格。

键盘行为

字段获得焦点时

Popup 打开时

当用户输入查询但未选择任何行，关闭 popup 后触发字段会恢复显示已提交的 label，不会把 query 当作值提交。

清除行为

清除按钮显示条件：

• clearable === true
• value.length > 0
• 非 disabled
• 非 readonly

清除后：

• 关闭 popup。
• 清空 query 展示。
• 字段获得焦点。
• value 变成 ''。
• 触发 onChange('', null)。

const clearableLookup = new RenderLookupEdit({  columns: [    { key: 'code', title: '编码', width: 92 },    { key: 'name', title: '名称' },  ],  rows: [    { code: 'A001', name: '项目 A' },  ],  valueKey: 'code',  labelKey: 'name',  value: 'A001',  clearable: true,  onChange: (value, row) => {    state.lookupValue = value    state.lookupRow = row  },})

只读和禁用

readonly 适合展示已选值但当前流程不允许改；disabled 适合字段完全不可交互的状态。

meta 显示

metaKey 或 metaFormatter 用于在触发字段右侧显示附加信息：

const examLookup = new RenderLookupEdit({  columns: [    { key: 'code', title: '项目编码', width: 104 },    { key: 'name', title: '检查项目' },    { key: 'dept', title: '执行科室', width: 120 },  ],  rows: [    { code: 'LAB001', name: '血常规', dept: '检验科' },    { code: 'IMG301', name: '头颅 CT', dept: '放射科' },  ],  valueKey: 'code',  labelKey: 'name',  metaFormatter: row => `执行: ${row.dept}`,  onChange: value => {    state.examCode = value  },})

显示规则：

• popup 关闭时，主文本显示 labelKey，右侧显示 meta。
• 用户输入 query 时，触发字段显示 query，并临时隐藏 meta。
• 选择或关闭 popup 后恢复已提交值展示。

Popup 布局和尺寸

Lookup popup 的宽度和高度由内部表格浮层计算：

• 最小宽度不小于触发字段宽度。
• 最小宽度不小于 200。
• 固定列使用 width。
• 未设置 width 的列按剩余宽度弹性分配，最小 60。
• 如果候选行超过可见行数，会保留垂直滚动条宽度。
• 下方空间不足时会尝试显示到触发字段上方。
• 右下角 resize grip 可调整 popup 宽高。

maxVisibleItems 控制自然高度，但用户调整过 popup 尺寸后，浮层会使用当前 override 尺寸。

rows / columns 动态更新

rows 和 columns 可以在运行时替换：

• popup 关闭时，只更新下一次打开使用的数据。
• popup 打开时，rows 替换会按当前 query 重新过滤并同步表格。
• popup 打开时，columns 替换会同步表格列，并重新设置当前查询结果。
• 替换 rows 或 columns 不会自动清空 value，也不会触发 onChange。

const dynamicLookup = new RenderLookupEdit({  columns: [    { key: 'code', title: '编码' },    { key: 'name', title: '名称' },  ],  rows: [    { code: 'OLD', name: '旧项目' },  ],  valueKey: 'code',  labelKey: 'name',  value: 'OLD',}) dynamicLookup.rows = [  { code: 'NEW', name: '新项目' },]if (!dynamicLookup.rows.some(row => row.code === dynamicLookup.value)) {  dynamicLookup.value = ''}

生命周期

• RenderLookupEdit.dispose() 会关闭并释放 popup、注销焦点、清理 query 和 hover。
• readonly / disabled 变为 true 会关闭 popup、清理 query、失焦并从焦点顺序中移除。
• popup 关闭会结束搜索输入 session，避免隐藏 textarea 残留。
• debugState() 在 popup 关闭时不会执行 queryProcessor，避免调试面板触发额外业务查询。

表单组合建议

const requiredDiagnosisLookup = new RenderLookupEdit({  columns: [    { key: 'code', title: '编码', width: 92 },    { key: 'name', title: '诊断名称' },  ],  rows: [    { code: 'DX001', name: '上呼吸道感染' },  ],  valueKey: 'code',  labelKey: 'name',  value: state.diagnosisCode,  prefixText: '诊断',  clearable: true,  status: state.diagnosisCode ? 'default' : 'error',  helperText: state.diagnosisCode ? '' : '请选择诊断',  onChange: value => {    state.diagnosisCode = value  },})

布局注意：

• 组件宽度由父布局约束决定；无限宽度下默认使用 220。
• helperText 会增加组件总高度。
• 主文本和 meta 共享触发字段的 value 区域，meta 会占用右侧空间。
• 长 label 会被裁剪，不会自动换行。

常见问题

为什么输入 query 后没有选中值？

LookupEdit 的输入只用于查询，只有选择 popup 行才会提交 value。关闭 popup 会恢复已提交 label，不会把 query 当作 value。

为什么设置了 value 但显示为空？

value 必须能在 rows 中找到 String(row[valueKey]) === value 的行。找不到时 selectedLabel 为空，触发字段会显示 placeholder。

为什么更新 rows 后 value 没有自动清空？

组件不替业务决定旧值是否仍有效。需要清空时由业务显式判断并设置 value = ''。

远程搜索怎么做？

当前 queryProcessor 是同步函数。推荐方式是业务层维护缓存 rows：用户查询时先返回当前缓存，业务异步请求完成后更新 lookup.rows。如果 popup 仍打开，组件会按当前 query 同步候选结果。

相关组件

• Dropdown
• MultiSelectDropdown
• DropTreeEdit
• DropTreeGridEdit
• GridView
• TextField