Uniapp Uview

When to use this skill

Use this skill whenever the user wants to:

• Integrate uView UI into UniApp projects
• Configure UniApp projects to work with uView UI (pages.json, manifest.json, easycom)
• Handle platform-specific behaviors when using uView in UniApp (H5, mini-program, App, nvue)
• Use UniApp features (navigation, APIs, lifecycle) with uView components
• Build cross-platform UniApp applications with uView UI components
• Configure easycom for automatic uView component import in UniApp
• Handle navigation and routing with uView in UniApp
• Optimize UniApp projects using uView UI
• Deploy uView-based UniApp applications to multiple platforms

How to use this skill

This skill is organized to match UniApp integration patterns and the official UniApp plugin structure (https://ext.dcloud.net.cn/plugin?id=1593). When working with uView UI in UniApp:

1. Install and setup uView UI in UniApp project:

• Load examples/getting-started/installation.md for installation in UniApp
• Load examples/getting-started/project-setup.md for UniApp project configuration
• Load examples/getting-started/easycom-config.md for easycom configuration

2. Integrate with UniApp features:

• Load examples/integration/pages-config.md for pages.json configuration
• Load examples/integration/manifest-config.md for manifest.json configuration
• Load examples/integration/navigation.md for navigation with uView
• Load examples/integration/uni-api.md for using UniApp APIs with uView

3. Handle platform-specific behaviors:

• Load examples/platform-specific/h5.md for H5 platform considerations
• Load examples/platform-specific/miniprogram.md for mini-program considerations
• Load examples/platform-specific/app.md for App platform considerations
• Load examples/platform-specific/nvue.md for nvue considerations

4. Advanced integration:

• Load examples/advanced/custom-theme.md for theme customization in UniApp
• Load examples/advanced/build-optimization.md for build optimization
• Load examples/advanced/multi-platform.md for multi-platform deployment

5. Reference the API documentation when needed:

• api/integration-api.md - UniApp and uView integration API
• api/config-api.md - Configuration API reference

6. Use templates for quick start:

• templates/basic-uniapp-project.md - Basic UniApp project with uView
• templates/pages-template.md - Pages configuration template
• templates/manifest-template.md - Manifest configuration template

Important Notes:

• This skill focuses on UniApp integration, not uView UI API documentation
• uView UI supports both Vue 2 and Vue 3, use appropriate syntax
• Always configure easycom in pages.json for automatic component import
• Use conditional compilation (#ifdef, #endif) for platform-specific code
• Test on all target platforms (H5, mini-programs, App) before deployment
• Use rpx units for responsive sizing in UniApp

Examples and Templates

Getting Started

• Installation: examples/getting-started/installation.md - How to install uView UI in UniApp projects
• Project Setup: examples/getting-started/project-setup.md - Setting up UniApp project with uView
• Easycom Config: examples/getting-started/easycom-config.md - Configuring easycom for automatic component import

Integration

• Pages Config: examples/integration/pages-config.md - Configuring pages.json with uView
• Manifest Config: examples/integration/manifest-config.md - Configuring manifest.json for uView
• Navigation: examples/integration/navigation.md - Navigation and routing with uView
• UniApp API: examples/integration/uni-api.md - Using UniApp APIs with uView components

Platform-Specific

• H5: examples/platform-specific/h5.md - H5 platform considerations with uView
• Mini-Program: examples/platform-specific/miniprogram.md - Mini-program considerations with uView
• App: examples/platform-specific/app.md - App platform considerations with uView
• nvue: examples/platform-specific/nvue.md - nvue considerations with uView

Advanced

• Custom Theme: examples/advanced/custom-theme.md - Customizing themes in UniApp projects
• Build Optimization: examples/advanced/build-optimization.md - Optimizing UniApp builds with uView
• Multi-Platform: examples/advanced/multi-platform.md - Multi-platform deployment strategies

Templates

• Basic Project: templates/basic-uniapp-project.md - Basic UniApp project structure with uView
• Pages Template: templates/pages-template.md - pages.json configuration template
• Manifest Template: templates/manifest-template.md - manifest.json configuration template

API Reference

• Integration API: api/integration-api.md - UniApp and uView integration API reference
• Config API: api/config-api.md - Configuration API reference for UniApp projects

Best Practices

1. Use easycom: Configure easycom in pages.json for automatic uView component import 2. Platform Testing: Test on all target platforms (H5, mini-programs, App) 3. Use rpx Units: Use rpx for responsive sizing in UniApp, px for fixed sizes 4. SCSS Support: Ensure SCSS is properly configured in UniApp project 5. Manifest Configuration: Properly configure manifest.json for each platform 6. Conditional Compilation: Use conditional compilation for platform-specific code 7. Performance: Optimize for each platform's specific requirements 8. Navigation: Use UniApp navigation API with uView components

Resources

• Official Plugin: https://ext.dcloud.net.cn/plugin?id=1593
• UniApp Documentation: https://uniapp.dcloud.net.cn/
• uView UI: https://www.uviewui.com/

Keywords

uniapp, uview, uview-ui, uniapp integration, uniapp configuration, easycom, pages.json, manifest.json, uni-app, 小程序, 跨平台, H5, App, nvue, 条件编译, 平台差异

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异 2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查 3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码 4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本 5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。

Configuration API

配置 API

UniApp + uView 项目的配置文件 API 参考。

pages.json 配置

easycom 配置

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

pages 配置

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationStyle": "default" | "custom",
        "navigationBarBackgroundColor": "#ffffff",
        "navigationBarTextStyle": "black" | "white",
        "backgroundColor": "#f5f5f5",
        "enablePullDownRefresh": true,
        "onReachBottomDistance": 50
      }
    }
  ]
}

globalStyle 配置

{
  "globalStyle": {
    "navigationBarTextStyle": "black" | "white",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  }
}

tabBar 配置

{
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#409EFF",
    "borderStyle": "black" | "white",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-current.png"
      }
    ]
  }
}

manifest.json 配置

基本配置

{
  "name": "uniapp-uview-project",
  "appid": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false
}

H5 配置

{
  "h5": {
    "router": {
      "mode": "hash" | "history",
      "base": "/"
    },
    "devServer": {
      "https": false,
      "port": 8080
    }
  }
}

微信小程序配置

{
  "mp-weixin": {
    "appid": "your-appid",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "enhance": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true
  }
}

App 配置

{
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app",
    "distribute": {
      "android": {
        "permissions": []
      },
      "ios": {}
    }
  }
}

uni.scss 配置

/* 引入 uView 主题变量 */
@import "uview-ui/theme.scss";

/* 自定义变量 */
$uni-color-primary: #409EFF;
$uni-bg-color: #f5f5f5;

