|-------|----------|--------------------------|
| 文档版本 | 更新日期 | 更新内容 |
| 1.0.0 | 2026/6/3 | 1.app打包Android流程及兼容性问题适配 |
背景
开发环境
-
开发工具: Visual Studio Code/HBuilderX5.0.7
-
部署目标: cli编译器版本：3.3.13/vue 2
基础配置
1.将三方分包集成到当前框架项目里面（框架源码）
暂时无法在飞书文档外展示此内容
分包文件及路由配置保持跟微信小程序集成方式一样
2.三方分包适配app兼容性
uni-app能实现一套代码、多端运行，适配App兼容性问题主要是使用条件编译
条件编译是用特殊的注释作为标记，在编译时根据这些特殊的注释，将注释里面的代码编译到不同平台。
写法： 以 #ifdef 或 #ifndef 加**%PLATFORM%** 开头，以 #endif 结尾。
-
#ifdef：if defined 仅在某平台存在
-
#ifndef：if not defined 除了某平台均存在
-
%PLATFORM%：平台名称
|------------------------------------------|-------------------------------------------------|
| 条件编译写法 | 说明 |
| #ifdef APP-PLUS 需条件编译的代码 #endif | 仅出现在 App 平台下的代码 |
| #ifndef H5 需条件编译的代码 #endif | 除了 H5 平台，其它平台均存在的代码 |
| #ifdef H5 || MP-WEIXIN 需条件编译的代码 #endif | 在 H5 平台或微信小程序平台存在的代码（这里只有||，不可能出现&&，因为没有交集） |
运行及调试App
++uniapp运行及编译可以参考++ ++官方文档++
1.连接设备
1.1Android设备连接
运行App到手机或模拟器：打开安卓手机设置里面的开发者模式，设置中开启USB调试，手机上允许电脑设备调试手机，进入项目，点击工具栏的运行 -> 运行App到手机或模拟器，可以看到运行设备名称,即可在设备上运行
2.Chrome及Safari调试app界面模式
主要功能是审查元素/控制台/断点相关功能，需要安卓手机开启调试模式（初试需要翻墙），参考官方配置
chrome调试地址：chrome://inspect/#devices,界面如下，左边是连接设备及展示页面，右边是审查的页面元素相关信息。
App发包
HBuilderX提供了离线打包和云端打包，本项目主要是通过HBuilderX云端发包到处ipa和apk包，详细发包流程参考文档
1.Android发包配置及导出apk
主要是包括包名和证书配置信息（证书别名，证书密钥，证书路径，在生成证书的过程中获取参考基础配置）。
配置信息填完，右下角提交打包即可生成apk文件
1.1 当前项目已经生成好证书文件
安卓证书文件名android.keystore，所在目录当前项目里面public/cert目录下
证书私钥密码123456
App兼容性适配
1、首页自定义导航栏高度适配
自定义首页导航栏使用到了悬浮按钮获取其布局相关信息，查询api，不支持APP。
使用条件编译方法，单独适配app获取原生导航栏布局相关信息
2、在发送验证码界面template里面单独适配
使用条件编译，只有非app走相关属性设
3、打开分享图片弹窗适配
微信小程序自带分享，uniapp支持的系统分享
// #ifndef APP-PLUS
uni.showShareImageMenu({
path: res.tempFilePath
})
// #endif
// #ifdef APP-PLUS
uni.shareWithSystem({
imageUrl:res.tempFilePath
})
// #endif4、基本数据类型定义规范
子组件props定义参数类型如果是Number,如果赋值的时候字符串类型，则App里面会提示错误，需按照属性类型传值,下面需要将返回的字符串转成Number类型
...
<view v-if="i.score">
<stars :ratingNum="i.score ? Number(i.score.toFixed(1)) : 0"></stars>
</view>
...
...
props:{
ratingNum:{
type:Number
},
}
...5、空对象上操作属性适配
在App运行会很明显出现空对象操作问题导致界面异常常见的有:
1.如果对象为undefined或者null, 需要做非空判断导致报错Error in render: "TypeError: Cannot read property 'length' of undefined"。
<view class="block" v-if="detail && detail.length"></view>6、图表echarts适配小程序与App端
app端主要是通过renderjs，在app和h5端使用完整的 echarts，或者考虑全端兼容插件uCharts
<script module="echarts" lang="renderjs">
let myChart
export default {
mounted() {
if (typeof window.echarts === 'function') {
console.log('function')
this.initEcharts()
} else {
console.log('script')
// 动态引入较大类库避免影响页面展示
const script = document.createElement('script')
// view 层的页面运行在 www 根目录，其相对路径相对于 www 计算
script.src = './static/echarts.js'
script.onload = this.initEcharts.bind(this)
document.head.appendChild(script)
}
},
methods: {
initEcharts() {
myChart = echarts.init(document.getElementById('echarts'))
console.log('myChart:',myChart)
// 观测更新的数据在 view 层可以直接访问到
myChart && myChart.setOption(this.options)
},
updateEcharts(newValue, oldValue, ownerInstance, instance) {
// 监听 service 层数据变更
myChart && myChart.setOption(newValue)
},
onClick(event, ownerInstance) {
// 调用 service 层的方法
ownerInstance.callMethod('onViewClick', {
test: 'test'
})
}
}
}
</script>7、scroll-view组件水平滚动App上滑动适配
在app上scroll-view组件添加css样式overflow-x与overflow-y属性会导致无法左右滑动的问题
/* #ifndef APP-PLUS */
overflow-x: auto;
overflow-y: hidden;
/* #endif */8、数据绑定未生效
某些情况在app里面数据双向绑定后，在js里面刷新数据，view层没有刷新，此时须$forceUpdate()强制刷新才行。