ProSelect 高级选择器

ProSelect 基于 NSelect，提供下拉远程分页和 ProPopup + ProTable 两种选择方式。两种模式共用同一个 modelValue、默认值补全、外部值同步、options 去重和 request 协议。

适用场景

dropdown：字段少、候选项可用 label 辨认，适合直接搜索和滚动选择。
popup：需要展示多列、组合查询、分页或跨页多选。popupProps.preset 可切换 modal、drawer，不会产生第二套选择逻辑。

基础用法

vue

<script setup lang="ts">
import { ProSelect } from '@coderych/naive-ui-pro-components'
import { ref } from 'vue'

const value = ref<number | null>(null)
async function request(params, selectedKeys, selectedRows) {
  const response = await queryUsers({ params, selectedKeys, selectedRows })
  return { data: response.list, total: response.total }
}
</script>

<template>
  <ProSelect
    v-model="value"
    label-field="name"
    :request="request"
    value-field="id"
  />
</template>

valueField 同时是 Select option key、modelValue 的来源和 ProTable row key，不需要再配置一套重复的 key 字段。

下拉单选

打开下拉时请求第一页；输入搜索词后重置分页；滚动到底部自动追加下一页。示例的默认值 37 不在第一页，组件会先单独补全它，打开下拉时仍照常请求列表。

下拉多选

多选时 modelValue、selectedKeys 是 key 数组，selectedRows 是 row 数组。搜索条件变化只清空普通列表，当前选中项仍保留在展示 options 中。

Popup 模式禁用普通下拉选择，右侧按钮是唯一选择入口。表格内的选择是临时状态，只有点击“确定”才更新 modelValue。

vue

<script setup lang="ts">
import type { ProSelectRequest } from '@naive-ui-pro/pro-select'
import type { ProTableColumn } from '@naive-ui-pro/pro-table'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NText } from 'naive-ui'
import { ref } from 'vue'

interface Customer {
  id: number
  name: string
  city: string
}

const customers: Customer[] = Array.from({ length: 32 }, (_, index) => ({
  id: index + 1,
  name: `客户 ${index + 1}`,
  city: index % 2 === 0 ? '上海' : '杭州',
}))
const value = ref<number | null>(18)
const selected = ref<Customer | null>(null)
const columns: ProTableColumn<Customer>[] = [
  { key: 'name', title: '客户名称', search: true },
  { key: 'city', title: '城市', search: true },
]

const request: ProSelectRequest<Customer> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 180))
  if (!('current' in params)) {
    const key = Array.isArray(selectedKeys) ? selectedKeys[0] : selectedKeys
    return { data: customers.filter(customer => customer.id === key), total: key ? 1 : 0 }
  }
  const name = String(params.name ?? '')
  const city = String(params.city ?? '')
  const filtered = customers.filter(customer =>
    customer.name.includes(name) && customer.city.includes(city),
  )
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}
</script>

<template>
  <ProSelect
    v-model="value"
    label-field="name"
    mode="popup"
    :popup-props="{ preset: 'modal', title: '选择客户', width: 760 }"
    :request="request"
    :table-props="{ columns, showIndex: false }"
    value-field="id"
    :page-size="10"
    @change="(_keys, rows) => selected = rows as Customer | null"
  />
  <NText depth="3">
    已确认：{{ selected?.name ?? `ID ${value ?? '-'}` }}
  </NText>
</template>

ProPopup 多选（Drawer）

跨页切换时，临时 keys 和已取得的完整 rows 都会保留。取消或直接关闭抽屉只丢弃临时状态，已确认值不变。

vue

<script setup lang="ts">
import type { ProSelectInst, ProSelectRequest } from '@naive-ui-pro/pro-select'
import type { ProTableColumn } from '@naive-ui-pro/pro-table'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NButton, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

interface Employee {
  id: number
  name: string
  department: string
}

