ZUI 高性能跨端组件库

| Prop | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| title | String | '' | 标题 |
| search | Boolean | false | 搜索框模式（替代标题区域），confirm 触发 `search` 事件 |
| search-placeholder | String | 搜索 | 搜索框占位文案 |
| left-arrow | Boolean | true | 返回箭头（仅存在上级页面时显示） |
| show-home | Boolean | false | 无上级页面时显示首页按钮 |
| home-path | String | /pages/index/index | 首页路径 |
| fixed / placeholder | Boolean | true | 固定顶部 / 生成占位 |
| transparent | Boolean | false | 沉浸透明模式 |
| scroll-top | Number | 0 | 页面滚动距离（配合 onPageScroll） |
| auto-threshold | Number | 80 | 透明→实色阈值（px） |
| background / color | String | bg-2 / text-1 | 颜色 |
| border | Boolean | true | 底部细线（透明模式不显示） |
| z-index | String | — | 导航层层级 |

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

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

### ZBacktop 返回顶部
> **适用场景**：长页面滚动一定距离后出现的返回顶部按钮。

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

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

点击自动 pageScrollTo(0)；默认插槽可自定义内容。

注意：页面可滚动距离必须超过 threshold 按钮才会出现——页面内容太短时按钮永远不会出现；且必须在页面 onPageScroll 中把 e.scrollTop 传给 scroll-top，否则组件感知不到滚动。

布局组件

ZRow / ZCol 栅格

适用场景：24 等分栅格布局，快速搭建页面的横向分栏。

<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。

ZRow 参数

ZCol 参数

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)。> 说明：H5 端 cell 内容由组件内置渲染（字符串直出 / 对象取 label-key 字段）；小程序与 App 端支持 #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。

ZSidebar 参数

事件：change(index)。

ZSidebarItem 参数

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 为注册顺序）。

ZGrid 参数

ZGridItem 参数：clickable（点击反馈）；事件 click(index)（index 为注册顺序，从 0 开始）；内容用默认插槽自由组合。

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 环形进度

适用场景：环形进度条，无 canvas 依赖全端可用。

<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)。

事件：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()。

插槽：left / right（操作按钮区）/ default（内容）。事件：open / close；实例方法 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 状态）。

ZTabbar 参数

ZTabbarItem 参数

事件：change(index)；icon 插槽带 active 状态。

ZPagination 分页器

适用场景：数据分页导航，自动省略号。

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

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

事件：change(page)。

ZPopover 气泡

适用场景：点击元素弹出的气泡提示。

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

事件：select(item) / select。

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

进阶组件

ZSorter 拖拽排序

适用场景：长按拖动调整列表顺序，跨行自动交换。

<z-sorter v-model="list" :item-height="96">
  <template #item="{ item }">
    <view class="row">{{ item.label }}</view>
  </template>
</z-sorter>

事件：sort-start(index) / sort-end(index)。

ZDropdownMenu 下拉菜单

适用场景：列表顶部的筛选下拉菜单，单开互斥。

<z-dropdown-menu v-model="openIndex">
  <z-dropdown-item v-model="sort" title="排序" :options="[{ text: '默认', value: 0 }, { text: '价格', value: 1 }]" />
  <z-dropdown-item v-model="type" :options="allOptions" active-color="#00b578" />
</z-dropdown-menu>

Menu：v-model（展开的 item 索引，-1 关闭）。Item：v-model（选中值）、options（[{ text, value }]）、title（默认取选中项文字）、disabled、active-color、max-height。事件：change(value, option)。支持默认插槽自定义面板内容。

ZDropdownMenu 参数

ZDropdownItem 参数

事件：change(value, option) / close（菜单收起）；插槽 default 自定义面板内容。

ZPullRefresh 下拉刷新

适用场景：下拉触发刷新，基于原生 refresher 全端可用。

<z-pull-refresh v-model="refreshing" height="100vh" @refresh="onRefresh">
  <view v-for="i in 20">条目 {{ i }}</view>
</z-pull-refresh>

基于 scroll-view 原生 refresher 实现（全端可用）。v-model 为刷新状态（刷新完成后置 false）；height 滚动区高度；支持 refresher 插槽自定义下拉头部。

事件：refresh / scroll；插槽 refresher 自定义下拉头部。

ZLiquid 水波进度球

适用场景：水波动画展示百分比进度。

<z-liquid :rate="65" />
<z-liquid :rate="30" color="#00b578" text="30%" />

双层旋转波纹动画，水位变化平滑过渡。

ZFitSwiper 自适应高度轮播

适用场景：每页高度随图片比例自动变化的轮播图。

<z-fit-swiper :list="['a.jpg', 'b.jpg']" :fallback-height="300" />

每页高度随图片宽高比自动变化，切换时高度平滑过渡。参数与 z-swiper 一致（autoplay/interval/circular/indicator 等），事件 change / click / loaded(index, ratio)。

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

