当前位置：首页 > news >正文

uni-app开发入门手册

news 2025/10/30 8:38:17

1. HBuilderX 的安装

HBuilderX 是一款由 DCloud 开发的高效前端开发工具，专门用于 uni-app 的开发。安装步骤如下：

下载 HBuilderX：访问 DCloud 官网，找到 HBuilderX 下载链接，选择适合自己操作系统的版本。
安装 HBuilderX：下载完成后，运行安装包并按照提示完成安装，安装过程简单，无需复杂设置。
首次启动：安装完成后，打开 HBuilderX，首次启动时可以选择创建一个新项目或打开现有项目。

2. HBuilderX 的使用

HBuilderX 提供了一系列便捷的功能，帮助开发者高效编写代码：

项目管理：通过左侧的项目管理面板，可以方便地创建、删除和管理项目文件。
代码编辑：支持语法高亮、自动补全、智能提示等功能，提升编码效率。
插件支持：可以通过插件市场安装各种插件，扩展编辑器功能，例如代码格式化、版本控制等。
实时预览：支持 H5 和小程序的实时预览，可以在编辑过程中立即看到效果。
调试工具：集成了调试工具，方便开发者进行断点调试和性能分析。

3. 初始化应用步骤

3.1. 创建新项目

打开 HBuilderX，在欢迎界面点击“新建”按钮，选择“uni-app”项目模板。
填写项目信息：在弹出的窗口中输入项目名称、项目路径、项目描述等信息，选择合适的模板。
点击创建：确认信息后点击“创建”，HBuilderX 将自动生成项目目录结构。

3.2. 配置项目

修改 manifest.json：在项目根目录下找到 manifest.json 文件，进行必要的配置，如应用名称、版本号、图标、描述等。
修改 pages.json：配置应用的页面路由，包括页面路径、导航栏样式等。此文件定义了项目的页面结构。

4. 调试应用程序

4.1. 调试 H5

启动 H5 预览：在 HBuilderX 中，点击工具栏的“运行”按钮，选择“运行到浏览器”或直接使用“运行到 Chrome”，启动 H5 版本的应用。
使用调试工具：在浏览器中打开的应用可以使用浏览器自带的开发者工具进行调试，查看控制台输出、网络请求、元素样式等信息。

4.2. 调试微信小程序

设置微信小程序环境：在 HBuilderX 中，需确保安装了微信开发者工具并在 manifest.json 中配置好小程序的 AppID。
运行到微信小程序：点击工具栏的“运行”按钮，选择“运行到微信小程序”。
使用微信开发者工具：HBuilderX 会自动打开微信开发者工具，开发者可以在此环境中调试小程序，包括查看控制台输出、模拟用户交互、监测性能等。

5. uni-app 基础开发

5.1. 项目结构

uni-app 的项目结构通常包含以下几个重要文件和目录：

|/src：存放源代码的目录。
|----/pages：页面目录，每个页面对应一个 .vue 文件。
|----/components：自定义组件目录。
|----/static：存放静态资源。
|manifest.json：项目配置文件，用于配置应用名称、图标、权限等。
|pages.json：页面路由配置文件，定义各个页面的路径和导航。

5.2. 基本页面结构

每个页面的基本结构如下：

<template><view class="container"><text>{{ message }}</text><button @click="handleClick">点击我</button></view>
</template><script>
export default {data() {return {message: 'Hello uni-app!'};},methods: {handleClick() {uni.showToast({title: '按钮被点击了！',icon: 'success'});}}
};
</script><style>
.container {display: flex;justify-content: center;align-items: center;height: 100vh;
}
</style>

6. 常见组件

6.1. 视图组件

<view>：块级容器，用于布局。
<text>：文本组件，用于显示文本。
<button>：按钮组件，用于触发事件。

<view><text>这是一个文本</text><button @click="handleClick">点击</button>
</view>

6.2. 输入组件

<input>：单行输入框。
<textarea>：多行输入框。

<view><input v-model="username" placeholder="请输入用户名" /><textarea v-model="content" placeholder="请输入内容"></textarea>
</view>

7. 常见 API

7.1. 网络请求

使用 uni.request 进行网络请求，示例代码如下：

uni.request({url: 'https://api.example.com/data',method: 'GET',success: (res) => {console.log('请求成功', res.data);},fail: (err) => {console.error('请求失败', err);}
});

7.2. 数据存储

使用 uni.setStorageSync 和 uni.getStorageSync 进行本地存储操作：

// 存储数据
uni.setStorageSync('key', 'value');// 获取数据
const value = uni.getStorageSync('key');
console.log(value); // 'value'

8. Vue3 Composition API 支持