const employees: Employee[] = Array.from({ length: 52 }, (_, index) => ({
  id: index + 1,
  name: `员工 ${index + 1}`,
  department: index % 2 === 0 ? '研发部' : '产品部',
}))
const selectRef = ref<ProSelectInst<Employee> | null>(null)
const value = ref<number[]>([3, 29])
const selectedRows = ref<Employee[]>([])
const columns: ProTableColumn<Employee>[] = [
  { key: 'name', title: '姓名', search: true },
  {
    key: 'department',
    title: '部门',
    search: {
      component: 'select',
      options: [
        { label: '研发部', value: '研发部' },
        { label: '产品部', value: '产品部' },
      ],
    },
  },
]

const request: ProSelectRequest<Employee> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 160))
  const keys = Array.isArray(selectedKeys) ? selectedKeys : []
  if (!('current' in params)) {
    return {
      data: employees.filter(employee => keys.includes(employee.id)),
      total: keys.length,
    }
  }
  const name = String(params.name ?? '')
  const department = String(params.department ?? '')
  const filtered = employees.filter(employee =>
    employee.name.includes(name)
    && (!department || employee.department === department),
  )
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}
</script>

<template>
  <NSpace vertical>
    <ProSelect
      ref="selectRef"
      v-model="value"
      label-field="name"
      mode="popup"
      multiple
      :page-size="8"
      :popup-props="{ preset: 'drawer', title: '跨页选择员工', width: 860 }"
      :request="request"
      :table-props="{ columns }"
      value-field="id"
      @change="(_keys, rows) => selectedRows = rows as Employee[]"
    />
    <NSpace>
      <NButton @click="selectRef?.table?.reload()">
        调用 table.reload()
      </NButton>
      <NText depth="3">
        已确认 {{ value.length }} 项：{{ selectedRows.map(row => row.name).join('、') || '打开抽屉查看默认值' }}
      </NText>
    </NSpace>
  </NSpace>
</template>

默认值和外部动态修改

外部值不在当前 options 时，组件把所有缺失 key 合并为一次补全请求。外部清空不会触发反向的 update:modelValue。

本地选项

当数据量较小或已有完整列表时，直接传 options 即可，无需 request。filterable 开启前端过滤，labelField 和 valueField 的用法与远程模式一致。

自定义请求参数

requestParams 会合并到每次请求的 params 中，适合联动外部筛选条件。searchField 可替换默认的 keyword 字段名，pageFields 可替换 current / size。searchDebounce 控制搜索防抖时间。

vue

<script setup lang="ts">
import type { ProSelectRequest } from '@naive-ui-pro/pro-select'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NButton, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

interface Article {
  articleId: number
  title: string
  category: string
  status: string
}

const articles: Article[] = Array.from({ length: 60 }, (_, index) => ({
  articleId: index + 1,
  title: `文章标题 ${index + 1}`,
  category: ['技术', '产品', '设计'][index % 3],
  status: index % 5 === 0 ? 'draft' : 'published',
}))

const value = ref<number | null>(null)
const category = ref('技术')
const status = ref('published')

const request: ProSelectRequest<Article> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 150))
  const keys = selectedKeys === null
    ? []
    : Array.isArray(selectedKeys) ? selectedKeys : [selectedKeys]
  if (!('page' in params)) {
    return {
      data: articles.filter(a => keys.includes(a.articleId)),
      total: keys.length,
    }
  }
  // 使用自定义 searchField（title）和自定义 pageFields（page / pageSize）
  const keyword = String(params.title ?? '')
  const cat = String(params.category ?? '')
  const st = String(params.status ?? '')
  const filtered = articles.filter(a =>
    a.title.includes(keyword)
    && (!cat || a.category === cat)
    && (!st || a.status === st),
  )
  const page = Number(params.page)
  const size = Number(params.pageSize)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}
</script>