ZTree 树形控件

适用场景：层级数据的展开与选择，支持多级嵌套。

<z-tree :data="treeData" selectable :default-expanded="['n1']" @node-click="onNodeClick" />

事件：node-click(node) / expand(node, expanded)。支持 node 插槽自定义节点内容。

子组件 z-tree-node 为递归节点渲染单元（支持 depth 层级 prop 控制缩进），z-tree 内部已自动使用，一般无需单独引入。

ZTable 表格

适用场景：列数据表格，支持横向滚动与斑马纹。

<z-table
  :columns="[{ key: 'name', title: '姓名', width: 180 }, { key: 'age', title: '年龄', width: 120, align: 'center' }]"
  :data="rows"
  stripe
  @row-click="onRow"
/>

插槽：cell（作用域 { row, column, index }）、empty；事件：row-click(row, index)。横向内容超宽自动滚动。

ZAnchor 滚动锚点

适用场景：侧边锚点导航，点击定位 + 滚动自动高亮。

<z-anchor :list="[{ id: 'a', title: '推荐' }, { id: 'b', title: '热卖' }]" height="100vh">
  <template #section="{ item }">区块内容</template>
</z-anchor>

右侧锚点导航（side 可选 left/right），点击滚动定位 + 滚动 scrollspy 自动高亮。事件：change(id)。

事件：change(id)（滚动高亮变化）/ select。

ZLink 超链接

适用场景：应用内跳转、拨打电话、复制、外部浏览器。

<z-link text="拨打电话" href="10086" mode="phone" />
<z-link text="复制链接" href="https://..." mode="copy" />
<z-link text="外部浏览器" href="https://..." mode="browser" />
<z-link text="应用内跳转" href="/pages/detail/detail" mode="navigate" />

mode：navigate / browser（App 外部浏览器，H5 新窗口，小程序降级复制）/ copy / phone。

事件：click（点击链接）。

ZArea 省市区选择

适用场景：表单中选择省 / 市 / 区，小程序与 App 为原生三级选择。

<z-area v-model="region" @change="onChange" />

小程序 / App 端基于原生 picker mode="region"，v-model 为 ['省', '市', '区'] 字符串数组。

H5 端平台差异：uni-h5 的 picker 不支持 region 模式（框架源码注明「暂不支持城市选择」），组件自动回退为内置省市两级级联选择（内置 34 个省级行政区 → 地级行政区 / 直辖市下辖区，无网络请求），v-model 为 ['省', '市']。如需完整三级或自定义区域，传入 data 树形数据即可（全平台生效）。

事件：change(value, detail)（H5 端为 change(value)）/ cancel。

ZClipper 图片裁剪

适用场景：全屏图片裁剪器，拖动 + 双指缩放，canvas 导出。

<z-clipper v-if="show" :src="imgSrc" @confirm="onConfirm" @cancel="show = false" />

全屏裁剪器：拖动调整位置、双指缩放，确认后经 canvas 导出临时文件路径（confirm(tempFilePath)）。正方形裁剪框，比例可通过 crop-ratio 调整。

事件：confirm(tempFilePath)（导出 PNG）/ cancel。全屏裁剪器：拖动调整位置、双指缩放、DPR 高清导出。

ZColorPicker 颜色选择器

适用场景：SV 面板 + 色相条 + 预设色板，纯 CSS 实现。

<z-color-picker v-model="color" @change="onChange" />

饱和度/明度面板 + 色相条 + 预设色板 + HEX/RGB 实时显示，纯 CSS 渐变实现（无 canvas）。v-model 为 '#RRGGBB'。

事件：change(hex, rgb)。

ZCalendar 日历

适用场景：单选 / 多选 / 范围三种模式。

<z-calendar v-model="date" mode="single" />
<z-calendar v-model="range" mode="range" />
<z-calendar v-model="dates" mode="multiple" />

事件：change(value)。支持年月切换、今天高亮、范围中间日浅色底，选中日期带主题色光圈；day 作用域插槽可自定义日期单元格（参数含 day/dateStr/selected/disabled）。

进阶组件（二）

ZKeyboard 虚拟键盘

适用场景：数字 / 身份证 / 车牌 / 自定义四种虚拟键盘。

<z-keyboard type="number" confirm-text="确定" @input="onKey" @delete="onDel" @confirm="onOk" />
<z-keyboard type="idcard" title="请输入身份证号" />
<z-keyboard type="plate" title="请输入车牌号" />
<z-keyboard type="custom" :custom-keys="[['7', '8', '9'], ['{del}', '0', '{confirm}']]" />

事件：input(key) / delete / confirm / close。

ZCodeInput 验证码输入

适用场景：验证码 / 密码分段输入框，支持明文密文与自定义样式。

