- name
- wand-skill
- description
- 帮助开发者在项目中快速集成和使用 Wand UI 2.0 移动端组件库。该技能提供完整的组件 API 参考、使用示例和最佳实践。适用于以下场景：(1) 需要在 Vue 2.0 项目中使用 Wand UI 组件；(2) 查询特定组件的属性、事件或插槽；(3) 需要组件使用示例和代码模板；(4) 解决 Wand UI 集成相关问题；(5) 实现表单、列表、导航等常见移动端界面。
Wand UI 技能
概述
Wand UI 2.0 是一个基于 Vue 2.0 的移动端 UI 组件库，专为移动端 H5 应用设计。本技能帮助你快速在项目中集成和使用 Wand UI 组件。
核心特性
- 36+ 精心设计的移动端组件
- 完整的 TypeScript 支持
- 支持按需引入
- 单元测试覆盖率 90%+
- 支持 SSR（服务端渲染）
- 兼容 Android 4.0+ 和 iOS 8+
快速开始
安装
npm install @weiyi/wand-ui引入方式
完整引入（适合小型项目）
import Vue from 'vue'
import WandUI from '@weiyi/wand-ui'
import '@weiyi/wand-ui/lib/wand-ui.css'
Vue.use(WandUI)按需引入（推荐，减小打包体积）
import { WandButton, WandInput } from '@weiyi/wand-ui'
import '@weiyi/wand-ui/lib/button/style.css'
import '@weiyi/wand-ui/lib/input/style.css'
export default {
components: {
WandButton,
WandInput
}
}组件分类
表单组件
用于数据输入和表单验证
| 组件 | 引入名称 | 主要用途 | |-|-|-| | Button | WandButton | 按钮操作 | | Input | WandInput | 单行文本输入 | | Textarea | WandTextarea | 多行文本输入 | | Check | WandCheck | 复选框 | | Switch | WandSwitch | 开关切换 | | Form | WandForm | 表单容器和验证 | | FormItem | WandFormItem | 表单项 | | Rate | WandRate | 评分 | | Uploader | WandUploader | 文件上传 |
示例：创建表单
<template>
<wand-form :model="formData" :rules="rules" ref="form">
<wand-form-item label="用户名" prop="username" required>
<wand-input v-model="formData.username" placeholder="请输入用户名" />
</wand-form-item>
<wand-button type="primary" @click="submit">提交</wand-button>
</wand-form>
</template>
<script>
export default {
data() {
return {
formData: { username: '' },
rules: {
username: [{ required: true, message: '请输入用户名' }]
}
}
},
methods: {
submit() {
this.$refs.form.validate((valid) => {
if (valid) {
// 提交表单
}
})
}
}
}
</script>选择器组件
用于日期、时间、选项等选择
| 组件 | 引入名称 | 主要用途 | |-|-|-| | Picker | WandPicker | 基础选择器 | | PopupPicker | WandPopupPicker | 弹出式选择器 | | Datetime | WandDatetime | 日期时间选择 | | Cascade | WandCascade | 级联选择（如省市区） |
示例：日期选择
<template>
<wand-popup-picker v-model="visible" title="选择日期">
<wand-datetime
v-model="selectedDate"
type="date"
@confirm="onConfirm"
/>
</wand-popup-picker>
</template>
<script>
export default {
data() {
return {
visible: false,
selectedDate: new Date()
}
},
methods: {
onConfirm(value) {
console.log('选择的日期:', value)
this.visible = false
}
}
}
</script>反馈组件
用于用户操作的反馈提示
| 组件 | 引入名称 | 主要用途 | |-|-|-| | Toast | WandToast | 轻提示 | | Loading | WandLoading | 加载状态 | | Dialog | WandDialog | 对话框 | | Confirm | WandConfirm | 确认框 | | Alert | WandAlert | 警告框 | | ActionSheet | WandActionSheet | 动作面板 |
示例：Toast 提示
// 文字提示
this.$toast('操作成功')
// 成功提示
this.$toast.success('保存成功')
// 失败提示
this.$toast.fail('操作失败')
// 加载中
this.$toast.loading('加载中...')示例：Dialog 对话框
<template>
<div>
<wand-button @click="showDialog">显示对话框</wand-button>
<wand-dialog
v-model="dialogVisible"
title="提示"
message="确定要删除吗？"
@confirm="handleConfirm"
@cancel="handleCancel"
/>
</div>
</template>展示组件
用于内容展示和布局
| 组件 | 引入名称 | 主要用途 | |-|-|-| | List | WandList | 列表和上拉加载 | | Swipe | WandSwipe | 轮播图 | | SwipeItem | WandSwipeItem | 轮播项 | | Collapse | WandCollapse | 折叠面板 | | CollapseGroup | WandCollapseGroup | 折叠面板组 | | NoticeBar | WandNoticeBar | 通知栏 | | PhotoViewer | WandPhotoViewer | 图片预览 |
示例：列表加载
<template>
<wand-list
:loading="loading"
:finished="finished"
@load="onLoad"
>
<div v-for="item in list" :key="item.id">
{{ item.title }}
</div>
</wand-list>
</template>
<script>
export default {
data() {
return {
list: [],
loading: false,
finished: false,
page: 1
}
},
methods: {
async onLoad() {
this.loading = true
const data = await this.fetchData(this.page)
this.list.push(...data)
this.loading = false
this.page++
if (data.length === 0) {
this.finished = true
}
}
}
}
</script>导航组件
用于页面导航和路由切换
| 组件 | 引入名称 | 主要用途 | |-|-|-| | Tab | WandTab | 标签页容器 | | TabItem | WandTabItem | 标签页项 | | TabBar | WandTabBar | 底部导航栏 | | TabBarItem | WandTabBarItem | 底部导航项 | | NavBar | WandNavBar | 顶部导航栏 |
示例：底部导航栏
<template>
<wand-tab-bar v-model="active" fixed>
<wand-tab-bar-item name="home" icon="home">
首页
</wand-tab-bar-item>
<wand-tab-bar-item name="user" icon="user">
我的
</wand-tab-bar-item>
</wand-tab-bar>
</template>
<script>
export default {
data() {
return {
active: 'home'
}
}
}
</script>其他组件
| 组件 | 引入名称 | 主要用途 | |-|-|-| | Popup | WandPopup | 弹出层基础组件 | | Popover | WandPopover | 气泡弹出框 | | Search | WandSearch | 搜索框 | | SwipeCell | WandSwipeCell | 滑动单元格 | | Affix | WandAffix | 固钉 |
组件使用工作流
步骤 1: 确定需求
根据用户需求，确定需要使用哪些组件：
- 表单页面 → Form, FormItem, Input, Button 等
- 列表页面 → List, NavBar
- 选择功能 → Picker, Datetime, Cascade
- 反馈提示 → Toast, Dialog, Loading
步骤 2: 引入组件
根据项目规模选择引入方式：
- 小型项目：完整引入所有组件
- 大型项目：按需引入需要的组件
步骤 3: 查询 API
当需要了解组件的具体属性、事件或插槽时：
- 查看
references/components_api.md了解组件的完整 API - 查看该组件的 Props、Events、Slots 等
步骤 4: 编写代码
参考示例代码和最佳实践编写组件代码：
- 在 template 中使用组件标签
- 在 script 中引入组件
- 绑定数据和事件处理器
步骤 5: 样式调整
如有需要，通过以下方式自定义样式：
- 使用组件的
customStyle属性（如 Button） - 通过 CSS 覆盖组件样式
- 使用组件提供的插槽自定义内容
常见使用场景
场景 1: 创建登录页面
<template>
<div class="login-page">
<wand-nav-bar title="登录" />
<wand-form :model="formData" :rules="rules" ref="loginForm">
<wand-form-item label="手机号" prop="mobile" required>
<wand-input
v-model="formData.mobile"
type="tel"
placeholder="请输入手机号"
clearable
/>
</wand-form-item>
<wand-form-item label="验证码" prop="code" required>
<wand-input
v-model="formData.code"
placeholder="请输入验证码"
>
<template #right-slot>
<wand-button
size="small"
type="primary"
@click="sendCode"
:disabled="codeSending"
>
{{ codeText }}
</wand-button>
</template>
</wand-input>
</wand-form-item>
<wand-button
type="primary"
size="large"
@click="handleLogin"
:disabled="loading"
>
{{ loading ? '登录中...' : '登录' }}
</wand-button>
</wand-form>
</div>
</template>
<script>
import {
WandNavBar,
WandForm,
WandFormItem,
WandInput,
WandButton
} from '@weiyi/wand-ui'
export default {
components: {
WandNavBar,
WandForm,
WandFormItem,
WandInput,
WandButton
},
data() {
return {
formData: {
mobile: '',
code: ''
},
rules: {
mobile: [
{ required: true, message: '请输入手机号' },
{ pattern: /^1[3-9]\d{9}$/, message: '手机号格式不正确' }
],
code: [
{ required: true, message: '请输入验证码' }
]
},
loading: false,
codeSending: false,
codeText: '发送验证码'
}
},
methods: {
async sendCode() {
// 发送验证码逻辑
},
async handleLogin() {
this.$refs.loginForm.validate(async (valid) => {
if (valid) {
this.loading = true
try {
// 登录 API 调用
await this.$api.login(this.formData)
this.$toast.success('登录成功')
this.$router.push('/home')
} catch (error) {
this.$toast.fail(error.message)
} finally {
this.loading = false
}
}
})
}
}
}
</script>场景 2: 创建商品列表页
<template>
<div class="product-list">
<wand-nav-bar
title="商品列表"
left-arrow
@click-left="$router.back()"
/>
<wand-search
v-model="searchText"
placeholder="搜索商品"
show-action
@search="onSearch"
/>
<wand-list
:loading="loading"
:finished="finished"
finished-text="没有更多商品了"
@load="loadMore"
>
<div
v-for="product in productList"
:key="product.id"
class="product-item"
@click="goToDetail(product.id)"
>
<img :src="product.image" class="product-image">
<div class="product-info">
<h3>{{ product.name }}</h3>
<p class="price">¥{{ product.price }}</p>
</div>
</div>
</wand-list>
</div>
</template>
<script>
import {
WandNavBar,
WandSearch,
WandList
} from '@weiyi/wand-ui'
export default {
components: {
WandNavBar,
WandSearch,
WandList
},
data() {
return {
searchText: '',
productList: [],
loading: false,
finished: false,
page: 1
}
},
methods: {
async loadMore() {
this.loading = true
try {
const data = await this.$api.getProducts({
page: this.page,
keyword: this.searchText
})
this.productList.push(...data.list)
this.page++
if (data.list.length === 0) {
this.finished = true
}
} catch (error) {
this.$toast.fail('加载失败')
} finally {
this.loading = false
}
},
onSearch() {
this.productList = []
this.page = 1
this.finished = false
this.loadMore()
},
goToDetail(id) {
this.$router.push(`/product/${id}`)
}
}
}
</script>最佳实践
1. 表单验证
使用 Form 组件的 rules 进行验证，统一在提交时调用 validate 方法：
this.$refs.form.validate((valid) => {
if (valid) {
// 表单验证通过，执行提交逻辑
} else {
// 表单验证失败
return false
}
})2. 列表加载
使用 List 组件实现下拉加载时，注意：
- 在 load 事件中设置
loading = true - 加载完成后设置
loading = false - 没有更多数据时设置
finished = true - 重置列表时要重置
finished = false
3. Toast 提示规范
// 成功操作
this.$toast.success('操作成功')
// 失败操作
this.$toast.fail('操作失败')
// 加载中（需要手动关闭）
const toast = this.$toast.loading('加载中...')
// 请求完成后
toast.clear()
// 普通提示
this.$toast('提示信息')4. 组件命名规范
在模板中使用 kebab-case（短横线命名），在 JavaScript 中使用 PascalCase（大驼峰命名）：
<template>
<!-- 模板中使用短横线命名 -->
<wand-button type="primary">按钮</wand-button>
<wand-nav-bar title="标题" />
</template>
<script>
// JavaScript 中使用大驼峰命名
import { WandButton, WandNavBar } from '@weiyi/wand-ui'
export default {
components: {
WandButton,
WandNavBar
}
}
</script>TypeScript 支持
Wand UI 提供完整的 TypeScript 类型定义：
import { WandButton } from '@weiyi/wand-ui'
import { Component, Vue } from 'vue-property-decorator'
@Component({
components: {
WandButton
}
})
export default class MyComponent extends Vue {
private message: string = 'Hello'
private handleClick(): void {
console.log(this.message)
}
}参考资源
本技能包含以下参考文档，可根据需要查看：
references/components_api.md
完整的组件 API 参考文档，包含所有组件的：
- Props（属性）
- Events（事件）
- Slots（插槽）
- Methods（方法）
- 使用示例
何时查看: 需要了解特定组件的详细 API 时
references/quickstart.md
快速入门指南，包含：
- 安装和引入方式
- 常见使用场景的完整示例
- 浏览器支持信息
- 常见问题解答
何时查看: 初次使用 Wand UI 或需要参考完整的使用示例时
故障排查
样式没有生效
问题: 组件显示不正常或没有样式
解决方案:
- 确保引入了 CSS 文件:
import '@weiyi/wand-ui/lib/wand-ui.css' - 按需引入时，确保引入了对应组件的样式文件
- 检查是否使用了 babel-plugin-component 插件
组件提示未注册
问题: 控制台报错"Unknown custom element"
解决方案:
- 确保在 components 中注册了组件
- 确保组件名称拼写正确
- 全局引入时确保调用了
Vue.use(WandUI)
Toast 等全局方法不存在
问题: this.$toast is not a function
解决方案:
- 确保使用了完整引入方式
Vue.use(WandUI) - 或者手动安装 Toast 组件:
Vue.use(WandToast)
移动端显示异常
问题: 在移动设备上显示不正常
解决方案: 在 HTML 的 <head> 中添加 viewport 标签：
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">