<template>
  <NSpace vertical :size="12">
    <NSpace align="center">
      <NText>分类：</NText>
      <NButton
        v-for="cat in ['技术', '产品', '设计']"
        :key="cat"
        :type="category === cat ? 'primary' : 'default'"
        size="small"
        @click="category = cat"
      >
        {{ cat }}
      </NButton>
      <NText style="margin-left: 16px;">状态：</NText>
      <NButton
        :type="status === 'published' ? 'primary' : 'default'"
        size="small"
        @click="status = 'published'"
      >
        已发布
      </NButton>
      <NButton
        :type="status === 'draft' ? 'primary' : 'default'"
        size="small"
        @click="status = 'draft'"
      >
        草稿
      </NButton>
    </NSpace>

    <ProSelect
      v-model="value"
      clearable
      filterable
      label-field="title"
      placeholder="输入标题搜索（searchDebounce=500ms）"
      :page-fields="{ page: 'page', pageSize: 'pageSize' }"
      :page-size="10"
      :request="request"
      :request-params="{ category, status }"
      :search-debounce="500"
      search-field="title"
      value-field="articleId"
    />

    <NText depth="3">
      当前值：{{ value ?? '未选择' }}；requestParams：category={{ category }}, status={{ status }}
    </NText>
  </NSpace>
</template>

自定义 Slots

ProSelect 支持全部 NSelect 插槽（default、header、action、empty、arrow），以及 button、popup-*、table-* 前缀插槽。popup-footer 提供 confirm 和 cancel 回调。

vue

<script setup lang="ts">
import type { ProSelectInst, ProSelectRequest } from '@naive-ui-pro/pro-select'
import type { ProTableColumn } from '@naive-ui-pro/pro-table'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NButton, NIcon, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

interface Supplier {
  id: number
  name: string
  region: string
}

const suppliers: Supplier[] = Array.from({ length: 28 }, (_, index) => ({
  id: index + 1,
  name: `供应商 ${index + 1}`,
  region: index % 2 === 0 ? '华东' : '华南',
}))

const selectRef = ref<ProSelectInst<Supplier> | null>(null)
const value = ref<number[]>([5, 12])
const selectedRows = ref<Supplier[]>([])

const columns: ProTableColumn<Supplier>[] = [
  { key: 'name', title: '供应商名称', search: true },
  { key: 'region', title: '区域', search: true },
]

const request: ProSelectRequest<Supplier> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 150))
  const keys = Array.isArray(selectedKeys) ? selectedKeys : []
  if (!('current' in params)) {
    return {
      data: suppliers.filter(s => keys.includes(s.id)),
      total: keys.length,
    }
  }
  const name = String(params.name ?? '')
  const region = String(params.region ?? '')
  const filtered = suppliers.filter(s =>
    s.name.includes(name) && (!region || s.region === region),
  )
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}
</script>

<template>
  <NSpace vertical :size="12">
    <ProSelect
      ref="selectRef"
      v-model="value"
      label-field="name"
      mode="popup"
      multiple
      :page-size="8"
      :popup-props="{ preset: 'modal', title: '选择供应商', width: 760 }"
      :request="request"
      :table-props="{ columns }"
      value-field="id"
      @change="(_keys, rows) => selectedRows = rows as Supplier[]"
    >
      <!-- 自定义入口按钮：图标 + 文字 -->
      <template #button="{ open, text }">
        <NButton type="primary" @click="open">
          <template #icon>
            <NIcon>
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10" /><path d="M12 8v8" /><path d="M8 12h8" /></svg>
            </NIcon>
          </template>
          {{ text }}
        </NButton>
      </template>

      <!-- 自定义弹窗标题 -->
      <template #popup-header>
        <NText strong style="font-size: 16px;">
          📦 选择供应商
        </NText>
      </template>

      <!-- 自定义弹窗底部：带选中数量提示 -->
      <template #popup-footer="{ confirm, cancel }">
        <NSpace justify="space-between" align="center" style="width: 100%; padding: 8px 0;">
          <NText depth="3">
            已选 {{ value.length }} 家供应商
          </NText>
          <NSpace>
            <NButton @click="cancel">
              取消
            </NButton>
            <NButton type="primary" @click="confirm">
              确认选择
            </NButton>
          </NSpace>
        </NSpace>
      </template>

      <!-- 自定义空状态 -->
      <template #empty>
        <NText depth="3" style="padding: 24px; display: block; text-align: center;">
          没有找到匹配的供应商，请调整搜索条件
        </NText>
      </template>
    </ProSelect>

    <NText depth="3">
      已确认 {{ value.length }} 项：{{ selectedRows.map(r => r.name).join('、') || '暂无' }}
    </NText>
  </NSpace>
