Quick Start
This chapter shows how to add uView Pro X to a uni-app x project and get your first component running.
Prerequisites
- Use HBuilderX to create or open a uni-app x project (Vue 3 + UTS).
- The library is distributed as a uni_modules package and must be imported from the DCloud plugin marketplace in HBuilderX into your project's
uni_modules/uview-pro-x-utsdirectory.
Install the library
Currently the library can only be imported from the DCloud plugin marketplace; npm installation is not supported.
Marketplace page:
Import steps:
- Open the marketplace link above and click "Import into HBuilderX".
- Choose the target uni-app x project to finish the import.
- The plugin lands in the project's
uni_modules/uview-pro-x-utsdirectory automatically — no manual copying needed.
Once installed, the project looks roughly like this:
your-project/
├─ uni_modules/
│ └─ uview-pro-x-uts/
│ ├─ components/ # ux-* components
│ ├─ libs/ # utilities and hooks
│ ├─ locale/ # built-in language packs
│ ├─ index.uts # library entry (install)
│ ├─ index.scss # unified style entry
│ └─ theme.scss # theme variables
├─ pages.json
├─ main.uts
└─ uni.scss # theme variables (paste the $u-* block for the encrypted build)Configure easycom
Enable easycom auto-scanning in pages.json so ux-* components need no manual import:
{
"easycom": {
"autoscan": true,
"custom": {
"^ux-(.*)": "@/uni_modules/uview-pro-x-uts/components/ux-$1/ux-$1.uvue"
}
}
}After that, just write <ux-button /> in a template. Components are compiled on demand — unused ones stay out of the build.
Register the library
Install it in main.uts via app.use, passing theme and locale as needed (omitted options fall back to built-in defaults):
import App from './App.uvue'
// Named import is required: the encrypted build's entry is generated with `export *`,
// which does not forward the default export.
import { uViewProX } from '@/uni_modules/uview-pro-x-uts'
import { createSSRApp } from 'vue'
export function createApp() {
const app = createSSRApp(App)
app.use(uViewProX, {
// Locale: defaults to zh-CN; zh-CN / en-US are built in
locale: {
defaultLocale: 'zh-CN'
}
})
return { app }
}Every install option is optional
app.use(uViewProX) with no arguments works too: locale falls back to zh-CN and theme to the built-in blue. The encrypted build also requires import { uViewProX } from '@/uni_modules/uview-pro-x-uts' — never use a default import, which is not re-exported by the encrypted entry.
Import theme styles
Import the library's theme variables at the end of uni.scss so the $u-* SCSS variables and --u-* CSS variables are available project-wide:
@import '@/uni_modules/uview-pro-x-uts/theme.scss';Source-code edition: ignore the variable block below
The source-code edition can @import '@/uni_modules/uview-pro-x-uts/theme.scss' directly and does not need the block below. The encrypted build cannot @import the library's theme.scss; copy the whole $u-* variable block below into the end of your uni.scss so the SCSS theme variables are available project-wide.
// Solid colors
$u-white-color: var(--u-white-color, #ffffff);
$u-black-color: var(--u-black-color, #000000);
// Text colors
$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);
// Border colors
$u-border-color: var(--u-border-color, #dcdfe6);
$u-divider-color: var(--u-divider-color, #e4e7ed);
// Mask colors
$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));
// Background colors
$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);
// Primary
$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);
// Warning
$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);
// Success
$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);
// Error
$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);
// Info
$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
- The
--u-*CSS variable defaults are provided by the library styles on thepageselector; runtime theme switching overrides them, so you do not need to declare them inuni.scss.
Use your first component
Use components directly in a page template:
<template>
<view class="page">
<ux-button text="Primary" type="primary" @click="onClick" />
<ux-tag text="Tag" type="success" />
</view>
</template>
<script setup lang="uts">
function onClick(): void {
uni.showToast({ title: 'Button tapped', icon: 'none' })
}
</script>
<style scoped>
.page {
display: flex;
flex-direction: column;
padding: 16px;
}
</style>Run and preview
- H5: in HBuilderX use "Run → Run to Browser", or start a dev server from the CLI.
- App: connect a device or emulator and use "Run → Run to Phone or Emulator".
- WeChat / Alipay Mini Program: set the mini-program appid in
manifest.json, then "Run → Run to Mini Program Simulator".
All platforms are compiled uniformly by uni-app x and behave consistently; see Notice for platform differences.