快速开始
本章介绍如何在 uni-app x 项目中引入 uView Pro X,并跑通第一个组件。
环境准备
- 使用 HBuilderX 创建或打开一个 uni-app x 项目(Vue3 + UTS)。
- 组件库以 uni_modules 形式分发,需在 HBuilderX 中通过 DCloud 插件市场导入到项目的
uni_modules/uview-pro-x-uts目录。
安装组件库
目前仅支持通过 DCloud 插件市场导入,不支持 npm 安装。
插件市场地址:
导入步骤:
- 打开上述插件市场链接,点击「导入到 HBuilderX」。
- 选择目标 uni-app x 项目,完成导入。
- 插件会自动落到项目的
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 统一编译,组件行为一致;平台差异详见注意事项。