uni-app x 跨平台实战入门：从 0 到 1 开发 HarmonyOS 5 鸿蒙原生应用

课程介绍

你将收获

• uni-app x 开发原生鸿蒙核心逻辑
• 多端界面适配思维和代码兼容实战
• 从 0 到 1 入门完成可上线的跨平台应用
• 掌握多端应用的开发能力(HarmonyOS Next/Android/iOS/微信小程序/Web)

适用人群

• 鸿蒙应用开发工程师，想切入跨平台领域；
• 想学习鸿蒙、小程序开发但缺乏实战案例的技术爱好者；
• 已学过 uni-app，想要进阶下一代 uni-app x 技术栈的小伙伴；
• 想要一套代码，同时覆盖多端的移动端开发工程师；
• 需快速开发多端应用的企业开发者或创业团队。

课程简介

本课程以「随机笑话」为实战案例，全面解析基于 uni-app x 的跨平台开发流程。通过从环境搭建、功能开发到多端适配的全链路实践，学员将掌握 uni-app x 的核心语法、跨平台组件调用、屏幕适配技巧及多端（HarmonyOS Next/Android/iOS/微信小程序/Web）打包部署能力。课程结合华为折叠屏适配、云打包等真实开发场景，侧重实战落地与前沿技术覆盖，助力开发者快速上手跨平台应用开发并积累项目经验。

课程亮点

1. 实战驱动，即学即用： 以完整开源项目为载体，涵盖从需求分析到上线部署的全流程，避免纯理论堆砌，侧重代码实操与问题解决（如折叠屏适配、多端样式兼容）。
2. 多端适配核心技术拆解： 深度解析 uni-app x 跨平台原理，通过华为折叠屏适配、鸿蒙平台签名配置、兼容性处理等实操，掌握不同设备与平台的差异化适配策略。
3. 前沿技术与生态覆盖： 结合鸿蒙（HarmonyOS Next）开发、Uni TypeScript 语法、SCSS 样式预处理等技术，适配当前跨平台开发趋势。

平台兼容性

• HarmonyOS NEXT(鸿蒙) ✅
• Android(安卓) ✅
• iOS(苹果) ✅
• 微信小程序 ✅
• Web(浏览器) ✅

运行效果

• iPhone 、Android、鸿蒙阔折叠(展开)、微信小程序

• iPhone 、Android、鸿蒙阔折叠(折叠)、微信小程序

技术栈

• UniApp X
• Uni TypeScript
• Vue 3

开发工具

• 操作系统：MacOS 15.4.1
• 编辑器：HBuilder X 4.65
• 鸿蒙开发环境：DevEco Studio 5.0.4 Release
• 安卓开发环境：Android Studio (version 2024.2)
• 苹果开发环境：Xcode Version 16.1 (16B40)
• 浏览器：Chrome 135.0.7049.85

uni-app x

uni-app x 简介

uni-app x，是下一代 uni-app，是一个跨平台应用开发引擎，现已支持编译成 HarmonyOS Next 原生应用(4.61+)

uni-app x 包括 uvue 渲染引擎、uts 语言、uni的组件和API、以及扩展机制。

uvue 渲染引擎

用 vue3 框架快速编写页面，最终编译为不同平台的、高性能的纯原生界面。

1. 模板式写法
2. 数据双向绑定
3. 组件机制

在 HarmonyOS Next 平台，uni-app x 的工程被整体编译为 ArkTS + ArkUI 代码，本质上是换了 vue 写法的原生鸿蒙应用。

uts 语言

uts 全称 uni typescript，是一门强类型的现代编程语言。支持跨平台，最终会被编译为不同平台的 native语言，如：

• web/小程序平台，编译为JavaScript
• 鸿蒙next平台，编译为ArkTS
• Android平台，编译为Kotlin
• iOS平台，编译Swift

uts 和 ts 很相似，但为了跨端，uts 进行了一些约束和特定平台的增补。详见 uts语言介绍

注意：在 ts 中，常通过 interface 或 type 定义对象类型，但在 uts 中，需使用 type 定义对象类型。因为 interface 在 kotlin 和 swift 中有差异。

uni 组件

ni-app x 的组件主要分三类：

• 内置基础组件：如 view、text、image、scroll-view、input… 等，详见组件清单
• 自定义组件：开发者自己通过 vue 语法封装的组件。
• uts组件插件：第三方组件，可通过插件市场下载。

准备工作

开发环境准备

• 下载安装 HBuilderX 编辑器
• 通过 HbuilderX 创建 uni-app x 项目

项目目录结构

├─pages             业务页面文件存放的目录
│  └─index
│     └─index.uvue  index页面
├─static            存放应用引用的本地静态资源的目录(注意：静态资源只能存放于此)
├─unpackage         非工程代码，一般存放运行或发行的编译结果
├─index.html        H5端页面
├─main.uts          Vue初始化入口文件
├─App.uvue          应用配置，用来配置App全局样式以及监听
├─pages.json        配置页面路由、导航条、选项卡等页面类信息
├─manifest.json     配置应用名称、appid、logo、版本等打包信息
└─uni.scss          uni-app内置的常用样式变量

