uni-app getLaunchOptionsSync 与 getEnterOptionsSync应用启动参数获取与直达页面开发实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app导读uni-app 框架为跨端应用提供了同步获取启动参数的能力uni.getLaunchOptionsSync()返回应用首次启动对应App.onLaunch时的完整参数uni.getEnterOptionsSync()返回本次启动/从后台回到前台对应App.onShow时的完整参数。两者组合可支撑“Scheme/AppLink 直达页面”“渠道归因统计”“分享回流追踪”等核心业务场景。本文基于开源仓库 uni-app 的官方 API 文档与uni-getLaunchOptionsSync、uni-getEnterOptionsSync两个 UTS 插件源码系统讲解 API 返回值结构、平台兼容性、原生端 Scheme/AppLink 配置方式、典型示例代码与自动化测试验证帮助你在 App、小程序、Web 多端统一落地启动参数处理逻辑。说明仓库内docs/api/get-launch-options-sync.md已迁移至docs/api/launch.md本文即基于该目标文档整理扩充。一、API 概览两个同步 API 的分工1.1 uni.getLaunchOptionsSync()获取首次启动时的参数返回值与App.onLaunch的回调参数一致仅在应用冷启动时产生。| 平台 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | 4.0 | 4.41 | 3.91 | 4.11 | 4.61 |1.2 uni.getEnterOptionsSync()获取本次启动时的参数返回值与App.onShow的回调参数一致。两者区别相当于应用生命周期中onLaunch与onShow的区别onLaunch只在冷启动时触发一次onShow在每次应用从后台激活到前台都会触发因此getEnterOptionsSync适合处理“后台切前台”以及“通过 Scheme/AppLink 从外部拉起”的动态场景。| 平台 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | 4.0 | 4.41 | 4.25 | 4.25 | 4.61 |应用生命周期onLaunch/onShow的完整说明可参见 应用生命周期文档。二、返回值结构与类型定义getLaunchOptionsSync()返回类型为OnLaunchOptionsgetEnterOptionsSync()返回类型为OnShowOptions两者字段结构一致。字段的官方定义见 getLaunchOptionsSync 接口定义。2.1 核心字段说明| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 首次启动或本次启动时的页面路径与App.onLaunch/App.onShow回调参数一致 | | appScheme | string | 否 | Android/iOS(VDOM): 4.25; Vapor: 5.25; HarmonyOS(VDOM): 4.81; Vapor: 5.25; Web/微信小程序: 不支持 | 启动时的 Scheme即通过自定义 URL Scheme 拉起应用时携带的 scheme | | appLink | string | 否 | iOS(VDOM): 4.25; iOS(Vapor): 5.25; HarmonyOS(VDOM): 4.81; Vapor: 5.25; 其余平台不支持 | 启动时的 AppLink通用链接 | | query | UTSJSONObject | 否 | Web: 4.0; 微信小程序: 4.41; Android/iOS: 全支持; HarmonyOS: 4.81 | 启动时的 query 参数UTSJSONObject 类型说明见 UTSJSONObject | | apiCategory | string | 否 | 微信小程序: 4.41基础库 2.20.0 | API 类别 | | forwardMaterials | any | 否 | 微信小程序: 4.41 | 打开的文件信息数组仅从聊天素材场景scene 为 1173打开时携带 | | hostExtraData | OnLaunchOptionsHostExtraData | 否 | 微信小程序: 4.41 | 宿主传递的数据第三方 App 中运行小程序时返回 | | referrerInfo | OnLaunchOptionsReferrerInfo | 否 | 微信小程序: 4.41 | 来源信息从另一个小程序、公众号或 App 进入时返回否则返回{}| | scene | number | 否 | 微信小程序: 4.41 | 场景值 | | chatType | number | 否 | 微信小程序: 4.41 | 从微信群聊/单聊打开小程序时的聊天类型 | | shareTicket | string | 否 | 微信小程序: 4.41 | 分享票据 |2.2 子对象字段详解apiCategory 合法值微信小程序专属| 合法值 | 含义 | | :- | :- | | default | 默认类别 | | nativeFunctionalized | 原生功能化视频号直播商品、商品橱窗等场景打开的小程序 | | browseOnly | 仅浏览朋友圈快照页等场景打开的小程序 | | embedded | 内嵌通过打开半屏小程序能力打开的小程序 | | chatTool | 聊天工具通过打开聊天工具能力打开的小程序 |hostExtraData 字段微信小程序专属| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | host_scene | string | 否 | 宿主 App 对应的场景值 |referrerInfo 字段微信小程序专属| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | appId | string | 否 | 来源小程序、公众号或 App 的 appId | | extraData | IAnyObject | 否 | 来源小程序传过来的数据scene 为 1037 或 1038 时支持 |chatType 合法值微信小程序专属| 合法值 | 含义 | | :- | :- | | 1 | 微信联系人单聊 | | 2 | 企业微信联系人单聊 | | 3 | 普通微信群聊 | | 4 | 企业微信互通群聊 |从类型定义可以看出appScheme与appLink在源码中声明为string | null且仅在 App 端VDOM 4.25/Vapor 5.25支持query声明为可选UTSJSONObjectApp 全平台支持而apiCategory、forwardMaterials、hostExtraData、referrerInfo、scene、chatType、shareTicket等字段仅在微信小程序端由宿主注入属于小程序生态特有的启动上下文。三、源码级实现原理同步 API 的数据从哪来getLaunchOptionsSync与getEnterOptionsSync分别由两个独立的 UTS 插件实现位于仓库src/uni_modules/目录下。3.1 getLaunchOptionsSync 的实现uni-getLaunchOptionsSync 插件主实现import { __uniConfig } from dcloudio/uni-runtime import { GetLaunchOptionsSync, OnLaunchOptions } from ./interface.uts let launchOptions { path: __uniConfig.entryPagePath, query: {} as UTSJSONObject, } as OnLaunchOptions export const setLaunchOptionsSync function (options: OnLaunchOptions) { launchOptions options } export const getLaunchOptionsSync defineSyncApiGetLaunchOptionsSync( getLaunchOptionsSync, (): OnLaunchOptions { return launchOptions }, )关键实现要点默认值兜底在框架尚未写入真实启动参数前launchOptions初始化为{ path: __uniConfig.entryPagePath, query: {} }即应用配置的首页路径entryPagePath来自 pages.json保证任何时机调用都有合理返回值。同步返回通过defineSyncApi声明为同步 API直接返回内存中缓存的launchOptions对象无需等待异步回调。写入入口setLaunchOptionsSync由框架在应用冷启动完成参数组装后调用将真实的OnLaunchOptions覆盖到模块内部变量这正是“返回值与App.onLaunch回调参数一致”的机制来源。3.2 getEnterOptionsSync 的实现uni-getEnterOptionsSync 插件主实现 采用了完全一致的实现模式仅默认值类型换为OnShowOptions、写入函数为setEnterOptionsSynclet enterOptions { path: __uniConfig.entryPagePath, query: {} as UTSJSONObject } as OnShowOptions export const setEnterOptionsSync function (options: OnShowOptions) { enterOptions options } export const getEnterOptionsSync defineSyncApiGetEnterOptionsSync( getEnterOptionsSync, (): OnShowOptions { return enterOptions }, )由于两个 API 共享同一套“默认值兜底 setter 覆盖 同步读取”模式它们的差异完全体现在框架何时调用 settersetLaunchOptionsSync在冷启动时写入setEnterOptionsSync在每次 onShow 时写入。UTS 插件本身通过 uni_modules 机制按平台编译Android 编译为 Kotlin、iOS 编译为 Swift、鸿蒙编译为 ArkTS、Web/小程序编译为 JavaScript插件结构说明详见 uni-getLaunchOptionsSync 插件 readme。四、Scheme 与 AppLink 直达页面配置文档明确指出如果应用通过Scheme或AppLink通用链接启动可以通过上述 API 获取相应参数。配置方式分为两层manifest.json 可视化配置在 HBuilderX 的 manifest 中配置 Scheme 与 AppLink原生配置文件兜底也可在原生AndroidManifest.xml、iOS 的Info.plist、鸿蒙的 json5 中直接配置仓库根目录可见 AndroidManifest.xml、Info.plist。配置均需打包后生效。若开发“直达页面”功能外部链接直接打开应用内指定页面一般需要在应用的onShow生命周期中监听并处理见 App 生命周期 onShow 说明。核心判断逻辑是启动时从path判断目标页面从query解析业务参数从appScheme/appLink确认外部来源渠道。仓库示例工程 App.uvue 展示了onLaunch中接收OnLaunchOptions的典型用法将启动参数写入全局 storeupdateGlobalData(launchOptions, res)、上报uni.report统计、按需处理隐私弹窗等。其中getRedirectUrl函数src/App.uvue即解析 scheme/universal link 以决定是否跳转直达页面的实现可作为落地参考。五、完整示例代码以下示例取自仓库示例工程src/pages/API/get-launch-options-sync/get-launch-options-sync.uvue同时参考文档内嵌示例可直接在页面中运行。5.1 获取首次启动参数getLaunchOptionsSynctemplate 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 reactive({ checked: false, homePagePath: pages/tabBar/component, launchOptionsPath: , launchOptionsString: , testResult: false } as DataType) 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要点说明调用uni.getLaunchOptionsSync()后可直接读取path、appScheme、appLink、query等字段示例通过JSON.stringify(launchOptions, null, 2)格式化展示完整返回compareOnLaunchRes将该 API 的结果与App.onLaunch写入全局 store 的state.globalData.launchOptions逐字段比对用于验证“返回值与 onLaunch 回调一致”的文档承诺全局 store 的类型定义见 src/store/index.uts。5.2 获取本次启动参数getEnterOptionsSynctemplate 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实际工程中getEnterOptionsSync更适合与onShow生命周期配合在每次从后台回到前台或外部拉起时重新读取参数并做路由分发文档建议直达页面逻辑放在 onShow 中处理。六、自动化测试验证仓库为上述两个 API 提供了对应的自动化测试见 get-launch-options-sync.test.jsconst isDom2 process.env.UNI_APP_X_DOM2 true const HOME_PATH isDom2 ? /pages/tabBar/tab-bar : /pages/tabBar/component const PAGE_PATH /pages/API/get-launch-options-sync/get-launch-options-sync 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后返回的path应与首页路径一致data.checked true一致性校验getLaunchOptionsSync()的返回与App.onLaunch回调写入全局 store 的launchOptions逐字段相等data.testResult true从测试层面锁定了文档所述“返回值与 App.onLaunch 的回调参数一致”的行为契约。getEnterOptionsSync的对应测试位于 get-enter-options-sync.test.js逻辑同构校验其与App.onShow回调参数的一致性。七、实战场景与选型建议| 场景 | 推荐 API | 原因 | | :- | :- | :- | | 冷启动渠道归因统计首次打开来源 | getLaunchOptionsSync | 只关心应用首次启动时的 path/query/appScheme/appLink | | Scheme/AppLink 直达页面 | getEnterOptionsSync onShow | 外部拉起可能发生在应用已运行后台切前台时需每次 onShow 读取 | | 微信小程序场景值统计 | 两者均可小程序端 | 可读取 scene/chatType/apiCategory/referrerInfo 等宿主注入字段 | | 判断是否从首页正常进入 | getLaunchOptionsSync | 对比path与首页路径如pages/tabBar/component |注意事项appScheme/appLink字段有严格平台限制Web 与微信小程序端不支持返回null仅 App 端 VDOM 4.25/Vapor 5.25、HarmonyOS 4.81 可用query的类型为UTSJSONObject取值后可继续用 JSON 解析提取业务参数文档中“如果应用通过 scheme 或 applink 启动可通过本 API 获取相应参数”的前提是原生侧配置已完成且打包生效referrerInfo在非来源场景下返回空对象{}读取其子字段前应先判空。八、总结uni.getLaunchOptionsSync()与uni.getEnterOptionsSync()是 uni-app 应用感知自身“从何而来、去往何页”的标准入口前者覆盖冷启动场景对应onLaunch后者覆盖每次前台展示场景对应onShow二者共享OnLaunchOptions/OnShowOptions结构配合原生 Scheme/AppLink 配置即可低成本实现跨端直达页面与启动归因。结合仓库中 UTS 插件源码默认值兜底 setter 覆盖 defineSyncApi 同步读取的实现模式与自动化测试返回参数与生命周期回调一致性断言开发者可以放心地在业务中同步读取启动参数并在多端统一维护同一套处理逻辑。相关接口文档与示例代码位于 docs/api/launch.md、示例页面 与 getEnterOptionsSync 示例。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考