Wot Design Uni：一个高颜值、轻量化的uni-app组件库，uni-app生态的新宠

news2024/12/27 2:48:33

一、介绍

wot-design-uni组件库基于vue3+Typescript构建，参照wot design的设计规范进行开发，提供70+高质量组件，支持暗黑模式、国际化和自定义主题，旨在给开发者提供统一的UI交互，同时提高研发的开发效率。

特性：

🎯 多平台覆盖，支持微信小程序、支付宝小程序、钉钉小程序、H5、APP 等.

🚀 70+ 个高质量组件，覆盖移动端主流场景.

💪 使用 Typescript 构建，提供良好的组件类型系统.

🌍 支持国际化，内置 6 种语言包.

📖 提供丰富的文档和组件示例.

🎨 支持修改 CSS 变量实现主题定制.

🍭 支持暗黑模式

二、安装及使用

Wot Design Uni提供了uni_modules和npm两种安装方式，按需选择。

使用uni_modules安装无需额外配置，即插即用，但是每次更新组件库需要处理代码差异（一般直接覆盖就可以）。

使用npm安装需要额外配置，更新组件库时无需处理代码差异。

2.1 安装

uni_modules安装：

在uni-app插件市场选择使用HBuildX导入，或者选择手动在src目录下创建uni_modules文件夹并将Wot Design Uni解压到uni_modules中，结构如下:

- uni_modules
- - - wot-design-uni

npm安装：

// npm
npm i wot-design-uni

// yarn 
yarn add wot-design-uni

// pnpm
pnpm add wot-design-uni

2.2 自动引入组件

配置easycom引入：
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。只要组件路径符合规范，就可以不用引用、注册，直接在页面中使用。

// pages.json
{
    "easycom": {
        "autoscan": true,
        "custom": {
          "^wd-(.*)": "wot-design-uni/components/wd-$1/wd-$1.vue"
        }
    },
    "pages": [
        // ......
    ]
}

基于vite配置引入：
可以通过@uni-helper/vite-plugin-uni-components实现组件的自动引入。

// npm
npm i @uni-helper/vite-plugin-uni-components -D

// yarn
yarn add @uni-helper/vite-plugin-uni-components -D

// pnpm
pnpm add @uni-helper/vite-plugin-uni-components -D

@uni-helper/vite-plugin-uni-components 0.0.8及之前版本vite.config.ts配置如下：

// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";

import Components, { kebabCase } from '@uni-helper/vite-plugin-uni-components'

export default defineConfig({
  plugins: [
    // make sure put it before `Uni()`
    Components({
    resolvers: [
      {
        type: 'component',
        resolve: (name: string) => {
          if (name.match(/^Wd[A-Z]/)) {
            const compName = kebabCase(name)
            return {
              name,
              from: `wot-design-uni/components/${compName}/${compName}.vue`,
            }
          }
        },
      }
    ]
  }), uni()],
});

@uni-helper/vite-plugin-uni-components 0.0.9及以后版本vite.config.ts配置如下：

// vite.config.ts
import { defineConfig } from "vite";
import uni from "@dcloudio/vite-plugin-uni";

import Components from '@uni-helper/vite-plugin-uni-components'
import { WotResolver } from '@uni-helper/vite-plugin-uni-components/resolvers'


export default defineConfig({
  plugins: [
    // make sure put it before `Uni()`
    Components({
    resolvers: [WotResolver()]
  }), uni()],
});

2.3 使用

Wot Design Uni安装、配置完成之后，支持组件自动引入，故可以直接在SFC中使用，无需在页面内import，也不需要在components内声明，即可在任意页面使用。值得注意的是，uni-app平台不支持全局挂载组件，所以Message、Toast等组件仍需在SFC中显式使用，例如:

// 使用toast
<wd-toast></wd-toast>

// 使用MessageBox
<wd-message-box></wd-message-box>

三、定制主题

3.1 自定义主题

Wot Design Uni 每1个组件基本都有自定义类名 custom-class，可以在组件根节点加入你页面上的类名，进行样式修改。

3.2 定制主题

每个组件提供了css 变量，可以参考config-provider组件的使用介绍来定制主题。

Wot 组件通过丰富的 CSS 变量来组织样式，通过覆盖这些 CSS 变量，可以实现定制主题、动态切换主题等效果。

这些变量的默认值被定义在 page 节点上，如果要转 H5，默认值被定义在 :root 节点上。

:root,
page {
  --wot-color-success: red;
  --wot-color-warning: yellow;
}

通过 CSS 覆盖：你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变。
/* 添加这段样式后，默认 Button 底色会变成绿色 */

:root,
page {
  --wot-button-normal-bg: green;
}

通过 ConfigProvider 覆盖：
ConfigProvider 组件提供了覆盖 CSS 变量的能力，你需要在根节点包裹一个 ConfigProvider 组件，并通过 theme-vars 属性来配置一些主题变量。

<wd-config-provider :theme-vars="themeVars">
  <div style="margin: 16px">
    <wd-button round block type="primary">提交</wd-button>
  </div>
</wd-config-provider>

import { ref, reactive } from 'vue'

export default {
  setup() {
    // themeVars 内的值会被转换成对应 CSS 变量
    // 比如 buttonPrimaryBg 会转换成 `--wot-button-primary-bg-color`
    const themeVars = reactive({
      buttonPrimaryBgColor: '#07c160',
      buttonPrimaryColor: '#07c160'
    })
    return {
      themeVars
    }
  }
}