07.2.4.3 条件编译与多端差异适配
所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.2 跨平台移动开发 / 07.2.4 uni-app
本节要解决的问题
- 条件编译到底是编译期裁剪还是运行时分支,为什么它比运行时判断更彻底?
#ifdef、#ifndef、#endif的语义差异,以及在 template、script、style、json 中怎么写?- 平台标识有哪些(APP-PLUS、APP-ANDROID、APP-IOS、H5、MP-WEIXIN、MP-ALIPAY 等),如何组合?
- rpx 的换算机制是什么,为什么设计稿要用 750 宽?
- 安全区、字体、滚动条、单位差异在各端怎么统一?
- 生命周期与 API 能力差异在各端有哪些,如何兜底?
- 如何设计适配层,把差异收敛到一处,避免条件编译散落在业务里?
版本前提:本页平台标识清单以官方文档(uniapp.dcloud.net.cn/tutorial/platform.html)为基线,具体标识名与支持范围随版本更新,标注待确认处需按项目实际版本核对。
覆盖范围
| 知识域 | 关键内容 |
|---|---|
| 条件编译语法 | #ifdef/#ifndef/#endif、平台标识、各文件类型写法 |
| 编译期 vs 运行期 | 裁剪时机、产物体积、调试差异 |
| 样式适配 | rpx 换算、安全区、单位、字体、滚动条 |
| 生命周期差异 | 应用/页面/组件在各端的时机映射 |
| API 差异与兜底 | 能力缺失、返回值差异、降级策略 |
| 适配层设计 | 差异收敛、条件编译滥用、踩坑与排查 |
题号索引
| 题号区间 | 主题 |
|---|---|
| 001-002 | 条件编译概念、#ifdef/#ifndef/#endif 语义 |
| 003-004 | 平台标识清单、组合写法 |
| 005-007 | template/script/style/json 中的条件编译 |
| 008 | 编译期裁剪 vs 运行时判断 |
| 009-011 | rpx、安全区、单位与字体差异 |
| 012-013 | 生命周期差异、API 能力差异与兜底 |
| 014-016 | 适配层设计、条件编译滥用、典型踩坑 |
| 017-018 | 综合:适配层组织、样式错位排查 |
07.2.4.3-001 条件编译解决什么问题?
一句话结论
条件编译让同一份源码在构建时按目标端保留或裁剪代码段,是 uni-app 处理"同一功能在不同端实现不同"的核心机制;它在编译期把差异代码从产物中剔除,而不是运行时判断后分支。
概念解释
跨端框架的根本矛盾是:业务希望"一套代码",但各端 API、组件样式、布局规则、权限模型都不同。如果用运行时 if (平台 == 'weixin') 做分支,差异代码会全部打进产物,且运行时判断有分支成本、调试链路长。条件编译把这个判断提前到构建期:构建微信小程序时,非微信代码直接从产物里删掉,产物里只有微信需要的代码。
条件编译的本质是"注释式预处理":用特殊注释包裹差异代码,编译器识别这些注释,按目标端决定保留还是删除。它不是运行时功能,不会在产物里留下判断逻辑。
原理流程
源码(含条件编译注释)
↓ 构建目标端 = MP-WEIXIN
编译器识别 #ifdef MP-WEIXIN 块 → 保留
↓ 其他端块
#iifdef H5 块 → 删除(不进入产物)
↓
产物里只有微信需要的代码
代码或图示
| 方式 | 差异代码进入产物 | 运行时判断 | 适用 |
|---|---|---|---|
| 条件编译 | 否(裁剪) | 无 | 端 API、组件、布局差异 |
| 运行时判断 | 是 | 有 | 运行时才知道的分支 |
常见误区
- 误区:条件编译是运行时判断;正解:它是编译期裁剪,产物里没有被裁掉的代码。
- 误区:条件编译能解决所有差异;正解:运行时才能确定的分支(如设备型号、屏幕尺寸)仍需运行时判断。
追问
- Q:条件编译会增加构建时间吗?A:预处理本身成本很低,主要成本在编译器识别注释,不是构建瓶颈。
- Q:条件编译后的产物能看到吗?A:能,构建产物目录里各端工程的代码就是裁剪后的结果。
07.2.4.3-002 #ifdef、#ifndef、#endif 的语义是什么?
一句话结论
#ifdef 平台 表示"如果是该平台则保留",#ifndef 平台 表示"如果不是该平台则保留",#endif 表示条件块结束;多平台用 || 分隔(如 #ifdef H5 || MP-WEIXIN)。
概念解释
#ifdef 是 if defined 的缩写:定义了这个平台标识就保留。#ifndef 是 if not defined:不是这个平台就保留。两者都用 #endif 收尾。多平台组合用 ||(或)连接,不能用 &&(与),因为一个构建产物只能对应一个目标端。
嵌套是允许的,但嵌套会降低可读性,建议扁平化。注意 #ifndef 容易误用:它不是"排除某平台",而是"在非该平台时保留"。
原理流程
#ifdef MP-WEIXIN
仅微信保留
#endif
#ifndef MP-WEIXIN
除微信外都保留(H5/App/其他小程序)
#endif
#ifdef H5 || MP-WEIXIN
H5 或微信都保留
#endif
代码或图示
| 写法 | 语义 |
|---|---|
| #ifdef MP-WEIXIN | 仅微信小程序 |
| #ifndef MP-WEIXIN | 非微信(H5/App/其他小程序) |
| #ifdef H5 || MP-WEIXIN | H5 或微信 |
| #ifdef APP-PLUS | 所有 App(Android + iOS) |
常见误区
- 误区:
#ifndef MP-WEIXIN是"在微信时不保留",用于排除微信;正解:它是"非微信时保留",语义相反但效果类似,注意命名。 - 误区:多平台用
&&;正解:一个构建只对应一个端,&&无意义,用||。
追问
- Q:能同时判断"是 App 且是 Android"吗?A:用
#ifdef APP-ANDROID,它比 APP-PLUS 更具体。 - Q:条件块能写多行吗?A:能,从
#ifdef到#endif之间都是条件范围。
07.2.4.3-003 平台标识有哪些?
一句话结论
常用标识分四类:App 端(APP-PLUS、APP-ANDROID、APP-IOS)、H5(H5)、小程序(MP-WEIXIN、MP-ALIPAY、MP-BAIDU、MP-TOUTIAO、MP-QQ、MP-360)、快应用(QUICKAPP-WEBVIEW-*);完整清单以官方文档为准,标注待确认。
概念解释
APP-PLUS 是 App 端总称(所有 App 构建都带这个标识),APP-ANDROID 与 APP-IOS 是更细的平台标识,用于区分双端。H5 是浏览器端。MP- 前缀是各小程序平台:MP-WEIXIN 微信、MP-ALIPAY 支付宝、MP-BAIDU 百度、MP-TOUTIAO 字节跳动(抖音)、MP-QQ 腾讯 QQ。
注意:一个构建产物只会命中一个标识。构建微信小程序时,#ifdef MP-WEIXIN 命中,#ifdef H5 不命中。如果不确定某标识是否存在,查官方文档"平台支持"页,不要凭记忆写。
还有一个细节是 APP-PLUS 与 APP-ANDROID/APP-IOS 的关系:构建 Android App 时,APP-PLUS 与 APP-ANDROID 同时命中;构建 iOS App 时,APP-PLUS 与 APP-IOS 同时命中。所以"所有 App 通用"用 APP-PLUS,"仅 Android"用 APP-ANDROID,"仅 iOS"用 APP-IOS。
原理流程
构建目标端 → 命中对应标识
├─ App Android → APP-PLUS + APP-ANDROID
├─ App iOS → APP-PLUS + APP-IOS
├─ H5 → H5
├─ 微信小程序 → MP-WEIXIN
└─ 支付宝小程序 → MP-ALIPAY
代码或图示
| 标识 | 含义 | 典型用途 |
|---|---|---|
| APP-PLUS | 所有 App | 双端通用 |
| APP-ANDROID | Android App | Android 特有 |
| APP-IOS | iOS App | iOS 特有 |
| H5 | 浏览器 | H5 特有 |
| MP-WEIXIN | 微信小程序 | 微信特有 |
| MP-ALIPAY | 支付宝小程序 | 支付宝特有 |
| MP-TOUTIAO | 字节跳动小程序 | 抖音特有 |
常见误区
- 误区:APP-PLUS 只指 Android;正解:它是所有 App 的总称,区分双端用 APP-ANDROID/APP-IOS。
- 误区:一个标识名写错了编译器会报错;正解:写错通常静默不保留,不会报错,要查文档核对。
追问
- Q:如何查某端是否支持某标识?A:官方文档"条件编译"页有完整标识表,标注待确认的以文档为准。
- Q:App 端条件编译能区分 Android/iOS 吗?A:能,用 APP-ANDROID/APP-IOS。
07.2.4.3-004 在 template 中怎么写条件编译?
一句话结论
在 template 中用 HTML 注释包裹:<!-- #ifdef 平台 --> 到 <!-- #endif -->,包裹的标签在目标端保留,其他端从模板中删除。
概念解释
template 是 HTML/Vue 模板,条件编译用 HTML 注释语法。包裹的标签在编译时按端保留或删除,不影响 DOM 结构与事件绑定。注意:条件编译块要包裹完整标签,不能只包裹标签的一部分属性(属性级差异用 class 或 style 绑定)。
典型场景:微信小程序需要一个自定义导航栏,H5 用浏览器默认导航;用条件编译把自定义导航组件包起来,H5 端不渲染。
原理流程
<template>
<view>
<!-- #ifdef MP-WEIXIN -->
<custom-navbar />
<!-- #endif -->
<content />
</view>
</template>
代码或图示
| 写法 | 作用 |
|---|---|
<!-- #ifdef MP-WEIXIN --> |
仅微信保留 |
<!-- #ifndef H5 --> |
非 H5 保留 |
<!-- #endif --> |
结束 |
常见误区
- 误区:条件编译能包裹属性;正解:属性级差异用
:class或:style运行时判断,模板条件编译只包裹完整标签。 - 误区:条件编译块里能写多个标签;正解:能,但建议整块语义完整,便于阅读。
追问
- Q:条件编译块里能写 v-if 吗?A:能,两者不冲突,但条件编译是编译期裁剪,v-if 是运行时显示。
- Q:模板里条件编译会留空节点吗?A:被裁掉的标签完全不进入产物,不留空节点。
07.2.4.3-005 在 script 中怎么写条件编译?
一句话结论
在 script 中用 JS 注释包裹:// #ifdef 平台 到 // #endif,包裹的代码在目标端保留,其他端从 JS 产物中删除。
概念解释
script 是 JS/TS 代码,条件编译用行注释 //。典型场景:微信小程序登录用 wx.login(),App 端用 uni.login() 的 provider 参数,差异在 service 层用条件编译包裹。
注意:条件编译块里的变量、函数在其他端不存在,跨端调用时要确保两端都有对应实现,否则运行时 ReferenceError。
原理流程
// #ifdef MP-WEIXIN
const code = await wx.login()
// #endif
// #ifdef APP-PLUS
const code = await uni.login({ provider: 'weixin' })
// #endif
代码或图示
| 写法 | 作用 |
|---|---|
// #ifdef MP-WEIXIN |
仅微信保留 |
// #ifndef H5 |
非 H5 保留 |
// #endif |
结束 |
常见误区
- 误区:条件编译能在函数中间包裹一段;正解:能,但要保证两端函数签名一致,否则其他端调用时函数不存在。
- 误区:TS 里条件编译不生效;正解:TS 是编译前预处理,条件编译对 TS 同样生效。
追问
- Q:条件编译块里 import 能裁剪吗?A:能,import 语句也可以被条件编译包裹,其他端不会引入该模块。
- Q:如何避免两端函数签名不一致?A:在适配层定义统一接口,内部条件编译分支,业务侧只调统一接口。
07.2.4.3-006 在 style 中怎么写条件编译?
一句话结论
在 style 中用 CSS 注释包裹:/* #ifdef 平台 */ 到 /* #endif */,包裹的样式在目标端保留,其他端从样式产物中删除。
概念解释
style 是 CSS,条件编译用块注释 /* */。典型场景:微信小程序导航栏高度不同,App 端需要安全区,用条件编译写不同 padding。
注意:CSS 选择器与属性级差异也可以用条件编译,但更常见的做法是用 CSS 变量或 class 切换,条件编译只用于"完全不同的样式规则块"。
原理流程
.content {
padding: 20rpx;
/* #ifdef APP-PLUS */
padding-top: 88rpx;
/* #endif */
}
代码或图示
| 写法 | 作用 |
|---|---|
/* #ifdef MP-WEIXIN */ |
仅微信保留 |
/* #ifndef H5 */ |
非 H5 保留 |
/* #endif */ |
结束 |
常见误区
- 误区:style 里用
//注释;正解:CSS 不支持行注释,必须用/* */。 - 误区:条件编译能写在 scoped style 里;正解:能,scoped 不影响条件编译。
追问
- Q:样式差异优先用条件编译还是 CSS 变量?A:小差异用 CSS 变量或 class,大块规则差异用条件编译。
- Q:App 端安全区样式怎么写?A:用
env(safe-area-inset-bottom)或条件编译写固定 padding,具体以官方文档为准。
07.2.4.3-007 在 json(pages.json/manifest.json)中怎么写条件编译?
一句话结论
json 文件不支持注释,uni-app 用 /* #ifdef 平台 */ 块注释语法做条件编译,包裹 JSON 片段,构建时按端裁剪;注意逗号位置必须正确。
概念解释
pages.json 与 manifest.json 是 JSON,本身不支持注释。uni-app 提供了一种特殊的注释语法:/* #ifdef MP-WEIXIN */ 包裹 JSON 片段,编译器识别后保留或裁剪。
典型场景:微信小程序 tabBar 需要某配置,H5 不需要;用条件编译把 tabBar 的差异字段包起来。关键是 JSON 逗号:被裁掉的字段前面不能有多余逗号,否则 JSON 解析失败。
原理流程
{
"tabBar": {
"color": "#999",
/* #ifdef MP-WEIXIN */
"backgroundColor": "#fff",
/* #endif */
"list": []
}
}
代码或图示
| 写法 | 作用 |
|---|---|
/* #ifdef MP-WEIXIN */ |
仅微信保留 |
/* #endif */ |
结束 |
| 逗号位置 | 关键,否则 JSON 解析失败 |
常见误区
- 误区:json 里用
//注释;正解:JSON 不支持行注释,用/* */。 - 误区:条件编译裁掉字段后逗号留着;正解:被裁掉的字段如果后面有逗号,要把逗号也包进条件块,否则 JSON 解析失败。
追问
- Q:json 条件编译失败怎么排查?A:构建报错或配置不生效,先看 JSON 逗号,再看注释位置。
- Q:manifest.json 也支持吗?A:支持,语法与 pages.json 一致。
07.2.4.3-008 编译期裁剪与运行时判断怎么取舍?
一句话结论
编译期条件编译用于"端确定、实现完全不同"的差异(API 调用、组件、布局);运行时判断用于"运行时才知道的分支"(设备型号、屏幕尺寸、用户配置);两者互补,不互斥。
概念解释
编译期裁剪的优势是产物干净、无分支成本;劣势是构建时才知道端,不能处理运行时变化。运行时判断的优势是灵活;劣势是差异代码全部打进产物,且有分支成本。
判断标准:如果差异在"构建时目标端"维度上就能确定(如微信 vs H5),用条件编译;如果差异在"运行时设备/环境"维度上(如 iPhone 刘海屏 vs Android 全面屏),用运行时判断(uni.getSystemInfoSync)。
原理流程
差异维度
├─ 构建时目标端(微信 vs H5)→ 条件编译
├─ 运行时设备(刘海屏 vs 普通屏)→ 运行时判断
└─ 运行时用户配置(会员 vs 普通)→ 运行时判断
代码或图示
| 场景 | 方式 |
|---|---|
| 微信登录 vs App 登录 | 条件编译 |
| 不同刘海屏高度 | 运行时 getSystemInfoSync |
| 不同 API 调用 | 条件编译 |
| 不同设备性能降级 | 运行时判断 |
常见误区
- 误区:所有差异都用条件编译;正解:运行时变化的差异用运行时判断,条件编译只处理构建时端差异。
- 误区:条件编译能减少产物体积;正解:能,被裁掉的代码不进产物,是它的核心收益。
追问
- Q:条件编译里能调用运行时 API 吗?A:能,但条件块本身在编译期裁剪,里面的 API 在该端构建时保留。
- Q:如何避免条件编译与运行时判断混用混乱?A:在适配层明确分层:条件编译处理端差异,运行时判断处理设备差异。
07.2.4.3-009 rpx 的换算机制是什么?
一句话结论
rpx 是响应式像素单位:750rpx = 屏幕宽度,1rpx = 屏幕宽度 / 750;设计稿按 750 宽设计时,px 直接换算成 rpx(1px = 2rpx,按 750 设计稿)。
概念解释
rpx 的设计目标是让"同一套代码在不同宽度屏幕上按比例缩放"。750rpx 对应屏幕宽度,所以 375px 宽的手机上 1rpx = 0.5px,414px 宽的手机上 1rpx ≈ 0.55px。设计稿按 750 宽出图时,设计稿上 1px = 2rpx(因为 750 设计稿对应 750rpx 屏宽)。
关键认知:rpx 是相对宽度单位,不是相对高度。竖屏布局用 rpx 按宽度缩放,横屏或高度敏感场景用 px 或 vh。
实际开发中,设计稿通常按 375pt(iPhone 逻辑分辨率)或 750px(@2x)出图。uni-app 官方推荐设计稿宽度 750,这样设计稿上 1px = 1rpx(因为 750 设计稿对应 750rpx 屏宽);如果设计稿是 375 宽,则 1px = 2rpx。换算工具有 Easy Sass 的 px2rpx 插件,或在构建时配置自动换算。
原理流程
屏幕宽度 W
↓
1rpx = W / 750
设计稿 750 宽:设计稿 1px = 2rpx
设计稿 375 宽:设计稿 1px = 1rpx
代码或图示
| 设计稿宽度 | 1px 对应 rpx |
|---|---|
| 750 | 2rpx |
| 375 | 1rpx |
| 1125(@2x) | 4rpx |
常见误区
- 误区:rpx 是相对高度;正解:它是相对宽度,高度敏感场景用 px 或 vh。
- 误区:rpx 在所有端都一样;正解:rpx 在各端换算逻辑一致,但各端 WebView 渲染可能有 1px 偏差,需真机核对。
追问
- Q:字体大小用 rpx 还是 px?A:字体建议用 rpx 保持比例,但小屏手机字会太小,可配合 px 下限。
- Q:H5 端 rpx 怎么算?A:H5 端按视口宽度换算,与小程序一致。
07.2.4.3-010 安全区(状态栏、底部 Home 条)怎么适配?
一句话结论
App 端与小程序端都有状态栏、底部 Home 条、刘海屏等安全区问题;uni-app 提供 uni.getSystemInfoSync() 获取状态栏高度,样式用 env(safe-area-inset-bottom) 或条件编译写固定 padding。
概念解释
安全区分三类:顶部状态栏(时间、信号)、底部 Home 条(iPhone X 及以后)、刘海/挖孔(顶部摄像头)。App 端 vue 页默认从状态栏下方开始渲染(取决于 pages.json 的 navigationStyle),如果自定义导航需要手动加状态栏高度。
获取方式:uni.getSystemInfoSync().statusBarHeight 拿到状态栏高度(单位 px),在样式里用 padding-top 加。底部安全区用 CSS env(safe-area-inset-bottom),各端支持情况不同,不支持时用固定值兜底。
实际开发中更稳妥的做法是在 onLaunch 时调用一次 uni.getSystemInfoSync(),把 statusBarHeight、safeArea 等信息存到 Pinia store 或全局变量,页面里直接读取,避免每个页面重复调用。自定义导航组件在内部统一处理状态栏高度,业务页面不感知。
原理流程
uni.getSystemInfoSync()
├─ statusBarHeight:顶部状态栏高度
├─ safeArea:安全区域(top/bottom/left/right)
└─ 屏幕宽高
样式:padding-top: statusBarHeight + 'px'
padding-bottom: env(safe-area-inset-bottom)
代码或图示
| 场景 | 适配方式 |
|---|---|
| 自定义导航 | statusBarHeight + 导航高度 |
| 底部按钮 | env(safe-area-inset-bottom) |
| 刘海屏内容避开 | safeArea.top/bottom |
| H5 端 | 浏览器顶部有地址栏,需额外处理 |
常见误区
- 误区:所有端状态栏高度一致;正解:Android/iOS/小程序各有差异,必须运行时获取。
- 误区:env(safe-area-inset-bottom) 所有端都支持;正解:小程序与 H5 支持情况不同,需真机核对,不支持时用固定值兜底。
追问
- Q:pages.json 里怎么配沉浸式?A:
navigationStyle: custom让页面自定义导航,然后手动加状态栏高度。 - Q:H5 端安全区怎么处理?A:H5 顶部是浏览器地址栏,不是安全区问题,是布局避让问题,用 CSS 或 JS 获取高度。
07.2.4.3-011 单位差异、字体与滚动条怎么统一?
一句话结论
单位差异主要在 rpx(跨端响应式)与 px(固定)之间;字体在各端默认字体不同,滚动条在 H5 与 App 表现不同;统一用 CSS 变量与条件编译处理。
概念解释
rpx 与 px 的取舍:响应式布局用 rpx,固定尺寸(图标、按钮最小高度)用 px。字体:各端默认字体不同(iOS 用系统字体,Android 用 Roboto,小程序有平台字体),跨端统一用 font-family 显式指定,或用系统字体栈。
滚动条:H5 端默认显示滚动条,App 端 vue 页 WebView 默认隐藏或样式不同,小程序端 scroll-view 有滚动条样式配置。需要自定义滚动条时用 CSS ::-webkit-scrollbar 或平台 API。
原理流程
响应式尺寸 → rpx
固定尺寸 → px
字体 → font-family 显式指定
滚动条 → CSS 或平台 API
代码或图示
| 差异点 | 处理方式 |
|---|---|
| 单位 | rpx 响应式,px 固定 |
| 字体 | font-family 显式指定 |
| 滚动条 | CSS 或平台 API |
| 边框 1px | 各端渲染差异,用 transform scale 或 0.5px |
常见误区
- 误区:所有尺寸都用 rpx;正解:固定尺寸(如图标、按钮最小高度)用 px,避免 rpx 缩放导致不可点。
- 误区:字体不用指定;正解:各端默认字体不同,显式指定保持一致。
追问
- Q:1px 边框在各端为什么看起来粗?A:各端屏幕像素密度不同,1px 物理像素 vs 逻辑像素,用 transform scale(0.5) 或 hairline 方案。
- Q:小程序端滚动条怎么隐藏?A:scroll-view 的 show-scrollbar 属性或 CSS,具体以官方文档为准。
07.2.4.3-012 生命周期在各端有什么差异?
一句话结论
uni-app 的应用生命周期(onLaunch/onShow/onHide)、页面生命周期(onLoad/onShow/onReady/onHide/onUnload)、组件生命周期(Vue 标准)在各端映射到对应平台机制,但时机与触发频率有差异。
概念解释
应用生命周期:onLaunch 在启动时触发一次,onShow 在 App 切前台时触发,onHide 在切后台时触发。各端差异:小程序端 onLaunch 是冷启动,App 端 onLaunch 同样是冷启动,但 H5 端 onLaunch 对应页面加载。
页面生命周期:onLoad 在页面加载时触发(接收参数),onShow 在页面显示时触发,onReady 在页面初次渲染完成时触发,onHide 在页面隐藏时触发,onUnload 在页面卸载时触发。关键差异:tab 页切换时 onShow 触发但 onLoad 不触发;navigateTo 新页面时旧页面 onHide 但不 onUnload。
组件生命周期:Vue 标准(beforeCreate/created/mounted 等),各端一致。
还有一个常见差异是 onReady 与首屏渲染:App 端 vue 页 onReady 触发时机与 WebView 加载完成相关,小程序端 onReady 在首次渲染完成后触发,H5 端 onReady 对应 DOMContentLoaded。首屏数据加载建议在 onLoad 里发请求,不要在 onReady,否则会白屏更久。
原理流程
应用启动:onLaunch → onShow
页面进入:onLoad → onShow → onReady
页面切后台:onHide
页面返回:onShow
页面关闭:onUnload
代码或图示
| 生命周期 | 触发时机 | 各端差异 |
|---|---|---|
| onLaunch | 应用启动一次 | 冷启动,各端一致 |
| onShow | 应用切前台 | 切后台回前台触发 |
| onHide | 应用切后台 | 切后台触发 |
| onLoad | 页面加载(带参数) | tab 页只首次触发 |
| onShow | 页面显示 | tab 页切换也触发 |
| onReady | 页面初次渲染完成 | 只触发一次 |
| onUnload | 页面卸载 | redirectTo/navigateBack 触发 |
常见误区
- 误区:onShow 每次页面进入都触发 onLoad;正解:tab 页切换只触发 onShow,onLoad 只首次。
- 误区:组件卸载定时器自动停;正解:要在 onUnload/beforeUnmount 里手动 clearInterval。
追问
- Q:onLoad 里能拿到页面参数吗?A:能,onLoad(options) 接收路由参数。
- Q:App 切后台再回前台触发什么?A:应用级 onShow,不是页面 onShow。
07.2.4.3-013 API 能力差异与兜底方案怎么做?
一句话结论
同一 uni.xxx API 在各端支持情况不同,返回值与错误码也可能不同;兜底方案是:先查官方平台支持表,不支持的端做条件编译降级或隐藏入口,运行时用 uni.canIUse 或 try-catch 兜底。
概念解释
每个 uni API 在官方文档都有"平台支持"表格,标注 H5/App/各小程序是否支持。不支持的端调用会报错或返回 fail。兜底策略分三层:
- 编译期:条件编译,不支持的端不调用该 API;
- 运行时:
uni.canIUse('xxx')判断能力是否可用,不可用则降级; - 错误兜底:调用 fail 回调或 try-catch,给用户友好提示。
返回值差异也要注意:同一 API 在不同端的 success/fail 回调参数可能不同,错误码也不同,业务侧不要硬编码错误码。
原理流程
调用 uni.xxx
↓
查平台支持表
├─ 支持 → 直接调用
├─ 不支持 → 条件编译或 canIUse 判断
└─ 失败 → fail 回调兜底
代码或图示
| 兜底方式 | 时机 | 适用 |
|---|---|---|
| 条件编译 | 编译期 | 端完全不支持 |
| uni.canIUse | 运行时 | 同端不同版本差异 |
| fail 回调 | 运行时 | 调用失败 |
| try-catch | 运行时 | 同步 API 异常 |
常见误区
- 误区:所有端都支持所有 API;正解:每个 API 都有平台支持表,调用前必须查。
- 误区:硬编码错误码判断;正解:错误码各端不同,用 fail 回调统一处理。
追问
- Q:uni.canIUse 怎么用?A:
uni.canIUse('getSystemInfoSync')返回布尔,判断 API 是否可用。 - Q:不支持的 API 怎么降级?A:隐藏入口、用替代 API、或给用户"暂不支持"提示。
07.2.4.3-014 如何设计多端适配层?
一句话结论
适配层把"端差异"收敛到统一接口后面:业务层调 auth.login(),适配层内部按端条件编译调微信登录/App 登录;业务代码不感知端差异,差异只存在于适配层。
概念解释
典型适配层分三类:服务适配(登录、支付、分享)、组件适配(跨端一致组件)、样式适配(统一设计 token)。
服务适配:定义 auth.ts 暴露 login()、getUserInfo(),内部 #ifdef 调各端 API。业务组件只 import { login } from '@/service/auth',不写条件编译。
组件适配:把跨端表现不一致的组件(如自定义导航、列表、弹窗)封装成统一组件,内部处理端差异。
样式适配:用 CSS 变量统一设计 token(颜色、间距、圆角),各端覆盖变量值。
还有一个常见做法是"能力检测层":定义一个 platform.ts 模块,导出 isWeixin、isApp、isH5 常量(基于条件编译),业务组件需要时引入判断,但这种运行时判断仍要谨慎使用,优先用条件编译在编译期裁剪。
原理流程
业务层:import { login } from '@/service/auth'
适配层:auth.login()
↓
#ifdef MP-WEIXIN → wx.login()
#ifdef APP-PLUS → uni.login()
#ifdef H5 → 自定义登录
代码或图示
| 适配层类型 | 职责 | 示例 |
|---|---|---|
| 服务适配 | 登录/支付/分享 | auth.ts |
| 组件适配 | 跨端一致组件 | custom-navbar |
| 样式适配 | 设计 token | CSS 变量 |
常见误区
- 误区:业务代码里到处写条件编译;正解:差异收敛到适配层,业务侧零端判断。
- 误区:适配层只做服务;正解:组件与样式差异也要收敛。
追问
- Q:适配层放在哪个目录?A:项目
src/adapter/或src/service/,按职责分文件。 - Q:如何避免适配层变成大杂烩?A:按领域分文件(auth/pay/share/storage),每个文件职责单一。
07.2.4.3-015 条件编译滥用带来什么问题?
一句话结论
条件编译散落在业务代码各处会导致:可读性差(看不出某段代码在哪端生效)、维护成本高(改一个功能要改多个端分支)、测试覆盖难(每个端都要回归)、新增端时要改所有散落点。
概念解释
典型滥用场景:一个组件里写 5 处 #ifdef,一个 service 里每个方法都写条件编译,业务页面里直接 uni.xxx 然后包条件编译。后果是:新人接手看不懂,改一个功能要在 4 个端分支里同步,测试时每个端都要回归一遍。
正确做法是"差异收敛":条件编译只出现在适配层,业务代码零端判断。如果发现业务页面里有条件编译,说明该差异应该被抽象到适配层。
原理流程
滥用:业务页面 → 直接 #ifdef → 多处散落
正确:业务页面 → 适配层接口 → 适配层内部 #ifdef
代码或图示
| 滥用信号 | 后果 |
|---|---|
| 业务页面有 #ifdef | 可读性差 |
| 一个组件多处 #ifdef | 维护难 |
| 改功能要改多个端分支 | 测试成本高 |
| 新增端要改所有散落点 | 扩展成本高 |
常见误区
- 误区:条件编译越多越灵活;正解:条件编译是技术债,越多越难维护。
- 误区:小项目可以不收敛;正解:小项目从一开始就该收敛,否则长大更难收拾。
追问
- Q:如何判断条件编译是否滥用?A:业务代码(页面、组件)里出现 #ifdef 就是滥用,应该收敛到适配层。
- Q:适配层有条件编译正常吗?A:正常,适配层就是为了收敛差异。
07.2.4.3-016 条件编译的典型踩坑有哪些?
一句话结论
常见踩坑:平台标识名写错(静默不生效)、json 条件编译逗号位置错(JSON 解析失败)、条件编译块里的变量在其他端不存在(ReferenceError)、嵌套过深难读、混淆编译期与运行时判断。
概念解释
一是标识名写错:如写成 #ifdef WEIXIN 而不是 #ifdef MP-WEIXIN,编译器不报错但代码不保留,难排查。二是 json 逗号:被裁掉的字段后面逗号留着,JSON 解析失败。三是变量作用域:条件编译块里定义的变量在其他端不存在,其他端引用时 ReferenceError。
四是嵌套:#ifdef 套 #ifdef,可读性差,建议扁平化。五是混淆编译期与运行时:用条件编译处理运行时设备差异,导致其他端没有该分支。
原理流程
踩坑排查:
代码不生效 → 查标识名拼写
JSON 报错 → 查逗号
ReferenceError → 查条件块变量
样式错位 → 查条件编译是否裁掉该端
代码或图示
| 踩坑 | 表现 | 排查 |
|---|---|---|
| 标识名错 | 代码不生效 | 查官方标识表 |
| JSON 逗号 | 构建失败 | 查条件块前后逗号 |
| 变量未定义 | ReferenceError | 查其他端是否有同名变量 |
| 嵌套过深 | 难读 | 扁平化 |
常见误区
- 误区:条件编译写错编译器会报错;正解:标识名错通常静默不生效,要靠测试发现。
- 误区:条件编译块里定义的函数其他端能用;正解:其他端没有该函数,要在两端都定义或用统一接口。
追问
- Q:如何避免标识名写错?A:把常用标识定义成常量或注释,团队统一查文档。
- Q:条件编译块里 import 其他端不存在的模块怎么办?A:把 import 也包进条件编译,或在适配层统一引入。
07.2.4.3-017 综合题:业务方要做"一套代码四端跑",怎么组织适配层?
一句话结论
按四步组织:列端差异清单(API/组件/样式/权限)、建适配层目录(service/adapter/component)、把条件编译收敛到适配层、业务代码零端判断;最后每端真机回归。
概念解释
第一步列差异清单:把所有端差异点列出来(登录、支付、分享、导航、列表、弹窗、权限)。第二步建目录:src/adapter/ 下按领域分文件(auth.ts、pay.ts、share.ts、navbar.vue)。第三步收敛:把每个差异点的条件编译写在适配层,业务侧调统一接口。第四步回归:每端真机跑核心链路。
关键原则:业务代码(页面、业务组件)里不出现 #ifdef,所有端差异在适配层。如果业务里出现条件编译,说明该差异应该被抽象。
原理流程
1. 列差异清单(登录/支付/分享/导航/列表/权限)
2. 建适配层目录
3. 收敛条件编译到适配层
4. 业务侧调统一接口
5. 每端真机回归
代码或图示
| 步骤 | 产出 |
|---|---|
| 差异清单 | 端差异点列表 |
| 适配层 | adapter/auth.ts、adapter/pay.ts |
| 业务调用 | 业务页面 import 统一接口 |
| 回归 | 四端真机跑核心链路 |
常见误区
- 一上来就写业务,差异后期补;正解:先列差异清单与适配层,再写业务。
- 业务代码里有条件编译;正解:那是适配层没收敛干净,重构掉。
追问
- Q:适配层太重怎么办?A:按领域分文件,只收敛高频差异,低频差异用条件编译兜底。
- Q:如何验收适配层?A:grep 业务代码里
#ifdef,出现就是没收敛干净。
07.2.4.3-018 综合题:某端样式错位,怎么排查?
一句话结论
按五步排查:先确认是哪一端错位(H5/App/某小程序),再看是布局错(rpx 换算)还是组件错(平台渲染差异),再看条件编译是否裁掉了该端样式,最后真机核对与设计稿。
概念解释
排查顺序:一是确认端:只 H5 错还是所有端错?只 H5 错是浏览器差异,所有端错是设计稿理解错。二是确认类型:布局错(位置、大小)还是组件错(按钮、弹窗样式)?三是查条件编译:是否某端样式被裁掉了。四是查单位:rpx 在该端换算是否正确,1px 边框是否 hairline 问题。五是真机核对:模拟器与真机可能不同,必须真机看。
常见原因:rpx 在不同宽度屏幕换算偏差、1px 边框在不同像素密度手机上表现不同、条件编译裁掉了该端样式、组件在各端默认样式不同。
原理流程
样式错位
↓
1. 哪端错? ── 仅 H5 → 浏览器差异
│ 所有端 → 设计稿理解错
↓
2. 布局错 or 组件错?
↓
3. 条件编译是否裁掉该端样式?
↓
4. rpx 换算 / 1px 边框 / 字体
↓
5. 真机核对
代码或图示
| 症状 | 可能原因 | 处置 |
|---|---|---|
| 仅 H5 错位 | 浏览器差异 | CSS 兼容写法 |
| 所有端错位 | 设计稿理解错 | 核对设计稿 |
| 1px 边框粗 | 像素密度 | hairline 方案 |
| rpx 缩放偏差 | 屏宽差异 | 用 px 固定关键尺寸 |
| 组件样式不同 | 平台默认样式 | 条件编译覆盖 |
常见误区
- 只看模拟器不看真机;正解:模拟器与真机渲染不同,必须真机核对。
- 样式错位就改 CSS;正解:先查条件编译是否裁掉了该端样式。
追问
- Q:如何快速定位是 rpx 还是组件问题?A:把该元素固定 px 看是否对齐,对齐就是 rpx 换算问题,不对齐就是组件渲染差异。
- Q:H5 端样式与 App 端差异大怎么办?A:H5 有浏览器默认样式(如按钮、input),用 reset CSS 或条件编译覆盖。