App.vue 配置

<style lang="scss">
/* 引入 uView 基础样式 */
@import "uview-ui/index.scss";
</style>

main.js 配置

Vue 2

import Vue from 'vue'
import App from './App'
import uView from 'uview-ui'

Vue.use(uView)

Vue 3

import { createSSRApp } from 'vue'
import App from './App'
import uView from 'uview-ui'

export function createApp() {
  const app = createSSRApp(App)
  app.use(uView)
  return { app }
}

Integration API

UniApp 与 uView 整合 API

UniApp 与 uView UI 整合使用的 API 参考。

easycom 配置 API

{
  "easycom": {
    "autoscan": boolean,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

pages.json API

{
  "pages": [
    {
      "path": "string",
      "style": {
        "navigationBarTitleText": "string",
        "navigationStyle": "default" | "custom",
        "navigationBarBackgroundColor": "string",
        "navigationBarTextStyle": "black" | "white",
        "enablePullDownRefresh": boolean,
        "onReachBottomDistance": number
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black" | "white",
    "navigationBarTitleText": "string",
    "navigationBarBackgroundColor": "string",
    "backgroundColor": "string"
  },
  "tabBar": {
    "color": "string",
    "selectedColor": "string",
    "borderStyle": "black" | "white",
    "backgroundColor": "string",
    "list": [
      {
        "pagePath": "string",
        "text": "string",
        "iconPath": "string",
        "selectedIconPath": "string"
      }
    ]
  }
}

manifest.json API

{
  "name": "string",
  "appid": "string",
  "versionName": "string",
  "versionCode": "string",
  "transformPx": boolean,
  "app-plus": {
    "usingComponents": boolean,
    "nvueStyleCompiler": "uni-app" | "weex"
  },
  "h5": {
    "router": {
      "mode": "hash" | "history",
      "base": "string"
    }
  },
  "mp-weixin": {
    "appid": "string",
    "setting": {
      "urlCheck": boolean,
      "es6": boolean,
      "enhance": boolean,
      "postcss": boolean,
      "minified": boolean
    },
    "usingComponents": boolean
  }
}

UniApp API 与 uView 配合

导航 API

// 页面跳转
uni.navigateTo({
  url: 'string',
  success: function,
  fail: function,
  complete: function
})

// 页面返回
uni.navigateBack({
  delta: number
})

// TabBar 跳转
uni.switchTab({
  url: 'string'
})

网络请求 API

uni.request({
  url: 'string',
  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
  data: object,
  header: object,
  success: function,
  fail: function,
  complete: function
})

存储 API

// 存储数据
uni.setStorage({
  key: 'string',
  data: any,
  success: function,
  fail: function
})

// 获取数据
uni.getStorage({
  key: 'string',
  success: function,
  fail: function
})

// 移除数据
uni.removeStorage({
  key: 'string',
  success: function,
  fail: function
})

条件编译 API

// #ifdef 平台名称
// 平台特定代码
// #endif

// #ifndef 平台名称
// 非平台特定代码
// #endif

// #ifdef H5
// H5 平台代码
// #endif

// #ifdef MP-WEIXIN
// 微信小程序代码
// #endif

// #ifdef APP-PLUS
// App 平台代码
// #endif

Build Optimization

构建优化

优化 UniApp + uView 项目的构建和性能。

代码分割

使用条件编译减少代码体积：

<template>
  <view>
    <!-- #ifdef H5 -->
    <u-button>H5 按钮</u-button>
    <!-- #endif -->
    
    <!-- #ifdef MP-WEIXIN -->
    <u-button>小程序按钮</u-button>
    <!-- #endif -->
  </view>
</template>

组件按需引入

虽然 easycom 会自动引入，但可以优化：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

图片优化

<template>
  <view>
    <!-- 使用 webp 格式（H5） -->
    <!-- #ifdef H5 -->
    <image src="/static/image.webp"></image>
    <!-- #endif -->
    
    <!-- 使用 png 格式（小程序） -->
    <!-- #ifdef MP-WEIXIN -->
    <image src="/static/image.png"></image>
    <!-- #endif -->
  </view>
</template>

样式优化

<style lang="scss" scoped>
/* 使用 scoped 避免样式污染 */
.container {
  /* 样式 */
}
</style>

打包配置

在 manifest.json 中配置打包选项：

{
  "mp-weixin": {
    "setting": {
      "minified": true,
      "postcss": true
    }
  },
  "h5": {
    "optimization": {
      "treeShaking": {
        "enable": true
      }
    }
  }
}

注意事项

1. 条件编译：使用条件编译减少代码体积 2. 图片优化：使用合适的图片格式和大小 3. 样式优化：使用 scoped 避免样式污染 4. 打包配置：正确配置打包选项 5. 性能测试：在不同平台测试性能

Custom Theme

自定义主题

在 UniApp 项目中自定义 uView UI 主题。

修改主题变量

在 uni.scss 中修改主题变量：

/* uni.scss */
@import "uview-ui/theme.scss";

/* 自定义主题变量 */
$u-type-primary: #409EFF;
$u-type-success: #67C23A;
$u-type-warning: #E6A23C;
$u-type-error: #F56C6C;
$u-type-info: #909399;

/* 自定义其他变量 */
$u-main-color: #303133;
$u-content-color: #606266;
$u-tips-color: #909399;
$u-light-color: #C0C4CC;
$u-border-color: #E4E7ED;
$u-bg-color: #F3F4F6;

使用 SCSS 变量

在组件中使用主题变量：

<template>
  <view class="custom-button">自定义按钮</view>
</template>

<style lang="scss" scoped>
.custom-button {
  background-color: $u-type-primary;
  color: #ffffff;
  padding: 20rpx 40rpx;
  border-radius: 8rpx;
}
</style>

全局样式覆盖

在 App.vue 中覆盖全局样式：

<style lang="scss">
@import "uview-ui/index.scss";

/* 覆盖 uView 默认样式 */
.u-button {
  border-radius: 8rpx;
}

.u-input {
  border-radius: 8rpx;
}
</style>

条件编译主题

不同平台可以使用不同主题：

/* uni.scss */
@import "uview-ui/theme.scss";

/* #ifdef H5 */
$u-type-primary: #409EFF;
/* #endif */

/* #ifdef MP-WEIXIN */
$u-type-primary: #07c160;
/* #endif */

/* #ifdef APP-PLUS */
$u-type-primary: #007AFF;
/* #endif */

注意事项

1. 变量名称：使用正确的变量名称 2. 引入顺序：先引入 uView 主题，再覆盖变量 3. 作用域：注意变量的作用域 4. 平台差异：使用条件编译处理平台差异 5. 测试验证：在不同平台测试主题效果

Multi-Platform Deployment

多平台部署

UniApp + uView 项目支持多平台部署的策略和注意事项。

平台差异处理

使用条件编译处理平台差异：

<template>
  <view>
    <!-- #ifdef H5 -->
    <view>H5 平台内容</view>
    <!-- #endif -->
    
    <!-- #ifdef MP-WEIXIN -->
    <view>微信小程序内容</view>
    <!-- #endif -->
    
    <!-- #ifdef APP-PLUS -->
    <view>App 平台内容</view>
    <!-- #endif -->
  </view>
</template>

<script>
export default {
  methods: {
    handlePlatform() {
      // #ifdef H5
      // H5 平台代码
      // #endif
      
      // #ifdef MP-WEIXIN
      // 微信小程序代码
      // #endif
      
      // #ifdef APP-PLUS
      // App 平台代码
      // #endif
    }
  }
}
</script>

统一 API 封装

封装统一的 API 调用：

// utils/api.js
export function request(url, options = {}) {
  return new Promise((resolve, reject) => {
    uni.request({
      url,
      ...options,
      success: (res) => {
        resolve(res.data)
      },
      fail: (err) => {
        reject(err)
      }
    })
  })
}

平台特定配置

在 manifest.json 中配置各平台：

{
  "h5": {
    "router": {
      "mode": "hash"
    }
  },
  "mp-weixin": {
    "appid": "your-appid"
  },
  "app-plus": {
    "usingComponents": true
  }
}

注意事项

1. 条件编译：使用条件编译处理平台差异 2. API 统一：封装统一的 API 调用 3. 配置管理：正确配置各平台参数 4. 测试验证：在各平台测试功能 5. 文档记录：记录平台差异和注意事项

Easycom Configuration

Easycom 配置

easycom 是 UniApp 的自动引入机制，配置后可以自动引入 uView 组件，无需手动 import。

基本配置

在 pages.json 中配置 easycom：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

配置说明

• autoscan: true：开启自动扫描
• custom：自定义规则
• ^u-(.*)：匹配以 u- 开头的组件名
• uview-ui/components/u-$1/u-$1.vue：组件路径，$1 是匹配的内容

使用示例

配置后，可以直接使用组件，无需引入：

<template>
  <view>
    <!-- 直接使用，无需 import -->
    <u-button type="primary">按钮</u-button>
    <u-input v-model="value" placeholder="请输入"></u-input>
    <u-form :model="form">
      <u-form-item label="用户名">
        <u-input v-model="form.username"></u-input>
      </u-form-item>
    </u-form>
  </view>
</template>

<script>
export default {
  data() {
    return {
      value: '',
      form: {
        username: ''
      }
    }
  }
}
</script>

完整 pages.json 示例

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  }
}

自定义组件路径

如果 uView 安装在不同位置，需要调整路径：

npm 安装

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "node_modules/uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

uni_modules 安装

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uni_modules/uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

禁用 easycom

如果不想使用 easycom，可以手动引入：

<template>
  <view>
    <u-button>按钮</u-button>
  </view>
</template>

<script>
import uButton from 'uview-ui/components/u-button/u-button.vue'

export default {
  components: {
    uButton
  }
}
</script>

验证配置

创建测试页面验证 easycom 是否生效：

<template>
  <view class="container">
    <u-button type="primary" @click="test">测试 Easycom</u-button>
  </view>
</template>

<script>
export default {
  methods: {
    test() {
      console.log('Easycom 配置成功！')
    }
  }
}
</script>

如果按钮正常显示且无报错，说明 easycom 配置成功。

注意事项

1. 路径必须正确：确保组件路径与实际安装位置一致 2. 组件名称：uView 组件都以 u- 开头 3. 重启项目：修改 easycom 配置后需要重启项目 4. 优先级：easycom 优先级高于手动引入 5. 性能：easycom 不会影响性能，按需加载组件

Installation

在 UniApp 项目中安装 uView UI

uView UI 是专为 UniApp 设计的 UI 组件库，需要正确集成到 UniApp 项目中。

方式一：通过 DCloud 插件市场安装（推荐）

1. 访问 DCloud 插件市场：https://ext.dcloud.net.cn/plugin?id=1593 2. 在 HBuilderX 中：

• 打开项目
• 点击"工具" → "插件安装"
• 搜索 "uView UI" 或直接输入插件 ID: 1593
• 点击"导入插件"

3. 插件会自动导入到 uni_modules/uview-ui 目录

方式二：通过 npm 安装

npm install uview-ui

安装后，uView UI 位于 node_modules/uview-ui 目录。

方式三：手动下载安装

1. 从 GitHub 下载：https://github.com/umicro/uView 2. 将下载的文件解压到项目的 uni_modules/uview-ui 目录

UniApp 项目配置

1. 在 main.js 中引入

// main.js
import App from './App'
import uView from 'uview-ui'

// #ifdef VUE3
import { createSSRApp } from 'vue'
export function createApp() {
  const app = createSSRApp(App)
  app.use(uView)
  return {
    app
  }
}
// #endif

// #ifndef VUE3
import Vue from 'vue'
Vue.use(uView)
Vue.config.productionTip = false
App.mpType = 'app'
const app = new Vue({
  ...App
})
app.$mount()
// #endif

2. 在 App.vue 中引入样式

<!-- App.vue -->
<style lang="scss">
/* 引入 uView 基础样式 */
@import "uview-ui/index.scss";
</style>

3. 在 uni.scss 中引入主题变量（可选）

/* uni.scss */
@import "uview-ui/theme.scss";

4. 配置 easycom（重要）

在 pages.json 中配置 easycom，实现组件自动引入：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    // ... 页面配置
  ]
}

