FTableSelect 表格下拉选择

基于表格的高阶表格下拉选择组件（主推标准组件名 FTableSelect，别名 FinTableSelect），支持 API 数据请求、单选/多选、服务端/本地搜索、分页/滚动加载、自定义头部底部插槽、自定义列模板等。在 FForm 中通过 component: 'FTableSelect' 声明使用。

基础用法

最简单的用法：静态数据 + 单选。点击行即选中，选中后面板自动关闭。

loading

loading

多选 + Tag 展示

开启 multiple 后可选择多项，选中值以 Tag 形式展示在输入框中。tagConfig.max 控制最多显示的 tag 数量，超出部分折叠为 +N。

loading

服务端搜索 + 分页

通过 request 配置 API 接口，filterable 开启搜索，searchMode: 'remote' 走服务端搜索，pagination 开启分页。keyword 会自动注入到请求参数中。

loading

loading

本地搜索 + 滚动加载

searchMode: 'local' 前端过滤已加载数据，paginationType: 'scroll' 滚动到底部自动加载更多。

loading

自定义列模板

通过列配置的 slot 属性指定插槽名，自定义单元格内容。插槽接收 { row, value, column } 三个参数。

loading

自定义头部和底部

使用 #header 和 #footer 插槽自定义下拉面板的头部和底部区域。头部接收 { keyword, search, selectedRows, total }，底部接收 { selectedRows, close, clear }。

loading

formatLabel 自定义标签

labelField 只能取单个字段，如果需要复合标签（如 编码 - 名称），使用 formatLabel 函数。优先级：#display 插槽 > formatLabel > labelField。

loading

自定义显示模式

新增的 demo 展示了多种显示方式和自定义渲染能力。

loading

在 FinForm 中使用

FTableSelect 已注册到表单字段注册表，可在 FormSchema 中通过 component: 'FTableSelect' 使用。

const schemas = [
  {
    field: 'userId',
    label: '选择用户',
    component: 'FTableSelect',
    componentProps: {
      columns: [
        { prop: 'id', label: 'ID', width: 60 },
        { prop: 'name', label: '姓名', minWidth: 120 },
      ],
      request: { api: fetchUsers },
      filterable: true,
      searchMode: 'remote',
      pagination: true,
      multiple: true,
      valueField: 'id',
      labelField: 'name',
    },
  },
]

API

Props

参数	说明	类型	默认值
modelValue	v-model 绑定值	any | any[]	—
columns	列定义	SelectColumn[]	必填
data	静态数据	any[]	—
request	API 请求配置	SelectRequestConfig	—
multiple	是否多选	boolean	false
multipleLimit	多选最大数量（0 = 不限）	number	0
valueField	值字段名	string	'id'
labelField	显示字段名	string	'name'
formatLabel	自定义标签函数（优先于 labelField）	(row) => string	—
rowKey	行唯一标识字段	string	valueField
filterable	是否显示搜索框	boolean	false
searchMode	搜索模式	'remote' | 'local'	'remote'
searchFields	本地搜索字段列表	string[]	所有列
debounce	搜索防抖（毫秒）	number	300
searchPlaceholder	搜索框占位文本	string	'请输入关键词搜索'
pagination	是否分页	boolean | SelectPaginationConfig	false
paginationType	分页方式	'page' | 'scroll'	'page'
displayMode	选中值展示方式	'tag' | 'text' | 'comma'	'tag'
tagConfig	Tag 配置	TagConfig	—
placeholder	占位文本	string	'请选择'
clearable	是否可清空	boolean	true
disabled	是否禁用	boolean	false
size	组件尺寸	'large' | 'default' | 'small'	'default'
maxHeight	表格最大高度	number	300
border	表格边框	boolean	false
stripe	斑马纹	boolean	true
popperWidth	下拉宽度	number | string	自适应
popperClass	下拉弹层类名	string	—
popperAppendToBody	是否将弹层 Teleport 并明确挂载到 document.body；设为 false 时保留在组件本地	boolean	true
closeOnSelect	选择后是否关闭	boolean	单选 true / 多选 false

SelectColumn

参数	说明	类型	默认值
prop	字段名	string	必填
label	列标题	string	必填
width	列宽	number | string	—
minWidth	最小列宽	number | string	—
align	对齐方式	'left' | 'center' | 'right'	'left'
fixed	固定列	'left' | 'right' | boolean	—
slot	自定义插槽名	string	—
formatter	内置格式化器	'money' | 'date' | 'status' | function	—
searchable	本地搜索时是否可搜	boolean	true

SelectRequestConfig

参数	说明	类型	默认值
api	数据请求函数	(params) => Promise<{ list, total }>	必填
immediate	是否立即请求	boolean	true
paramsMap	参数名映射	{ page?, pageSize?, keyword? }	—
beforeRequest	请求前钩子	(params) => params	—
afterResponse	响应后钩子	(data) => { list, total }	—

Slots

插槽名	说明	参数
default	替换整个表格	{ tableData, loading, selectedRows, toggleRow, isSelected }
display	自定义 trigger 显示	{ selectedRows, value }
header	下拉面板头部	{ keyword, search, selectedRows, total }
footer	下拉面板底部	{ selectedRows, close, clear }
[col.slot]	自定义列单元格	{ row, value, column }

Events

事件名	说明	参数
update:modelValue	v-model 更新	(value)
change	选择变化	(value, rows)
select	选中某行	(row)
clear	清空选择	—
visible-change	下拉显隐变化	(visible)
search	搜索触发	(keyword)
data-change	数据变化	({ list, total })

Exposed Methods

方法名	说明
clearSelection()	清空选择
fetchData()	手动触发数据请求
open()	打开下拉
close()	关闭下拉
focus()	聚焦 trigger