# uni-app-x-joke

**Repository Path**: Megasu/uni-app-x-joke

## Basic Information

- **Project Name**: uni-app-x-joke
- **Description**: 这是一个基于 uni-app x 开发的随机笑话应用，用户可以通过点击按钮获取随机笑话，界面简洁美观，支持多端原生打包运行。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 2
- **Created**: 2025-05-16
- **Last Updated**: 2025-08-23

## Categories & Tags

**Categories**: mobile-app

**Tags**: None

## README

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

## 课程介绍

### 你将收获

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

### 适用人群

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

### 课程简介

![应用图标](./screenshot/logo.png)

本课程以「随机笑话」为实战案例，全面解析基于 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、鸿蒙阔折叠(展开)、微信小程序

![运行效果1](./screenshot/screenshot01.png)

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

![运行效果2](./screenshot/screenshot02.png)

### 技术栈

+ 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语言介绍](https://doc.dcloud.net.cn/uni-app-x/uts/index.html)

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

### uni 组件

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

+ `内置基础组件`：如 view、text、image、scroll-view、input... 等，详见[组件清单](https://doc.dcloud.net.cn/uni-app-x/component/index.html)
+ `自定义组件`：开发者自己通过 vue 语法封装的组件。
+ `uts组件插件`：第三方组件，可通过[插件市场](https://ext.dcloud.net.cn/)下载。

## 准备工作

### 开发环境准备

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

### 项目目录结构

```shell
├─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 编译器插件
+ 编译并运行鸿蒙原生应用

## 项目实战

### 效果预览

![桌面图标](./screenshot/screenshot03.png)

![应用运行](./screenshot/screenshot04.png)

### 素材下载

[项目图片素材.zip](https://www.yuque.com/attachments/yuque/0/2025/zip/2735051/1747623334802-848b63f4-0fd7-4578-ad63-0125237a305d.zip)

### 结构和样式

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

布局注意点：

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

参考代码：

```vue
<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](https://hmajax.itheima.net/api/randjoke)
+ 网络请求API：[https://doc.dcloud.net.cn/uni-app-x/api/request.html](https://doc.dcloud.net.cn/uni-app-x/api/request.html)
+ request联网教程：[https://doc.dcloud.net.cn/uni-app-x/tutorial/request.html](https://doc.dcloud.net.cn/uni-app-x/tutorial/request.html)

参考代码：

```vue
<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](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 | 监听页面返回 |

参考代码：

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

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

### 阔折叠屏适配

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

注意事项：

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

效果预览：

![阔折叠效果](./screenshot/screenshot05.png)

参考代码：

```vue
<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](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html#/)，点击"开发与服务"。

2. 在项目页面中点击"添加项目"。
![添加项目](./screenshot/agc01.png)

3. 在"创建项目"页面中输入项目名称后，点击"完成"。
![创建项目](./screenshot/agc02.png)

4. 选择"证书、APP ID和Profile"，在左侧导航栏选择"APP ID"，进入页面后，点击右上角"新建"。
![App ID](./screenshot/agc03.png)

### 鸿蒙调试证书

1. 打开 `manifest.json` 文件，选择"鸿蒙App配置"菜单后，点击调试证书的"配置"按钮。
![鸿蒙App配置](./screenshot/signing01.png)

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

![配置调试证书](./screenshot/signing02.png)

### 鸿蒙发布证书

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

+ 发布证书文件

![发布证书文件](./screenshot/signing03.png)

+ 配置发布证书

![发布证书](./screenshot/signing04.png)

+ 发布证书说明

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

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

## 鸿蒙应用打包和发行

### 鸿蒙应用本地打包

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

![本地打包](./screenshot/package01.png)

### 鸿蒙应用上架

在 AGC 平台上传携带签名信息的 `.app` 安装包，请参加视频讲解或者查看官方文档：[发布HarmonyOS应用（HarmonyOS NEXT）](https://developer.huawei.com/consumer/cn/doc/app/agc-help-harmonyos-releaseapp-0000001914554900)

![上传app包](./screenshot/package02.png)

### 安卓应用云打包(补充)

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

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

![云打包](./screenshot/package03.png)