更新记录

1.2.1（2026-09-26）

变更

• 插件 ID 由 zui 更名为 zdd-zui（组件标签前缀 z- 不变），升级方式：删除旧 uni_modules/zui 后重新导入本插件，并将页面中 uni_modules/zui 引用路径批量替换为 uni_modules/zdd-zui

平台兼容性

uni-app(5.26)

uni-app x(5.26)

ZUI 高性能跨端组件库

基于 Vue3 Composition API 的轻量级 uniapp 组件库 —— 61 个组件，覆盖基础、表单、反馈、展示、导航、布局与高级业务场景。

• 🚀 一键使用：标准 uni_modules + easycom，导入即写标签，无需 import、无需注册
• 🎨 CSS 变量主题：一行换肤，任意容器加 zui-dark 类即刻切换暗黑模式
• 📦 零外部依赖：内置 35 个矢量图标字体（base64 内嵌，无网络请求）
• 🖥 全端兼容：H5 / App（Android、iOS）/ 微信、支付宝、百度、字节跳动、QQ 等小程序
• ⚡ 函数式调用：toast() / showDialog() / showActionSheet() 随处可调
• 🧩 高级业务组件：上传、轮播图、索引列表、侧边栏、宫格、滑动单元格、倒计时、环形进度、水印、悬浮按钮……

平台兼容

本组件库基于 <script setup> 语法，仅支持 Vue3 项目（HBuilderX 3.6+），不支持 Vue2 与 nvue 页面。

快速上手

1. 导入

在插件市场点击「使用 HBuilderX 导入插件」到你的项目，或手动复制 uni_modules/zdd-zui 到项目 uni_modules/ 目录。

2. 引入主题（推荐）

在 App.vue 中引入主题文件（不引入也能用，组件内置了默认值，引入后才能定制与切换暗黑模式）：

<style lang="scss">
@import 'uni_modules/zdd-zui/theme/index.scss';

page {
  background: var(--z-bg);
  color: var(--z-text-1);
}
</style>

⚠️ 请不要把组件库内部路径写进 uni.scss（部分 HBuilderX 版本的 sass 注入编译无法解析 uni_modules 路径）。组件自身已通过相对路径自包含，无需任何额外导入。

3. 直接使用

<template>
  <z-button type="primary" block @click="onClick">主要按钮</z-button>
  <z-cell title="昵称" value="陌上花开" arrow clickable />
  <z-rate v-model="score" />
</template>

<script setup>
import { ref } from 'vue'
const score = ref(3)
const onClick = () => {}
</script>

若项目关闭了 easycom 自动扫描，请在 pages.json 中添加：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^z-(.*)": "@/uni_modules/zdd-zui/components/z-$1/z-$1.vue"
    }
  }
}

4. 函数式调用（Toast / Dialog / ActionSheet）

第一步：在页面模板中放置一次挂载组件（每个需要用到的页面放一份）：

<template>
  <view>
    <!-- 页面内容 -->
    <z-toast />
    <z-dialog />
    <z-action-sheet />
  </view>
</template>

第二步：任意位置调用：

import { toast, showDialog, showActionSheet } from '@/uni_modules/zdd-zui/libs/feedback'

toast('保存成功')                          // 纯文字
toast.success('操作成功')                  // 成功
toast.error('网络异常')                    // 失败
toast.loading('提交中...')                 // 加载（不自动关闭）
setTimeout(() => toast.hide(), 1500)

const ok = await showDialog.confirm('确定删除吗？')   // true / false
await showDialog.alert('只有确定按钮')

const idx = await showActionSheet(['拍照', '从相册选择'])  // 索引 / -1(取消)

⚠️ 命名注意：请在 <script setup> 中按上面示例命名导入（showDialog / showActionSheet）。若变量名与组件标签的驼峰形式同名（如 import { zDialog }），Vue 会把模板里的 <z-dialog> 编译为该变量，导致组件无法渲染。

组件总览

基础组件

ZButton 按钮

<z-button type="primary">主要按钮</z-button>
<z-button type="success" plain round>朴素圆角</z-button>
<z-button icon="search" loading loading-text="加载中" />
<z-button block size="large" color="#7b61ff">块级自定义色</z-button>

事件：click（disabled/loading 时不触发）。支持透传 open-type 等原生 button 属性。

ZIcon 图标

<z-icon name="star" size="40" color="#ff9f18" />

内置图标：close check plus minus search star heart user home gear bell trash edit share location calendar clock photo eye lock phone info warning success error loading chevron-right chevron-down chevron-left chevron-up arrow-right arrow-down arrow-left arrow-up more，别名：clear refresh complete warn。

ZImage 图片

<z-image src="https://..." width="220" height="150" radius="16" />

插槽：loading（加载占位）、error（失败占位）；事件：load / error。

ZBadge 徽标

