UI 组件库

概述

zq-ui 是为 UniApp 打造的跨平台 UI 组件库，包含 32 个组件，覆盖基础、表单、反馈、展示、导航五大类。所有组件通过 easycom 自动注册，支持 light/dark 主题切换和三语言国际化。

组件列表

基础组件（8个）

组件	标签	说明
Button	<zq-button>	按钮（primary/success/warning/danger/info，plain/block/round/loading）
Cell	<zq-cell>	单元格/菜单项（icon + title + value + is-link + url）
Tag	<zq-tag>	标签（type/plain/round/closable）
Badge	<zq-badge>	徽标（content/dot/max）
Divider	<zq-divider>	分割线（dashed/content/position）
Loading	<zq-loading>	加载（type/size/color/text）
Empty	<zq-empty>	空状态（description/image）
Overlay	<zq-overlay>	遮罩层（show/z-index/duration）

表单组件（10个）

组件	标签	说明
Input	<zq-input>	输入框（type/placeholder/clearable/maxlength）
Textarea	<zq-textarea>	文本域（autoHeight/maxlength/showCount）
Switch	<zq-switch>	开关（activeColor/inactiveColor/size）
Checkbox	<zq-checkbox>	复选框（shape/size/disabled）
Radio	<zq-radio>	单选框（shape/size/disabled）
Stepper	<zq-stepper>	步进器（min/max/step/integer）
Rate	<zq-rate>	评分（count/size/color/allowHalf）
Slider	<zq-slider>	滑块（min/max/step/showValue）
SearchBar	<zq-search-bar>	搜索栏（placeholder/clearable/showAction）
Picker	<zq-picker>	通用选择器

选择器组件（3个）

组件	标签	说明
DatePicker	<zq-date-picker>	日期选择器
TimePicker	<zq-time-picker>	时间选择器
DatetimePicker	<zq-datetime-picker>	日期时间选择器

反馈组件（3个）

组件	标签	说明
Popup	<zq-popup>	弹出层（position: top/bottom/left/right/center）
ActionSheet	<zq-action-sheet>	动作面板（actions/cancelText）
NoticeBar	<zq-notice-bar>	通知栏（scrollable/wrapable/mode）

展示组件（8个）

组件	标签	说明
Card	<zq-card>	卡片（title/thumb/extra）
Avatar	<zq-avatar>	头像（src/size/shape/text）
Progress	<zq-progress>	进度条（percentage/type/color/showText）
Skeleton	<zq-skeleton>	骨架屏（rows/avatar/animate）
Steps	<zq-steps>	步骤条（active/direction/finishIcon）
Collapse	<zq-collapse>	折叠面板（accordion/border）
CountDown	<zq-count-down>	倒计时（time/format/autoStart）
Grid	<zq-grid>	宫格（items/columnNum/border/square）

导航组件（1个）

组件	标签	说明
Tabs	<zq-tabs>	标签页（type/scrollable/animated）

全局组件（3个）

组件	标签	说明
Icon	<zq-icon>	SVG 内联图标（Lucide 风格）
Navbar	<zq-navbar>	自定义导航栏
Tabbar	<zq-tabbar>	自定义底部导航

使用示例

基础

<!-- 按钮 -->
<zq-button type="primary" text="提交" @click="handleSubmit" />
<zq-button type="danger" plain block icon="log-out" text="退出" />

<!-- 单元格 -->
<zq-cell title="设置" icon="settings" is-link url="/pages/settings/index" />
<zq-cell title="语言" icon="languages" :value="currentLocale" @click="handleClick" />

<!-- 标签 -->
<zq-tag type="success">已通过</zq-tag>
<zq-tag type="danger" plain>已拒绝</zq-tag>

表单

<!-- 输入框 -->
<zq-input v-model="name" :placeholder="t('form.name')" clearable />

<!-- 选择器 -->
<zq-radio v-model="gender" :options="genderOptions" />
<zq-checkbox v-model="hobbies" :options="hobbyOptions" />

<!-- 搜索 -->
<zq-search-bar v-model="keyword" :placeholder="t('common.search')" @search="handleSearch" />

展示

<!-- 宫格 -->
<zq-grid :items="gridItems" :column-num="4" :border="false" @click="handleGridClick" />

<!-- 骨架屏 -->
<zq-skeleton :rows="3" avatar animate v-if="loading" />

<!-- 步骤条 -->
<zq-steps :active="currentStep" :items="stepItems" />

反馈

<!-- 弹出层 -->
<zq-popup v-model:show="showPopup" position="bottom" round>
  <view class="popup-content">...</view>
</zq-popup>

<!-- 动作面板 -->
<zq-action-sheet
  v-model:show="showActions"
  :actions="actions"
  :cancel-text="t('common.cancel')"
  @select="handleSelect"
/>

设计规范

颜色

所有组件通过 CSS 变量继承主题色，组件内部禁止硬编码颜色：

// 组件内部样式示例
.zq-button--primary {
  background-color: var(--color-primary);
  color: #ffffff;
}

尺寸

统一使用 rpx（750rpx = 屏幕宽度）：

场景	尺寸
页面边距	24rpx - 32rpx
卡片圆角	12rpx - 16rpx
字体大小（正文）	28rpx
字体大小（标题）	32rpx - 36rpx
图标尺寸	36rpx - 48rpx
按钮高度	72rpx - 88rpx

图标

使用 zq-icon 组件，图标名称参考 Lucide 图标库：

<zq-icon name="settings" :size="20" color="var(--color-primary)" />
<zq-icon name="chevron-right" :size="16" color="var(--color-text-secondary)" />

国际化

组件内置支持国际化，开发者在业务页面中使用 useI18n()：

<zq-empty :description="t('common.noData')" />
<zq-button :text="t('common.save')" type="primary" />