Cascader 级联选择

基于 Element Plus el-cascader 封装，支持静态 options 和远程数据源。

基础用法

基础 / 可搜索 / 禁用

基础 options

值: []

可搜索

值: []

禁用

<template>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">基础 options</p>
      <HxCascader
        v-model="value1"
        :options="staticOptions"
        placeholder="请选择"
      />
      <p class="demo-value">值: {{ JSON.stringify(value1) }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">可搜索</p>
      <HxCascader
        v-model="value2"
        :options="staticOptions"
        :show-all-levels="false"
        :emitPath="false"
        placeholder="请选择"
        filterable
      />
      <p class="demo-value">值: {{ JSON.stringify(value2) }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">禁用</p>
      <HxCascader
        v-model="value1"
        :options="staticOptions"
        
        disabled
      />
    </div>
  </div>
</template>

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

const value1 = ref<string[]>([])
/** emitPath=false 时仅为叶子 value（string | number） */
const value2 = ref<string | number | string[]>([])

const staticOptions = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
      {
        label: "南京",
        value: "nanjing",
        children: [
          { label: "玄武区", value: "xuanwu" },
          { label: "鼓楼区", value: "gulou" },
        ],
      },
    ],
  },
  {
    label: "华北",
    value: "north",
    children: [
      { label: "北京", value: "beijing" },
      { label: "天津", value: "tianjin" },
    ],
  },
]
</script>

远程数据

传入 remote 配置自动请求远端接口获取 options，支持字段映射。

静态 / 远程请求

<template>
  <ClientOnly>
  <div class="demo-grid">
    <div class="demo-item">
      <p class="demo-label">静态 options（无 remote）</p>
      <HxCascader
        v-model="value1"
        :options="staticOptions"
        placeholder="请选择"
      />
      <p class="demo-value">值: {{ JSON.stringify(value1) }}</p>
    </div>

    <div class="demo-item">
      <p class="demo-label">remote 请求（可搜索）</p>
      <HxCascader
        v-model="value2"
        :remote="remoteConfig"
        placeholder="请选择"
        filterable
      />
      <p class="demo-value">值: {{ JSON.stringify(value2) }}</p>
    </div>
  </div>
  </ClientOnly>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { HxCascader } from "@whhx/ui"
import type { RemoteConfig } from "@whhx/ui"

const value1 = ref<string[]>([])
const value2 = ref<string[]>([])

const staticOptions = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
  {
    label: "华北",
    value: "north",
    children: [
      { label: "北京", value: "beijing" },
      { label: "天津", value: "tianjin" },
    ],
  },
]

const remoteConfig: RemoteConfig = {
  url: "/api/options/cascader",
}
</script>

API

Props

参数	说明	类型	默认值
v-model	绑定值	string | number | string[]	-
options	静态选项列表（优先级高于 remote）	Record<string, any>[]	-
remote	远程数据获取配置	RemoteConfig	-
placeholder	占位文本	string	-
disabled	是否禁用	boolean	false
filterable	是否可搜索	boolean	false
clearable	是否可清空	boolean	true

RemoteConfig

参数	说明	类型	默认值
url	请求地址	string	-
method	请求方法	'get' | 'post'	'get'
params	URL query 参数	Record<string, any>	-
body	请求体参数（POST）	Record<string, any>	-
bodyType	body 格式	'json' | 'form-data'	'json'
labelKey	响应中 label 字段名	string	'label'
valueKey	响应中 value 字段名	string	'value'
childrenKey	响应中 children 字段名	string	'children'