5. 验证安装

创建测试页面 pages/index/index.vue：

<template>
  <view class="container">
    <u-button type="primary">uView 按钮</u-button>
  </view>
</template>

<script>
export default {
  data() {
    return {}
  }
}
</script>

<style lang="scss" scoped>
.container {
  padding: 20rpx;
}
</style>

如果按钮正常显示，说明安装成功。

目录结构

安装后的项目结构：

uniapp-project/
├── uni_modules/
│   └── uview-ui/          # uView UI 插件
│       ├── components/    # 组件目录
│       ├── index.scss     # 基础样式
│       └── theme.scss     # 主题变量
├── pages/                 # 页面目录
├── static/                # 静态资源
├── App.vue                # 应用入口
├── main.js                # 主入口文件
├── pages.json             # 页面配置
├── manifest.json          # 应用配置
└── uni.scss               # 全局样式变量

注意事项

1. SCSS 支持：确保项目支持 SCSS，在 HBuilderX 中创建项目时选择支持 SCSS 2. easycom 配置：必须配置 easycom，否则需要手动引入每个组件 3. 路径问题：如果使用 npm 安装，注意路径可能需要调整 4. 版本兼容：确保 uView UI 版本与 UniApp 版本兼容 5. Vue 版本：uView UI 支持 Vue 2 和 Vue 3，注意对应的使用方式