编译运行

• 安装 uni-app x 编译器插件
• 编译并运行鸿蒙原生应用

项目实战

效果预览

素材下载

项目图片素材.zip

结构和样式

使用 uni-app x 组件库实现项目基本布局。

布局注意点：

• view 组件默认是 flex 模式且方向是垂直 column
• uni-app x 样式不会继承，文字需要用 text 包裹并单独设置字体样式

参考代码：

<template>
  <view class="container">
    <!-- 卡片容器 -->
    <view class="card">
      <!-- 头部标题 -->
      <view class="header">
        <text class="header-text">随机笑话</text>
      </view>
      <!-- 滚动内容区 -->
      <scroll-view class="scroll-content">
        <text class="scroll-content-text">笑话加载中...</text>
      </scroll-view>
      <!-- 底部按钮 -->
      <view class="footer">
        <button class="footer-button" @click="getJoke()">换一个</button>
      </view>
    </view>
  </view>
</template>

<style lang="scss">
  .container {
    /* 注意点1: view 默认是 flex，方向是 column */
    /* display: flex; */
    /* flex-direction: column;  */
    /* 注意点2：uni-app x 样式不会继承，文字需要用 text 包裹并单独设置字体样式 */
    /* font-size: 100rpx; */
    flex: 1;
    justify-content: center;
    align-items: center;
    background-color: #f6f6f6;
  }

  .card {
    width: 90%;
    border-radius: 20rpx;
    /* 1. 盒子阴影  X 轴偏移量、Y 轴偏移量、模糊半径 和 颜色 */
    box-shadow: 0 10rpx 30rpx #a7b3f9;
    /* iOS 端存在兼容问题，需要主动设置为白色 */
    background-color: #fff;
  }

  .header {
    background-color: #1534f5;
    height: 110rpx;
    padding: 0 30rpx;
    /* iOS 端圆角不受父级约束，需要主动设置圆角 */
    border-radius: 20rpx 20rpx 0 0;

    /* 2. 主轴垂直方向居中 */
    justify-content: center;

    /* 3. style 添加 lang="scss" 后，支持类名嵌套 */
    /* 4. 文字不能继承，需要给 text 定义类名修改 */
    .header-text {
      font-size: 28rpx;
      font-weight: 700;
      color: #fff;
    }
  }

  .scroll-content {
    padding: 40rpx 30rpx;
    /* 5. 最小高度 */
    min-height: 300rpx;

    .scroll-content-text {
      font-size: 30rpx;
      color: #3204ac;
      line-height: 45rpx;
    }
  }

  .footer {
    /* 6. 水平靠右对齐 */
    align-items: flex-end;
    padding-bottom: 20rpx;
    padding-right: 20rpx;

    .footer-button {
      background-color: #1534f5;
      color: #fff;
      font-size: 26rpx;
      border-radius: 50rpx;
      padding: 6rpx 30rpx;
    }
  }
</style>

业务逻辑

• 笑话接口：https://hmajax.itheima.net/api/randjoke
• 网络请求API：https://doc.dcloud.net.cn/uni-app-x/api/request.html
• request联网教程：https://doc.dcloud.net.cn/uni-app-x/tutorial/request.html

参考代码：

<script setup lang="uts">
  import { ref } from 'vue'

  const jokeText = ref('笑话加载中...')

  // 注意：uni-app x 需要用 type 定义对象类型，用 interface 存在兼容问题
  type ServiceData = {
    message : string
    data : string
  }

  function getJoke() {
    // 通过范型指定后端返回的数据类型
    uni.request<ServiceData>({
      url: 'https://hmajax.itheima.net/api/randjoke',
      method: 'GET',
      success: (res) => {
        // 兼容安卓端类型的写法
        const jokeStr = res.data?.data
        if (jokeStr !== null) {
          jokeText.value = jokeStr
        }
      },
      fail: () => {
        jokeText.value = '数据获取失败，请检查网络...'
      }
    })
  }
</script>

<template>
  <view class="container">
    <view class="card">
      <view class="header">
        <text class="header-text">随机笑话</text>
      </view>
      <scroll-view class="scroll-content">
        <text class="scroll-content-text">{{ jokeText }}</text>
      </scroll-view>
      <view class="footer">
        <button class="footer-button" @click="getJoke()">换一个</button>
      </view>
    </view>
  </view>
</template>

生命周期

页面生命周期

页面生命周期：https://doc.dcloud.net.cn/uni-app-x/page.html#lifecycle

