Skip to content

快速开始 ​

本章介绍如何在 uni-app x 项目中引入 uView Pro X,并跑通第一个组件。

环境准备 ​

  • 使用 HBuilderX 创建或打开一个 uni-app x 项目(Vue3 + UTS)。
  • 组件库以 uni_modules 形式分发,需在 HBuilderX 中通过 DCloud 插件市场导入到项目的 uni_modules/uview-pro-x-uts 目录。

安装组件库 ​

目前仅支持通过 DCloud 插件市场导入,不支持 npm 安装。

插件市场地址:

导入步骤:

  1. 打开上述插件市场链接,点击「导入到 HBuilderX」。
  2. 选择目标 uni-app x 项目,完成导入。
  3. 插件会自动落到项目的 uni_modules/uview-pro-x-uts 目录,无需手动拷贝。

安装完成后,项目结构大致如下:

your-project/
├─ uni_modules/
│  └─ uview-pro-x-uts/
│     ├─ components/        # ux-* 组件
│     ├─ libs/              # 工具函数与 hooks
│     ├─ locale/            # 内置语言包
│     ├─ index.uts          # 库入口(install)
│     ├─ index.scss         # 样式统一入口
│     └─ theme.scss         # 主题变量
├─ pages.json
├─ main.uts
└─ uni.scss                 # 主题变量(加密版粘贴 $u-* 变量块)

配置 easycom ​

在 pages.json 中开启 easycom 自动扫描,使 ux-* 组件无需手动 import:

json
{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^ux-(.*)": "@/uni_modules/uview-pro-x-uts/components/ux-$1/ux-$1.uvue"
    }
  }
}

配置后,模板里直接写 <ux-button /> 即可,组件按需编译,未使用的组件不会进入产物。

注册组件库 ​

在 main.uts 中通过 app.use 安装,并按需传入主题与语言(不传则使用内置默认值):

ts
import App from './App.uvue'
// 必须使用命名导入:加密版入口由云端编译生成,`export *` 不会转发 default
import { uViewProX } from '@/uni_modules/uview-pro-x-uts'
import { createSSRApp } from 'vue'

export function createApp() {
    const app = createSSRApp(App)
    app.use(uViewProX, {
        // 语言:默认 zh-CN,内置 zh-CN / en-US
        locale: {
            defaultLocale: 'zh-CN'
        }
    })
    return { app }
}

安装选项可全部省略

app.use(uViewProX) 不带参数也能运行:语言取内置 zh-CN,主题取内置官方蓝。加密版也必须使用 import { uViewProX } from '@/uni_modules/uview-pro-x-uts',不要使用 default 导入(加密入口不转发 default)。

引入主题样式 ​

在 uni.scss 末尾引入组件库的主题变量,使 $u-* SCSS 变量与 --u-* CSS 变量在全项目可用:

scss
@import '@/uni_modules/uview-pro-x-uts/theme.scss';

源码版请忽略下面的变量块

源码版可直接 @import '@/uni_modules/uview-pro-x-uts/theme.scss',无需添加下面的变量块。加密版插件无法直接 @import 组件库的 theme.scss,需把下面的 $u-* 变量块整体复制到项目 uni.scss 末尾,SCSS 主题变量才能在全项目可用。

scss
// 纯色
$u-white-color: var(--u-white-color, #ffffff);
$u-black-color: var(--u-black-color, #000000);

// 字体色
$u-main-color: var(--u-main-color, #303133);
$u-content-color: var(--u-content-color, #606266);
$u-tips-color: var(--u-tips-color, #909399);
$u-light-color: var(--u-light-color, #c0c4cc);

// 边框色
$u-border-color: var(--u-border-color, #dcdfe6);
$u-divider-color: var(--u-divider-color, #e4e7ed);

// 遮罩色
$u-mask-color: var(--u-mask-color, rgba(0, 0, 0, 0.4));
$u-shadow-color: var(--u-shadow-color, rgba(0, 0, 0, 0.1));

// 背景色
$u-bg-color: var(--u-bg-color, #f3f4f6);
$u-bg-white: var(--u-bg-white, #ffffff);
$u-bg-gray-light: var(--u-bg-gray-light, #f1f1f1);
$u-bg-gray-dark: var(--u-bg-gray-dark, #2f343c);
$u-bg-black: var(--u-bg-black, #000000);

// 主色
$u-type-primary: var(--u-type-primary, #2979ff);
$u-type-primary-disabled: var(--u-type-primary-disabled, #a0cfff);
$u-type-primary-dark: var(--u-type-primary-dark, #2b85e4);
$u-type-primary-light: var(--u-type-primary-light, #ecf5ff);

// 警告色
$u-type-warning: var(--u-type-warning, #ff9900);
$u-type-warning-disabled: var(--u-type-warning-disabled, #fcbd71);
$u-type-warning-dark: var(--u-type-warning-dark, #f29100);
$u-type-warning-light: var(--u-type-warning-light, #fdf6ec);

// 成功色
$u-type-success: var(--u-type-success, #19be6b);
$u-type-success-disabled: var(--u-type-success-disabled, #71d5a1);
$u-type-success-dark: var(--u-type-success-dark, #18b566);
$u-type-success-light: var(--u-type-success-light, #dbf1e1);

// 错误色
$u-type-error: var(--u-type-error, #fa3534);
$u-type-error-disabled: var(--u-type-error-disabled, #fab6b6);
$u-type-error-dark: var(--u-type-error-dark, #dd6161);
$u-type-error-light: var(--u-type-error-light, #fef0f0);

// 信息色
$u-type-info: var(--u-type-info, #909399);
$u-type-info-disabled: var(--u-type-info-disabled, #c8c9cc);
$u-type-info-dark: var(--u-type-info-dark, #82848a);
$u-type-info-light: var(--u-type-info-light, #f4f4f5);

TIP

  • --u-* CSS 变量默认值由组件库样式在 page 层提供,运行时主题切换通过注入覆盖,无需在 uni.scss 中声明。

使用第一个组件 ​

在页面模板中直接使用组件:

vue
<template>
    <view class="page">
        <ux-button text="主要按钮" type="primary" @click="onClick" />
        <ux-tag text="标签" type="success" />
    </view>
</template>

<script setup lang="uts">
function onClick(): void {
    uni.showToast({ title: '点击了按钮', icon: 'none' })
}
</script>

<style scoped>
.page {
    display: flex;
    flex-direction: column;
    padding: 16px;
}
</style>

运行与预览 ​

  • H5:HBuilderX 菜单「运行 → 运行到浏览器」,或命令行启动 dev server。
  • App:连接真机或模拟器,「运行 → 运行到手机或模拟器」。
  • 微信 / 支付宝小程序:需先配置 manifest.json 中的小程序 appid,再「运行 → 运行到小程序模拟器」。

各端渲染均由 uni-app x 统一编译,组件行为一致;平台差异详见注意事项。

下一步 ​