PureUi 官方中文文档
搜索 K

深色模式

级联选择器 Cascader ​

级联选择器组件。

提示

弹窗类组件需放到页面根组件适用，否则可能会因为父元素层级问题导致点击等事件失效。

兼容性 ​

  • 兼容：✅
  • 不兼容：❌
  • 未知：❔
H5安卓苹果微信支付宝百度抖音QQ快手飞书京东
✅✅✅✅✅✅✅✅✅✅✅
小红书鸿蒙360华为快应用快应用联盟
✅❔❔❔❔

插件市场地址 ​

DCloud 插件市场地址

基础使用 ​

  • 通过 options 属性设置数据，数据格式见下方数据说明。
  • 通过 show 属性控制组件的显示与隐藏。
  • 通过 title 属性设置标题。
  • 通过 @confirm 事件监听最后一级选择完成事件。
  • 通过 @select 事件监听每一级的选择事件。
  • 通过 @close 事件监听关闭事件。
vue
<template>
    <pure-cascader
        :show="show"
        :options="options"
        title="请选择收货地址"
        @confirm="handleConfirm"
        @select="handleSelect"
        @close="show = false"
    ></pure-cascader>
</template>

<script setup>
import { ref } from 'vue'

// 显示状态
const show = ref(false)

// 数据格式
// options 是一个数组，数组中的每一项是一个对象，对象有一下属性：
//     * label： 选项显示的文本
//     * disabled： 是否禁用
//     * hide: 是否隐藏，不展示
//     * children： 子级数据，子数据是一个同 options 数据结构一样的数组
// 其中 label 和 children 属性是必须的，其他属性可选。

const options = [
    {
        label: '北京',
        disabled: false,
        hide: false,
        children: [
            {
                label: '北京',
                children: [
                    {
                        label: '朝阳区',
                        disabled: true,
                    },
                    {
                        label: '海淀区',
                        hide: false
                    },
                    {
                        label: '丰台区'
                    }
                ]
            }
        ]
    }
];
</script>

异步加载数据 ​

  • 通过 @select 事件监听每一级的选择事件，然后自行加载异步数据，只需在加载到数据后更新到 options 中即可。
vue
<template>
    <pure-cascader
        :show="show"
        :options="options"
        title="请选择收货地址"
        @confirm="handleConfirm"
        @select="handleSelect"
        @close="show = false"
    ></pure-cascader>
</template>

<script setup>
import { ref } from 'vue'

// 显示状态
const show = ref(false)

// 数据
const options = [
    {
        label: '北京',
        children: [
            {
                label: '北京',
                children: []
            }
        ]
    }
];

// 选择事件
// indexes 是一个数组，数组中的每一项是一个数字，数字表示每一级选中项的索引。
// levelIndex 是当前点击项的层级，从 `0` 开始。
// optionIndex 是当前点击项的的索引
// option 是当前点击项的数据
function handleSelect(indexes, levelIndex, optionIndex, option) {
    if(option.label === '北京') {
        uni.showLoading({
            title: '加载中...'
            mask: true
        });

        // 异步加载数据
        setTimeout(() => {
            options[0].children = [
                {
                    label: '朝阳区'
                },
                {
                    label: '海淀区'
                },
                {
                    label: '丰台区'
                }
            ];
            uni.hideLoading();
        }, 1000)
    }
}
</script>

自定义选项上方的标题 ​

  • 通过 titles 属性自定义每一级别选项上方的标题。
    • 当 titles 是一个数组时，表示每一级别选项上方的标题。
    • 当 titles 是一个字符串时，表示所有级别的选项上方的标题
    • 当 titles 是一个函数时，表示自定义格式化标题，该函数需返回一个字符串，参数为 levelIndex: 表示级别，从 0 开始。
vue
<template>
    <pure-cascader
        :show="show"
        :options="options"
        :titles="titles"
        title="请选择收货地址"
        @confirm="handleConfirm"
        @select="handleSelect"
        @close="show = false"
    ></pure-cascader>
</template>

<script setup>
import { ref } from 'vue'

// 显示状态
const show = ref(false);

// 数据
const options = [
   // ...
];

// 自定义标题
// const titles = ['请选择省份', '请选择城市', '请选择区县'];

// 自定义标题
// const titles = '请选择';

// 自定义标题
function titles(levelIndex) {
    return `请选择第 ${levelIndex + 1} 级`;
}
</script>

自定义提示 ​

  • 通过 placeholder 属性自定义未选中时的提示文案。
    • 当 placeholder 是一个数组时，表示每一级别选项上方的提示文案。
    • 当 placeholder 是一个字符串时，表示所有级别的选项上方的提示文案
    • 当 placeholder 是一个函数时，表示自定义格式化提示文案，该函数需返回一个字符串，参数为 levelIndex: 表示级别，从 0 开始。
vue
<template>
    <pure-cascader
        :show="show"
        :options="options"
        :placeholder="placeholder"
        title="请选择收货地址"
        @confirm="handleConfirm"
        @select="handleSelect"
        @close="show = false"
    ></pure-cascader>
</template>

<script setup>
import { ref } from 'vue'

// 显示状态
const show = ref(false);

// 数据
const options = [
   // ...
];

// 自定义提示文案
// const placeholder = ['省份', '城市', '区县'];

// 自定义提示文案
// const placeholder = '请选择';

// 自定义提示文案
function placeholder(levelIndex) {
    if(levelIndex === 0) {
        return '请选择省份';
    }
    if(levelIndex === 1) {
        return '请选择城市';
    }
    if(levelIndex === 2) {
        return '请选择区县';
    }
    return '请选择';
}
</script>

Props ​

属性名说明类型默认值可选值版本
hoverClass同 view 的 hover-classString"pure-hover"-+1.0.0
show显示状态Booleanfalsetrue+1.0.0
options数据Array[Object][]-+1.0.0
labelKey选项显示文本的字段名Stringlabel-+1.0.0
childrenKey自数据的字段名Stringchildren-+1.0.0
defaultIndexes默认选中项的索引，设置后会默认触发一次 @confirm 事件Array[]-+1.0.0
title弹窗标题String--+1.0.0
close是否显示关闭按钮Booleantruefalse+1.0.0
closeIcon关闭按钮图标名称，同图标组件（Icon）的 name 属性，参考String__cuo-+1.0.0
selectedIcon选项选中时的图标名称，同图标组件（Icon）的 name 属性，参考String__gouxuan-+1.0.0
placeholder未选中时的提示文案[String, Array[String], Function]请选择-+1.0.0
titles自定义选项上方的标题[String, Array[String], Function][]-+1.0.0
overlay是否显示遮罩Booleantruefalse+1.0.0
stopCloseOnClickOverlay是否禁用点击遮罩关闭弹窗功能Booleanfalsetrue+1.0.0
safeBottom开启安全底部Booleantruefalse+1.0.0
disabledClass选项禁用时的类名Stringpure-disabled-+1.0.0

Event ​

事件名说明回调参数版本
confirm最后一级选项选择后的确认事件indexes: 数组，选中的索引； options: 数组，选中的选项；+1.0.0
select单个选项选中事件indexes: 数组，选中的索引；levelIndex: 被点击项锁在的级别，从 0 开始；optionIndex: 被点击项的索引；option: 被点击项的数据；+1.0.0
close关闭事件-+1.0.0

Slots ​

名称说明参数版本
close关闭按钮-+1.0.0
footer底部 Footer-+1.0.0

基于 MIT 许可发布

版权所有 © 2024-2029 济南晨霜信息技术有限公司