</template>

实例方法与 Expose

通过 ref 获取 ProSelectInst，可访问 focus、blur 等 SelectInst 方法，以及 selectedKeys、selectedRows、table、popup 等增强字段。

vue

<script setup lang="ts">
import type { ProSelectInst, ProSelectRequest } from '@naive-ui-pro/pro-select'
import type { ProTableColumn } from '@naive-ui-pro/pro-table'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NAlert, NButton, NCode, NSpace, NText } from 'naive-ui'
import { nextTick, ref } from 'vue'

interface Employee {
  id: number
  name: string
  department: string
  role: string
}

const employees: Employee[] = Array.from({ length: 40 }, (_, index) => ({
  id: index + 1,
  name: `员工 ${index + 1}`,
  department: ['研发部', '产品部', '设计部'][index % 3],
  role: ['工程师', '产品经理', '设计师'][index % 3],
}))

const selectRef = ref<ProSelectInst<Employee> | null>(null)
const value = ref<number[]>([3, 15])
const result = ref('点击按钮调用 ProSelect 实例方法')
const snapshot = ref('{}')

const columns: ProTableColumn<Employee>[] = [
  { key: 'name', title: '姓名', search: true },
  { key: 'department', title: '部门' },
  { key: 'role', title: '角色' },
]

const request: ProSelectRequest<Employee> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 150))
  const keys = Array.isArray(selectedKeys) ? selectedKeys : []
  if (!('current' in params)) {
    return {
      data: employees.filter(e => keys.includes(e.id)),
      total: keys.length,
    }
  }
  const name = String(params.name ?? '')
  const filtered = employees.filter(e => e.name.includes(name))
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}

interface MethodAction {
  label: string
  description: string
  run: (inst: ProSelectInst<Employee>) => unknown
}

const actions: MethodAction[] = [
  {
    label: 'focus()',
    description: '聚焦到 Select 输入框',
    run: (inst) => { inst.focus() },
  },
  {
    label: 'blur()',
    description: '取消聚焦',
    run: (inst) => { inst.blur() },
  },
  {
    label: '读取 selectedKeys',
    description: '获取当前已确认的 keys',
    run: (inst) => {
      return JSON.stringify(inst.selectedKeys)
    },
  },
  {
    label: '读取 selectedRows',
    description: '获取当前已确认的完整 rows',
    run: (inst) => {
      const rows = inst.selectedRows
      return Array.isArray(rows) ? rows.map(r => r.name) : rows?.name ?? null
    },
  },
  {
    label: 'table.reload()',
    description: '刷新 Popup 表格数据',
    run: async (inst) => {
      await inst.table?.reload()
      return '表格已刷新'
    },
  },
  {
    label: 'table.search()',
    description: '按条件搜索 Popup 表格',
    run: async (inst) => {
      await inst.table?.search({ name: '员工 1' })
      return '已搜索 "员工 1"'
    },
  },
  {
    label: 'table.reset()',
    description: '重置 Popup 表格搜索条件',
    run: async (inst) => {
      await inst.table?.reset()
      return '表格条件已重置'
    },
  },
  {
    label: 'popup 状态',
    description: '读取 popup 实例',
    run: (inst) => {
      return inst.popup ? 'Popup 实例存在' : 'Popup 实例为空（未打开过）'
    },
  },
]

async function invoke(action: MethodAction): Promise<void> {
  const inst = selectRef.value
  if (!inst)
    return
  const returnValue = await action.run(inst)
  await nextTick()
  result.value = `${action.label}：${action.description}`
  snapshot.value = JSON.stringify({
    returnValue,
    selectedKeys: inst.selectedKeys,
    selectedRows: Array.isArray(inst.selectedRows)
      ? inst.selectedRows.map(r => r.name)
      : inst.selectedRows?.name ?? null,
    tableData: inst.table?.data?.length ?? 'N/A',
    popupExists: !!inst.popup,
  }, null, 2)
}
</script>

