web-component-gallery 2.3.33 → 2.3.35

package/lib/form-comp/ASelectCustom.vue

@@ -1,18 +1,13 @@
 <template>
-  <!-- 自定义选择器组件，支持分页加载、搜索等功能 -->
-  <div
-    @mousedown="handleMouseDown"
-    ref="main"
-    class="ASelectCustom"
-  >
+  <!-- 自定义选择器组件 - 支持单选/多选/tags三种模式 -->
+  <div @mousedown="handleMouseDown" ref="main" class="ASelectCustom">
     <Select
       :style="{ width: width || '100%' }"
-      :mode="mode" 
-      :open="isSelectOpen"
+      :mode="mode"
       :placeholder="placeholder"
       :getPopupContainer="getPopupContainer"
       @select="handleSelect"
-      @search="debouncedSearch"
+      @search="handleSearchInput"
       @change="handleChange"
       @popupScroll="handleScroll"
       v-bind="selectAttrs"
@@ -27,19 +22,19 @@
         <slot :name="name" v-bind="data" />
       </template> 
       
-      <!-- 下拉菜单渲染 -->
+      <!-- 下拉菜单自定义渲染 -->
       <div slot="dropdownRender" slot-scope="menu">
-        <!-- 多选模式下的全选按钮 -->
+        <!-- 全选按钮：仅多选模式显示 -->
         <Checkbox 
-          v-if="isMultipleMode" 
+          v-if="isMultiple && !isTags"
           :checked="isCheckedAll" 
           @change="handleSelectAll"
         >
           全选
         </Checkbox>
         <v-nodes :vnodes="menu" />
-        <!-- 加载状态提示 -->
-        <div v-if="isLoadingMore" class="loading-more">
+        <!-- 加载更多提示：仅分页模式显示 -->
+        <div v-if="isLoadingMore && needPagination" class="loading-more">
           <Icon type="loading" />
           加载中...
         </div>
@@ -74,237 +69,142 @@ export default {
     Checkbox
   },
   
-  /**
-   * 组件属性定义
-   * 包含基础配置、数据映射、数据源和分页配置
-   */
   props: {
-    // 基础配置
-    value: {
-      type: [String, Number, Array, Boolean, Object],
-      default: undefined
-    },
-    mode: String,
+    // ========== 基础配置 ==========
+    value: [String, Number, Array, Boolean, Object],
+    mode: String, // (默认单选) | 'multiple' | 'tags'
     width: String,
-    isInput: {
-      type: Boolean,
-      default: false
-    },
-    placeholder: {
-      type: String,
-      default: '请选择'
-    },
+    isInput: { type: Boolean, default: false }, // 是否允许手动输入
+    placeholder: { type: String, default: '请选择' },
 
-    // 数据映射 - 定义数据字段的键名
-    valueKey: {
-      type: String,
-      default: 'value'
-    },
-    labelKey: {
-      type: String,
-      default: 'label' 
-    },
-    customLabel: String,
+    // ========== 数据映射 ==========
+    valueKey: { type: String, default: 'value' },
+    labelKey: { type: String, default: 'label' },
+    customLabel: String, // 自定义标签模板，如 '{{name}} - {{code}}'
 
-    // 数据源 - 静态选项或动态处理器
-    options: {
-      type: Array,
-      default: () => []
-    },
-    initLoad: {
-      type: Boolean,
-      default: true
-    },
-    autoClearSearchValue: {
-      type: Boolean,
-      default: true
-    },
-    listPageParams: Object,
-    listPageHandler: Function,
+    // ========== 数据源配置 ==========
+    options: { type: Array, default: () => [] }, // 静态选项
+    initLoad: { type: Boolean, default: true }, // 是否初始化加载
+    autoClearSearchValue: { type: Boolean, default: true }, // 关闭时是否清空搜索
+    
+    // 分页数据源（动态加载）
+    listPageParams: Object, // 额外请求参数
+    listPageHandler: Function, // 分页请求函数
 
-    // 分页配置
-    pSize: {
-      type: Number,
-      default: 50
-    },
-    searchKey: {
-      type: String,
-      default: 'keyword'
-    }
+    // ========== 分页配置 ==========
+    pSize: { type: Number, default: 50 }, // 每页数量
+    searchKey: { type: String, default: 'keyword' } // 搜索参数名
   },
   
