Skip to content

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-uts directory.

Install the library ​

Currently the library can only be imported from the DCloud plugin marketplace; npm installation is not supported.

Marketplace page:

Import steps:

  1. Open the marketplace link above and click "Import into HBuilderX".
  2. Choose the target uni-app x project to finish the import.
  3. The plugin lands in the project's uni_modules/uview-pro-x-uts directory 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:

json
{
  "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):

ts
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:

scss
@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.

scss
// 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 the page selector; runtime theme switching overrides them, so you do not need to declare them in uni.scss.

Use your first component ​

Use components directly in a page template:

vue
<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.

Next steps ​