快速开始

本章节介绍 Vital Design 的安装、引入与项目配置。

安装

将包解压到项目的 node_modules 中，目录结构如下：

node_modules
├─ vital-design
└─ @vital-design
   ├─ shared
   ├─ use
   ├─ icons
   └─ styles

下载地址：Vital Design

安装后需确保 vital-design 与 @vital-design/* 子包版本一致。

Sass

组件库样式基于 Sass 编写。使用前请确认项目已安装 sass：

# npm
npm i sass@1.62.1 -D

# yarn
yarn add sass@1.62.1 -D

# pnpm
pnpm add sass@1.62.1 -D

在 Vite 配置中全局注入样式变量，即可在业务代码里直接使用 $vd-* 变量：

// vite.config.ts
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: '@import "@vital-design/styles";',
      },
    },
  },
});

TIP

@vital-design/styles 仅含变量与 mixin。动画 @keyframes 已内置到对应组件样式中；自定义动画可按需 @import '@vital-design/styles/effect/index.scss'。

Sass 版本

Sass 3.0.0 起废弃了部分 API，可能产生警告或兼容问题，建议使用 1.62.x ~ 1.78.x。

导入组件

使用 easycom 自动引入

easycom 是 uni-app 的组件自动导入规则，无需手动 import 与注册即可在模板中使用。

// pages.json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^vd-(.*)": "vital-design/components/$1/$1.vue"
    }
  }
}

基于 Vite 配置自动引入

配合 @uni-helper/vite-plugin-uni-components 与内置解析器，可在编译期按需引入组件并生成类型声明：

// vite.config.ts
import { defineConfig } from 'vite';
import { resolve } from 'node:path';
import Uni from '@dcloudio/vite-plugin-uni';
import Components from '@uni-helper/vite-plugin-uni-components';
import { vitalDesignResolver } from 'vital-design/resolver';

export default defineConfig({
  root: process.cwd(),
  base: './',
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
  plugins: [
    Components({
      resolvers: [vitalDesignResolver()],
      dts: 'src/components.d.ts',
    }),
    Uni(),
  ],
});

TIP

@uni-helper/vite-plugin-uni-components 需注册在 Uni() 插件之前，否则不会生效。

TypeScript

在 tsconfig.json 中引入组件库全局类型，即可获得 vd-* 组件的模板类型提示：

{
  "compilerOptions": {
    "types": [
      "@dcloudio/types",
      "@uni-helper/uni-app-types",
      "vital-design/global.d.ts"
    ]
  },
  "include": [
    "node_modules/vital-design/global.d.ts",
    "src/**/*.vue",
    "src/**/*.ts"
  ]
}

业务代码中可按需导入类型：

import type { ButtonProps, FormInstance } from 'vital-design';

全局配置

建议在应用根节点使用 vd-config-provider 包裹页面，以启用主题变量、导航栏/标签栏高度等全局能力：

<vd-config-provider :theme="theme">
  <!-- 页面内容 -->
</vd-config-provider>

深色模式、主题变量等用法见 定制主题。

函数式组件

Toast、Dialog、Notify、ImagePreview 等组件支持通过函数调用。使用前需在页面中挂载对应组件实例（通常放在布局根节点）：

<vd-toast name="page" />
<vd-dialog name="page" />
<vd-notify name="page" />
<vd-image-preview name="page" />

import { showToast, showDialog } from 'vital-design';

showToast({ message: '提交成功', type: 'success' });
showDialog({ title: '提示', message: '确认删除？' });

WARNING

函数式调用依赖页面中已挂载的组件实例。若找不到对应组件，请检查是否已渲染宿主，以及 name 是否一致。

使用

完成上述配置后，即可在页面中直接使用组件：

<vd-button type="primary">按钮</vd-button>

更多组件用法请查看 组件文档。