@antsoo-lib/core 2.0.5 → 3.0.1

package/src/SSelectPage/index.vue

@@ -1,607 +1,607 @@
-<script lang="ts" setup>
-import { Divider, Pagination, Select, SelectOption } from '@antsoo-lib/components'
-import type { SelectProps } from '@antsoo-lib/components'
-import type { AnyObject } from '@antsoo-lib/shared'
-import { debounce, isEqual } from 'lodash-es'
-
-import { computed, defineComponent, nextTick, reactive, ref, watch } from 'vue'
-
-// 请求基础配置
-interface RequestConfig {
-  method?: 'GET' | 'POST'
-  url: string
-  headers?: Record<string, string>
-  params?: AnyObject
-  data?: AnyObject
-}
-
-// 外部注入请求函数类型
-type Requester = (
-  config: Required<Pick<RequestConfig, 'method' | 'url'>> & RequestConfig,
-) => Promise<any>
-
-// 组件 API 配置
-interface ApiConfig extends RequestConfig {
-  request?: Requester
-}
-
-// 数据映射配置
-interface DataMapping {
-  list?: string
-  total?: string
-  value?: string
-  label?: string
-}
-
-// 分页配置
-interface PaginationConfig {
-  pageField?: string
-  pageSizeField?: string
-  searchField?: string
-  searchContains?: string
-}
-
-// 组件 Props
-interface Props extends /* @vue-ignore */ Omit<SelectProps, 'options' | 'loading'> {
-  placeholder?: string
-  allowClear?: boolean
-  showSearch?: boolean
-  disabled?: boolean
-  maxTagCount?: 'responsive' | number
-  size?: 'large' | 'middle' | 'small'
-  mode?: 'multiple' | 'tags'
-  value?: any
-  api: ApiConfig
-  dataMapping?: DataMapping
-  pagination?: boolean
-  paginationConfig?: PaginationConfig
-  pageSize?: number
-  searchDelay?: number
-  extraParams?: AnyObject
-  params?: AnyObject
-  transformData?: (data: any) => any
-  autoLoad?: boolean
-  attr?: Record<string, string>
-}
-
-type OptionItem = Record<string, unknown> & { disabled?: boolean }
-type SelectValue = SelectProps['value']
-type RequestPayload = Required<Pick<RequestConfig, 'method' | 'url'>> & RequestConfig
-interface ResponseProcessResult {
-  listData: OptionItem[]
-  totalCount: number
-  shouldDisablePagination: boolean
-}
-interface ExposedMethods {
-  reload: () => void
-  fetchData: () => Promise<void> | void
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  pagination: true,
-  pageSize: 10,
-  searchDelay: 300,
-  extraParams: () => ({}),
-  params: () => ({}),
-  autoLoad: true,
-  allowClear: true,
-  showSearch: true,
-  placeholder: '请选择',
-  maxTagCount: 1,
-})
-
-const emit = defineEmits<{
-  change: [value: any, option: any, allOptions: any]
-  search: [value: string]
-  clear: []
-  'update:value': [value: any]
-}>()
-
-const selectedValue = ref<SelectValue>()
-const loading = ref(false)
-const options = ref<OptionItem[]>([])
-const currentPage = ref(1)
-const total = ref(0)
-const searchKeyword = ref('')
-const selectRef = ref<{ focus?: () => void } | null>(null)
-const isSearching = ref(false)
-const dynamicPagination = ref(true)
-let lastRequestId = 0
-
-// 临时查询参数（用于回显时按 value 拉取选项）
-const seekParams = reactive<AnyObject>({})
-
-const mergedDataMapping = computed<Required<DataMapping>>(() => {
-  const defaultMapping: Required<DataMapping> = {
-    list: 'list',
-    total: 'total',
-    value: 'id',
-    label: 'name',
-  }
-  if (!props.dataMapping) return defaultMapping
-  return {
-    list: props.dataMapping.list ?? defaultMapping.list,
-    total: props.dataMapping.total ?? defaultMapping.total,
-    value: props.dataMapping.value ?? defaultMapping.value,
-    label: props.dataMapping.label ?? defaultMapping.label,
-  }
-})
-
-const mergedPaginationConfig = computed<Required<PaginationConfig>>(() => {
-  const defaultPaginationConfig: Required<PaginationConfig> = {
-    pageField: 'pageNum',
-    pageSizeField: 'pageSize',
-    searchField: 'keyword',
-    searchContains: '',
-  }
-  if (!props.paginationConfig) return defaultPaginationConfig
-  return {
-    pageField: props.paginationConfig.pageField ?? defaultPaginationConfig.pageField,
-    pageSizeField: props.paginationConfig.pageSizeField ?? defaultPaginationConfig.pageSizeField,
-    searchField: props.paginationConfig.searchField ?? defaultPaginationConfig.searchField,
-    searchContains: props.paginationConfig.searchContains ?? defaultPaginationConfig.searchContains,
-  }
-})
-
-const requestParams = computed(() => {
-  const params: AnyObject = {}
-  if (props.pagination && dynamicPagination.value) {
-    params[mergedPaginationConfig.value.pageField] = currentPage.value
-    params[mergedPaginationConfig.value.pageSizeField] = props.pageSize
-  }
-
-  const allParams = {
-    ...props.extraParams,
-    ...props.params,
-    ...seekParams,
-  }
-
-  if (searchKeyword.value && mergedPaginationConfig.value.searchField) {
-    allParams[mergedPaginationConfig.value.searchField] = searchKeyword.value
-  }
-
-  return {
-    ...params,
-    ...allParams,
-  }
-})
-
-/**
- * 获取嵌套路径值
- * @param obj 源对象
- * @param path 使用点号分隔的路径
- */
-const getNestedValue = (obj: unknown, path: string): any => {
-  const source = (obj ?? {}) as AnyObject
-  return path.split('.').reduce((current: AnyObject, key: string) => current?.[key], source)
-}
-
-const getOptionValue = (item: any) => {
-  return getNestedValue(item, mergedDataMapping.value.value)
-}
-
-const getOptionLabel = (item: any) => {
-  return getNestedValue(item, mergedDataMapping.value.label)
-}
-
-/**
- * 处理后端响应结构，统一抽取列表与总数，并判断是否需要关闭分页
- * @param data 响应数据
- */
-const processResponseData = (data: unknown): ResponseProcessResult => {
-  if (!data || typeof data !== 'object') {
-    return { listData: [], totalCount: 0, shouldDisablePagination: true }
-  }
-
-  if ('code' in data && 'data' in data) {
-    const actualData = data.data
-    if (actualData && typeof actualData === 'object' && 'list' in actualData) {
-      const listData = actualData.list
-      if (Array.isArray(listData) && listData.length > 0) {
-        const totalCount = mergedDataMapping.value.total
-          ? getNestedValue(actualData, mergedDataMapping.value.total)
-          : listData.length
-        return { listData, totalCount, shouldDisablePagination: false }
-      }
-    }
-
-    if (Array.isArray(actualData)) {
-      return { listData: actualData, totalCount: actualData.length, shouldDisablePagination: true }
-    }
-
-    if (actualData && typeof actualData === 'object') {
-      const listData = mergedDataMapping.value.list
-        ? getNestedValue(actualData, mergedDataMapping.value.list)
-        : actualData
-      if (Array.isArray(listData)) {
-        const totalCount = mergedDataMapping.value.total
-          ? getNestedValue(actualData, mergedDataMapping.value.total)
-          : listData.length
-        const shouldDisablePagination =
-          !mergedDataMapping.value.list || mergedDataMapping.value.list === 'list'
-        return { listData, totalCount, shouldDisablePagination }
-      }
-    }
-
-    return { listData: [], totalCount: 0, shouldDisablePagination: true }
-  }
-
-  if ('list' in data) {
-    const listData = data.list
-    if (Array.isArray(listData) && listData.length > 0) {
-      const totalCount = mergedDataMapping.value.total
-        ? getNestedValue(data, mergedDataMapping.value.total)
-        : listData.length
-      return { listData, totalCount, shouldDisablePagination: false }
-    }
-  }
-
-  if (Array.isArray(data)) {
-    return { listData: data, totalCount: data.length, shouldDisablePagination: true }
-  }
-
-  const listData = mergedDataMapping.value.list
-    ? getNestedValue(data, mergedDataMapping.value.list)
-    : data
-  if (Array.isArray(listData)) {
-    const totalCount = mergedDataMapping.value.total
-      ? getNestedValue(data, mergedDataMapping.value.total)
-      : listData.length
-    const shouldDisablePagination =
-      !mergedDataMapping.value.list || mergedDataMapping.value.list === 'list'
-    return { listData, totalCount, shouldDisablePagination }
-  }
-
-  return { listData: [], totalCount: 0, shouldDisablePagination: true }
-}
-
-/**
- * 统一兼容 axios 风格与直返数据风格
- * @param response 请求返回值或 axios 响应对象
- */
-const normalizeRequestData = (response: unknown): unknown => {
-  if (response && typeof response === 'object' && 'data' in response) {
-    return (response as { data: unknown }).data
-  }
-  return response
-}
-
-/**
- * 发起请求并刷新选项
- */
-const fetchData = async (): Promise<void> => {
-  if (!props.api.url) return
-  if (!props.api.request || typeof props.api.request !== 'function') {
-    options.value = []
-    total.value = 0
-    dynamicPagination.value = true
-    loading.value = false
-    console.error('SSelectPage: api.request 未提供，无法发起请求')
-    return
-  }
-
-  const requestId = ++lastRequestId
-  loading.value = true
-  try {
-    const method = props.api.method || 'GET'
-    const request = props.api.request
-    const payload: RequestPayload = {
-      method,
-      url: props.api.url,
-      headers: props.api.headers || {},
-      params: { ...requestParams.value, ...props.api.params },
-      data: { ...requestParams.value, ...props.api.data },
-    }
-
-    const response = await request(payload)
-
-    let data = normalizeRequestData(response)
-    if (props.transformData) {
-      data = props.transformData(data)
-    }
-
-    const { listData, totalCount, shouldDisablePagination } = processResponseData(data)
-    if (requestId !== lastRequestId) return
-
-    options.value = listData
-    total.value = totalCount
-    dynamicPagination.value = !shouldDisablePagination
-    if (shouldDisablePagination) {
-      currentPage.value = 1
-    }
-  } catch (error) {
-    if (requestId !== lastRequestId) return
-    options.value = []
-    total.value = 0
-    dynamicPagination.value = true
-    console.error('SSelectPage 数据加载失败:', error)
-  } finally {
-    if (requestId === lastRequestId) {
-      loading.value = false
-    }
-  }
-}
-
-watch(
-  () => props.value,
-  (newValue) => {
-    let hasRequestedByValue = false
-    const canBackfillBySingleValue =
-      newValue !== undefined &&
-      newValue !== null &&
-      !Array.isArray(newValue) &&
-      typeof newValue !== 'object'
-
-    if (canBackfillBySingleValue && newValue !== selectedValue.value) {
-      const exists = Array.isArray(options.value)
-        ? options.value.some((item) => getOptionValue(item) === newValue)
-        : false
-      if (!exists) {
-        hasRequestedByValue = true
-        seekParams[`${mergedDataMapping.value.value}`] = newValue
-        fetchData().finally(() => {
-          Object.keys(seekParams).forEach((key) => {
-            delete seekParams[key]
-          })
-        })
-      }
-    }
-
-    if (!hasRequestedByValue && props.autoLoad && (!options.value || options.value.length === 0)) {
-      fetchData()
-    }
-
-    if (
-      (props.mode === 'multiple' || props.mode === 'tags') &&
-      (newValue === null || newValue === undefined)
-    ) {
-      selectedValue.value = []
-    } else {
-      selectedValue.value = newValue || undefined
-    }
-  },
-  { immediate: true },
-)
-
-/**
- * 分页变更
- */
-const handlePageChange = (page: number): void => {
-  currentPage.value = page
-  fetchData()
-}
-
-watch(
-  () => props.extraParams,
-  (newParams, oldParams) => {
-    if (!isEqual(newParams, oldParams)) {
-      currentPage.value = 1
-      fetchData()
-    }
-  },
-  {
-    deep: true,
-    immediate: false,
-  },
-)
-
-watch(
-  () => props.params,
-  (newParams, oldParams) => {
-    if (!isEqual(newParams, oldParams)) {
-      currentPage.value = 1
-      fetchData()
-    }
-  },
-  {
-    deep: true,
-    immediate: false,
-  },
-)
-
-/**
- * 防抖搜索
- */
-const debouncedSearch = debounce((keyword: string) => {
-  searchKeyword.value = keyword
-  currentPage.value = 1
-  isSearching.value = true
-  fetchData().finally(() => {
-    isSearching.value = false
-  })
-}, props.searchDelay)
-
-/**
- * 搜索事件
- */
-const handleSearch = (value: string): void => {
-  emit('search', value)
-  debouncedSearch(value)
-}
-
-/**
- * 清空选择与搜索
- */
-const handleClear = (): void => {
-  if (props.mode === 'multiple' || props.mode === 'tags') {
-    selectedValue.value = []
-    emit('update:value', [])
-  } else {
-    selectedValue.value = undefined
-    emit('update:value', undefined)
-  }
-  searchKeyword.value = ''
-  currentPage.value = 1
-  fetchData()
-  emit('clear')
-}
-
-/**
- * 下拉显隐
- */
-const handleDropdownVisibleChange = (open: boolean): void => {
-  if (open && options.value.length === 0 && props.autoLoad) {
-    fetchData()
-  }
-  if (!open && !isSearching.value) {
-    searchKeyword.value = ''
-  }
-}
-
-/**
- * 聚焦事件
- */
-const handleFocus = (): void => {
-  if (searchKeyword.value && selectRef.value) {
-    nextTick(() => {
-      if (selectRef.value && typeof selectRef.value.focus === 'function') {
-        selectRef.value.focus()
-      }
-    })
-  }
-}
-
-/**
- * 值变更并组装回传对象
- */
-const handleChange = (value: SelectValue): void => {
-  selectedValue.value = value
-
-  let safeOption: unknown = null
-  let allOptions: unknown = null
-  if (Array.isArray(value)) {
-    safeOption = value
-      .map((val) => {
-        const opt = options.value.find((item) => getOptionValue(item) === val)
-        return opt
-          ? {
-              [mergedDataMapping.value.value]: getOptionValue(opt),
-              [mergedDataMapping.value.label]: getOptionLabel(opt),
-              __raw: opt,
-            }
-          : null
-      })
-      .filter(Boolean)
-    allOptions = value
-  } else {
-    const opt = options.value.find((item) => getOptionValue(item) === value)
-    safeOption = opt
-      ? {
-          [mergedDataMapping.value.value]: getOptionValue(opt),
-          [mergedDataMapping.value.label]: getOptionLabel(opt),
-          __raw: opt,
-        }
-      : null
-    allOptions = opt
-  }
-
-  emit('update:value', value)
-  nextTick(() => {
-    emit('change', value, safeOption, allOptions)
-  })
-  searchKeyword.value = ''
-}
-
-interface SelectEvents {
-  change: (value: SelectValue) => void
-  dropdownVisibleChange: (open: boolean) => void
-  clear: () => void
-  focus: () => void
-  search?: (value: string) => void
-}
-
-/**
- * 选择组件事件映射
- */
-const selectEvents = computed<SelectEvents>(() => {
-  const ev: SelectEvents = {
-    change: handleChange,
-    dropdownVisibleChange: handleDropdownVisibleChange,
-    clear: handleClear,
-    focus: handleFocus,
-  }
-  if (props.showSearch) ev.search = handleSearch
-  return ev
-})
-
-/**
- * 重新加载并重置分页与搜索
- */
-const reload = (): void => {
-  currentPage.value = 1
-  searchKeyword.value = ''
-  fetchData()
-}
-
-// 用于渲染 dropdownRender 的原始 VNode
-const VNodes = defineComponent({
-  name: 'VNodes',
-  props: {
-    vnodes: {
-      type: [Object, Array],
-      default: null,
-    },
-  },
-  setup(_props) {
-    return () => _props.vnodes as any
-  },
-})
-
-defineExpose<ExposedMethods>({
-  reload,
-  fetchData,
-})
-</script>
-
-<template>
-  <Select
-    ref="selectRef"
-    v-bind="$attrs"
-    v-model:value="selectedValue"
-    :mode="mode"
-    :placeholder="placeholder"
-    :loading="loading"
-    :disabled="disabled"
-    :allow-clear="allowClear"
-    :show-search="showSearch"
-    :filter-option="false"
-    :max-tag-count="maxTagCount"
-    v-on="selectEvents"
-  >
-    <SelectOption
-      v-for="item in options"
-      :key="getOptionValue(item)"
-      :value="getOptionValue(item)"
-      :disabled="item.disabled"
-    >
-      {{ getOptionLabel(item) }}
-    </SelectOption>
-    <template #dropdownRender="{ menuNode }">
-      <div>
-        <VNodes :vnodes="menuNode" />
-        <template v-if="props.pagination && dynamicPagination && options.length > 0">
-          <Divider style="margin: 4px 0" />
-          <div style="padding: 8px; text-align: center">
-            <Pagination
-              :current="currentPage"
-              :total="total"
-              :page-size="pageSize"
-              size="small"
-              :show-size-changer="false"
-              :show-less-items="true"
-              @change="handlePageChange"
-            />
-          </div>
-        </template>
-      </div>
-    </template>
-  </Select>
-</template>
-
-<style lang="scss" scoped>
-:deep(.ant-select-dropdown) {
-  .ant-pagination {
-    margin: 0;
-  }
-}
-</style>
+<script lang="ts" setup>
+import { Divider, Pagination, Select, SelectOption } from '@antsoo-lib/components'
+import type { SelectProps } from '@antsoo-lib/components'
+import type { AnyObject } from '@antsoo-lib/shared'
+import { debounce, isEqual } from 'lodash-es'
+
+import { computed, defineComponent, nextTick, reactive, ref, watch } from 'vue'
+
+// 请求基础配置
+interface RequestConfig {
+  method?: 'GET' | 'POST'
+  url: string
+  headers?: Record<string, string>
+  params?: AnyObject
+  data?: AnyObject
+}
+
+// 外部注入请求函数类型
+type Requester = (
+  config: Required<Pick<RequestConfig, 'method' | 'url'>> & RequestConfig,
+) => Promise<any>
+
+// 组件 API 配置
+interface ApiConfig extends RequestConfig {
+  request?: Requester
+}
+
+// 数据映射配置
+interface DataMapping {
+  list?: string
+  total?: string
+  value?: string
+  label?: string
+}
+
+// 分页配置
+interface PaginationConfig {
+  pageField?: string
+  pageSizeField?: string
+  searchField?: string
+  searchContains?: string
+}
+
+// 组件 Props
+interface Props extends /* @vue-ignore */ Omit<SelectProps, 'options' | 'loading'> {
+  placeholder?: string
+  allowClear?: boolean
+  showSearch?: boolean
+  disabled?: boolean
+  maxTagCount?: 'responsive' | number
+  size?: 'large' | 'middle' | 'small'
+  mode?: 'multiple' | 'tags'
+  value?: any
+  api: ApiConfig
+  dataMapping?: DataMapping
+  pagination?: boolean
+  paginationConfig?: PaginationConfig
+  pageSize?: number
+  searchDelay?: number
+  extraParams?: AnyObject
+  params?: AnyObject
+  transformData?: (data: any) => any
+  autoLoad?: boolean
+  attr?: Record<string, string>
+}
+
+type OptionItem = Record<string, unknown> & { disabled?: boolean }
+type SelectValue = SelectProps['value']
+type RequestPayload = Required<Pick<RequestConfig, 'method' | 'url'>> & RequestConfig
+interface ResponseProcessResult {
+  listData: OptionItem[]
+  totalCount: number
+  shouldDisablePagination: boolean
+}
+interface ExposedMethods {
+  reload: () => void
+  fetchData: () => Promise<void> | void
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  pagination: true,
+  pageSize: 10,
+  searchDelay: 300,
+  extraParams: () => ({}),
+  params: () => ({}),
+  autoLoad: true,
+  allowClear: true,
+  showSearch: true,
+  placeholder: '请选择',
+  maxTagCount: 1,
+})
+
+const emit = defineEmits<{
+  change: [value: any, option: any, allOptions: any]
+  search: [value: string]
+  clear: []
+  'update:value': [value: any]
+}>()
+
+const selectedValue = ref<SelectValue>()
+const loading = ref(false)
+const options = ref<OptionItem[]>([])
+const currentPage = ref(1)
+const total = ref(0)
+const searchKeyword = ref('')
+const selectRef = ref<{ focus?: () => void } | null>(null)
+const isSearching = ref(false)
+const dynamicPagination = ref(true)
+let lastRequestId = 0
+
+// 临时查询参数（用于回显时按 value 拉取选项）
+const seekParams = reactive<AnyObject>({})
+
+const mergedDataMapping = computed<Required<DataMapping>>(() => {
+  const defaultMapping: Required<DataMapping> = {
+    list: 'list',
+    total: 'total',
+    value: 'id',
+    label: 'name',
+  }
+  if (!props.dataMapping) return defaultMapping
+  return {
+    list: props.dataMapping.list ?? defaultMapping.list,
+    total: props.dataMapping.total ?? defaultMapping.total,
+    value: props.dataMapping.value ?? defaultMapping.value,
+    label: props.dataMapping.label ?? defaultMapping.label,
+  }
+})
+
+const mergedPaginationConfig = computed<Required<PaginationConfig>>(() => {
+  const defaultPaginationConfig: Required<PaginationConfig> = {
+    pageField: 'pageNum',
+    pageSizeField: 'pageSize',
+    searchField: 'keyword',
+    searchContains: '',
+  }
+  if (!props.paginationConfig) return defaultPaginationConfig
+  return {
+    pageField: props.paginationConfig.pageField ?? defaultPaginationConfig.pageField,
+    pageSizeField: props.paginationConfig.pageSizeField ?? defaultPaginationConfig.pageSizeField,
+    searchField: props.paginationConfig.searchField ?? defaultPaginationConfig.searchField,
+    searchContains: props.paginationConfig.searchContains ?? defaultPaginationConfig.searchContains,
+  }
+})
+
+const requestParams = computed(() => {
+  const params: AnyObject = {}
+  if (props.pagination && dynamicPagination.value) {
+    params[mergedPaginationConfig.value.pageField] = currentPage.value
+    params[mergedPaginationConfig.value.pageSizeField] = props.pageSize
+  }
+
+  const allParams = {
+    ...props.extraParams,
+    ...props.params,
+    ...seekParams,
+  }
+
+  if (searchKeyword.value && mergedPaginationConfig.value.searchField) {
+    allParams[mergedPaginationConfig.value.searchField] = searchKeyword.value
+  }
+
+  return {
+    ...params,
+    ...allParams,
+  }
+})
+
+/**
+ * 获取嵌套路径值
+ * @param obj 源对象
+ * @param path 使用点号分隔的路径
+ */
+const getNestedValue = (obj: unknown, path: string): any => {
+  const source = (obj ?? {}) as AnyObject
+  return path.split('.').reduce((current: AnyObject, key: string) => current?.[key], source)
+}
+
+const getOptionValue = (item: any) => {
+  return getNestedValue(item, mergedDataMapping.value.value)
+}
+
+const getOptionLabel = (item: any) => {
+  return getNestedValue(item, mergedDataMapping.value.label)
+}
+
+/**
+ * 处理后端响应结构，统一抽取列表与总数，并判断是否需要关闭分页
+ * @param data 响应数据
+ */
+const processResponseData = (data: unknown): ResponseProcessResult => {
+  if (!data || typeof data !== 'object') {
+    return { listData: [], totalCount: 0, shouldDisablePagination: true }
+  }
+
+  if ('code' in data && 'data' in data) {
+    const actualData = data.data
+    if (actualData && typeof actualData === 'object' && 'list' in actualData) {
+      const listData = actualData.list
+      if (Array.isArray(listData) && listData.length > 0) {
+        const totalCount = mergedDataMapping.value.total
+          ? getNestedValue(actualData, mergedDataMapping.value.total)
+          : listData.length
+        return { listData, totalCount, shouldDisablePagination: false }
+      }
+    }
+
+    if (Array.isArray(actualData)) {
+      return { listData: actualData, totalCount: actualData.length, shouldDisablePagination: true }
+    }
+
+    if (actualData && typeof actualData === 'object') {
+      const listData = mergedDataMapping.value.list
+        ? getNestedValue(actualData, mergedDataMapping.value.list)
+        : actualData
+      if (Array.isArray(listData)) {
+        const totalCount = mergedDataMapping.value.total
+          ? getNestedValue(actualData, mergedDataMapping.value.total)
+          : listData.length
+        const shouldDisablePagination =
+          !mergedDataMapping.value.list || mergedDataMapping.value.list === 'list'
+        return { listData, totalCount, shouldDisablePagination }
+      }
+    }
+
+    return { listData: [], totalCount: 0, shouldDisablePagination: true }
+  }
+
+  if ('list' in data) {
+    const listData = data.list
+    if (Array.isArray(listData) && listData.length > 0) {
+      const totalCount = mergedDataMapping.value.total
+        ? getNestedValue(data, mergedDataMapping.value.total)
+        : listData.length
+      return { listData, totalCount, shouldDisablePagination: false }
+    }
+  }
+
+  if (Array.isArray(data)) {
+    return { listData: data, totalCount: data.length, shouldDisablePagination: true }
+  }
+
+  const listData = mergedDataMapping.value.list
+    ? getNestedValue(data, mergedDataMapping.value.list)
+    : data
+  if (Array.isArray(listData)) {
+    const totalCount = mergedDataMapping.value.total
+      ? getNestedValue(data, mergedDataMapping.value.total)
+      : listData.length
+    const shouldDisablePagination =
+      !mergedDataMapping.value.list || mergedDataMapping.value.list === 'list'
+    return { listData, totalCount, shouldDisablePagination }
+  }
+
+  return { listData: [], totalCount: 0, shouldDisablePagination: true }
+}
+
+/**
+ * 统一兼容 axios 风格与直返数据风格
+ * @param response 请求返回值或 axios 响应对象
+ */
+const normalizeRequestData = (response: unknown): unknown => {
+  if (response && typeof response === 'object' && 'data' in response) {
+    return (response as { data: unknown }).data
+  }
+  return response
+}
+
+/**
+ * 发起请求并刷新选项
+ */
+const fetchData = async (): Promise<void> => {
+  if (!props.api.url) return
+  if (!props.api.request || typeof props.api.request !== 'function') {
+    options.value = []
+    total.value = 0
+    dynamicPagination.value = true
+    loading.value = false
+    console.error('SSelectPage: api.request 未提供，无法发起请求')
+    return
+  }
+
+  const requestId = ++lastRequestId
+  loading.value = true
+  try {
+    const method = props.api.method || 'GET'
+    const request = props.api.request
+    const payload: RequestPayload = {
+      method,
+      url: props.api.url,
+      headers: props.api.headers || {},
+      params: { ...requestParams.value, ...props.api.params },
+      data: { ...requestParams.value, ...props.api.data },
+    }
+
+    const response = await request(payload)
+
+    let data = normalizeRequestData(response)
+    if (props.transformData) {
+      data = props.transformData(data)
+    }
+
+    const { listData, totalCount, shouldDisablePagination } = processResponseData(data)
+    if (requestId !== lastRequestId) return
+
+    options.value = listData
+    total.value = totalCount
+    dynamicPagination.value = !shouldDisablePagination
+    if (shouldDisablePagination) {
+      currentPage.value = 1
+    }
+  } catch (error) {
+    if (requestId !== lastRequestId) return
+    options.value = []
+    total.value = 0
+    dynamicPagination.value = true
+    console.error('SSelectPage 数据加载失败:', error)
+  } finally {
+    if (requestId === lastRequestId) {
+      loading.value = false
+    }
+  }
+}
+
+watch(
+  () => props.value,
+  (newValue) => {
+    let hasRequestedByValue = false
+    const canBackfillBySingleValue =
+      newValue !== undefined &&
+      newValue !== null &&
+      !Array.isArray(newValue) &&
+      typeof newValue !== 'object'
+
+    if (canBackfillBySingleValue && newValue !== selectedValue.value) {
+      const exists = Array.isArray(options.value)
+        ? options.value.some((item) => getOptionValue(item) === newValue)
+        : false
+      if (!exists) {
+        hasRequestedByValue = true
+        seekParams[`${mergedDataMapping.value.value}`] = newValue
+        fetchData().finally(() => {
+          Object.keys(seekParams).forEach((key) => {
+            delete seekParams[key]
+          })
+        })
+      }
+    }
+
+    if (!hasRequestedByValue && props.autoLoad && (!options.value || options.value.length === 0)) {
+      fetchData()
+    }
+
+    if (
+      (props.mode === 'multiple' || props.mode === 'tags') &&
+      (newValue === null || newValue === undefined)
+    ) {
+      selectedValue.value = []
+    } else {
+      selectedValue.value = newValue || undefined
+    }
+  },
+  { immediate: true },
+)
+
+/**
+ * 分页变更
+ */
+const handlePageChange = (page: number): void => {
+  currentPage.value = page
+  fetchData()
+}
+
+watch(
+  () => props.extraParams,
+  (newParams, oldParams) => {
+    if (!isEqual(newParams, oldParams)) {
+      currentPage.value = 1
+      fetchData()
+    }
+  },
+  {
+    deep: true,
+    immediate: false,
+  },
+)
+
+watch(
+  () => props.params,
+  (newParams, oldParams) => {
+    if (!isEqual(newParams, oldParams)) {
+      currentPage.value = 1
+      fetchData()
+    }
+  },
+  {
+    deep: true,
+    immediate: false,
+  },
+)
+
+/**
+ * 防抖搜索
+ */
+const debouncedSearch = debounce((keyword: string) => {
+  searchKeyword.value = keyword
+  currentPage.value = 1
+  isSearching.value = true
+  fetchData().finally(() => {
+    isSearching.value = false
+  })
+}, props.searchDelay)
+
+/**
+ * 搜索事件
+ */
+const handleSearch = (value: string): void => {
+  emit('search', value)
+  debouncedSearch(value)
+}
+
+/**
+ * 清空选择与搜索
+ */
+const handleClear = (): void => {
+  if (props.mode === 'multiple' || props.mode === 'tags') {
+    selectedValue.value = []
+    emit('update:value', [])
+  } else {
+    selectedValue.value = undefined
+    emit('update:value', undefined)
+  }
+  searchKeyword.value = ''
+  currentPage.value = 1
+  fetchData()
+  emit('clear')
+}
+
+/**
+ * 下拉显隐
+ */
+const handleDropdownVisibleChange = (open: boolean): void => {
+  if (open && options.value.length === 0 && props.autoLoad) {
+    fetchData()
+  }
+  if (!open && !isSearching.value) {
+    searchKeyword.value = ''
+  }
+}
+
+/**
+ * 聚焦事件
+ */
+const handleFocus = (): void => {
+  if (searchKeyword.value && selectRef.value) {
+    nextTick(() => {
+      if (selectRef.value && typeof selectRef.value.focus === 'function') {
+        selectRef.value.focus()
+      }
+    })
+  }
+}
+
+/**
+ * 值变更并组装回传对象
+ */
+const handleChange = (value: SelectValue): void => {
+  selectedValue.value = value
+
+  let safeOption: unknown = null
+  let allOptions: unknown = null
+  if (Array.isArray(value)) {
+    safeOption = value
+      .map((val) => {
+        const opt = options.value.find((item) => getOptionValue(item) === val)
+        return opt
+          ? {
+              [mergedDataMapping.value.value]: getOptionValue(opt),
+              [mergedDataMapping.value.label]: getOptionLabel(opt),
+              __raw: opt,
+            }
+          : null
+      })
+      .filter(Boolean)
+    allOptions = value
+  } else {
+    const opt = options.value.find((item) => getOptionValue(item) === value)
+    safeOption = opt
+      ? {
+          [mergedDataMapping.value.value]: getOptionValue(opt),
+          [mergedDataMapping.value.label]: getOptionLabel(opt),
+          __raw: opt,
+        }
+      : null
+    allOptions = opt
+  }
+
+  emit('update:value', value)
+  nextTick(() => {
+    emit('change', value, safeOption, allOptions)
+  })
+  searchKeyword.value = ''
+}
+
+interface SelectEvents {
+  change: (value: SelectValue) => void
+  dropdownVisibleChange: (open: boolean) => void
+  clear: () => void
+  focus: () => void
+  search?: (value: string) => void
+}
+
+/**
+ * 选择组件事件映射
+ */
+const selectEvents = computed<SelectEvents>(() => {
+  const ev: SelectEvents = {
+    change: handleChange,
+    dropdownVisibleChange: handleDropdownVisibleChange,
+    clear: handleClear,
+    focus: handleFocus,
+  }
+  if (props.showSearch) ev.search = handleSearch
+  return ev
+})
+
+/**
+ * 重新加载并重置分页与搜索
+ */
+const reload = (): void => {
+  currentPage.value = 1
+  searchKeyword.value = ''
+  fetchData()
+}
+
+// 用于渲染 dropdownRender 的原始 VNode
+const VNodes = defineComponent({
+  name: 'VNodes',
+  props: {
+    vnodes: {
+      type: [Object, Array],
+      default: null,
+    },
+  },
+  setup(_props) {
+    return () => _props.vnodes as any
+  },
+})
+
+defineExpose<ExposedMethods>({
+  reload,
+  fetchData,
+})
+</script>
+
+<template>
+  <Select
+    ref="selectRef"
+    v-bind="$attrs"
+    v-model:value="selectedValue"
+    :mode="mode"
+    :placeholder="placeholder"
+    :loading="loading"
+    :disabled="disabled"
+    :allow-clear="allowClear"
+    :show-search="showSearch"
+    :filter-option="false"
+    :max-tag-count="maxTagCount"
+    v-on="selectEvents"
+  >
+    <SelectOption
+      v-for="item in options"
+      :key="getOptionValue(item)"
+      :value="getOptionValue(item)"
+      :disabled="item.disabled"
+    >
+      {{ getOptionLabel(item) }}
+    </SelectOption>
+    <template #dropdownRender="{ menuNode }">
+      <div>
+        <VNodes :vnodes="menuNode" />
+        <template v-if="props.pagination && dynamicPagination && options.length > 0">
+          <Divider style="margin: 4px 0" />
+          <div style="padding: 8px; text-align: center">
+            <Pagination
+              :current="currentPage"
+              :total="total"
+              :page-size="pageSize"
+              size="small"
+              :show-size-changer="false"
+              :show-less-items="true"
+              @change="handlePageChange"
+            />
+          </div>
+        </template>
+      </div>
+    </template>
+  </Select>
+</template>
+
+<style lang="scss" scoped>
+:deep(.ant-select-dropdown) {
+  .ant-pagination {
+    margin: 0;
+  }
+}
+</style>