uni-app x 启动参数获取uni-getLaunchOptionsSync UTS 插件实现与跨端实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南围绕开源仓库uni-app中uni-getLaunchOptionsSync这一 uni_modules 模块展开讲解它如何以 UTS 插件的形式实现uni.getLaunchOptionsSync()同步获取应用首次启动参数页面路径、query、scheme、appLink的能力。读完本文你将掌握该 API 的跨端兼容性、OnLaunchOptions返回结构、底层defineSyncApi实现机制以及如何在 uni-app x 项目中用它实现 scheme/通用链接直达页面、启动参数上报等实战方案。模块定位获取首次启动参数uni-getLaunchOptionsSync是一个标准的 uni_modules 插件其功能定位在模块自述中非常明确实现获取应用首次启动的参数功能。它向业务层暴露的 API 是uni.getLaunchOptionsSync()返回值与App.onLaunch回调参数一致——也就是说应用冷启动时框架下发的启动信息既可以异步地在onLaunch生命周期里收到也可以在任何时机通过该同步 API 主动取回。该模块的完整源码位于仓库 src/uni_modules/uni-getLaunchOptionsSync 目录由四个文件组成| 文件 | 作用 | | -- | -- | | utssdk/index.uts | 插件核心实现getLaunchOptionsSync与内部写入器setLaunchOptionsSync| | utssdk/interface.uts | 类型定义OnLaunchOptions、GetLaunchOptionsSync及挂载到Uni接口上的声明 | | package.json | 插件元数据dcloudext.type声明为uts含平台支持矩阵 | | readme.md | 模块说明与 UTS 插件机制简介 |其中package.json的dcloudext.type: uts表明这是一个 UTS 插件engines.HBuilderX: ^3.6.8声明了最低 HBuilderX 版本要求uni_modules.platforms中列出了客户端覆盖的 Vue2/Vue3、AppAndroid/iOS、H5 及微信、阿里、百度、字节、QQ、钉钉、快手、飞书、京东等小程序端。UTS 语言与 UTS 插件机制理解这个模块前需要先了解它的载体——UTS 插件。以下内容来自模块 readme.md 的说明。uts 是什么utsuni type script是一门跨平台的、高性能的、强类型的现代编程语言它可以被编译为不同平台的编程语言Android 平台编译为 KotliniOS 平台编译为 Swift鸿蒙 OS 平台编译为 ArkTSweb 平台 / 小程序编译为 JavaScriptuts 采用了与 TypeScript 基本一致的语法规范支持绝大部分 ES6 API。为了跨端uts 做了一些约束和特定平台的增补。过去在 js 引擎下运行支持的语法大部分在 uts 的处理下也可以平滑地在 Kotlin 和 Swift 中使用但有一些无法抹平的能力差异需要使用条件编译。和 uni-app 的条件编译类似uts 也支持条件编译写在条件编译里的代码可以调用平台特有的扩展语法。语言细节可参考仓库 docs/uts/README.md 与 docs/uts/uts_diff_ts.md。UTS 插件是什么UTS 插件是一种特定的 uni_modules 插件其核心目的是允许 uni-app/uni-app x 开发者使用 UTS 语法来调用扩展 API封装原生系统的 API 或三方 SDK。UTS 插件的实现代码主要位于utssdk目录下并按平台进行分离和组织模块 readme 中的目录说明如下| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS, Kotlin, Java | 存放 UTS 插件在 Android 平台上的具体实现源码 | |utssdk/app-ios| iOS | UTS, Swift | 存放 UTS 插件在 iOS 平台上的具体实现源码 | |utssdk/app-harmony| HarmonyOS鸿蒙 | UTS, ArkTS | 存放 UTS 插件在 HarmonyOS 平台上的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 存放使用 UTS 语言编写的、可供所有平台共用的实现源码 |uni-getLaunchOptionsSync恰好属于最后一种形态它没有平台分目录全部实现集中在多平台共用的 utssdk/index.uts 中一次编写即可在各端编译运行。完整的插件开发范式可继续阅读 docs/plugin/uts-plugin.md、混编方案 docs/plugin/uts-plugin-hybrid.md以及各平台注意事项 docs/plugin/uts-for-android.md、docs/plugin/uts-for-ios.md、docs/plugin/uts-for-harmony.md。uni.getLaunchOptionsSync API 说明仓库 docs/api/launch.md 提供了该 API 的权威规范说明uni.getLaunchOptionsSync()用于获取首次启动时的参数返回值与 App.onLaunch 的回调参数一致返回类型为OnLaunchOptions。返回值OnLaunchOptions 属性| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | path | string | 是 | 首次启动时的页面路径返回值与 App.onLaunch 的回调参数一致 | | appScheme | string | 否 | 首次启动时的 Scheme返回值与 App.onLaunch 的回调参数一致 | | appLink | string | 否 | 首次启动时的 appLink通用链接返回值与 App.onLaunch 的回调参数一致 | | query | UTSJSONObject | 否 | 启动时的 query 参数 |在微信小程序平台返回对象还扩展了apiCategory、forwardMaterials、hostExtraData、referrerInfo、scene、chatType、shareTicket等小程序场景字段如referrerInfo.appId表示来源小程序/公众号/App 的 appIdchatType表示群聊类型apiCategory表示 API 类别详见 docs/api/launch.md 的完整属性表。兼容性根据 docs/api/launch.md 的兼容性表基础能力path/query各端支持情况如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 3.91 | 4.11 | 4.61 |appScheme与appLink属于较新的能力Android/iOS 在 VDOM 架构下自 4.25 起支持HarmonyOS 自 4.81 起支持微信小程序、Web 端不支持标记为 x。query在 Android/iOS 上始终支持√HarmonyOS 自 4.81 起支持。同一份平台标记也以uniPlatform注释的形式写在 utssdk/interface.uts 的每个字段上供 HBuilderX 编译与代码提示使用。使用前提若应用通过 scheme 或 appLink通用链接启动可通过本 API 获取相应参数。scheme 或 appLink 需要在manifest.json中配置或在原生的AndroidManifest.xml、iOS 的Info.plist、鸿蒙的 json5 中配置打包后生效。若要开发直达页面功能一般配合应用的onShow生命周期监听详见 docs/collocation/app.md。源码级实现解析核心实现defineSyncApi 与模块内状态整个插件的实现只有十几行完整源码如下utssdk/index.utsimport { __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是模块内部的闭包变量默认值取__uniConfig.entryPagePath即pages.json中配置的入口页面路径作为pathquery初始为空对象。也就是说即使框架尚未注入真实启动信息API 也能返回一个合理默认值。内部写入器setLaunchOptionsSync(options)用于在应用启动阶段由框架注入真实的启动参数。它被export导出但并不对业务层开放Uni接口中未声明该方法属于插件内部约定的写入通道体现了框架写入、业务读取的职责划分。对外 APIdefineSyncApiGetLaunchOptionsSync(getLaunchOptionsSync, () launchOptions)是 uts 定义同步 API 的标准方式——第一个参数是 API 名称第二个参数是同步执行函数直接返回模块内缓存的launchOptions。由于是纯同步读取调用无需回调、立即返回结果。类型契约interface.utsutssdk/interface.uts 定义了三个关键类型export type OnLaunchOptions { path: string, // 首次启动时的页面路径 appScheme: string | null, // 首次启动时的 Scheme appLink: string | null, // 首次启动时的 appLink query?: UTSJSONObject | null // 启动时的 query 参数 } export type GetLaunchOptionsSync () OnLaunchOptions export interface Uni { getLaunchOptionsSync(): OnLaunchOptions }值得注意的细节appScheme与appLink是可空的string | null只有通过 scheme/通用链接方式启动时才非空普通点击图标启动时返回nullquery是可选字段类型为UTSJSONObject携带的是首次启动时页面 URL 上的 query 参数类型定义上每个字段都带有uniPlatform注释如 AndroidunixVer: 3.91、iOSunixVer: 4.11、HarmonyOSuniVer: 4.31、微信小程序unixVer: 4.41等这是 uni-app x 生态中为编辑器提供平台兼容性提示的通用做法——鼠标悬停即可看到该字段在各端各架构VDOM/Vapor下的支持版本Uni接口的声明意味着该 API 会被挂载到全局uni对象上业务代码直接以uni.getLaunchOptionsSync()调用。实战在 uni-app x 项目中读取启动参数仓库自带一个完整的示例页面 src/pages/API/get-launch-options-sync/get-launch-options-sync.uvue展示了两种典型用法读取启动路径并校验首页const getLaunchOptionsSync () { const launchOptions uni.getLaunchOptionsSync() data.launchOptionsPath launchOptions.path if (launchOptions.path data.homePagePath) { data.checked true } }点击按钮后调用uni.getLaunchOptionsSync()取出path与预期首页路径比对即可判断本次启动是否从首页进入。对比 onLaunch 回调结果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 }这里用state.globalData.launchOptions由App.onLaunch写入与uni.getLaunchOptionsSync()的结果逐字段比对验证两者一致性——这也正是文档所述返回值与 App.onLaunch 的回调参数一致的工程化验证方式。onLaunch侧的数据写入见 src/App.uvueonLaunch((res : OnLaunchOptions) { updateGlobalData(launchOptions, res) ... })典型场景scheme/通用链接直达页面应用冷启动通过 scheme 或通用链接进入时这些启动参数是判断从哪来、去哪页的关键。仓库 src/App.uvue 给出了一个完整的 scheme/universal link 解析直达页面的范例scheme 格式约定为uniappx://redirect/pages/component/view/view?keyvalueredirect后为页面路径universal link 格式约定为https://uniappx.dcloud.net.cn/ulink/redirect.html?url%2Fpages%2Fcomponent%2Fview%2Fview%3Fkey%3Dvalueurl参数值需做 url 编码可用encodeURIComponent在onAppShow中取出res.appScheme、res.appLink解析出目标路径再通过uni.navigateTo完成直达onAppShow((res : OnShowOptions) { let url getRedirectUrl(res.appScheme, res.appLink); if (null ! url) { uni.navigateTo({ url: url }) } ... })注意 scheme/通用链接的解析一般放在onShow而非 onLaunch 中因为应用可能从后台被 scheme 唤醒此时需要的是本次展示的参数对应uni.getEnterOptionsSync()而getLaunchOptionsSync只反映首次启动。生态中的二次引用该 API 还被统计类插件引用。例如 src/uni_modules/uni-stat/utssdk/common/utils/pageInfo.uts 中注释保留了通过uni.getLaunchOptionsSync()?.scene获取启动场景值的用法可见它可作为应用级埋点/统计的启动信息来源。自动化测试验证与 onLaunch 的一致性仓库为该 API 编写了端到端测试 src/pages/API/get-launch-options-sync/get-launch-options-sync.test.js两个用例分别覆盖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等于入口页面Vapor 架构下为/pages/tabBar/tab-bar其他架构为/pages/tabBar/component第二个用例验证核心契约uni.getLaunchOptionsSync()与App.onLaunch回调结果在 path、appScheme、appLink 三个字段上完全一致。这组测试同时印证了源码中setLaunchOptionsSync写入通道与onLaunch回调数据同源的设计事实。与 getEnterOptionsSync 的区别uni.getLaunchOptionsSync常与 docs/api/launch.md 中同篇收录的uni.getEnterOptionsSync()对比后者获取的是本次启动含从后台激活到前台时的参数返回值与App.onShow回调参数一致。两者的区别相当于应用的onShow与onLaunch的区别——冷启动取getLaunchOptionsSync冷启动或热启动后台回到前台均需要取getEnterOptionsSync。选择哪个 API取决于业务要响应应用首次启动还是应用每次展示。总结uni-getLaunchOptionsSync是 uni-app x 中一个小而美的 UTS 插件范本通过defineSyncApi注册同步 API、以模块级闭包维护启动信息、用uniPlatform注释管理跨端兼容性并在 docs/api/launch.md 中沉淀了完整的字段契约与兼容矩阵。掌握它的实现与用法不仅能正确处理冷启动路径、query、scheme、appLink 等场景如活动页直达、渠道归因、启动埋点也能举一反三地理解整个 uni-app x UTS 插件生态的编写范式。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考