<z-badge :value="120" :max="99"><z-button size="small">消息</z-button></z-badge>
<z-badge dot><z-icon name="bell" size="44" /></z-badge>

ZTag 标签

<z-tag type="success" plain closable @close="onClose">标签</z-tag>

事件：click / close。

ZAvatar 头像

<z-avatar src="https://..." size="88" />
<z-avatar icon="user" shape="square" bg-color="#00b578" />
<z-avatar text="Z" />

ZLoading 加载

<z-loading text="加载中" />
<z-loading color="#00b578" text="垂直" vertical />

表单组件

ZInput 输入框

<z-input v-model="text" placeholder="请输入" clearable />
<z-input v-model="pwd" password prefix-icon="lock" placeholder="密码" />
<z-input v-model="tel" type="number" prefix-icon="phone" suffix-icon="info" />

插槽：prefix / suffix；事件：input / focus / blur / confirm / clear / click-suffix。

ZTextarea 文本域

<z-textarea v-model="content" :maxlength="100" show-count auto-height />

ZSearch 搜索框

<z-search v-model="keyword" action-text="搜索" @search="onSearch" />

事件：search / clear / input。

ZCheckbox / ZRadio 复选与单选

<z-checkbox-group v-model="checked">
  <z-checkbox name="apple">苹果</z-checkbox>
  <z-checkbox name="banana" shape="circle">香蕉</z-checkbox>
  <z-checkbox name="grape" disabled>禁用</z-checkbox>
</z-checkbox-group>

<z-radio-group v-model="radio">
  <z-radio name="1">选项一</z-radio>
  <z-radio name="2">选项二</z-radio>
</z-radio-group>

Group：v-model（数组 / 值）、disabled、checked-color、direction（horizontal / vertical）。Item：name、shape（checkbox：square / circle）、disabled、label（也可用插槽）、label-disabled、checked-color。

ZSwitch 开关

<z-switch v-model="on" active-color="#00b578" />

ZRate 评分

<z-rate v-model="score" allow-half />
<z-rate :model-value="3" readonly icon="heart" active-color="#f5455c" />

ZSlider 滑块

<z-slider v-model="val" show-tip :min="0" :max="100" :step="1" />

事件：change（拖动结束）/ dragging（拖动中）。

ZStepper 步进器

<z-stepper v-model="num" :min="1" :max="10" :step="0.5" />

事件：change / blur / plus / minus。

反馈组件

ZPopup 弹层（核心组件）

<z-popup v-model:show="show" position="bottom" round closeable>
  <view style="padding: 40rpx;">底部弹层内容</view>
</z-popup>

事件：open / opened / close / closed / click-overlay。

ZDialog 对话框（函数式）

import { showDialog } from '@/uni_modules/zdd-zui/libs/feedback'

await showDialog.alert('只有确定按钮')                       // Promise<true>
const ok = await showDialog.confirm('确定删除吗？', '删除确认') // Promise<true/false>
await showDialog({
  title: '自定义',
  content: '内容',
  showCancelButton: true,
  cancelText: '取消',
  confirmText: '确定'
})

页面需放置 <z-dialog />。支持默认插槽自定义内容。

ZToast 轻提示（函数式）

import { toast } from '@/uni_modules/zdd-zui/libs/feedback'

toast('纯文字')
toast.success('成功')       // toast.error / toast.warning / toast.info
toast.loading('加载中...')   // duration=0 不自动关闭
setTimeout(() => toast.hide(), 1500)
toast({ message: '顶部提示', position: 'top', duration: 3000, mask: true })

页面需放置 <z-toast />。type：text / success / error / warning / loading；position：top / center / bottom。

ZActionSheet 动作面板（函数式）

import { showActionSheet } from '@/uni_modules/zdd-zui/libs/feedback'

const idx = await showActionSheet({
  title: '选择上传方式',
  items: [{ name: '拍照' }, { name: '相册', subname: '从手机相册选择' }],
  cancelText: '取消'
})
// idx：点击项索引；点击取消/遮罩返回 -1

页面需放置 <z-action-sheet />。item 支持 name / subname / color / disabled。

ZProgress 进度条

<z-progress :percent="60" color="#00b578" pivot-text="已完成" />

ZSkeleton 骨架屏

<z-skeleton :loading="loading" avatar :row="3">
  <你的真实内容 />
</z-skeleton>

ZEmpty 空状态

<z-empty text="暂无订单" description="去逛逛看看想买的">
  <z-button size="small" round>去逛逛</z-button>
</z-empty>

展示组件

ZCard 卡片

<z-card title="订单信息" shadow>
  <text>内容区域</text>
  <template #extra><z-tag size="small">进行中</z-tag></template>
  <template #footer><z-button size="mini" plain>查看详情</z-button></template>
</z-card>

插槽：title / extra / default / footer。

