uvx-ui

外观

DropDown 下拉筛选 ​

uvx-drop-down 用于页面顶部或列表顶部的条件筛选，由菜单容器、菜单项和筛选弹层三个组件配合完成。

平台兼容性 ​

AndroidiOS鸿蒙H5微信
5.21+5.11+5.0+4.0+4.41+

小程序端仅支持微信。App Vapor 模式的最低版本由 provide/inject 组件通信能力决定。

平台能力 ​

能力AndroidiOS鸿蒙H5微信
菜单项、筛选弹层、遮罩关闭√√√√√
普通值与激活值状态√√√√√
默认列表与自定义弹层插槽√√√√√
菜单吸顶需滚动回调需滚动回调需滚动回调√√
暗色主题与自定义颜色√√√√√

使用须知

  1. uvx-drop-down、uvx-drop-down-item 和 uvx-drop-down-popup 需要配合使用；容器与弹层的 sign 必须一致，同一页面的多组筛选应使用不同 sign。
  2. default-value 默认为 [0, "0", "all"]。菜单项 value 命中其中任一值时使用普通状态，否则使用激活状态。
  3. type="1" 只切换当前项的布尔激活状态，不打开弹层；type="2" 打开同 sign 的筛选弹层。
  4. App 页面通过 scroll-view 滚动时，应在滚动事件中调用 uvx-drop-down 的 init()，用于更新吸顶状态和弹层位置。Web、微信端使用原生 position: sticky，滚动后仍建议调用 init() 刷新弹层锚点。
  5. current-drop-item.activeIndex 控制选中项外观，点击默认选项时组件会先同步该索引，再发送 clickItem；使用方切换菜单数据时仍应提供对应的当前索引。
  6. text-color、text-active-color 及菜单数据中的 color、activeColor 默认均为空字符串，此时使用主题文本色和主色；显式颜色不会随主题切换。
  7. 弹层应放在页面内容末尾。App 的 fixed 节点会提升到页面根层级，组件通过 z-index 与锚点位置控制覆盖范围。

基础用法 ​

三个组件通过相同的 sign 建立关联。uvx-drop-down-item 必须是 uvx-drop-down 的后代节点。

vue
<template>
   <uvx-drop-down
      ref="uDropDown"
      sign="document-filter"
      @click="handleMenuClick"
   >
      <uvx-drop-down-item
         name="order"
         type="2"
         label="综合排序"
         value="all"
      ></uvx-drop-down-item>
      <uvx-drop-down-item
         name="vip"
         type="1"
         label="VIP文档"
         :value="0"
      ></uvx-drop-down-item>
   </uvx-drop-down>

   <uvx-drop-down-popup
      sign="document-filter"
      :current-drop-item="orderMenu"
      @clickItem="handleItemClick"
   ></uvx-drop-down-popup>
</template>

<script lang="uts" setup>
import type { ItemClickEvent } from "@/uni_modules/uvx-ui/components/uvx-drop-down/types/index.uts";
import type { Menu } from "@/uni_modules/uvx-ui/components/uvx-drop-down-popup/types/index.uts";

// 下拉筛选组件实例
const uDropDown = ref<UvxDropDownComponentPublicInstance | null>(null);
const orderMenu = ref<Menu>({
   activeIndex: 0,
   child: [
      { "label": "综合排序", "value": "all" },
      { "label": "最新发布", "value": "new" },
   ],
});

/**
 * 处理菜单点击
 * @param event 菜单点击参数
 * @returns null
 */
const handleMenuClick = (event: ItemClickEvent): void => {
   console.log(event.name, event.active, event.type);
};

/**
 * 处理筛选选项点击
 * @param item 选项数据
 * @returns null
 */
const handleItemClick = (item: UTSJSONObject): void => {
   console.log(item.getString("label", ""));
};
</script>

默认值与激活状态 ​

default-value 定义“尚未筛选”的值。菜单项值不在该数组内时，文字和图标自动切换为激活外观。

vue
<uvx-drop-down :default-value="[0, '0', 'all']">
   <uvx-drop-down-item label="综合排序" value="all"></uvx-drop-down-item>
   <uvx-drop-down-item label="最新发布" value="new"></uvx-drop-down-item>
</uvx-drop-down>

上例中“综合排序”为普通状态，“最新发布”为激活状态。

两种菜单项类型 ​

type="1" 适合 VIP、仅看有货等开关条件；点击时 click 事件中的 active 在 true 与 false 间切换。type="2" 适合排序、分类等多选一条件；点击时打开或关闭弹层。

vue
<uvx-drop-down sign="filter-types" @click="handleMenuClick">
   <uvx-drop-down-item
      name="category"
      type="2"
      label="全部分类"
      value="all"
   ></uvx-drop-down-item>
   <uvx-drop-down-item
      name="stock"
      type="1"
      label="仅看有货"
      :value="0"
   ></uvx-drop-down-item>
</uvx-drop-down>

弹层菜单数据 ​

current-drop-item.child 是 UTSJSONObject[]。默认读取每项的 label 字段，可通过 key-name 改为其他字段；activeIndex 控制选中项外观。

uts
import type { Menu } from "@/uni_modules/uvx-ui/components/uvx-drop-down-popup/types/index.uts";

const categoryMenu = ref<Menu>({
   activeIndex: 1,
   size: 14,
   activeSize: 15,
   itemCustomStyle: "padding-left: 20px;",
   itemActiveCustomStyle: "padding-left: 20px;",
   child: [
      { "label": "全部分类", "value": "all" },
      { "label": "技术文档", "value": "technology" },
   ],
});