<z-code-input v-model="code" :length="4" @finish="onFinish" />
<z-code-input v-model="pwd" :length="6" :plaintext="false" mask-char="●" />

事件：finish(code)（输入满）/ input / focus / blur。

ZSignCalendar 签到日历

适用场景：数据驱动的签到打卡日历，支持补签与连续天数统计。

<z-sign-calendar :signed-dates="signed" allow-makeup @sign="onSign" @makeup="onMakeup" />

内置统计栏：累计签到 / 连续签到 / 今日状态。已签日期显示为蓝底白字日期 + 「已签」标记。事件：sign(date)（今日签到）/ makeup(date)（补签）/ month-change(y, m)。组件为数据驱动：点击后由父组件把日期 push 进 signed-dates（参考演示页），allow-makeup 为 false 时仅「今天」可触发 sign。

ZSignature 签名板

适用场景：手写签名板，支持撤销 / 重做 / 清空与压感模拟。

<z-signature :height="400" pen-color="#111827" @confirm="onConfirm" />

支持 触摸与鼠标双输入（桌面 H5 可直接用鼠标签名）；画布 CSS 尺寸恒为父容器的 100%（宽度自适应、不溢出屏幕），高度由 height（rpx）控制。

事件：confirm(tempFilePath)（导出签名图片）/ clear / first-draw。实例：撤销 / 重做 / 清空由内置工具栏提供。

ZTransition 过渡动画

适用场景：元素进入 / 离开的过渡动画封装，8 种动画类型。

<z-transition v-model:show="show" anim="fade-up" :duration="400">
  <view>内容</view>
</z-transition>

事件：before-enter / after-enter / before-leave / after-leave / click。

进阶组件（三）

ZQRCode 二维码

适用场景：生成二维码，内置编码算法无外部依赖，支持导出图片。

<z-qrcode value="https://uniapp.dcloud.net.cn" :size="360" />
<z-qrcode value="ZUI" fg-color="#3370ff" bg-color="#f0f4ff" level="H" />

内置 qrcode-generator 编码算法（base64 无外部请求）。事件：ready(canvasId) / click；实例方法 exportImage(cb) 导出图片。

ZBarcode 条形码

适用场景：Code39 条形码，canvas 绘制，支持底部文字。

<z-barcode value="ZUI2026" :height="140" />
<z-barcode value="HELLO" color="#3370ff" :show-text="false" />

Code39 编码，canvas 绘制。value 支持大写字母 / 数字 / - . $ / + % 空格；height 条码高度（rpx）；show-text 显示底部文字；color / bg-color 定制。

事件：ready(canvasId) / click。

ZChart 轻量图表

适用场景：canvas 自绘轻量图表：折线 / 柱状 / 饼图，无需 echarts 依赖。

<z-chart type="line" :labels="['1月', '2月']" :series="[{ name: '销量', data: [320, 402] }]" />
<z-chart type="bar" :labels="labels" :series="series" />
<z-chart type="pie" :labels="pieLabels" :series="pieSeries" :height="420" />

canvas 自绘轻量实现，无 echarts 依赖；需要复杂交互图表时可配合 renderjs 引入 echarts。

ZWaterfall 瀑布流

适用场景：按累计高度均衡分列的瀑布流布局。

<z-waterfall :list="items" :columns="2">
  <template #item="{ item }">
    <view>卡片内容（图片 + 文字）</view>
  </template>
</z-waterfall>

事件：item-click(item)。

ZCascader 级联选择

适用场景：多级联动的树形选择弹窗。

<z-cascader v-model:show="show" v-model="values" :options="treeOptions" title="选择地区" @finish="onFinish" />

顶部面包屑可点击回退层级。事件：finish(values, labels) / change。

事件：cancel（取消选择关闭弹层）。

ZDatetimePicker 时间选择

适用场景：表单中选择日期、时间或日期时间，底部弹窗式选择。

<z-datetime-picker v-model:show="show" v-model="dt" mode="datetime" @confirm="onOk" />

事件：confirm(value) / cancel / change。

ZConfetti 彩带

适用场景：canvas 粒子彩带庆祝动画，支持自定义颜色与数量。

<z-confetti ref="confetti" :particle-count="120" />
<z-button @click="$refs.confetti.fire()">放彩带</z-button>

实例方法：fire({ x, y, particleCount, colors })（x/y 为屏幕坐标）、stop()；事件：done。canvas 粒子物理动画（重力 + 旋转），自动回收。

常见问题

Q：调用 toast() 没反应？ 未放置 <z-toast /> 时会自动降级为 uni.showToast 原生提示（<z-dialog /> / <z-action-sheet /> 同理，降级为 uni.showModal / uni.showActionSheet），功能不受影响；若提示一闪而过，请检查是否误传了 duration: 0 或被 toast.loading 占用未 hide。

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，可免费商用。