Wand UI 技能#

概述#

Wand UI 2.0 是一个基于 Vue 2.0 的移动端 UI 组件库，专为移动端 H5 应用设计。本技能帮助你快速在项目中集成和使用 Wand UI 组件。

核心特性

• 36+ 精心设计的移动端组件
• 完整的 TypeScript 支持
• 支持按需引入
• 单元测试覆盖率 90%+
• 支持 SSR（服务端渲染）
• 兼容 Android 4.0+ 和 iOS 8+

快速开始#

安装#

bash

npm install @weiyi/wand-ui

引入方式#

完整引入（适合小型项目）

js

import Vue from 'vue'
import WandUI from '@weiyi/wand-ui'
import '@weiyi/wand-ui/lib/wand-ui.css'

Vue.use(WandUI)

按需引入（推荐，减小打包体积）

js

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

组件分类#

表单组件#

用于数据输入和表单验证

组件引入名称主要用途ButtonWandButton按钮操作InputWandInput单行文本输入TextareaWandTextarea多行文本输入CheckWandCheck复选框SwitchWandSwitch开关切换FormWandForm表单容器和验证FormItemWandFormItem表单项RateWandRate评分UploaderWandUploader文件上传

示例：创建表单

vue

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

选择器组件#

用于日期、时间、选项等选择

组件引入名称主要用途PickerWandPicker基础选择器PopupPickerWandPopupPicker弹出式选择器DatetimeWandDatetime日期时间选择CascadeWandCascade级联选择（如省市区）

示例：日期选择

vue

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

反馈组件#

用于用户操作的反馈提示

组件引入名称主要用途ToastWandToast轻提示LoadingWandLoading加载状态DialogWandDialog对话框ConfirmWandConfirm确认框AlertWandAlert警告框ActionSheetWandActionSheet动作面板

示例：Toast 提示

js

// 文字提示
this.$toast('操作成功')

// 成功提示
this.$toast.success('保存成功')

// 失败提示
this.$toast.fail('操作失败')

// 加载中
this.$toast.loading('加载中...')

示例：Dialog 对话框

vue

<template>
  <div>
    <wand-button @click="showDialog">显示对话框</wand-button>

    <wand-dialog
      v-model="dialogVisible"
      title="提示"
      message="确定要删除吗？"
      @confirm="handleConfirm"
      @cancel="handleCancel"
    />
  </div>
</template>

展示组件#

用于内容展示和布局

组件引入名称主要用途ListWandList列表和上拉加载SwipeWandSwipe轮播图SwipeItemWandSwipeItem轮播项CollapseWandCollapse折叠面板CollapseGroupWandCollapseGroup折叠面板组NoticeBarWandNoticeBar通知栏PhotoViewerWandPhotoViewer图片预览

示例：列表加载

vue

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

导航组件#

用于页面导航和路由切换

组件引入名称主要用途TabWandTab标签页容器TabItemWandTabItem标签页项TabBarWandTabBar底部导航栏TabBarItemWandTabBarItem底部导航项NavBarWandNavBar顶部导航栏

示例：底部导航栏

vue

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

其他组件#

组件引入名称主要用途PopupWandPopup弹出层基础组件PopoverWandPopover气泡弹出框SearchWandSearch搜索框SwipeCellWandSwipeCell滑动单元格AffixWandAffix固钉

组件使用工作流#

步骤 1: 确定需求#

根据用户需求，确定需要使用哪些组件：

• 表单页面 → Form, FormItem, Input, Button 等
• 列表页面 → List, NavBar
• 选择功能 → Picker, Datetime, Cascade
• 反馈提示 → Toast, Dialog, Loading

步骤 2: 引入组件#

根据项目规模选择引入方式：

• 小型项目：完整引入所有组件
• 大型项目：按需引入需要的组件

步骤 3: 查询 API#

当需要了解组件的具体属性、事件或插槽时：

1. 查看 references/components_api.md 了解组件的完整 API
2. 查看该组件的 Props、Events、Slots 等

步骤 4: 编写代码#

参考示例代码和最佳实践编写组件代码：

1. 在 template 中使用组件标签
2. 在 script 中引入组件
3. 绑定数据和事件处理器

步骤 5: 样式调整#

如有需要，通过以下方式自定义样式：

• 使用组件的 customStyle 属性（如 Button）
• 通过 CSS 覆盖组件样式
• 使用组件提供的插槽自定义内容

常见使用场景#

场景 1: 创建登录页面#

vue

<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: 创建商品列表页#

vue

<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 方法：

js

this.$refs.form.validate((valid) => {
  if (valid) {
    // 表单验证通过，执行提交逻辑
  } else {
    // 表单验证失败
    return false
  }
})

2. 列表加载#

使用 List 组件实现下拉加载时，注意：

• 在 load 事件中设置 loading = true
• 加载完成后设置 loading = false
• 没有更多数据时设置 finished = true
• 重置列表时要重置 finished = false

3. Toast 提示规范#

js

// 成功操作
this.$toast.success('操作成功')

// 失败操作
this.$toast.fail('操作失败')

// 加载中（需要手动关闭）
const toast = this.$toast.loading('加载中...')
// 请求完成后
toast.clear()

// 普通提示
this.$toast('提示信息')

4. 组件命名规范#

在模板中使用 kebab-case（短横线命名），在 JavaScript 中使用 PascalCase（大驼峰命名）：

vue

<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 类型定义：

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 或需要参考完整的使用示例时

故障排查#

样式没有生效#

问题: 组件显示不正常或没有样式

解决方案:

1. 确保引入了 CSS 文件: import '@weiyi/wand-ui/lib/wand-ui.css'
2. 按需引入时，确保引入了对应组件的样式文件
3. 检查是否使用了 babel-plugin-component 插件

组件提示未注册#

问题: 控制台报错"Unknown custom element"

解决方案:

1. 确保在 components 中注册了组件
2. 确保组件名称拼写正确
3. 全局引入时确保调用了 Vue.use(WandUI)

Toast 等全局方法不存在#

问题: this.$toast is not a function

解决方案:

1. 确保使用了完整引入方式 Vue.use(WandUI)
2. 或者手动安装 Toast 组件: Vue.use(WandToast)

移动端显示异常#

问题: 在移动设备上显示不正常

解决方案: 在 HTML 的 <head> 中添加 viewport 标签：

html

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">