<template>
  <NSpace vertical :size="12">
    <NText strong>
      实例方法
    </NText>
    <NSpace>
      <NButton
        v-for="action in actions"
        :key="action.label"
        secondary
        type="primary"
        @click="invoke(action)"
      >
        {{ action.label }}
      </NButton>
    </NSpace>

    <NAlert type="info" :show-icon="false">
      {{ result }}
    </NAlert>
    <NCode :code="snapshot" language="json" word-wrap />

    <ProSelect
      ref="selectRef"
      v-model="value"
      label-field="name"
      mode="popup"
      multiple
      :page-size="8"
      :popup-props="{ preset: 'drawer', title: '选择员工', width: 800 }"
      :request="request"
      :table-props="{ columns }"
      value-field="id"
    />
  </NSpace>
</template>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

禁用与按钮配置

disabled 同时作用于下拉和 Popup 模式。buttonText 自定义入口按钮文案，buttonProps 传递按钮属性（type、size、round 等）。组件继承 NSelect 的 size 和 status。

vue

<script setup lang="ts">
import type { ProSelectRequest } from '@naive-ui-pro/pro-select'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NButton, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

interface Tag {
  id: number
  name: string
}

const tags: Tag[] = Array.from({ length: 20 }, (_, index) => ({
  id: index + 1,
  name: `标签 ${index + 1}`,
}))

const value1 = ref<number | null>(5)
const value2 = ref<number[]>([2, 8])
const disabled = ref(false)

const request: ProSelectRequest<Tag> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 100))
  const keys = selectedKeys === null
    ? []
    : Array.isArray(selectedKeys) ? selectedKeys : [selectedKeys]
  if (!('current' in params)) {
    return { data: tags.filter(t => keys.includes(t.id)), total: keys.length }
  }
  const keyword = String(params.keyword ?? '')
  const filtered = tags.filter(t => t.name.includes(keyword))
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}
</script>

<template>
  <NSpace vertical :size="16">
    <!-- disabled 状态 -->
    <NText strong>disabled 属性</NText>
    <NSpace align="center">
      <NButton size="small" @click="disabled = !disabled">
        切换 disabled：{{ disabled }}
      </NButton>
    </NSpace>
    <ProSelect
      v-model="value1"
      clearable
      filterable
      label-field="name"
      placeholder="下拉模式"
      :disabled="disabled"
      :request="request"
      value-field="id"
    />
    <ProSelect
      v-model="value2"
      label-field="name"
      mode="popup"
      multiple
      :disabled="disabled"
      :popup-props="{ preset: 'modal', title: '选择标签', width: 600 }"
      :request="request"
      :table-props="{ columns: [{ key: 'name', title: '标签名称', search: true }] }"
      value-field="id"
    />

    <!-- 自定义按钮文字和属性 -->
    <NText strong>buttonText 与 buttonProps</NText>
    <ProSelect
      v-model="value1"
      button-text="选择标签"
      clearable
      filterable
      label-field="name"
      mode="popup"
      :button-props="{ type: 'warning', size: 'small', round: true }"
      :popup-props="{ preset: 'modal', title: '选择标签', width: 600 }"
      :request="request"
      :table-props="{ columns: [{ key: 'name', title: '标签名称', search: true }] }"
      value-field="id"
    />

    <!-- 继承 NSelect 的 size / status -->
    <NText strong>继承 NSelect Props：size 与 status</NText>
    <NSpace vertical>
      <ProSelect
        v-model="value1"
        clearable
        filterable
        label-field="name"
        placeholder="small 尺寸"
        size="small"
        :request="request"
        value-field="id"
      />
      <ProSelect
        v-model="value1"
        clearable
        filterable
        label-field="name"
        placeholder="large 尺寸"
        size="large"
        :request="request"
        value-field="id"
      />
      <ProSelect
        v-model="value1"
        clearable
        filterable
        label-field="name"
        placeholder="error 状态"
        status="error"
        :request="request"
        value-field="id"
      />
      <ProSelect
        v-model="value1"
        clearable
        filterable
        label-field="name"
        placeholder="warning 状态"
        status="warning"
        :request="request"
        value-field="id"
      />
    </NSpace>
  </NSpace>