ZCell 单元格

<z-cell title="昵称" icon="edit" value="陌上花开" arrow clickable />
<z-cell title="地址" label="上海市浦东新区" arrow />

插槽：icon / title / label / default（值区域）/ right-icon。

ZCollapse 折叠面板

<z-collapse v-model="opened">
  <z-collapse-item title="什么是 ZUI？" name="1">内容</z-collapse-item>
  <z-collapse-item title="禁用项" name="2" disabled>内容</z-collapse-item>
</z-collapse>

Collapse：v-model（数组，accordion 模式为单值）、accordion。Item：name、title、label、value（右侧附加文字）、disabled。

ZSteps 步骤条

<z-steps :items="[{ title: '下单' }, { title: '付款', desc: '已支付' }]" :current="1" />
<z-steps :items="items" :current="2" direction="vertical" />

ZNoticeBar 通知栏

<z-notice-bar text="超长通知自动滚动播放" left-icon="bell" closeable />

事件：close / click。

导航组件

ZTabs 标签页

<z-tabs v-model="tab" :list="['关注', '推荐', '热榜']" @change="onChange" />
<z-tabs v-model="tab2" :list="list" :line-width="48" active-color="#00b578" />

事件：change / click。激活项自动滚动到可视区。

ZNavbar 导航栏（自定义导航栏）

<!-- 常规 -->
<z-navbar title="标题" @left="onBack" />

<!-- 透明沉浸模式：滚动后自动变实色（页面需 navigationStyle: custom） -->
<z-navbar title="详情" transparent :scroll-top="scrollTop" :auto-threshold="80" show-home />

插槽：left / right / default（标题）；事件：left / home（未监听时执行默认返回/回首页）。

页面开启自定义导航：pages.json 对应页面加 "navigationStyle": "custom"。

ZBacktop 返回顶部

<z-backtop :scroll-top="scrollTop" :threshold="300" />

页面 onPageScroll 中把 e.scrollTop 传给 scroll-top。点击自动 pageScrollTo(0)。

布局组件

ZRow / ZCol 栅格

<z-row gutter="16">
  <z-col :span="12"><view>左</view></z-col>
  <z-col :span="6" :offset="6"><view>右</view></z-col>
</z-row>

Row：gutter（列间距 rpx）、justify（start/center/end/space-between/space-around）、align（top/center/bottom）、wrap。Col：span（1-24）、offset。

ZDivider 分割线

<z-divider>文字</z-divider>
<z-divider dashed>虚线</z-divider>
<z-divider vertical />

高级组件

ZUpload 上传

<!-- 图片上传（配置 action 后自动上传） -->
<z-upload v-model="files" accept="image" action="https://api/upload" :max-count="5" @success="onOk" />

<!-- 文件上传 -->
<z-upload v-model="docs" accept="file" :max-count="3" />

<!-- 完全自定义上传 -->
<z-upload v-model="files" :custom-upload="uploadFn" />

事件：change / success / fail / progress / oversize / delete。文件状态：loading（含进度与重试）/ done / failed（点击重试）。

ZSwiper 轮播图

<z-swiper :list="['https://...a.jpg', { image: 'https://...b.jpg', title: '标题' }]" :height="320" :radius="16" />

<!-- 自定义 slide -->
<z-swiper indicator="line">
  <swiper-item>...</swiper-item>
</z-swiper>

事件：change(index) / click(index, item)。

ZIndexList 索引列表

<z-index-list :list="cityList" height="100vh" @select="">
  <template #item="{ item }">
    <text>{{ item }}</text>
  </template>
</z-index-list>

内置右侧索引条（触摸滑动定位）、中央字母提示。事件：select(item)。

ZSidebar / ZSidebarItem 侧边栏

<view style="display: flex; height: 600rpx;">
  <z-sidebar v-model="active">
    <z-sidebar-item v-for="c in cats" :key="c" :title="c" :dot="c === '热卖'" />
  </z-sidebar>
  <view style="flex: 1;">右侧内容区（随 active 切换）</view>
</view>

Sidebar：v-model（索引）。Item：title、disabled、dot、badge、active-color。

ZGrid / ZGridItem 宫格

<z-grid :columns="4">
  <z-grid-item v-for="(g, i) in list" :key="i" @click="onClick(i)">
    <z-icon :name="g.icon" size="40" />
    <text>{{ g.name }}</text>
  </z-grid-item>
</z-grid>

Grid：columns（列数）、border（边框，自动隐藏末列右框）。Item：clickable、事件 click(index)（index 为注册顺序）。

ZCountdown 倒计时

<z-countdown :time="7200 * 1000" format="HH:mm:ss" @finish="onFinish" />
<z-countdown :time="90000" format="mm:ss" />

事件：finish / change(remain)；实例方法 start() / stop()。

ZCircleProgress 环形进度