组合式	选项式	描述
onLoad	onLoad	生命周期回调 监听页面加载 页面加载时触发。一个页面只会调用一次，可以在 onLoad 的参数中获取打开当前页面路径中的参数。
onPageShow	onShow	生命周期回调 监听页面显示 页面显示/切入前台时触发。
onReady	onReady	生命周期回调 监听页面初次渲染完成 页面初次渲染完成时触发。一个页面只会调用一次，代表页面已经准备妥当，可以和视图层进行交互。
onPageHide	onHide	生命周期回调 监听页面隐藏 页面隐藏/切入后台时触发。 如 navigateTo或底部 tab切换到其他页面，应用切入后台等。
onUnload	onUnload	生命周期回调 监听页面卸载 页面卸载时触发。如 redirectTo或 navigateBack到其他页面时。
onResize	onResize	页面尺寸改变时触发
onBackPress	onBackPress	监听页面返回

参考代码：

<script setup lang="uts">
  // ...前面代码省略

  // 页面加载时
  onLoad(() => {
    // 获取笑话
    getJoke()
  })
</script>

阔折叠屏适配

• 获取窗口信息：https://doc.dcloud.net.cn/uni-app-x/api/get-window-info.html

注意事项：

• vh 单位只能用于 微信小程序端 和 Web 端，HarmonyOS、Android、iOS 端均不支持
• max-height、min-height 等属性兼容多端只能使用 数字 或 px 单位

效果预览：

参考代码：

<script setup lang="uts">
  // ...省略其他代码
  
  // 同步获取窗口信息，返回的单位 px
  const windowInfo = uni.getWindowInfo()
</script>

<template>
  <view class="container">
    <view class="card">
      <view class="header">
        <text class="header-text">随机笑话</text>
      </view>
      <!-- 滚动内容区 -->
      <scroll-view class="scroll-content" :style="{ maxHeight: windowInfo.screenHeight * 0.66 + 'px' }">
        <text class="scroll-content-text">{{ jokeText }}</text>
      </scroll-view>
      <view class="footer">
        <button class="footer-button" @click="getJoke()">换一个</button>
      </view>
    </view>
  </view>
</template>

<style lang="scss">

  .scroll-content {
    padding: 40rpx 30rpx;
    // 5. 最小高度
    min-height: 300rpx;
    // vh 单位只能用于 微信小程序端 和 Web 端，max-height、min-height 只支持 数字 或 px 单位
    /* #ifdef MP-WEIXIN || WEB */
    max-height: 66vh; /* 最大高度，屏幕高度 66% */
    /* #endif */
  }
</style>

鸿蒙应用签名证书

• 鸿蒙调试证书，用于真机调试
• 鸿蒙发布证书，用于发布上架
• AGC 平台创建项目和应用
• HBuilderX 配置鸿蒙调试证书

鸿蒙签名证书

DevEco Studio	Hbuilder	备注
storeFile	私钥库文件	.p12
storePassword	私钥库密码	·······
keyAlias	私钥别名	debugKey / releaseKey
keyPassword	私钥密码	·······
profile	签名描述文件	.p7b
certpath	证书文件	.cer

AGC 平台创建项目和应用

这里步骤较多，请耐心检查每个步骤，直到完成应用创建。

1. 登录AppGallery Connect，点击"开发与服务"。

2. 在项目页面中点击"添加项目"。
   

3. 在"创建项目"页面中输入项目名称后，点击"完成"。
   

4. 选择"证书、APP ID和Profile"，在左侧导航栏选择"APP ID"，进入页面后，点击右上角"新建"。
   

鸿蒙调试证书

1. 打开 manifest.json 文件，选择"鸿蒙App配置"菜单后，点击调试证书的"配置"按钮。
   

2. 在配置调试证书中，检查"应用包名"，"运行设备"无误后，点击 “自动申请调试证书” 按钮。

鸿蒙发布证书

鸿蒙发布证书不能自动生成，步骤流程较多，请参考视频讲解，耐心检查每个步骤，直到完成配置。

• 发布证书文件

• 配置发布证书

• 发布证书说明

签名描述文件 .p7b 因包含包名信息不能复用，其他证书文件均可在多个项目复用，请牢记私钥别名和密码。

DevEco Studio	Hbuilder	备注
storeFile	私钥库文件	.p12
storePassword	私钥库密码	·······
keyAlias	私钥别名	debugKey / releaseKey
keyPassword	私钥密码	·······
profile	签名描述文件	.p7b
certpath	证书文件	.cer

鸿蒙应用打包和发行

鸿蒙应用本地打包

在配置鸿蒙发布证书后，就可以进行鸿蒙应用本地打包，最终生成一个携带签名信息的 .app 安装包。

鸿蒙应用上架

在 AGC 平台上传携带签名信息的 .app 安装包，请参加视频讲解或者查看官方文档：发布HarmonyOS应用（HarmonyOS NEXT）

安卓应用云打包(补充)

安卓应用可直接使用云证书完成打包，最终生成一个携带签名信息的 .apk 安装包。

用户可把 apk 上架到各个安卓应用商店。