常见问题

组件找不到

• 检查 easycom 配置是否正确
• 检查组件名称是否正确（u-button, u-input 等）
• 检查是否在 main.js 中注册了 uView

样式不生效

• 检查是否在 App.vue 中引入了 uview-ui/index.scss
• 检查 style 标签是否设置了 lang="scss"
• 检查项目是否支持 SCSS

主题变量不生效

• 检查是否在 uni.scss 中引入了 uview-ui/theme.scss
• 检查变量名称是否正确
• 检查 SCSS 语法是否正确

Project Setup

UniApp 项目配置

配置 UniApp 项目以正确使用 uView UI。

项目结构

标准的 UniApp + uView 项目结构：

uniapp-project/
├── uni_modules/
│   └── uview-ui/          # uView UI 插件
├── pages/                 # 页面目录
│   ├── index/
│   │   └── index.vue
│   └── ...
├── components/            # 自定义组件
├── static/               # 静态资源
├── utils/                # 工具函数
├── App.vue               # 应用入口
├── main.js               # 主入口文件
├── pages.json            # 页面配置
├── manifest.json         # 应用配置
└── uni.scss              # 全局样式变量

App.vue 配置

<template>
  <view id="app">
    <!-- 应用根组件 -->
  </view>
</template>

<script>
export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  onShow: function() {
    console.log('App Show')
  },
  onHide: function() {
    console.log('App Hide')
  }
}
</script>

<style lang="scss">
/* 引入 uView 基础样式 */
@import "uview-ui/index.scss";

/* 全局样式 */
page {
  background-color: #f5f5f5;
}
</style>

main.js 配置

Vue 2 项目

import Vue from 'vue'
import App from './App'
import uView from 'uview-ui'

Vue.use(uView)

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  ...App
})
app.$mount()

Vue 3 项目

import { createSSRApp } from 'vue'
import App from './App'
import uView from 'uview-ui'

export function createApp() {
  const app = createSSRApp(App)
  app.use(uView)
  return {
    app
  }
}

pages.json 配置

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationStyle": "default",
        "navigationBarBackgroundColor": "#ffffff",
        "navigationBarTextStyle": "black"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-current.png",
        "text": "首页"
      }
    ]
  }
}

uni.scss 配置

/* uni.scss */
/* 引入 uView 主题变量 */
@import "uview-ui/theme.scss";

/* 自定义全局变量 */
$uni-color-primary: #409EFF;
$uni-bg-color: #f5f5f5;

manifest.json 配置要点

{
  "name": "uniapp-uview-project",
  "appid": "",
  "description": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true
  },
  "h5": {
    "router": {
      "mode": "hash"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

开发环境配置

HBuilderX 配置

1. 启用 SCSS 支持：

• 创建项目时选择支持 SCSS
• 或在项目设置中启用 SCSS 编译

2. 配置编译器：

• 工具 → 选项 → HBuilderX → 编译器
• 确保启用 SCSS 编译

条件编译

使用条件编译处理平台差异：

<template>
  <view>
    <!-- #ifdef H5 -->
    <view>H5 平台特有内容</view>
    <!-- #endif -->
    
    <!-- #ifdef MP-WEIXIN -->
    <view>微信小程序特有内容</view>
    <!-- #endif -->
    
    <!-- #ifdef APP-PLUS -->
    <view>App 平台特有内容</view>
    <!-- #endif -->
  </view>
</template>

验证配置

创建测试页面验证配置是否正确：

<template>
  <view class="container">
    <u-navbar title="测试页面"></u-navbar>
    <view class="content">
      <u-button type="primary" @click="test">测试按钮</u-button>
      <u-toast ref="uToast"></u-toast>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {}
  },
  methods: {
    test() {
      this.$u.toast('配置成功！')
    }
  }
}
</script>

<style lang="scss" scoped>
.container {
  min-height: 100vh;
  background-color: #f5f5f5;
}

.content {
  padding: 20rpx;
}
</style>

注意事项

1. easycom 必须配置：否则需要手动引入每个组件 2. SCSS 必须支持：uView 依赖 SCSS 3. 路径正确性：确保引入路径正确 4. 版本兼容：确保 UniApp 和 uView 版本兼容 5. 平台测试：在不同平台测试功能

Manifest Configuration

manifest.json 配置

manifest.json 是 UniApp 的应用配置文件，需要正确配置以支持 uView UI 在不同平台运行。

基本配置

{
  "name": "uniapp-uview-project",
  "appid": "",
  "description": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true
  },
  "h5": {
    "router": {
      "mode": "hash"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

H5 平台配置

{
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    },
    "devServer": {
      "https": false,
      "port": 8080
    },
    "publicPath": "/",
    "template": "index.html"
  }
}

微信小程序配置

{
  "mp-weixin": {
    "appid": "your-appid",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "enhance": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true,
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于小程序位置接口的效果展示"
      }
    }
  }
}

App 平台配置

{
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app",
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    },
    "modules": {},
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\"/>"
        ]
      },
      "ios": {},
      "sdkConfigs": {}
    }
  }
}

支付宝小程序配置

{
  "mp-alipay": {
    "usingComponents": true
  }
}

百度小程序配置

{
  "mp-baidu": {
    "usingComponents": true
  }
}

字节跳动小程序配置

{
  "mp-toutiao": {
    "usingComponents": true
  }
}

QQ 小程序配置

{
  "mp-qq": {
    "usingComponents": true
  }
}

完整配置示例

{
  "name": "uniapp-uview-project",
  "appid": "",
  "description": "UniApp + uView UI 项目",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app"
  },
  "h5": {
    "router": {
      "mode": "hash"
    },
    "devServer": {
      "port": 8080
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "enhance": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true
  },
  "mp-alipay": {
    "usingComponents": true
  },
  "mp-baidu": {
    "usingComponents": true
  },
  "mp-toutiao": {
    "usingComponents": true
  },
  "mp-qq": {
    "usingComponents": true
  },
  "quickapp": {},
  "vueVersion": "3"
}

关键配置说明

usingComponents

所有平台都需要设置 "usingComponents": true，以支持组件使用。

transformPx

建议设置为 false，使用 rpx 单位进行响应式布局。

vueVersion

指定 Vue 版本：

• "2" - Vue 2
• "3" - Vue 3