</template>

请求错误处理

request-error 事件在 request 抛出异常时触发，参数为 (error, context)。context 区分补全（hydrate）、下拉列表（dropdown）和 Popup 表格（popup）三种场景。

vue

<script setup lang="ts">
import type { ProSelectRequest, ProSelectRequestContext } from '@naive-ui-pro/pro-select'
import { ProSelect } from '@naive-ui-pro/pro-select'
import { NAlert, NButton, NSpace, NText } from 'naive-ui'
import { ref } from 'vue'

interface Item {
  id: number
  name: string
}

const items: Item[] = Array.from({ length: 30 }, (_, index) => ({
  id: index + 1,
  name: `项目 ${index + 1}`,
}))

const value = ref<number | null>(5)
const errorMessage = ref('')
const errorContext = ref<ProSelectRequestContext | ''>('')
const failCount = ref(0)

const request: ProSelectRequest<Item> = async (params, selectedKeys) => {
  await new Promise(resolve => setTimeout(resolve, 200))
  const keys = selectedKeys === null
    ? []
    : Array.isArray(selectedKeys) ? selectedKeys : [selectedKeys]
  if (!('current' in params)) {
    return { data: items.filter(i => keys.includes(i.id)), total: keys.length }
  }

  // 前两次请求模拟失败
  if (failCount.value < 2) {
    failCount.value++
    throw new Error(`模拟网络错误（第 ${failCount.value} 次）`)
  }

  const keyword = String(params.keyword ?? '')
  const filtered = items.filter(i => i.name.includes(keyword))
  const page = Number(params.current)
  const size = Number(params.size)
  return {
    data: filtered.slice((page - 1) * size, page * size),
    total: filtered.length,
  }
}

function handleError(error: unknown, context: ProSelectRequestContext) {
  errorMessage.value = error instanceof Error ? error.message : String(error)
  errorContext.value = context
}

function resetDemo() {
  failCount.value = 0
  errorMessage.value = ''
  errorContext.value = ''
}
</script>

<template>
  <NSpace vertical :size="12">
    <NAlert v-if="errorMessage" type="error" closable @close="errorMessage = ''">
      <NText strong>请求失败</NText>（场景：{{ errorContext }}）：{{ errorMessage }}
    </NAlert>
    <NAlert v-else type="info" :show-icon="false">
      已失败 {{ failCount }} 次，再打开下拉将开始正常请求（模拟 2 次失败后恢复）
    </NAlert>

    <NSpace>
      <NButton size="small" @click="resetDemo">
        重置失败计数
      </NButton>
    </NSpace>

    <ProSelect
      v-model="value"
      clearable
      filterable
      label-field="name"
      placeholder="打开下拉触发请求（前两次会失败）"
      :request="request"
      value-field="id"
      @request-error="handleError"
    />

    <NText depth="3">
      当前值：{{ value ?? '未选择' }}；request-error 事件捕获请求异常并展示上下文
    </NText>
  </NSpace>
</template>

request 协议

type ProSelectRequest<T> = (
  params: Record<string, unknown>,
  selectedKeys: string | number | (string | number)[] | null,
  selectedRows: T | T[] | null,
) => Promise<{
  total: number
  data: T[]
}>

调用类型如下：

场景	params	selectedKeys / selectedRows
默认值、外部值补全	`requestParams`，不带分页字段	当前全部 keys，以及 options 中已经存在的 rows
下拉列表	`requestParams + keyword + current + size`	当前已确认选择
Popup 表格	`requestParams + ProTable 查询与分页参数`	当前临时选择

单选始终传 key | null 和 row | null；多选始终传 key[] 和 row[]。补全请求只有在至少一个 key 缺少完整 row 时才发出，接口可根据 selectedKeys 与 selectedRows 的差集只查询缺失数据。

如果后端分页字段不是 current、size：

vue

<ProSelect
  :page-fields="{ page: 'pageNumber', pageSize: 'pageSize' }"
  :request="request"
/>