自定义颜色与图标 ​

容器级颜色和图标会下发到全部菜单项。颜色为空时使用暗色主题可切换的语义颜色。

vue
<template>
   <uvx-drop-down
      text-color="#606266"
      text-active-color="#2979ff"
      :extra-icon="NORMAL_ICON"
      :extra-active-icon="ACTIVE_ICON"
   >
      <uvx-drop-down-item label="综合排序"></uvx-drop-down-item>
   </uvx-drop-down>
</template>

<script lang="uts" setup>
import type { Icon } from "@/uni_modules/uvx-ui/components/uvx-drop-down/types/index.uts";

// 普通状态图标
const NORMAL_ICON: Icon = {
   name: "arrow-down-fill",
   size: 13,
   color: "#606266",
};
// 激活状态图标
const ACTIVE_ICON: Icon = {
   name: "arrow-up-fill",
   size: 13,
   color: "#2979ff",
};
</script>

自定义弹层内容 ​

uvx-drop-down-popup 的默认插槽会替换内置选项列表。遮罩、定位、打开关闭和 popupChange 事件仍由组件处理。

vue
<uvx-drop-down-popup sign="custom-filter">
   <view class="custom-filter-panel">
      <text>自定义筛选内容</text>
   </view>
</uvx-drop-down-popup>

吸顶与位置更新 ​

App 演示页使用 uvx-page 的滚动事件更新位置；普通页面在 onPageScroll 中调用相同方法。

vue
<template>
   <uvx-page @scroll="handleScroll">
      <uvx-drop-down ref="uDropDown" sign="sticky-filter">
         <uvx-drop-down-item label="排序"></uvx-drop-down-item>
      </uvx-drop-down>
      <uvx-drop-down-popup sign="sticky-filter"></uvx-drop-down-popup>
   </uvx-page>
</template>

<script lang="uts" setup>
// 下拉筛选组件实例
const uDropDown = ref<UvxDropDownComponentPublicInstance | null>(null);

/**
 * 更新筛选栏位置
 * @param _event 滚动事件
 * @returns null
 */
const handleScroll = (_event: UniScrollEvent): void => {
   uDropDown.value?.init();
};
</script>

API ​

属性说明类型默认值平台
is-sticky是否启用吸顶；App 需在滚动时调用 init()booleantrue全部
sign组件通信标识，需与弹层一致string | numberUVDROPDOWN全部
default-value未筛选状态的值集合Value[][0, "0", "all"]全部
text-size普通菜单文字字号，数字默认补充 pxstring | number15px全部
text-color普通菜单文字颜色；空值跟随主题string""全部
text-active-size激活菜单文字字号，数字默认补充 pxstring | number15px全部
text-active-color激活菜单文字颜色；空值使用主题主色string""全部
extra-icon普通图标配置Icon{ name: "arrow-down", size: 15, color: "" }全部
extra-active-icon激活图标配置Icon{ name: "arrow-up", size: 15, color: "primary" }全部
u-style菜单栏自定义样式，CSS 字符串string""全部
u-class菜单栏外部类名string""全部
属性说明类型默认值平台
name字段标识，会原样传入点击事件string | number""全部
type1 直接切换，2 打开弹层string | number2全部
label菜单文字string""全部
value当前筛选值string | number | null""全部
is-drop外部控制当前项是否展开booleanfalse全部
u-style菜单项根节点自定义样式，CSS 字符串string""全部
u-class菜单项根节点外部类名string""全部
属性说明类型默认值平台
sign组件通信标识，需与容器一致string | numberUVDROPDOWN全部
z-index弹层层级string | number999全部
opacity遮罩透明度，超出 0-1 时自动限制string | number0.5全部
click-overlay-on-close点击遮罩是否关闭弹层booleantrue全部
current-drop-item当前筛选菜单数据Menu{ activeIndex: 0, child: [] }全部
key-name选项文字字段名stringlabel全部
u-style遮罩自定义样式，CSS 字符串string""全部
u-class遮罩外部类名string""全部

Icon ​

字段说明类型必填
nameuvx-icon 图标名称string是
size图标尺寸，数字默认补充 pxstring | number是
color图标颜色；可使用 primary 等主题类型string是
字段说明类型必填
activeIndex当前选中项索引number是
child筛选选项列表UTSJSONObject[]是
label菜单默认文字，供业务回退使用string否
value菜单默认值string | number | null否
color普通选项文字颜色，空值跟随主题string否
activeColor选中项文字颜色，空值使用主题主色string否
size普通选项文字字号string | number否
activeSize选中项文字字号string | number否
itemCustomStyle普通选项样式，CSS 字符串string否
itemActiveCustomStyle选中项样式，CSS 字符串string否

Events ​

组件事件说明参数平台
uvx-drop-downclick点击任一菜单项{ name, active, type }全部
uvx-drop-down-itemclick点击当前菜单项{ name, active, type }全部
uvx-drop-down-popupclickItem点击默认筛选选项UTSJSONObject全部
uvx-drop-down-popuppopupChange弹层打开或关闭{ show: boolean }全部

Slots ​

组件名称说明平台
uvx-drop-downdefault放置 uvx-drop-down-item全部
uvx-drop-down-popupdefault替换默认筛选选项列表全部

Methods ​

组件方法说明参数平台
uvx-drop-downinit()更新吸顶状态和弹层锚点位置-全部

参考 ​

uvx-ui · uni-app x 组件库

Released under the MIT License.