<z-circle-progress :rate="72" :size="160" />
<z-circle-progress :rate="45" color="#00b578" text="完成" />

基于 conic-gradient 实现，无 canvas 依赖。支持插槽自定义中心内容。

ZLoadMore 加载更多

<z-load-more :status="status" @loadmore="loadNext" />

点击 loadmore 状态时触发 loadmore 事件。

ZSegmented 分段器

<z-segmented v-model="tab" :options="['日', '周', '月']" />
<z-segmented v-model="type" :options="[{ label: '全部', value: 0 }]" active-color="#00b578" />

滑动指示块动画；事件：change(value, index)。

ZCountTo 数字滚动

<z-count-to :end="128450" :duration="2000" font-size="48" />

事件：end；实例方法 play() / stop()。

扩展组件

ZOverlay 遮罩层

<z-overlay :show="show" @click="show = false">可插入内容</z-overlay>

ZFab 悬浮按钮

<z-fab :actions="[{ icon: 'camera', text: '拍照' }, { icon: 'photo', text: '相册' }]" @select="" />
<z-fab icon="plus" @click="onClick" />

事件：click（主按钮）/ select(index, action)。

ZSwipeCell 滑动单元格

<z-swipe-cell>
  <z-cell title="左滑显示操作" value="内容" />
  <template #right>
    <view class="btn" @click="del">删除</view>
  </template>
</z-swipe-cell>

插槽：left / right / default。支持触摸跟手、阻尼回弹、点击内容收回；v-model（false / true / 'right'）、实例方法 close()。

ZTabbar / ZTabbarItem 底部标签栏

<z-tabbar v-model="tab">
  <z-tabbar-item title="首页" icon="home" />
  <z-tabbar-item title="购物车" icon="star" :badge="6" />
  <z-tabbar-item title="我的" icon="user" />
</z-tabbar>

Tabbar：v-model、fixed / placeholder（默认 true，自动安全区）、border、active-color / inactive-color。Item：title、icon、dot、badge、icon 插槽（含 active 状态）。

ZPagination 分页器

<z-pagination v-model="page" :total-items="100" :items-per-page="10" @change="onChange" />

也支持直接传 page-count。自动生成省略号页码。

ZPopover 气泡

<z-popover content="气泡内容" placement="top" theme="dark">
  <z-button size="small">点击我</z-button>
</z-popover>

ZReadMore 文本展开

<z-read-more :lines="2">{{ 长文本 }}</z-read-more>

事件：expand / collapse。

ZWatermark 水印

<z-watermark content="仅供演示" :opacity="0.06" />

ZHighlight 高亮

<z-highlight text="ZUI 轻量级跨端组件库" keywords="跨端" />
<z-highlight :text="title" :keywords="['ZUI', '组件']" color="#00b578" />

ZSticky 吸顶

<z-sticky :offset-top="0">
  <view>滚动到顶部时吸附</view>
</z-sticky>

ZFooter 页脚

<z-footer copyright="© 2026 ZUI">
  <text>关于</text>
  <text>协议</text>
</z-footer>

主题定制

覆盖 CSS 变量

/* App.vue 中 theme/index.scss 之后 */
page {
  --z-primary: #7b61ff;
  --z-radius-md: 12rpx;
}

暗黑模式

在页面根容器加 zui-dark 类，整个子树自动切换：

<template>
  <view :class="{ 'zui-dark': dark }">
    <!-- 所有 ZUI 组件随之切换 -->
  </view>
</template>

变量清单

颜色    --z-primary --z-success --z-warning --z-danger --z-info
文字    --z-text-1 --z-text-2 --z-text-3 --z-text-white
背景    --z-bg --z-bg-2 --z-border --z-mask
圆角    --z-radius-sm --z-radius-md --z-radius-lg --z-radius-round
阴影    --z-shadow --z-shadow-lg

常见问题

Q：调用 toast() 没反应？ 页面模板中需要放置一次 <z-toast />（<z-dialog />、<z-action-sheet /> 同理）。未放置时调用会在控制台输出警告。

Q：sass 报 "Can't find stylesheet to import"？ 不要在 uni.scss 中 @import 'uni_modules/...'。组件已自包含；如需 SCSS 变量，请在对应文件的 <style lang="scss"> 中 @import '@/uni_modules/zdd-zui/theme/var.scss';。

Q：对话框/动作面板不显示？ 检查 <script setup> 中导入的函数名是否为 showDialog / showActionSheet。若变量名与组件标签的驼峰形式同名（如 zDialog），Vue 会把 <z-dialog> 标签编译为该变量导致组件无法渲染。

Q：修改后不生效？ HBuilderX 的编译缓存可能滞后，请删除项目 unpackage 目录后重新运行。

更新日志

详见 changelog.md。

许可证

MIT，可免费商用。