pageFields 同时作用于 dropdown 和 ProTable，保证两种模式使用相同协议。

数据流

text

打开 / 搜索
→ 重置普通列表和页码
→ request 第一页
→ 触底后按页追加
→ 用户选择
→ 更新已确认 keys、rows 和 modelValue

首次加载、下一页、补全分别维护 loading 和请求标识。下一页成功后才推进页码；失败时再次触底可重试。组件默认把 resetMenuOnOptionsChange 设为 false，并在追加后兜底恢复滚动位置。

ProPopup

text

已确认选择
→ 打开时复制为临时选择
→ ProTable 查询、分页、跨页选择
→ 确定：临时选择提交为已确认选择
→ 取消 / 关闭：丢弃临时选择

modal 和 drawer 只由 popupProps.preset 决定展示形式，使用同一个 popupVisible、临时选择和请求函数。

options 管理

组件只保留两类可变数据：

listOptions：下拉普通列表，搜索时允许重置；
selectedOptions：默认值、外部值和已确认选择对应的完整 rows。

最终 options 由 props.options + listOptions + selectedOptions 按 valueField 合并。相同 key 更新原位置的数据，不使用对象引用或数组下标判断，顺序保持稳定。

Props

除下表外，继承 NSelect 的常用 Props。value 改为 Vue 标准的 modelValue，避免两套受控值语义。

属性	类型	默认值	说明
modelValue	`Key \| Key[] \| null`	-	`v-model` 值
defaultValue	`Key \| Key[] \| null`	`null`	非受控初始值
mode	`'dropdown' \| 'popup'`	`'dropdown'`	选择模式
request	`ProSelectRequest`	-	统一异步请求
options	`Record<string, any>[]`	`[]`	本地或预置完整 rows
requestParams	`Record<string, unknown>`	`{}`	外部业务参数
pageSize	`number`	`20`	两种模式的每页数量
pageFields	`{ page: string, pageSize: string }`	`{ page: 'current', pageSize: 'size' }`	分页字段名
searchField	`string`	`'keyword'`	dropdown 搜索字段名
searchDebounce	`number`	`300`	dropdown 远程搜索防抖时间
popupProps	`ProPopupProps`	`{}`	ProPopup 属性；用 `preset` 设置 modal/drawer
tableProps	`ProTableProps`	`{}`	ProTable 属性
buttonText	`string`	国际化 `selectText`	Popup 入口按钮文案
buttonProps	`ButtonProps`	`{}`	入口按钮属性
labelField	`string`	`'label'`	row 的展示字段
valueField	`string`	`'value'`	row 的唯一 key 字段
multiple	`boolean`	`false`	是否多选
resetMenuOnOptionsChange	`boolean`	`false`	是否在 options 变化时重置菜单

show、request、manual、pageFields、pagination.pageSize、checkedRowKeys、rowKey 和 selection 列由 ProSelect 控制时，传入 popupProps 或 tableProps 的同名值会被内部状态覆盖。其他属性正常透传。

Events

事件名	参数	说明
update:modelValue	`keys`	用户在 dropdown 选择，或 Popup 确认时触发
change	`(keys, rows)`	同时取得当前 keys 与完整 rows；外部赋值不会触发
request-error	`(error, context)`	请求失败；`context` 为 `hydrate`、`dropdown` 或 `popup`

NSelect 的 search、scroll、update:show 等回调属性仍会被调用。

Slots

Select 插槽保持原名；ProPopup 和 ProTable 插槽增加前缀，避免同名冲突。

插槽	说明
default / header / action / empty / arrow	原 `NSelect` 插槽
button	自定义 Popup 入口，参数 `{ open, disabled, text }`
popup-header / popup-header-extra / popup-action / popup-close / popup-icon	对应 ProPopup 插槽
popup-footer	自定义底部，参数 `{ confirm, cancel }`
table-default / table-form / table-header / table-header-extra / table-title	对应 ProTable 插槽
table-batch-actions / table-empty 等	对应 ProTable / NDataTable 插槽

例如：

vue

