FilterItem 筛选选项

用于选型筛选条件中单个筛选字段的选项选择器，支持单选/多选、远程数据加载、联动清空等功能。通常作为 HxFilterPanel 的子组件使用，也支持独立使用。

独立使用

展示 FilterItem 的三种使用场景：单选、多选、自定义字段映射

单选（multiple=false）

状态

待审核

已通过

已驳回

已撤销

""

多选（multiple=true）

分类

技术

产品

设计

运营

[]

多选 modelValueType 对比

modelValueType="array"（默认）

分类

技术

产品

设计

运营

[]

modelValueType="string"

分类

技术

产品

设计

运营

""

自定义 labelKey / valueKey

标签

重要

紧急

普通

归档

""

<template>
  <div class="demo-section">
    <p class="demo-title">单选（multiple=false）</p>
    <HxFilterItem
      v-model="singleValue"
      label="状态"
      :options="statusOptions"
      :multiple="false"
      @change="onSingleChange"
    />
    <pre class="demo-pre">{{ JSON.stringify(singleValue) }}</pre>

    <p class="demo-title" style="margin-top: 28px">多选（multiple=true）</p>
    <HxFilterItem
      v-model="multiValue"
      label="分类"
      :options="categoryOptions"
      :multiple="true"
      @change="onMultiChange"
    />
    <pre class="demo-pre">{{ JSON.stringify(multiValue) }}</pre>

    <p class="demo-title" style="margin-top: 28px">多选 modelValueType 对比</p>
    <div style="display: flex; gap: 24px;">
      <div style="flex: 1;">
        <p class="demo-title">modelValueType="array"（默认）</p>
        <HxFilterItem
          v-model="multiArrayValue"
          label="分类"
          :options="categoryOptions"
          :multiple="true"
          model-value-type="array"
        />
        <pre class="demo-pre">{{ JSON.stringify(multiArrayValue, null, 2) }}</pre>
      </div>
      <div style="flex: 1;">
        <p class="demo-title">modelValueType="string"</p>
        <HxFilterItem
          v-model="multiStringValue"
          label="分类"
          :options="categoryOptions"
          :multiple="true"
          model-value-type="string"
        />
        <pre class="demo-pre">{{ JSON.stringify(multiStringValue) }}</pre>
      </div>
    </div>

    <p class="demo-title" style="margin-top: 28px">自定义 labelKey / valueKey</p>
    <HxFilterItem
      v-model="customValue"
      label="标签"
      :options="customOptions"
      label-key="name"
      value-key="id"
      :multiple="false"
    />
    <pre class="demo-pre">{{ JSON.stringify(customValue) }}</pre>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { HxFilterItem } from '@whhx/ui'

const singleValue = ref('')
const multiValue = ref<string[]>([])
const multiArrayValue = ref<string[]>([])
const multiStringValue = ref('')
const customValue = ref('')

const statusOptions = [
  { label: '待审核', value: 'pending' },
  { label: '已通过', value: 'approved' },
  { label: '已驳回', value: 'rejected' },
  { label: '已撤销', value: 'withdrawn', disabled: true },
]

const categoryOptions = [
  { label: '技术', value: 'tech' },
  { label: '产品', value: 'product' },
  { label: '设计', value: 'design' },
  { label: '运营', value: 'operations' },
]

const customOptions = [
  { name: '重要', id: 'important' },
  { name: '紧急', id: 'urgent' },
  { name: '普通', id: 'normal' },
  { name: '归档', id: 'archived', disabled: true },
]

function onSingleChange(val: any) {
  console.log('单选变化:', val)
}

function onMultiChange(val: any) {
  console.log('多选变化:', val)
}
</script>

<style scoped>
.demo-section {
	padding: 4px 0;
}
.demo-title {
	margin: 0 0 10px;
	font-size: 13px;
	color: var(--el-text-color-secondary);
	font-weight: 500;
}
.demo-pre {
	margin: 8px 0 0;
	padding: 8px 12px;
	font-size: 13px;
	line-height: 1.5;
	background: var(--el-fill-color-lightest);
	border-radius: 4px;
	color: var(--el-text-color-primary);
	font-family: 'Menlo', 'Monaco', monospace;
}
</style>

API

HxFilterItem Props

参数	说明	类型	默认值
modelValue / v-model	当前选中的值，单选为 string | number，多选根据 modelValueType 决定为数组或逗号拼接字符串	FilterValueType	—
label	左侧标签文本	string	''
options	静态选项列表	FilterOption[]	—
labelKey	选项文本字段名	string	'label'
valueKey	选项值字段名	string	'value'
multiple	是否支持多选	boolean	false
modelValueType	多选时 v-model 的值类型："array" 发送数组，"string" 发送逗号拼接字符串（仅在 multiple=true 时有效）	'string' | 'array'	'array'
allowDeselectAll	多选模式下是否允许取消所有选项（最后一项也可取消）	boolean	true
remote	远程数据配置，优先级高于 options	FilterRemoteConfig	—
dependsOn	联动：依赖的父级 prop 名称，父值变化时自动清空自身选中值	string	—
dependsOnValue	联动：父级 prop 当前选中的值	FilterValueType	—

HxFilterItem Emits

事件名	说明	参数
update:modelValue	选中值变化	(value: FilterValueType)
change	选中值变化（与 update:modelValue 同时触发）	(value: FilterValueType)
options-updated	远程数据加载完成，选项列表更新	()

FilterOption

参数	说明	类型	默认值
[key: string]	可配置任意字段，通过 labelKey / valueKey 指定用于显示和取值的字段	any	—
disabled	是否禁用该选项	boolean	false

FilterRemoteConfig

参数	说明	类型	默认值
url	远程请求 URL	string	—
method	请求方法	'get' | 'post'	'get'
params	URL query 参数（GET 自动拼接在 ? 后）	Record<string, unknown>	—
body	请求体参数（POST 序列化为 JSON 放入 body）	Record<string, unknown>	—
bodyType	请求体格式	'json' | 'form-data'	'json'
labelKey	响应数据中 label 字段名	string	'label'
valueKey	响应数据中 value 字段名	string	'value'
childrenKey	响应数据中 children 字段名（用于级联和分组）	string	'children'
dependsOn	联动：依赖的父级 prop 名称，父值变化时自动重新请求	string	—
dependsOnParamKey	联动：父值作为哪个参数名传递	string	'value'
dependsOnIn	联动：父值注入在 query 还是 body 中，默认跟随 method	'query' | 'body'	—

类型定义

import type {
  FilterItemProps,
  FilterItemEmits,
  FilterItemInstance,
  FilterValueType,
  FilterOption,
  FilterRemoteConfig,
} from '@whhx/ui'

功能说明

• 单选/多选：通过 multiple 属性控制。单选模式点击同一选项可取消选中；多选模式每项独立切换。
• 多选值类型：多选模式下通过 modelValueType 控制 v-model 的值格式：
  • "array"（默认）：v-model 值为 (string \| number)[] 数组
  • "string"：v-model 值为逗号拼接字符串（如 "a,b,c"），适用于表单提交时可直接传入的格式
• 禁用选项：选项中设置 disabled: true 可禁用该选项。
• 自定义字段匹配：通过 labelKey 和 valueKey 指定选项对象中用于显示文本和值的字段名。
• 远程数据：配置 remote 后自动发起请求，请求参数可包含 dependsOnValue 实现联动。
• 联动清空：当 dependsOn 指定的父级 prop 值变化时，自动清空当前选中值。
• 主动清空：设置 modelValue 为空字符串（单选）或空数组（多选）即可清空选中状态。