uni-app开发入门手册

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', // 云文件 ID
    success: (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 提供监控和日志功能，可以帮助开发者实时查看云函数的运行状态和性能数据。

• 日志管理：可以通过控制台查看云函数的日志输出，帮助调试和排查问题。

• 性能监控：监控云函数的调用次数、执行时长等，便于优化应用性能。

13.4. 适用场景

• 移动应用：提供后端支持，处理用户请求和数据存储。

• 小程序：快速实现小程序的云端功能，提升用户体验。

• Web 应用：支持动态内容生成和数据管理，便于快速迭代开发。

14. 补充资料

• HBuilderX 编辑器工具：https://www.dcloud.io/hbuilderx.html

• uni-app 官网：https://uniapp.dcloud.net.cn/

• uni 云服务：https://unicloud.dcloud.net.cn

• 插件市场：https://ext.dcloud.net.cn/?vue3=1&type=HotList

• ThorUI：https://ext.dcloud.net.cn/plugin?id=556