注意事项

1. usingComponents：必须设置为 true 2. 平台差异：不同平台有不同的配置项 3. AppID：小程序平台需要配置对应的 AppID 4. 权限配置：根据功能需求配置相应权限 5. 版本号：正确配置版本号和版本名称

Navigation

导航和路由

在 UniApp 中使用 uView UI 组件进行页面导航和路由管理。

使用 UniApp 导航 API

页面跳转

// 保留当前页面，跳转到应用内的某个页面
uni.navigateTo({
  url: '/pages/detail/detail?id=1'
})

// 关闭当前页面，跳转到应用内的某个页面
uni.redirectTo({
  url: '/pages/login/login'
})

// 跳转到 tabBar 页面
uni.switchTab({
  url: '/pages/index/index'
})

// 返回上一页面
uni.navigateBack({
  delta: 1
})

使用 uView 按钮进行跳转

<template>
  <view>
    <u-button 
      type="primary" 
      @click="goToDetail"
    >
      跳转到详情页
    </u-button>
  </view>
</template>

<script>
export default {
  methods: {
    goToDetail() {
      uni.navigateTo({
        url: '/pages/detail/detail?id=1'
      })
    }
  }
}
</script>

使用 uView 导航栏

自定义导航栏

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationStyle": "custom"
      }
    }
  ]
}

页面中使用 uView 导航栏：

<template>
  <view>
    <u-navbar 
      title="首页" 
      :border="true"
      :back-icon-color="'#ffffff'"
      :background="{
        background: 'linear-gradient(45deg, #409EFF, #67C23A)'
      }"
    >
      <view slot="right" @click="handleRight">
        <u-icon name="more-dot-fill" color="#ffffff"></u-icon>
      </view>
    </u-navbar>
    
    <!-- 页面内容 -->
  </view>
</template>

<script>
export default {
  methods: {
    handleRight() {
      // 右侧按钮点击事件
    }
  }
}
</script>

使用 uView 返回顶部

<template>
  <view class="container">
    <!-- 长列表内容 -->
    <u-back-top :scroll-top="scrollTop"></u-back-top>
  </view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0
    }
  },
  onPageScroll(e) {
    this.scrollTop = e.scrollTop
  }
}
</script>

TabBar 导航

使用原生 TabBar

{
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#409EFF",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      },
      {
        "pagePath": "pages/user/user",
        "text": "我的"
      }
    ]
  }
}

使用 uView TabBar 组件

<template>
  <view>
    <u-tabbar 
      :list="tabbarList" 
      :mid-button="true"
      @change="tabbarChange"
    ></u-tabbar>
  </view>
</template>

<script>
export default {
  data() {
    return {
      tabbarList: [
        {
          iconPath: "static/tab-home.png",
          selectedIconPath: "static/tab-home-current.png",
          text: "首页",
          pagePath: "/pages/index/index"
        },
        {
          iconPath: "static/tab-user.png",
          selectedIconPath: "static/tab-user-current.png",
          text: "我的",
          pagePath: "/pages/user/user"
        }
      ]
    }
  },
  methods: {
    tabbarChange(index) {
      const pagePath = this.tabbarList[index].pagePath
      uni.switchTab({
        url: pagePath
      })
    }
  }
}
</script>

页面传参

传递参数

// 跳转并传递参数
uni.navigateTo({
  url: '/pages/detail/detail?id=1&name=test'
})

接收参数

<template>
  <view>
    <text>ID: {{ id }}</text>
    <text>Name: {{ name }}</text>
  </view>
</template>

<script>
export default {
  data() {
    return {
      id: '',
      name: ''
    }
  },
  onLoad(options) {
    this.id = options.id
    this.name = options.name
  }
}
</script>

使用 uView 搜索框导航

<template>
  <view>
    <u-search 
      placeholder="搜索内容" 
      v-model="keyword"
      @search="handleSearch"
      @custom="handleCustom"
    ></u-search>
  </view>
</template>

<script>
export default {
  data() {
    return {
      keyword: ''
    }
  },
  methods: {
    handleSearch() {
      uni.navigateTo({
        url: `/pages/search/search?keyword=${this.keyword}`
      })
    },
    handleCustom() {
      // 自定义操作
    }
  }
}
</script>

导航栏返回按钮自定义

<template>
  <view>
    <u-navbar 
      title="详情页"
      :back-icon-name="'arrow-left'"
      @leftClick="handleBack"
    ></u-navbar>
  </view>
</template>

<script>
export default {
  methods: {
    handleBack() {
      // 自定义返回逻辑
      uni.navigateBack({
        delta: 1
      })
    }
  }
}
</script>

注意事项

1. 路径格式：路径必须以 / 开头 2. TabBar 跳转：使用 uni.switchTab 跳转到 tabBar 页面 3. 参数传递：URL 参数需要编码 4. 页面栈：注意页面栈限制（最多 10 层） 5. 返回按钮：自定义导航栏需要自己处理返回逻辑

Pages Configuration

pages.json 配置

在 UniApp 项目中，pages.json 是页面配置文件，需要正确配置以使用 uView UI。

基本配置

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  }
}

使用 uView 导航栏

方式一：使用 uView 导航栏组件

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationStyle": "custom",
        "navigationBarTitleText": "首页"
      }
    }
  ]
}

页面中使用 uView 导航栏：

<template>
  <view>
    <u-navbar title="首页" :border="true"></u-navbar>
    <!-- 页面内容 -->
  </view>
</template>

方式二：使用原生导航栏

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationBarBackgroundColor": "#409EFF",
        "navigationBarTextStyle": "white"
      }
    }
  ]
}

TabBar 配置

{
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#409EFF",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-current.png",
        "text": "首页"
      },
      {
        "pagePath": "pages/user/user",
        "iconPath": "static/tab-user.png",
        "selectedIconPath": "static/tab-user-current.png",
        "text": "我的"
      }
    ]
  }
}

使用 uView TabBar 组件

如果使用 uView 的 TabBar 组件，可以禁用原生 TabBar：

{
  "tabBar": {
    "custom": true,
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      }
    ]
  }
}

页面样式配置

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationBarBackgroundColor": "#409EFF",
        "navigationBarTextStyle": "white",
        "backgroundColor": "#f5f5f5",
        "enablePullDownRefresh": true,
        "onReachBottomDistance": 50
      }
    }
  ]
}

下拉刷新配置

{
  "pages": [
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "列表",
        "enablePullDownRefresh": true
      }
    }
  ]
}

页面中使用 uView 下拉刷新：

<template>
  <view>
    <u-list @refresh="onRefresh" @loadmore="onLoadMore">
      <!-- 列表内容 -->
    </u-list>
  </view>
