uni-app x 启动参数获取全指南：uni.getLaunchOptionsSync 与 uni.getEnterOptionsSync 实战解析

uni-app x 启动参数获取全指南uni.getLaunchOptionsSync 与 uni.getEnterOptionsSync 实战解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 是一套基于 Vue.js 的跨平台应用框架支持将同一套代码编译到 Web、微信小程序、Android、iOS 与 HarmonyOS 等多个平台。在真实业务中应用常常需要借助 scheme深链、Universal Link通用链接或小程序场景值携带参数启动此时“启动参数”的获取就决定了冷启动、热启动两种场景下的用户直达体验。本文以官方 API 文档为核心系统讲解uni.getLaunchOptionsSync()与uni.getEnterOptionsSync()两个同步启动参数 API 的返回值结构、平台兼容性、与onLaunch/onShow生命周期回调的关系并结合当前开源仓库uni-app中的 App 生命周期实现、页面示例与自动化测试给出可复制的方案级代码。一、两个 API 的核心定位一次启动两个视角| API | 语义 | 对应生命周期 | 典型场景 | | :- | :- | :- | :- | |uni.getLaunchOptionsSync()| 获取首次启动时的参数 | 与App.onLaunch回调参数一致 | 冷启动统计首启来源、渠道归因、隐私弹窗 | |uni.getEnterOptionsSync()| 获取本次启动时的参数 | 与App.onShow回调参数一致 | 冷启动 后台切前台scheme/Universal Link 直达页面 |文档原文明确指出uni.getEnterOptionsSync和uni.getLaunchOptionsSync的区别相当于应用的onShow和onLaunch的区别。换句话说getLaunchOptionsSync只在应用进程冷启动时携带信息而getEnterOptionsSync在应用从后台被激活到前台时同样会刷新因此直达页面、处理外部唤起这类功能应优先在onShow生命周期或getEnterOptionsSync中实现。关于应用生命周期的完整说明可参见 docs/collocation/app.md。这一设计在当前仓库的示例工程src/App.uvue中得到了完整印证onLaunch((res: OnLaunchOptions))回调中将res写入全局状态updateGlobalData(launchOptions, res)onAppShow((res: OnShowOptions))回调中将res写入updateGlobalData(showOptions, res)全局状态容器定义在 src/store/index.uts其中GlobalData类型明确声明了launchOptions: OnLaunchOptions与showOptions: OnShowOptions两个字段。也就是说onLaunch拿到的是OnLaunchOptions类型onShow拿到的是OnShowOptions类型而两个同步 API 的返回值分别与它们一一对应这正是文档中“返回值与 App.onLaunch 的回调参数一致 / 与 App.onShow 的回调参数一致”的含义。二、uni.getLaunchOptionsSync()首次启动参数1. 基本语法与兼容性const launchOptions: OnLaunchOptions uni.getLaunchOptionsSync()| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.91 | 4.11 | 4.61 |兼容性数值对应当前 uni-app x 各平台的编译器/运行时版本号使用前请确认你的 HBuilderX 版本不低于表中数值。2. 返回值 OnLaunchOptions 属性表| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | path | string | 是 | 首次启动时的页面路径 | | appScheme | string | 否 | 首次启动时的 schemeDeep Link | | appLink | string | 否 | 首次启动时的 appLinkUniversal Link | | query | UTSJSONObject | 否 | 启动时的 query 参数 | | apiCategory | string | 否 | 微信小程序 API 类别需基础库 2.20.0 | | forwardMaterials | any | 否 | 微信小程序聊天素材打开的文件信息数组仅 scene1173 携带 | | hostExtraData | OnLaunchOptionsHostExtraData | 否 | 微信小程序宿主传递的数据第三方 App 中运行小程序时返回 | | referrerInfo | OnLaunchOptionsReferrerInfo | 否 | 微信小程序来源信息小程序/公众号/App 进入时返回否则为{} | | scene | number | 否 | 微信小程序启动场景值 | | chatType | number | 否 | 微信群聊/单聊打开时的聊天类型 | | shareTicket | string | 否 | 微信小程序转发票据 |各属性在不同平台的可用性存在差异path与query是跨端通用的核心字段appScheme在 Android(VDOM) 4.25、Android(Vapor) 5.25、iOS(VDOM) 4.25、iOS(Vapor) 5.25、HarmonyOS(VDOM) 4.81、HarmonyOS(Vapor) 5.25 起可用Web 与微信小程序标记为 x不支持appLink则仅 iOS 与 HarmonyOS 的 VDOM/Vapor 双渲染架构支持。3. 微信小程序专属字段详解apiCategory合法值default默认、nativeFunctionalized原生功能化如视频号直播商品、商品橱窗场景、browseOnly仅浏览如朋友圈快照页、embedded内嵌通过半屏小程序打开、chatTool聊天工具打开。chatType合法值1 微信联系人单聊、2 企业微信联系人单聊、3 普通微信群聊、4 企业微信互通群聊。referrerInfoappId来源小程序/公众号/App 的 appId、extraData来源小程序传入数据scene1037 或 1038 时支持。hostExtraDatahost_scene宿主 App 对应的场景值。这些字段与微信官方wx.getLaunchOptionsSync保持语义一致便于从微信小程序迁移到 uni-app x 的开发者平滑过渡。4. 示例代码读取并校验首次启动参数以下示例来自官方文档在当前仓库对应页面示例 src/pages/API/get-launch-options-sync/get-launch-options-sync.uvuetemplate page-head titlegetLaunchOptionsSync/page-head view classuni-padding-wrap button clickgetLaunchOptionsSyncgetLaunchOptionsSync/button view classuni-common-mt text应用本次启动路径/text text stylemargin-top: 5px{{ data.launchOptionsPath }}/text /view view classuni-common-mt text应用本次启动/text text stylemargin-top: 5px{{ data.launchOptionsString }}/text /view /view /template script setup languts import { state } from /store/index.uts type DataType { checked: boolean; homePagePath: string; launchOptionsPath: string; launchOptionsString: string; testResult: boolean; } const data reactiveDataType({ checked: false, homePagePath: pages/tabBar/component, launchOptionsPath: , launchOptionsString: , testResult: false }) const compareOnLaunchRes () { const launchOptions uni.getLaunchOptionsSync(); data.launchOptionsString JSON.stringify(launchOptions, null, 2) const appLaunchOptions state.globalData.launchOptions const isPathSame launchOptions.path appLaunchOptions.path const isAppSchemeSame launchOptions.appScheme appLaunchOptions.appScheme const isAppLinkSame launchOptions.appLink appLaunchOptions.appLink data.testResult isPathSame isAppSchemeSame isAppLinkSame } const getLaunchOptionsSync () { const launchOptions uni.getLaunchOptionsSync() data.launchOptionsPath launchOptions.path if (launchOptions.path data.homePagePath) { data.checked true } } onReady(() { compareOnLaunchRes() }) defineExpose({ data, getLaunchOptionsSync }) /script示例中有两个关键技巧值得借鉴与 onLaunch 结果比对compareOnLaunchRes同时读取uni.getLaunchOptionsSync()与state.globalData.launchOptions即onLaunch回调写入的原始参数逐一比对path、appScheme、appLink三个字段验证两者的一致性。这本质上是官方在页面层面对“返回值与 onLaunch 回调参数一致”这一文档承诺的自检。路径校验通过launchOptions.path data.homePagePath判断本次启动是否落在首页可用于决定是否需要重定向或展示引导。5. 自动化测试佐证仓库中配套的自动化测试 src/pages/API/get-launch-options-sync/get-launch-options-sync.test.js 直接验证了两条核心行为describe(getLaunchOptionsSync, () { it(getLaunchOptionsSync, async () { page await program.navigateTo(PAGE_PATH) await page.waitFor(view) await page.callMethod(getLaunchOptionsSync) const data await page.data(data) expect(data.checked).toBe(true) }) it(app onLaunch 和 getLaunchOptionsSync 结果一致, async () { const page await program.navigateTo(PAGE_PATH) await page.waitFor(view) const pageData await page.data(data) expect(pageData.testResult).toBe(true) }) })第一个用例调用页面暴露的getLaunchOptionsSync方法并断言checked为true即启动路径与首页一致第二个用例直接断言testResult为true从测试层面锁定了“getLaunchOptionsSync与onLaunch回调参数一致”的行为契约。三、uni.getEnterOptionsSync()本次启动参数1. 基本语法与兼容性const enterOptions: OnShowOptions uni.getEnterOptionsSync()| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 4.25 | 4.25 | 4.61 |2. 返回值 OnShowOptions 属性表OnShowOptions的字段与OnLaunchOptions完全同构仅语义从“首次启动”变为“本次启动/每次进入前台”| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | path | string | 是 | 本次启动时页面的路径 | | appScheme | string | 否 | 本次启动时的 scheme | | appLink | string | 否 | 本次启动时的 appLink | | query | UTSJSONObject | 否 | 启动时的 query 参数 | | apiCategory | string | 否 | 微信小程序 API 类别 | | forwardMaterials | any | 否 | 聊天素材场景scene1173打开的文件信息数组 | | hostExtraData | OnShowOptionsHostExtraData | 否 | 宿主传递的数据 | | referrerInfo | OnShowOptionsReferrerInfo | 否 | 来源信息 | | scene | number | 否 | 启动场景值 | | chatType | number | 否 | 微信群聊/单聊类型1/2/3/4 | | shareTicket | string | 否 | 转发票据 |子对象结构与OnLaunchOptions完全一致apiCategory合法值为 default / nativeFunctionalized / browseOnly / embedded / chatToolchatType合法值为 1 / 2 / 3 / 4referrerInfo包含appId与extraDatahostExtraData包含host_scene。这里不再赘述可直接复用第一节的属性含义。3. 示例代码读取并校验本次启动参数对应页面示例 src/pages/API/get-enter-options-sync/get-enter-options-sync.uvuetemplate page-head titlegetEnterOptionsSync/page-head view classuni-padding-wrap view classuni-common-mt text应用本次启动路径/text text stylemargin-top: 5px{{ data.enterOptionsString }}/text /view /view /template script setup languts import { state } from /store/index.uts type DataType { enterOptionsString: string, testResult: boolean, } const data reactive({ enterOptionsString: , testResult: false, } as DataType) onReady(() { const appShowOptions state.globalData.showOptions const enterOptions uni.getEnterOptionsSync() data.enterOptionsString JSON.stringify(enterOptions, null, 2) data.testResult (enterOptions.path appShowOptions.path enterOptions.appScheme appShowOptions.appScheme enterOptions.appLink appShowOptions.appLink) }) defineExpose({ data }) /script配套测试 src/pages/API/get-enter-options-sync/get-enter-options-sync.test.js 同样断言了testResult true验证getEnterOptionsSync与onShow回调参数一致。4. 冷启动 vs 热启动的实操差异在 App 端使用getEnterOptionsSync时有一个关键细节值得注意应用通过 scheme 或 appLink通用链接启动、或从后台激活到前台时都能通过本 API 获取相应参数。因此若只关心冷启动进程被杀后唤起用getLaunchOptionsSync即可若需要覆盖冷启动 后台切前台例如用户停留在 App 内又从浏览器/短信被 scheme 唤起必须使用getEnterOptionsSync因为它每次进入前台都会携带最新参数。四、App 生命周期回调中的完整落地实现1. 全局状态承接启动参数当前仓库在 src/store/index.uts 中提供了标准做法GlobalData类型声明launchOptions与showOptions字段并在状态初始化时给出空壳默认值launchOptions: { path: , } as OnLaunchOptions, showOptions: { path: } as OnShowOptions同时通过updateGlobalData函数按 key 分发写入src/store/index.utsApp.uvue中onLaunch与onAppShow回调调用updateGlobalData(launchOptions, res)/updateGlobalData(showOptions, res)完成全局状态同步。这样任意页面都可以通过state.globalData.launchOptions拿到与 API 返回值一致的启动参数实现“一处收集、全局消费”。2. scheme / Universal Link 直达页面的完整链路docs/collocation/app.md中对直达页面功能给出了官方指引先配置 schemedeeplink或 appLink通用链接启动应用在应用的onShow生命周期获取并解析appScheme/appLink参数再调用uni.navigateTo等路由 API 跳转页面。onShow的优势在于不管首页启动还是后台激活到前台都会触发——当然初次启动时仍会先打开 App 首页再执行开发者编写的路由代码。当前仓库的src/App.uvue给出了一个可以直接复用的解析实现getRedirectUrlsrc/App.uvuescheme 格式uniappx://redirect/pages/component/view/view?keyvalue即redirect后紧跟页面路径Universal Link 格式https://uniappx.dcloud.net.cn/ulink/redirect.html?url%2Fpages%2Fcomponent%2Fview%2Fview%3Fkey%3Dvalue通用链接路径需固定url参数值为 url 编码后的页面路径可用encodeURIComponent方法编码。解析逻辑分两步先从 scheme 中提取//之后的redirect前缀并截取页面路径若无 scheme则解析 Universal Link 的url查询参数并decodeURIComponent还原。然后在onAppShow中调用并跳转onAppShow((res : OnShowOptions) { updateGlobalData(showOptions, res) // 处理scheme或通用链接直达 let url getRedirectUrl(res.appScheme, res.appLink); if (null ! url) { uni.navigateTo({ url: url }) } ... })这段代码直接展示了OnShowOptions中appScheme、appLink两个字段的真实业务价值——它们是跨 App 外部唤起的“入口凭证”。3. 配置 scheme / appLink 的注意事项配置 scheme 或 appLink 需要在manifest.json中配置或者在原生侧直接配置Android 的AndroidManifest.xml、iOS 的Info.plist、鸿蒙的 json5 配置文件中声明打包后生效修改配置需要重新打包微信小程序等平台无appScheme/appLink兼容性标记为 x这部分能力属于 App 端特性。仓库根目录提供各平台原生配置文件供参考src/AndroidManifest.xml、src/Info.plist。4. 一次启动中的完整调用时序将上述要素串联起来一次带参冷启动的完整时序为系统通过 scheme / Universal Link / 桌面图标拉起应用进程框架触发onLaunch回调参数类型为OnLaunchOptionspath、query、appScheme、appLink等App.uvue将其写入全局状态首页加载完成后触发onAppShow回调参数类型为OnShowOptions同样写入全局状态并在src/App.uvue中执行 scheme/Universal Link 解析与uni.navigateTo直达跳转页面侧随时可调用uni.getLaunchOptionsSync()/uni.getEnterOptionsSync()同步读取二者的返回值分别与第 2、3 步的回调参数一致且经自动化测试锁定。五、跨平台差异与使用建议1. 平台能力差异速查| 能力 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | |path启动页路径 | 4.0 | 4.41 | 3.91/4.25 | 4.11/4.25 | 4.61 | |query启动参数 | 4.0 | 4.41 | √ | √ | 4.81 | |appScheme| 不支持 | 不支持 | VDOM 4.25 / Vapor 5.25 | VDOM 4.25 / Vapor 5.25 | VDOM 4.81 / Vapor 5.25 | |appLink| 不支持 | 不支持 | 不支持 | VDOM 4.25 / Vapor 5.25 | VDOM 4.81 / Vapor 5.25 | |apiCategory/scene/chatType/referrerInfo/shareTicket等 | 不支持 | 4.41 | 不支持 | 不支持 | 不支持 |可以看到getLaunchOptionsSync在 Android/iOS 上更早可用3.91/4.11而getEnterOptionsSync在两端均为 4.25 起可用微信小程序生态特有的字段集中在 4.41HarmonyOS 的 Vapor 渲染架构5.x对 scheme/appLink 的支持与 VDOM 架构4.x并存使用时需注意区分渲染架构版本。2. 推荐使用姿势总结渠道归因 / 首启统计onLaunchuni.getLaunchOptionsSync()一次取足path、query、appScheme、appLink记录到全局状态或上报服务端外部唤起直达scheme/Universal LinkonAppShowuni.getEnterOptionsSync()参照src/App.uvue的getRedirectUrl方案解析并跳转微信小程序来源分析读取referrerInfo、scene、chatType、apiCategory判断用户来自分享卡片、聊天工具还是半屏小程序类型安全所有字段均以OnLaunchOptions/OnShowOptions类型约束在 UTS 中可借助类型提示避免拼写错误。六、结语uni.getLaunchOptionsSync()与uni.getEnterOptionsSync()是 uni-app x 中获取启动参数的同步 API分别对应onLaunch与onShow生命周期前者锁定冷启动首次参数后者覆盖冷启动与后台切前台的全量场景。本文从返回值结构、平台兼容性、微信小程序专属字段到 scheme/Universal Link 直达页面的完整实现结合 docs/collocation/app.md 生命周期文档、src/App.uvue 的全局状态承接与 URL 解析实现以及 get-launch-options-sync.test.js 与 get-enter-options-sync.test.js 的自动化测试完成了从“能跑”到“懂原理”的闭环。开发者可直接将示例代码与getRedirectUrl方案迁移到自己的项目中快速实现跨端启动参数采集与深链直达功能。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考