在 uni-app 中，使用 Vue 3 的 Composition API 可以更灵活地组织和管理组件逻辑。以下是一个使用 setup 函数编写 Composition API 的示例，展示了如何在 uni-app 中实现这一特性。

8.1. 基本结构

使用 Composition API 时，所有的逻辑都在 setup 函数中处理。以下是一个简单的示例组件，演示如何使用 setup 创建响应式数据和方法。

示例：待办事项列表

<template><view class="todo-container"><input v-model="newTodo" placeholder="添加待办事项" @confirm="addTodo" /><view v-for="(todo, index) in todos" :key="index" class="todo-item"><text>{{ todo }}</text><button @click="removeTodo(index)">删除</button></view></view>
</template><script>
import { ref, onMounted } from 'vue';export default {setup() {// 响应式数据const newTodo = ref('');const todos = ref([]);// 添加待办事项const addTodo = () => {if (newTodo.value) {todos.value.push(newTodo.value);newTodo.value = '';uni.setStorageSync('todos', todos.value); // 存储到本地}};// 删除待办事项const removeTodo = (index) => {todos.value.splice(index, 1);uni.setStorageSync('todos', todos.value); // 更新本地存储};// 组件挂载时获取本地存储的数据onMounted(() => {const storedTodos = uni.getStorageSync('todos');if (storedTodos) {todos.value = storedTodos; // 初始化时获取本地存储的数据}});// 返回需要在模板中使用的变量和方法return {newTodo,todos,addTodo,removeTodo};}
};
</script><style>
.todo-container {padding: 20px;
}.todo-item {display: flex;justify-content: space-between;margin: 10px 0;
}
</style>

8.2. 关键点解析

响应式数据：使用 ref 创建响应式数据，ref 可以让基本类型的数据变成响应式的。
方法定义：在 setup 中定义的方法可以直接操作响应式数据。
生命周期钩子：使用 onMounted 钩子来执行组件挂载后的逻辑，例如从本地存储获取数据。
返回值：setup 函数的返回值是模板中可用的变量和方法。

9. 页面生命周期

9.1. 页面加载时序介绍

在 uni-app 中，页面的生命周期主要由以下几个关键阶段组成：

页面创建：根据 pages.json 的配置，创建页面，设置原生导航栏和背景色。
DOM 创建：根据页面模板中的组件创建 DOM。注意，静态 DOM 是在首次渲染时处理的，动态生成的 DOM不会在这个阶段创建。
触发 onLoad：此时页面还未显示，不能直接操作 DOM。适合进行数据请求和参数处理。
开始转场动画：新页面进入时，启动转场动画，默认耗时 300ms。
触发 onReady：此时 DOM 已经创建，可以操作 DOM 元素，开始展示首批渲染内容。
转场动画结束：动画完成后，页面完全展示。

9.2. 关键方法和事件

以下是页面生命周期中的重要方法和事件：

9.3. 页面加载常见问题

1. 白屏优化

避免页面 DOM 元素过多，影响加载速度。
在 onLoad 中进行数据请求，不要在 onReady 中请求。
使用简单的占位组件，如 loading 组件或骨架屏，避免空白展示。

2. 卡住动画不启动

大量同步计算会影响转场动画的启动，避免在 onLoad 中执行重计算逻辑。

10. 组件生命周期

uni-app 的组件生命周期与 Vue 标准组件的生命周期相同，不包含页面级的生命周期方法。

以下是组件详细生命周期：

运行示意图如下：

一个APP启动到页面加载到组件加载的执行顺序如下：

App Launch
App Show
Component beforeCreate
Component created
Page onLoad
Page onShow
Component beforeMount
Page onReady
Component mounted

11. 条件编译

11.1. 条件编译简介

条件编译通过特殊注释作为标记，在编译时根据平台进行选择性编译，以满足不同平台的需求。

1. 基本语法

#ifdef：定义条件，仅在指定平台上编译。
#ifndef：反向条件，除指定平台外均编译。
%PLATFORM%：平台名称。

2. 代码示例

仅在 App 平台

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

除 H5 平台外的所有平台

#ifndef H5
// 仅非 H5 平台的代码
#endif

在 H5 或微信小程序平台

#ifdef H5 || MP-WEIXIN
// H5 和微信小程序平台的代码
#endif

11.2. 支持的平台标识及文件类型

1. 平台标识

VUE3：用于区分 vue2 和 vue3。
APP-PLUS、APP-IOS、APP-ANDROID 等，分别用于 App、iOS 和 Android 平台。
MP-WEIXIN、MP-ALIPAY 等小程序平台。

2. 支持的文件类型

.vue、.nvue、.js、.css、.scss 等多种文件。

11.3. 各种条件编译

1. API 的条件编译

在 API 层面，可以用条件编译实现平台特有的 API 调用。例如：

// #ifdef APP-PLUS
uni.showToast({ title: "App 专有功能" });
// #endif

2. 组件的条件编译

在组件层面，条件编译可以控制特定组件仅在指定平台展示。例如，仅在微信小程序中展示公众号关注组件：

<view><!-- #ifdef MP-WEIXIN --><official-account></official-account><!-- #endif -->
</view>

3. 样式的条件编译

在样式层面，也可以使用条件编译来定制特定平台的样式。注意，样式编译需要用 /* 注释 */ 格式。

/* #ifdef APP-PLUS */
body { background-color: blue; }
/* #endif */

4. pages.json 的条件编译

pages.json 支持条件编译，可定义某页面仅在特定平台加载，优化包体积。

{"pages": [{"path": "pages/home/index","style": { /* 仅在 App 平台生效 */ }// #ifdef APP-PLUS// 页面相关配置// #endif}]
}

5. 资源和目录的条件编译

static 目录：可以创建专用目录，放置不同平台的静态资源。如 static/mp-weixin/a.png 仅在微信小程序中编译进项目。
整体目录条件编译：可在根目录创建 platforms 目录，进一步分出 app-plus、mp-weixin 等子目录，专用于不同平台的页面文件。

11.4. HBuilderX 支持

HBuilderX 对 uni-app 的条件编译提供了全面支持：

代码块支持：输入 ifdef 可快速生成代码片段。
语法高亮：提供语法高亮提示，帮助检查写法正确性。
注释快捷键：Ctrl+Alt+/ 生成正确注释（//、/* */、）。
折叠与选中：可以快速折叠或选中条件编译部分的代码。

11.5. 特殊说明

区分 Android 和 iOS：建议使用 uni.getSystemInfo 而非条件编译。
低版本兼容：低于 HBuilderX 3.9 的版本不支持 uniVersion 条件编译。
条件编译 vs 多态：条件编译能有效避免代码冗余，是跨平台适配的更优方案。

12. 应用构建发布与上线

在 uni-app 中，构建和发布应用是一个至关重要的环节。其实发布上线的工作，主要在于平台特性，比如微信小程序的上线，uni-app 构建打包好以后，对应包在小程序后台提交审核。

以下是 uni-app 应用的完整构建、发布和上线流程，包括细节和注意事项。

12.1. 应用构建流程

1. 环境准备

在开始构建之前，需要确保开发环境已正确配置。主要步骤如下：

安装 HBuilderX：下载并安装最新版本的 HBuilderX，这是 uni-app 官方推荐的开发工具。
安装 Node.js：确保本地已安装 Node.js，用于依赖管理和构建。

2. 项目配置

在项目中，确保以下文件配置正确：

manifest.json：配置应用名称、图标、版本号、权限等基本信息。
pages.json：配置应用页面路径、标题、导航栏样式等。

3. 构建应用

在 HBuilderX 中，使用菜单进行构建：

打开项目后，点击菜单中的“发行” => “小程序-微信”或“小程序-支付宝”，根据目标平台进行选择。
在弹出的构建窗口中，选择需要的构建选项，如“压缩”、“加密”等，完成配置后点击“开始发行”。

12.2. 发布流程

不同平台有不同的发布流程，下面以微信和支付宝为例：

1. 微信小程序发布

注册小程序账号：在微信公众平台注册小程序账号，获取 AppID。
上传代码：在 HBuilderX 中构建完成后，使用微信开发者工具打开 dist 目录，进行代码上传。
填写版本信息：在微信公众平台中填写版本信息，设置更新内容和版本号。
提交审核：提交审核，等待审核通过后进行发布。

2. 支付宝小程序发布

注册小程序账号：在支付宝开放平台注册小程序账号，获取 AppID。
上传代码：在 HBuilderX 中构建完成后，使用支付宝开发者工具打开 dist 目录，进行代码上传。
填写版本信息：在支付宝开放平台填写版本信息，设置更新内容和版本号。
提交审核：提交审核，等待审核通过后进行发布。

12.3. 上线工作

1. 上线前的准备

在应用上线之前，确保完成以下准备工作：

功能测试：对应用进行全面测试，确保所有功能正常。
性能优化：检查应用性能，优化加载速度和资源使用，确保用户体验良好。
安全检查：确保应用符合安全标准，避免敏感数据泄露。

2. 上线

在各个平台审核通过后，正式发布应用。
在应用发布后，监控用户反馈和使用情况，及时修复可能出现的问题。

3. 版本迭代

根据用户反馈和需求，定期进行版本迭代和更新。
在每次更新时，遵循相同的发布流程，确保每个版本都经过测试和审核。

13. uni-cloud云开发

uni-cloud 是 DCloud 提供的一种无服务器云服务解决方案，旨在为开发者提供后端支持，简化云端应用的构建和管理。

允许开发者将业务逻辑、数据存储和实时功能迁移到云端，提升开发效率和应用性能。

13.1. 什么是uni-cloud

uni-cloud 是一种无服务器（Serverless）架构的云服务，允许开发者将应用逻辑和数据处理放在云端运行，免去服务器管理的烦恼。

它通过提供一系列强大的后端服务，支持多种应用场景，包括移动应用、Web 应用和小程序。

13.2. 主要特点

无服务器架构：开发者无需管理和维护服务器，云服务按需扩展，降低了运维成本和复杂性。
一站式服务：提供云函数、云数据库、云存储等服务，方便快速构建后端应用。
与 uni-app 深度集成：uni-cloud 与 uni-app 平台紧密结合，简化开发流程，减少配置和学习成本。
支持多种平台：兼容 H5、iOS、Android 和各大主流小程序平台，支持跨平台开发。
高安全性：提供用户身份验证和权限管理，确保数据安全。

13.3. 核心功能

1. 云函数

云函数是 uni-cloud 的核心功能之一，允许开发者编写业务逻辑代码并在云端运行。云函数支持多种触发方式，包括 HTTP 请求、数据库触发器等。

示例代码：创建云函数（工程选择为 uni-cloud）

(1). 在 HBuilderX 中创建云函数：右键项目，选择“新建” => “云函数”，命名为 helloWorld。

(2). 编写 helloWorld/index.js

// helloWorld/index.js
exports.main = async (event, context) => {return {message: 'Hello, uni-cloud!',input: event};
};

(3). 部署云函数，在 HBuilderX 中，右键云函数，选择 "上传到云端"。

(4). 调用云函数

uniCloud.callFunction({name: 'helloWorld',data: { name: 'User' },success: (res) => {console.log(res.result); // 输出: { message: 'Hello, uni-cloud!', input: { name: 'User' } }},fail: (err) => {console.error(err);}
});

2. 云数据库

uni-cloud 提供强大的云数据库服务，支持数据的存储、查询、更新和删除操作。

示例代码：使用云数据库。

(1). 在云函数中操作数据库

// helloWorld/index.js
const db = uniCloud.database();exports.main = async (event, context) => {// 插入数据await db.collection('users').add({name: event.name,createdAt: db.serverDate()});// 查询数据const result = await db.collection('users').get();return {users: result.data};
};

(2). 调用云函数并传递数据

unicloud.callFunction({name: 'helloWorld',data: { name: 'User' },success: (res) => {console.log(res.result.users); // 输出数据库中的用户数据},fail: (err) => {console.error(err);}
});

3. 云存储

uni-cloud 提供云存储服务，可以上传和管理文件，如图片和视频。

示例代码：使用云存储

(1). 上传文件。

const cloudPath = 'images/' + Date.now() + '.jpg'; // 设置云存储路径
const file = ...; // 获取文件对象，例如从相册选择的图片uniCloud.uploadFile({cloudPath: cloudPath,file: file,success: (res) => {console.log('文件上传成功:', res.fileID); // 输出文件 ID},fail: (err) => {console.error('文件上传失败:', err);}
});

(2). 下载文件

uniCloud.downloadFile({fileID: 'cloud://your-cloud-path/file.jpg', // 云文件 IDsuccess: (res) => {console.log('文件下载成功:', res.tempFilePath); // 下载到的文件路径},fail: (err) => {console.error('文件下载失败:', err);}
});

4. 实时数据推送

uni-cloud 支持 WebSocket 实现实时消息推送，适合即时通讯和实时更新场景。

示例代码：实时数据推送

(1). 在云函数中创建 WebSocket 连接。

exports.main = async (event, context) => {const ws = uniCloud.websocket;ws.on('connection', (ws) => {ws.on('message', (message) => {// 处理接收到的消息ws.send('收到消息：' + message);});});
};

(2). 客户端连接 WebSocket。

const socket = uni.connectSocket({url: 'wss://your-websocket-url'
});socket.onOpen(() => {console.log('WebSocket 连接成功');socket.send({ data: 'Hello, WebSocket!' });
});socket.onMessage((res) => {console.log('收到消息:', res.data);
});

5. 监控与分析

uni-cloud 提供监控和日志功能，可以帮助开发者实时查看云函数的运行状态和性能数据。