</template>

<script>
export default {
  methods: {
    onRefresh() {
      // 刷新逻辑
    },
    onLoadMore() {
      // 加载更多逻辑
    }
  }
}
</script>

条件编译配置

不同平台可以有不同的配置：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "// #ifdef H5": {
          "navigationStyle": "custom"
        },
        "// #ifdef MP-WEIXIN": {
          "navigationBarTitleText": "微信首页"
        }
      }
    }
  ]
}

完整示例

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationBarBackgroundColor": "#409EFF",
        "navigationBarTextStyle": "white"
      }
    },
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "列表",
        "enablePullDownRefresh": true
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#409EFF",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      }
    ]
  }
}

注意事项

1. easycom 配置：必须在 pages.json 中配置 easycom 2. 路径正确性：确保组件路径正确 3. 样式配置：合理配置页面样式，与 uView 主题协调 4. 平台差异：注意不同平台的配置差异 5. 性能优化：合理配置下拉刷新和上拉加载

UniApp API Integration

UniApp API 与 uView 整合

在 UniApp 项目中使用 UniApp API 与 uView UI 组件配合使用。

网络请求

使用 uni.request

// 基础请求
uni.request({
  url: 'https://api.example.com/user/info',
  method: 'GET',
  data: {
    id: 1
  },
  success: (res) => {
    console.log(res.data)
    this.$u.toast('请求成功')
  },
  fail: (err) => {
    console.error(err)
    this.$u.toast({
      type: 'error',
      message: '请求失败'
    })
  }
})

配合 uView Loading

<template>
  <view>
    <u-button @click="fetchData">加载数据</u-button>
    <u-loading :show="loading"></u-loading>
  </view>
</template>

<script>
export default {
  data() {
    return {
      loading: false
    }
  },
  methods: {
    fetchData() {
      this.loading = true
      uni.request({
        url: 'https://api.example.com/data',
        success: (res) => {
          this.$u.toast('加载成功')
        },
        fail: (err) => {
          this.$u.toast({
            type: 'error',
            message: '加载失败'
          })
        },
        complete: () => {
          this.loading = false
        }
      })
    }
  }
}
</script>

存储 API

使用 uni.setStorage

// 保存数据
uni.setStorage({
  key: 'token',
  data: 'xxx',
  success: () => {
    this.$u.toast('保存成功')
  }
})

// 获取数据
uni.getStorage({
  key: 'token',
  success: (res) => {
    console.log(res.data)
  }
})

// 移除数据
uni.removeStorage({
  key: 'token',
  success: () => {
    this.$u.toast('删除成功')
  }
})

配合 uView 表单

<template>
  <view>
    <u-form :model="form">
      <u-form-item label="用户名">
        <u-input v-model="form.username"></u-input>
      </u-form-item>
      <u-button @click="saveForm">保存</u-button>
    </u-form>
  </view>
</template>

<script>
export default {
  data() {
    return {
      form: {
        username: ''
      }
    }
  },
  onLoad() {
    // 加载保存的数据
    uni.getStorage({
      key: 'formData',
      success: (res) => {
        this.form = res.data
      }
    })
  },
  methods: {
    saveForm() {
      uni.setStorage({
        key: 'formData',
        data: this.form,
        success: () => {
          this.$u.toast('保存成功')
        }
      })
    }
  }
}
</script>

图片选择

使用 uni.chooseImage

<template>
  <view>
    <u-upload 
      :file-list="fileList"
      @after-read="afterRead"
      @delete="deletePic"
      name="file"
      multiple
      :max-count="9"
    ></u-upload>
  </view>
</template>

<script>
export default {
  data() {
    return {
      fileList: []
    }
  },
  methods: {
    afterRead(event) {
      // 上传图片
      const file = event.file
      uni.uploadFile({
        url: 'https://api.example.com/upload',
        filePath: file.url,
        name: 'file',
        success: (res) => {
          this.$u.toast('上传成功')
        }
      })
    },
    deletePic(event) {
      this.fileList.splice(event.index, 1)
    }
  }
}
</script>

位置信息

使用 uni.getLocation

<template>
  <view>
    <u-button @click="getLocation">获取位置</u-button>
    <view v-if="location">
      <text>经度: {{ location.longitude }}</text>
      <text>纬度: {{ location.latitude }}</text>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      location: null
    }
  },
  methods: {
    getLocation() {
      uni.getLocation({
        type: 'gcj02',
        success: (res) => {
          this.location = res
          this.$u.toast('获取位置成功')
        },
        fail: (err) => {
          this.$u.toast({
            type: 'error',
            message: '获取位置失败'
          })
        }
      })
    }
  }
}
</script>

分享功能

使用 uni.share

<template>
  <view>
    <u-button @click="share">分享</u-button>
  </view>
</template>

<script>
export default {
  methods: {
    share() {
      // #ifdef MP-WEIXIN
      uni.share({
        provider: 'weixin',
        scene: 'WXSceneSession',
        type: 0,
        href: 'https://example.com',
        title: '分享标题',
        summary: '分享描述',
        imageUrl: 'https://example.com/image.png',
        success: () => {
          this.$u.toast('分享成功')
        }
      })
      // #endif
    }
  }
}
</script>

页面生命周期

配合 uView 组件

<template>
  <view>
    <u-list 
      :list="list"
      @refresh="onRefresh"
      @loadmore="onLoadMore"
    ></u-list>
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: []
    }
  },
  onLoad() {
    // 页面加载时获取数据
    this.loadData()
  },
  onShow() {
    // 页面显示时刷新数据
    this.loadData()
  },
  onPullDownRefresh() {
    // 下拉刷新
    this.onRefresh()
  },
  onReachBottom() {
    // 上拉加载
    this.onLoadMore()
  },
  methods: {
    loadData() {
      uni.request({
        url: 'https://api.example.com/list',
        success: (res) => {
          this.list = res.data
        }
      })
    },
    onRefresh() {
      this.loadData()
      setTimeout(() => {
        uni.stopPullDownRefresh()
      }, 1000)
    },
    onLoadMore() {
      // 加载更多逻辑
    }
  }
}
</script>

条件编译

平台特定 API

<template>
  <view>
    <u-button @click="handlePlatform">平台操作</u-button>
  </view>
</template>

<script>
export default {
  methods: {
    handlePlatform() {
      // #ifdef H5
      // H5 平台特定代码
      this.$u.toast('H5 平台')
      // #endif
      
      // #ifdef MP-WEIXIN
      // 微信小程序特定代码
      uni.login({
        success: (res) => {
          this.$u.toast('微信登录')
        }
      })
      // #endif
      
      // #ifdef APP-PLUS
      // App 平台特定代码
      plus.share.sendWithSystem({
        content: '分享内容'
      })
      // #endif
    }
  }
}
</script>

