xtf-dropdown-item

组件说明

xtf-dropdown-item 是下拉菜单项组件，必须配合 xtf-dropdown-menu 使用。支持单选/多选、选项列表、自定义内容和底部操作栏，适用于筛选条件和分类选择等场景。

基础用法

1. 单选

通过 options 设置选项列表，通过 v-model 绑定选中值：

vue

<template>
  <xtf-dropdown-menu>
    <xtf-dropdown-item v-model="sort" title="排序" :options="sortOptions" />
  </xtf-dropdown-menu>
</template>

<script>
export default {
  data() {
    return {
      sort: 'default',
      sortOptions: [
        { text: '默认', value: 'default' },
        { text: '最新', value: 'newest' },
        { text: '最热', value: 'popular' }
      ]
    }
  }
}
</script>

2. 多选

通过 multiple 启用多选模式：

vue

<template>
  <xtf-dropdown-menu>
    <xtf-dropdown-item v-model="tags" title="标签" :options="tagOptions" multiple />
  </xtf-dropdown-menu>
</template>

<script>
export default {
  data() {
    return {
      tags: [],
      tagOptions: [
        { text: '包邮', value: 'free' },
        { text: '折扣', value: 'discount' },
        { text: '新品', value: 'new' }
      ]
    }
  }
}
</script>

3. 自定义内容

不传 options 时使用默认插槽：

vue

<template>
  <xtf-dropdown-menu>
    <xtf-dropdown-item title="价格">
      <view style="padding: 24rpx">
        <xtf-slider v-model="price" :min="0" :max="999" />
      </view>
    </xtf-dropdown-item>
  </xtf-dropdown-menu>
</template>

<script>
export default {
  data() {
    return {
      price: 500
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`title`	`String`	`''`	菜单标题	标题
`disabled`	`Boolean`	`false`	是否禁用	禁用
`options`	`Array`	`[]`	选项列表	选项
`value` / `modelValue`	`String \| Number \| Array`	`undefined`	选中值	双向绑定
`valueKey`	`String`	`'value'`	选项值字段名	数据映射
`labelKey`	`String`	`'text'`	选项标签字段名	数据映射
`multiple`	`Boolean`	`false`	是否多选	多选
`showToolbar`	`Boolean`	`true`	是否显示底部操作栏（多选模式）	操作栏
`showHeader`	`Boolean`	`false`	是否显示头部	头部
`visibleOptionCount`	`String \| Number`	`0`	可见选项数量	滚动
`optionHeight`	`String \| Number`	`76`	选项高度（rpx）	选项高度
`maxHeight`	`String \| Number`	`'600'`	最大高度（rpx）	最大高度
`useScrollView`	`Boolean`	`true`	是否使用内部纵向滚动容器	长选项列表
`confirmText`	`String`	`''`	确认按钮文字	按钮
`resetText`	`String`	`''`	重置按钮文字	按钮
`emptyText`	`String`	`''`	空状态文字	空状态
`showSelectedTitle`	`Boolean`	`true`	是否以已选项更新菜单标题	选中状态展示
`showSelectedCount`	`Boolean`	`true`	多选时是否显示已选数量徽标	多选状态展示
`rememberKey`	`String`	`''`	本地存储已选值的键名	非受控持久化
`optionColumns`	`String \| Number`	`1`	选项列数	网格布局
`selectedSeparator`	`String`	`' / '`	多选标题拼接分隔符	不显示数量时
`popupClass` / `popupStyle`	`String` / `String \| Object`	`''`	弹层根节点类名/样式	弹层定制
`headerClass` / `headerStyle`	`String` / `String \| Object`	`''`	标题区类名/样式	标题区定制
`bodyClass` / `bodyStyle`	`String` / `String \| Object`	`''`	选项区类名/样式	选项区定制
`optionClass` / `optionStyle` / `activeOptionClass`	`String` / `String \| Object` / `String`	`''`	选项及激活选项的样式钩子	选项定制
`footerClass` / `footerStyle`	`String` / `String \| Object`	`''`	多选工具栏类名/样式	工具栏定制
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`change`	点选或确认时触发	`({ value, option?, index?, confirmed? })`	值、涉及的选项和索引；确认后带 `confirmed: true`
`confirm`	确认选项后触发	`({ value, option?, index? })`	已提交值及单选时的选项信息
`reset`	多选点击重置时触发	`({ value: Array })`	清空后的草稿值
`open`	打开时触发	-	-
`close`	关闭时触发	-	-
`opened` / `closed`	打开或关闭后的下一轮渲染触发	-	-
`input` / `update:value` / `update:modelValue`	提交选项值时触发	`(value: String \| Number \| Array)`	三种双向绑定兼容事件

事件使用示例

vue

<template>
  <xtf-dropdown-menu>
    <xtf-dropdown-item
      v-model="values"
      title="标签"
      multiple
      :options="options"
      @open="log('open')"
      @opened="log('opened')"
      @change="onChange"
      @confirm="onConfirm"
      @reset="onReset"
      @close="log('close')"
      @closed="log('closed')"
    />
  </xtf-dropdown-menu>
</template>

<script>
export default {
  data() {
    return {
      values: [],
      options: [
        { text: '新品', value: 'new' },
        { text: '包邮', value: 'free' }
      ]
    }
  },
  methods: {
    log(name) {
      console.log(name)
    },
    onChange(payload) {
      console.log('change', payload)
    },
    onConfirm(payload) {
      uni.showToast({ title: payload.value.join(','), icon: 'none' })
    },
    onReset(payload) {
      console.log('reset', payload.value)
    }
  }
}
</script>

插槽

插槽名称	说明
`default`	未提供 `options` 时显示的自定义内容

主题说明

选项使用 xtf-icon 显示选中标记
多选底部操作栏使用 xtf-button 组件
选中项使用主题色高亮
禁用项置灰不可点击

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。

xtf-dropdown-item ​

组件说明 ​

基础用法 ​

1. 单选 ​

2. 多选 ​

3. 自定义内容 ​

全部属性 ​

事件 ​

事件使用示例 ​

插槽 ​

主题说明 ​