-  /**
-   * 组件内部数据
-   * 包含分页状态、当前数据和UI状态
-   */
   data() {
     return {
-      // 分页状态管理
-      pagination: {
-        current: 1,
-        size: this.pSize,
-        total: 0
-      },
-
-      // 选项数据
-      innerOptions: [],
-      
-      // UI交互状态
-      isInitialized: false,      // 是否已初始化
-      isSelectOpen: false,       // 选择器是否打开
-      isLoadingMore: false,      // 是否正在加载更多
-      searchValue: '',           // 搜索值
-      hasPreloadedSelected: false, // 是否已预加载选中项
-      prevOptionsHash: null      // 上次 options 的哈希值（用于防抖）
+      pagination: { current: 1, size: this.pSize, total: 0 },
+      innerOptions: [], // 内部选项列表
+      isInitialized: false, // 是否已初始化
+      isSelectOpen: false, // 下拉框是否打开
+      isLoadingMore: false, // 是否正在加载更多
+      searchValue: '', // 当前搜索值
+      hasPreloadedSelected: false // 是否已预加载选中项
     }
   },
   
-  /**
-   * 计算属性
-   * 提供响应式的数据计算
-   */
   computed: {
-    // 内部值管理
+    // 双向绑定
     innerValue: {
-      get() {
-        return this.value
-      },
-      set(val) {
-        this.$emit('input', val)
-      }
+      get() { return this.value || undefined },
+      set(val) { this.$emit('input', val) }
     },
     
-    // 选择器属性配置
-    selectAttrs() { 
-      return {
+    // 模式判断
+    isTags() { return this.mode === 'tags' },
+    isMultiple() { return !!this.mode }, // multiple 或 tags 都为多选
+    
+    // 是否需要分页加载
+    needPagination() { return !!this.listPageHandler },
+  
+    // Select组件属性配置
+    selectAttrs() {
+      const attrs = {
         allowClear: true,
         showSearch: true,
-        // 多选、标签模式下默认最多显示3个Tag
-        // maxTagCount: 3,
-        defaultActiveFirstOption: !this.isInput,
-        filterOption: this.shouldUseLocalFilter,
+        defaultActiveFirstOption: !this.isInput && !this.isTags,
+        filterOption: this.needPagination ? false : this.filterOption,
         ...this.$attrs
       }
-    },
-    
-    // 是否使用本地过滤
-    shouldUseLocalFilter() {
-      return !this.listPageHandler ? this.filterOption : false
-    },
-    
-    // 是否为多选模式
-    isMultipleMode() {
-      return !!this.mode
+      // tags模式不控制open状态
+      if (!this.isTags) attrs.open = this.isSelectOpen
+      return attrs
     },
     
     // 是否还有更多数据
-    hasMore() {
-      return this.innerOptions.length < this.pagination.total
-    },
+    hasMore() { return this.innerOptions.length < this.pagination.total },
     
-    // 全选状态
+    // 全选状态判断
     isCheckedAll() {
-      return this.innerValue?.length === this.innerOptions?.length
+      if (!this.innerValue?.length && !this.innerOptions?.length) return false
+      return this.innerValue?.length === this.innerOptions?.length && this.innerOptions?.length > 0
     }
   },
   
-  /**
-   * 数据监听器
-   * 响应数据变化并执行相应逻辑
-   */
   watch: {
     // 监听静态选项变化
-    options: {
-      handler: 'handleOptionsChange',
-      immediate: true
-    },
-    
-    // 监听选择器开关状态
-    isSelectOpen: 'handleSelectOpenChange',
-    
-    // 监听分页参数变化
-    listPageParams: {
-      handler: 'resetRequest',
-      deep: true
-    },
-    
-    // 监听分页处理器变化
-    listPageHandler: {
-      handler: 'resetRequest',
-      deep: true
-    },
-    
-    // 监听value变化 - 优先加载已选数据
-    value: {
-      handler: 'handleValueChange',
-      immediate: true
-    }
+    options: { handler: 'syncOptions', immediate: true },
+    // 监听下拉框开关
+    isSelectOpen: 'handleDropdownToggle',
+    // 监听分页参数变化，重置数据
+    listPageParams: { handler: 'resetAndFetch', deep: true },
+    listPageHandler: { handler: 'resetAndFetch', deep: true },
+    // 监听value变化，预加载选中项
+    value: { handler: 'handleValueChange', immediate: true }
   },
   
-  /**
-   * 生命周期钩子
-   */
   created() {
-    // 创建防抖函数
-    this.setupDebounceFunctions()
+    this.initDebounce()
   },
   
   mounted() {
-    this.bindGlobalEvents()
+    document.addEventListener('click', this.handleOutsideClick)
   },
   
   beforeDestroy() {
-    this.unbindGlobalEvents()
-    this.cancelDebounceFunctions()
+    document.removeEventListener('click', this.handleOutsideClick)
+    this.cancelDebounce()
   },
   
-  /**
-   * 组件方法集合
-   * 按功能分类组织方法
-   */
   methods: {
-    // ==================== 初始化相关方法 ====================
-    
-    /**
-     * 设置防抖函数
-     */
-    setupDebounceFunctions() {
-      this.debouncedSearch = debounce(this.handleSearch, 800, { leading: true, trailing: false })
-      this.debouncedLoadMore = debounce(this.loadMoreData, 300, { leading: false, trailing: true })
-    },
-    
-    /**
-     * 绑定全局事件
-     */
-    bindGlobalEvents() {
-      document.addEventListener('click', this.handleDocumentClick)
-    },
+    // ========== 初始化方法 ==========
     
     /**
-     * 解绑全局事件
+     * 初始化防抖函数
+     * 仅在需要分页时使用防抖，本地过滤无需防抖
      */
-    unbindGlobalEvents() {
-      document.removeEventListener('click', this.handleDocumentClick)
+    initDebounce() {
+      if (this.needPagination) {
+        // 远程搜索：800ms防抖
+        this.debouncedSearch = debounce(this.executeSearch, 800, { leading: true, trailing: false })
+        // 滚动加载：300ms防抖
+        this.debouncedLoadMore = debounce(this.loadMore, 300, { leading: false, trailing: true })
+      }
     },
     
     /**
-     * 取消防抖函数
+     * 取消防抖
      */
-    cancelDebounceFunctions() {
-      this.debouncedSearch?.cancel()
-      this.debouncedLoadMore?.cancel()
+    cancelDebounce() {
+      if (this.needPagination) {
+        this.debouncedSearch?.cancel()
+        this.debouncedLoadMore?.cancel()
+      }
     },
     
-    // ==================== 事件处理相关方法 ====================
+    // ========== 事件处理方法 ==========
     
     /**
-     * 鼠标按下处理
+     * 鼠标按下：打开下拉框
      */
     handleMouseDown(e) {
       e.preventDefault()
-      if (!this.$attrs.disabled) {
-        this.isSelectOpen = true
-      }
+      if (!this.$attrs.disabled) this.isSelectOpen = true
     },
     
     /**
@@ -315,200 +215,228 @@ export default {
     },
     
     /**
-     * 滚动加载更多数据
+     * 滚动到底部：加载更多
      */
     handleScroll(e) {
+      if (!this.needPagination) return
+      
       const { scrollTop, scrollHeight, clientHeight } = e.target
       const reachBottom = scrollTop + clientHeight >= scrollHeight - 10
+      
       if (reachBottom && !this.isLoadingMore && this.hasMore) {
         this.debouncedLoadMore()
       }
     },
 
     /**
-     * 值改变事件处理
+     * 值改变：清空时重置
      */
     handleChange(value) {
-      if (!value) {
-        this.resetRequest()
-      }
+      if (!value) this.resetAndFetch()
     },
 
     /**
-     * 搜索事件处理
+     * 搜索输入处理
      */
-    handleSearch(value) {
-      if (this.isInput) {
-        this.innerValue = value
-      }
+    handleSearchInput(value) {
+      // 输入模式下更新值（仅单选）
+      if (this.isInput && !this.isMultiple) this.innerValue = value
+      
       this.searchValue = value
-      this.pagination.current = 1
-      this.fetchData()
+      
+      // 分页模式：重置页码并执行远程搜索
+      if (this.needPagination) {
+        this.pagination.current = 1
+        // 执行搜索（防抖由initDebounce控制）
+        this.debouncedSearch()
+      }
     },
 
     /**
-     * 本地搜索过滤
+     * 执行搜索逻辑
+     * 分页模式：调用fetchData进行远程搜索
+     * 本地模式：无需处理，由filterOption自动过滤
+     */
+    executeSearch() {
+      if (this.needPagination) this.fetchData()
+    },
+
+    /**
+     * 本地过滤函数
      */
     filterOption(input, option) {
-      if (this.isInput) {
-        this.innerValue = input
-      }
       return option.componentOptions.children[0].text
         .toLowerCase()
         .includes(input.toLowerCase())
     },
 
     /**
-     * 点击文档关闭下拉
+     * 点击外部关闭下拉框
      */
-    handleDocumentClick(e) {
+    handleOutsideClick(e) {
       if (this.$refs.main && !this.$refs.main.contains(e.target)) {
         this.isSelectOpen = false
       }
     },
 
     /**
-     * 全选处理
+     * 全选/取消全选（仅多选模式，排除tags）
      */
     handleSelectAll({ target }) {
-      const selectOptions = target.checked
+      if (!this.isMultiple || this.isTags) return
+      
+      this.$emit('input', target.checked 
         ? this.innerOptions.map(item => item[this.valueKey])
         : []
+      )
       this.isSelectOpen = false
-      this.$emit('input', selectOptions)
     }, 
 
     /**
-     * 选中单个选项
+     * 选中单项
      */
     handleSelect(value) {
       if (!value) return
       
       this.isSelectOpen = false
+
       const selectedOption = this.innerOptions.find(
         item => item[this.valueKey] === value
       )
-      // 定义为choose事件，与原生select事件区分
+
+      // 触发choose事件，传递选中值和完整选项对象
       if (selectedOption) {
         this.$emit('choose', value, selectedOption)
       }
     },
     
-    // ==================== 数据处理相关方法 ====================
+    // ========== 数据管理方法 ==========
     
     /**
-     * 处理选项变化
+     * 同步静态选项
      */
-    handleOptionsChange(newVal) {
-      this.innerOptions = this.listPageHandler
-        ? this.deduplicateOptions([...newVal, ...this.innerOptions])
+    syncOptions(newVal) {
+      // 分页模式：合并新旧选项并去重；本地模式：直接使用新选项
+      this.innerOptions = this.needPagination
+        ? this.deduplicate([...newVal, ...this.innerOptions])
         : [...newVal]
     },
     
     /**
-     * 处理选择器开关变化
+     * 下拉框开关切换
      */
-    handleSelectOpenChange(newVal) {
-      const shouldClear = !newVal && this.searchValue && this.autoClearSearchValue
-      if (shouldClear) {
-        this.resetRequest()
+    handleDropdownToggle(isOpen) {
+      // 关闭时且开启了自动清空，则重置搜索
+      if (!isOpen && this.searchValue && this.autoClearSearchValue) {
+        this.resetAndFetch()
       }
     },
     
     /**
-     * 处理值变化
+     * 值变化处理：预加载选中项
      */
     handleValueChange(newVal) {
-      if (this.hasPreloadedSelected || !this.listPageHandler) {
+      // 非分页模式：未初始化时执行加载
+      if (!this.needPagination) {
+        if (!this.isInitialized && this.initLoad) this.fetchData(false)
         return
       }
+      
+      // 已预加载则跳过
+      if (this.hasPreloadedSelected) return
 
+      // 无选中值：直接加载第一页
       if (!newVal || newVal.length === 0) {
         if (this.initLoad) this.fetchData(false)
         return
       }
 
+      // 有选中值：预加载选中项数据
       const selectedIds = Array.isArray(newVal) ? newVal : [newVal]
-      this.preloadSelectedData(selectedIds)
+      this.preloadSelected(selectedIds)
     },
     
     /**
-     * 重置分页并重新请求数据
+     * 重置并重新获取数据
      */
-    resetRequest() {
+    resetAndFetch() {
       this.searchValue = ''
       this.pagination.current = 1
       this.fetchData()
     },
     
     /**
-     * 根据valueKey对选项数组进行去重
-     * @param {Array} options - 待去重的选项数组
-     * @returns {Array} 去重后的选项数组
+     * 数组去重（基于valueKey）
      */
-    deduplicateOptions(options) {
+    deduplicate(options) {
       const seen = new Set()
       return options.filter(item => {
         const value = item[this.valueKey]
-        if (seen.has(value)) {
-          return false
-        }
+        if (seen.has(value)) return false
         seen.add(value)
         return true
       })
     },
 
     /**
-     * 预加载已选择的ID数据
-     * @param {Array} selectedIds - 已选择的ID数组
+     * 预加载选中项数据
+     * 通过ids批量查询选中项的完整信息
      */
-    async preloadSelectedData(selectedIds) {
+    async preloadSelected(selectedIds) {
       try {        
-        const params = {
+        const { records } = await this.listPageHandler({
           ...this.listPageParams,
           ids: selectedIds,
           current: 1,
           size: selectedIds.length
-        }
-
-        const { records } = await this.listPageHandler(params)
+        })
 
-        this.innerOptions = this.deduplicateOptions([...records])
+        this.innerOptions = this.deduplicate([...records])
         this.hasPreloadedSelected = true
           
-        // 请求正常的分页数据
+        // 预加载完成后，再加载正常分页数据
         this.fetchData()
       } catch (error) {
-        console.error('预加载已选择数据失败:', error)
-        // 预加载失败，继续执行正常的分页请求
+        console.error('预加载选中数据失败:', error)
         this.fetchData()
       }
     },
 
     /**
      * 获取分页数据
-     * @param {Boolean} isReset - 是否重置数据
+     * @param {Boolean} isReset - 是否重置为第一页
      */
     async fetchData(isReset = true) {
-      if (!this.listPageHandler) return
+      // 非分页模式：仅触发初始化事件
+      if (!this.needPagination) {
+        if (!this.isInitialized && this.initLoad) {
+          this.$emit('fetchInitialData', {
+            options: [...this.innerOptions],
+            pagination: { ...this.pagination }
+          })
+          this.isInitialized = true
+        }
+        return
+      }
       
       try {
         this.isLoadingMore = true
+        
         const { total, records } = await this.listPageHandler({
           ...this.pagination,
           ...this.listPageParams,
           [this.searchKey]: this.searchValue
         })
         
-        let newInnerOptions = []
-        this.pagination.current === 1 && isReset
-          ? newInnerOptions = [...this.options, ...records]
-          : newInnerOptions = [...this.innerOptions, ...this.handleFilter(records)]
+        // 第一页：合并静态选项和接口数据；后续页：过滤后追加
+        const newOptions = this.pagination.current === 1 && isReset
+          ? [...this.options, ...records]
+          : [...this.innerOptions, ...this.filterNewRecords(records)]
         
-        // 对合并后的数据进行去重
-        this.innerOptions = this.deduplicateOptions(newInnerOptions)
+        this.innerOptions = this.deduplicate(newOptions)
         this.pagination.total = total
 
+        // 首次加载完成，触发事件
         if (!this.isInitialized) {
           this.$emit('fetchInitialData', {
             options: [...this.innerOptions],
@@ -516,6 +444,7 @@ export default {
           })
         }
       } catch (error) {
+        // 请求失败，回退页码
         this.pagination.current--
         console.error('分页加载失败:', error)
       } finally {
@@ -525,18 +454,16 @@ export default {
     },
 
     /**
-     * 过滤掉重复数据
-     * @param {Array} data - 待过滤的数据
-     * @returns {Array} 过滤后的数据
+     * 过滤出新记录（排除已存在的）
      */
-    handleFilter(data) {
-      const optionsCache = new Map(
-        this.innerOptions.map(item => [item[this.valueKey], item])
+    filterNewRecords(data) {
+      const existMap = new Map(
+        this.innerOptions.map(item => [item[this.valueKey], true])
       )
-      return data.filter(item => !optionsCache.has(item[this.valueKey]))
+      return data.filter(item => !existMap.has(item[this.valueKey]))
     },
     
-    // ==================== 工具方法 ====================
+    // ========== 工具方法 ==========
     
     /**
      * 获取选项的唯一key
@@ -546,32 +473,24 @@ export default {
     },
     
     /**
-     * 获取选项显示标签
+     * 获取选项显示文本
      */
     getOptionLabel(item) {
-      if (this.customLabel) {
-        return this.customLabelHandler(item)
-      }
-      return item[this.labelKey]
+      return this.customLabel 
+        ? this.parseCustomLabel(item)
+        : item[this.labelKey]
     },
     
     /**
-     * 安全的自定义标签处理
-     * @param {Object} item - 选项数据
-     * @returns {String} 处理后的标签文本
+     * 解析自定义标签模板
+     * 支持 {{field}} 和 {{nested.field}} 语法
      */
-    customLabelHandler(item) {
+    parseCustomLabel(item) {
       if (!this.customLabel) return item[this.labelKey]
       
       try {
-        // 使用安全的模板字符串解析
-        return this.customLabel.replace(/{{([^{}]+)}}/g, (match, key) => {
-          const path = key.trim().split('.')
-          let value = item
-          for (const p of path) {
-            if (value == null) return ''
-            value = value[p]
-          }
+        return this.customLabel.replace(/{{([^{}]+)}}/g, (_, key) => {
+          const value = key.trim().split('.').reduce((obj, path) => obj?.[path], item)
           return value == null ? '-' : value
         })
       } catch (e) {
@@ -583,8 +502,8 @@ export default {
     /**
      * 加载更多数据
      */
-    async loadMoreData() {
-      if (this.isLoadingMore || !this.hasMore) return
+    async loadMore() {
+      if (!this.needPagination || this.isLoadingMore || !this.hasMore) return
       
       this.pagination.current++
       await this.fetchData()