注意事项

1. API 兼容性：注意不同平台 API 的兼容性 2. 权限配置：某些 API 需要在 manifest.json 中配置权限 3. 错误处理：始终处理 API 调用的错误情况 4. 条件编译：使用条件编译处理平台差异 5. 用户体验：配合 uView 组件提供良好的用户反馈

App Platform

App 平台注意事项

在 App 平台（iOS/Android）使用 uView UI 时的特殊注意事项。

manifest.json 配置

{
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app",
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    },
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\"/>"
        ]
      },
      "ios": {}
    }
  }
}

权限配置

Android 权限

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>"
        ]
      }
    }
  }
}

iOS 权限

在 manifest.json 中配置，或在 Xcode 中配置 Info.plist。

原生插件

App 平台可以使用原生插件：

// #ifdef APP-PLUS
// 使用 5+ API
plus.device.getInfo((info) => {
  console.log('设备信息', info)
})

// 使用原生插件
const plugin = uni.requireNativePlugin('your-plugin-name')
// #endif

条件编译

<template>
  <view>
    <!-- #ifdef APP-PLUS -->
    <view>App 平台特有内容</view>
    <!-- #endif -->
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      // #ifdef APP-PLUS
      // App 平台特定代码
      plus.share.sendWithSystem({
        content: '分享内容'
      })
      // #endif
    }
  }
}
</script>

状态栏适配

<template>
  <view>
    <u-navbar 
      title="首页"
      :safe-area-inset-top="true"
    ></u-navbar>
  </view>
</template>

注意事项

1. 权限配置：根据功能需求配置相应权限 2. 原生插件：可以使用原生插件扩展功能 3. 性能优化：App 平台需要注意性能优化 4. 打包配置：正确配置打包参数 5. 版本号：正确配置版本号和版本名称

H5 Platform

H5 平台注意事项

在 H5 平台使用 uView UI 时的特殊注意事项。

manifest.json 配置

{
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    },
    "devServer": {
      "https": false,
      "port": 8080
    },
    "publicPath": "/",
    "template": "index.html"
  }
}

路由模式

H5 支持两种路由模式：

Hash 模式（推荐）

{
  "h5": {
    "router": {
      "mode": "hash"
    }
  }
}

History 模式

{
  "h5": {
    "router": {
      "mode": "history"
    }
  }
}

样式适配

H5 平台需要注意样式适配：

<template>
  <view class="container">
    <u-button type="primary">按钮</u-button>
  </view>
</template>

<style lang="scss" scoped>
.container {
  /* H5 平台特定样式 */
  /* #ifdef H5 */
  min-height: 100vh;
  /* #endif */
  
  /* 通用样式 */
  padding: 20rpx;
}
</style>

条件编译

使用条件编译处理 H5 平台特定逻辑：

<template>
  <view>
    <!-- #ifdef H5 -->
    <view>H5 平台特有内容</view>
    <!-- #endif -->
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      // #ifdef H5
      // H5 平台特定代码
      window.location.href = 'https://example.com'
      // #endif
    }
  }
}
</script>

浏览器兼容性

H5 平台需要考虑浏览器兼容性：

<template>
  <view>
    <u-button @click="checkBrowser">检查浏览器</u-button>
  </view>
</template>

<script>
export default {
  methods: {
    checkBrowser() {
      // #ifdef H5
      const ua = navigator.userAgent
      if (ua.indexOf('Chrome') > -1) {
        this.$u.toast('Chrome 浏览器')
      } else if (ua.indexOf('Safari') > -1) {
        this.$u.toast('Safari 浏览器')
      }
      // #endif
    }
  }
}
</script>

响应式布局

H5 平台可以使用媒体查询：

<style lang="scss" scoped>
.container {
  width: 100%;
  
  /* #ifdef H5 */
  @media (min-width: 768px) {
    max-width: 1200px;
    margin: 0 auto;
  }
  /* #endif */
}
</style>

注意事项

1. 路由模式：推荐使用 hash 模式，兼容性更好 2. 样式单位：H5 平台 rpx 会自动转换为 rem 3. 浏览器兼容：注意不同浏览器的兼容性 4. 性能优化：H5 平台可以使用更多 Web API 5. 调试工具：可以使用浏览器开发者工具调试

Mini-Program Platform

小程序平台注意事项

在微信小程序等小程序平台使用 uView UI 时的特殊注意事项。

manifest.json 配置

{
  "mp-weixin": {
    "appid": "your-appid",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "enhance": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true
  }
}

组件使用

小程序平台需要确保组件正确注册：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  }
}

条件编译

使用条件编译处理小程序平台特定逻辑：

<template>
  <view>
    <!-- #ifdef MP-WEIXIN -->
    <view>微信小程序特有内容</view>
    <!-- #endif -->
  </view>
</template>

<script>
export default {
  methods: {
    handleClick() {
      // #ifdef MP-WEIXIN
      // 微信小程序特定代码
      wx.login({
        success: (res) => {
          this.$u.toast('登录成功')
        }
      })
      // #endif
    }
  }
}
</script>

小程序 API

登录

// #ifdef MP-WEIXIN
wx.login({
  success: (res) => {
    if (res.code) {
      // 发送 res.code 到后台换取 openId, sessionKey, unionId
      this.$u.post('/api/login', {
        code: res.code
      }).then(result => {
        this.$u.toast('登录成功')
      })
    }
  }
})
// #endif

获取用户信息

// #ifdef MP-WEIXIN
wx.getUserProfile({
  desc: '用于完善用户资料',
  success: (res) => {
    this.userInfo = res.userInfo
    this.$u.toast('获取用户信息成功')
  }
})
// #endif

分享

onShareAppMessage() {
  // #ifdef MP-WEIXIN
  return {
    title: '分享标题',
    path: '/pages/index/index',
    imageUrl: '/static/share.png'
  }
  // #endif
}

页面配置

小程序页面需要在 pages.json 中配置：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true
      }
    }
  ]
}

下拉刷新

<template>
  <view>
    <u-list 
      :list="list"
      @refresh="onRefresh"
    ></u-list>
  </view>
</template>

<script>
export default {
  data() {
    return {
      list: []
    }
  },
  onPullDownRefresh() {
    this.onRefresh()
  },
  methods: {
    onRefresh() {
      // 刷新数据
      setTimeout(() => {
        uni.stopPullDownRefresh()
      }, 1000)
    }
  }
}
</script>

注意事项