<ProSelect mode="popup" v-model="value" :request="request">
  <template #popup-header>选择供应商</template>
  <template #table-empty>没有符合条件的供应商</template>
  <template #popup-footer="{ confirm, cancel }">
    <n-space justify="end">
      <n-button @click="cancel">返回</n-button>
      <n-button type="primary" @click="confirm">使用所选供应商</n-button>
    </n-space>
  </template>
</ProSelect>

Expose

import type { ProSelectInst } from '@coderych/naive-ui-pro-components'

const selectRef = ref<ProSelectInst<User> | null>(null)

selectRef.value?.focus()
selectRef.value?.select?.blur()
await selectRef.value?.table?.reload()
selectRef.value?.popup?.mergedClsPrefix
console.log(selectRef.value?.selectedKeys)
console.log(selectRef.value?.selectedRows)

字段	说明
select	`NSelect` 实例
table	`ProTable` 实例，包含增强 API 与 `NDataTable` API
popup	`ProPopup` 转发的 `NModal` 或 `NDrawer` 实例
selectedKeys	当前已确认 keys
selectedRows	当前已确认完整 rows

组件本身也直接转发 SelectInst 的 focus、blur、focusInput 和 blurInput。

国际化

入口按钮默认读取 selectText，Popup 确认和取消读取 okText、cancelText。buttonText、popupProps.okText 和 popupProps.cancelText 的优先级更高。切换 createProConfig 使用的响应式语言后，默认按钮文案会同步更新。

注意事项

每条数据必须在 valueField 上提供稳定的 string | number，无有效 key 的数据不会进入 options。
默认值补全接口可以只返回找到的 rows；未返回的 key 不会导致组件报错。
Popup 模式的确认是同步状态提交；业务保存应在外部监听 change 后处理。
关闭 Popup 会使当前请求结果失效，旧搜索、旧补全和旧表格请求都不能覆盖最新状态。
requestParams 或 pageSize 在组件打开期间变化时，会自动从第一页重新查询。

ProSelect 高级选择器

适用场景

基础用法

下拉单选

下拉单选、远程搜索与滚动分页

下拉多选

下拉多选

Modal + ProTable 单选

ProPopup 多选（Drawer）

Drawer + ProTable 跨页多选

默认值和外部动态修改

默认值与外部值变化

本地选项

本地选项单选与多选

自定义请求参数

requestParams、searchField 与 pageFields

自定义 Slots

button、popup-header、popup-footer 与 empty 插槽

实例方法与 Expose

实例方法调用与状态读取

禁用与按钮配置

disabled、buttonText、buttonProps 与 size/status

请求错误处理

request-error 事件

request 协议

数据流

ProPopup

options 管理

Props

Events

Slots

Expose

国际化

注意事项

ProSelect 高级选择器 ​

适用场景 ​

基础用法 ​

下拉单选 ​

下拉单选、远程搜索与滚动分页

下拉多选 ​

下拉多选

ProPopup 单选（Modal） ​

Modal + ProTable 单选

ProPopup 多选（Drawer） ​

Drawer + ProTable 跨页多选

默认值和外部动态修改 ​

默认值与外部值变化

本地选项 ​

本地选项单选与多选

自定义请求参数 ​

requestParams、searchField 与 pageFields

自定义 Slots ​

button、popup-header、popup-footer 与 empty 插槽

实例方法与 Expose ​

实例方法调用与状态读取

禁用与按钮配置 ​

disabled、buttonText、buttonProps 与 size/status

请求错误处理 ​

request-error 事件

request 协议 ​

数据流 ​

Dropdown ​

ProPopup ​

options 管理 ​

Props ​

Events ​

Slots ​

Expose ​

国际化 ​

注意事项 ​

ProSelect 高级选择器

适用场景

基础用法

下拉单选

下拉多选

ProPopup 单选（Modal）

ProPopup 多选（Drawer）

默认值和外部动态修改

本地选项

自定义请求参数

自定义 Slots

实例方法与 Expose

禁用与按钮配置

请求错误处理

request 协议

数据流

Dropdown

ProPopup

options 管理

Props

Events

Slots

Expose

国际化

注意事项