1. AppID 配置：必须在 manifest.json 中配置正确的 AppID 2. URL 检查：开发时可以关闭 urlCheck 3. 组件注册：确保 easycom 配置正确 4. 页面路径：页面路径必须以 / 开头 5. 代码包大小：注意小程序代码包大小限制

nvue Platform

nvue 平台注意事项

在 nvue 页面使用 uView UI 时的特殊注意事项。

manifest.json 配置

{
  "app-plus": {
    "nvueStyleCompiler": "uni-app",
    "nvue": {
      "flex-direction": "column"
    }
  }
}

样式限制

nvue 平台样式有限制：

<template>
  <view class="container">
    <u-button type="primary">按钮</u-button>
  </view>
</template>

<style lang="scss" scoped>
.container {
  /* nvue 支持的样式 */
  flex-direction: column;
  padding: 20rpx;
  
  /* nvue 不支持的样式需要条件编译 */
  /* #ifndef APP-PLUS-NVUE */
  display: flex;
  /* #endif */
}
</style>

组件兼容性

某些 uView 组件在 nvue 中可能不完全支持，需要使用条件编译：

<template>
  <view>
    <!-- #ifndef APP-PLUS-NVUE -->
    <u-parse :html="content"></u-parse>
    <!-- #endif -->
    
    <!-- #ifdef APP-PLUS-NVUE -->
    <text>{{ content }}</text>
    <!-- #endif -->
  </view>
</template>

Flex 布局

nvue 主要使用 Flex 布局：

<template>
  <view class="container">
    <view class="item">Item 1</view>
    <view class="item">Item 2</view>
  </view>
</template>

<style lang="scss" scoped>
.container {
  flex-direction: row;
  justify-content: space-between;
}

.item {
  flex: 1;
}
</style>

注意事项

1. 样式限制：nvue 不支持所有 CSS 属性 2. 组件兼容：某些组件在 nvue 中可能不完全支持 3. Flex 布局：主要使用 Flex 布局 4. 性能：nvue 性能更好，但功能有限 5. 条件编译：使用条件编译处理兼容性问题

Basic UniApp Project Template

基础 UniApp 项目模板

这是一个基础的 UniApp + uView UI 项目模板。

项目结构

uniapp-uview-project/
├── uni_modules/
│   └── uview-ui/          # uView UI 插件
├── pages/
│   ├── index/
│   │   └── index.vue
│   └── ...
├── static/                # 静态资源
├── App.vue                # 应用入口
├── main.js                # 主入口文件
├── pages.json             # 页面配置
├── manifest.json          # 应用配置
└── uni.scss               # 全局样式变量

App.vue

<template>
  <view id="app">
    <!-- 应用根组件 -->
  </view>
</template>

<script>
export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  onShow: function() {
    console.log('App Show')
  },
  onHide: function() {
    console.log('App Hide')
  }
}
</script>

<style lang="scss">
/* 引入 uView 基础样式 */
@import "uview-ui/index.scss";

/* 全局样式 */
page {
  background-color: #f5f5f5;
}
</style>

main.js

import App from './App'
import uView from 'uview-ui'

// #ifdef VUE3
import { createSSRApp } from 'vue'
export function createApp() {
  const app = createSSRApp(App)
  app.use(uView)
  return {
    app
  }
}
// #endif

// #ifndef VUE3
import Vue from 'vue'
Vue.use(uView)
Vue.config.productionTip = false
App.mpType = 'app'
const app = new Vue({
  ...App
})
app.$mount()
// #endif

pages.json

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  }
}

uni.scss

/* 引入 uView 主题变量 */
@import "uview-ui/theme.scss";

manifest.json

{
  "name": "uniapp-uview-project",
  "appid": "",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true
  },
  "h5": {
    "router": {
      "mode": "hash"
    }
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  }
}

pages/index/index.vue

<template>
  <view class="container">
    <u-navbar title="首页"></u-navbar>
    <view class="content">
      <u-button type="primary" @click="handleClick">点击按钮</u-button>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {}
  },
  methods: {
    handleClick() {
      this.$u.toast('按钮被点击')
    }
  }
}
</script>

<style lang="scss" scoped>
.container {
  min-height: 100vh;
  background-color: #f5f5f5;
}

.content {
  padding: 20rpx;
}
</style>

Manifest Configuration Template

manifest.json 配置模板

UniApp + uView 项目的 manifest.json 配置模板。

完整模板

{
  "name": "uniapp-uview-project",
  "appid": "",
  "description": "UniApp + uView UI 项目",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true,
    "nvueStyleCompiler": "uni-app",
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    },
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.INTERNET\"/>"
        ]
      },
      "ios": {}
    }
  },
  "h5": {
    "router": {
      "mode": "hash",
      "base": "/"
    },
    "devServer": {
      "https": false,
      "port": 8080
    },
    "publicPath": "/",
    "template": "index.html"
  },
  "mp-weixin": {
    "appid": "",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "enhance": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true,
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于小程序位置接口的效果展示"
      }
    }
  },
  "mp-alipay": {
    "usingComponents": true
  },
  "mp-baidu": {
    "usingComponents": true
  },
  "mp-toutiao": {
    "usingComponents": true
  },
  "mp-qq": {
    "usingComponents": true
  },
  "quickapp": {},
  "vueVersion": "3"
}

使用说明

1. appid：小程序平台需要配置对应的 AppID 2. usingComponents：所有平台都需要设置为 true 3. transformPx：建议设置为 false，使用 rpx 4. vueVersion：指定 Vue 版本（2 或 3） 5. 平台配置：根据目标平台配置相应参数

Pages Configuration Template

pages.json 配置模板

UniApp + uView 项目的 pages.json 配置模板。

完整模板

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^u-(.*)": "uview-ui/components/u-$1/u-$1.vue"
    }
  },
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "navigationBarBackgroundColor": "#409EFF",
        "navigationBarTextStyle": "white"
      }
    },
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "列表",
        "enablePullDownRefresh": true
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "详情",
        "navigationStyle": "custom"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp",
    "navigationBarBackgroundColor": "#ffffff",
    "backgroundColor": "#f5f5f5"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#409EFF",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-current.png"
      },
      {
        "pagePath": "pages/user/user",
        "text": "我的",
        "iconPath": "static/tab-user.png",
        "selectedIconPath": "static/tab-user-current.png"
      }
    ]
  },
  "condition": {
    "current": 0,
    "list": [
      {
        "name": "首页",
        "path": "pages/index/index"
      }
    ]
  }
}

使用说明

1. easycom 配置：必须配置，用于自动引入 uView 组件 2. pages 配置：配置所有页面路径和样式 3. globalStyle：配置全局样式 4. tabBar：配置底部导航栏（可选） 5. condition：配置条件编译（开发工具用）