uni-app x 启动参数获取：uni-getLaunchOptionsSync UTS 插件实现与跨端实战-创锋一号

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 目录，由四个文件组成：

其中package.json的dcloudext.type: "uts"表明这是一个 UTS 插件；engines.HBuilderX: "^3.6.8"声明了最低 HBuilderX 版本要求；uni_modules.platforms中列出了客户端覆盖的 Vue2/Vue3、App（Android/iOS）、H5 及微信、阿里、百度、字节、QQ、钉钉、快手、飞书、京东等小程序端。

UTS 语言与 UTS 插件机制

理解这个模块前，需要先了解它的载体——UTS 插件。以下内容来自模块 readme.md 的说明。

uts 是什么

uts（uni type script）是一门跨平台的、高性能的、强类型的现代编程语言，它可以被编译为不同平台的编程语言：

Android 平台：编译为 Kotlin
iOS 平台：编译为 Swift
鸿蒙 OS 平台：编译为 ArkTS
web 平台 / 小程序：编译为 JavaScript

uts 采用了与 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 的 appId，chatType表示群聊类型，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.uts）：

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 = defineSyncApi<GetLaunchOptionsSync>( 'getLaunchOptionsSync', (): OnLaunchOptions => { return launchOptions }, )

从源码结构可以拆解出它的三层设计：

模块级状态：launchOptions是模块内部的闭包变量，默认值取__uniConfig.entryPagePath（即pages.json中配置的入口页面路径）作为path，query初始为空对象。也就是说，即使框架尚未注入真实启动信息，API 也能返回一个合理默认值。
内部写入器：setLaunchOptionsSync(options)用于在应用启动阶段由框架注入真实的启动参数。它被export导出但并不对业务层开放（Uni接口中未声明该方法），属于插件内部约定的写入通道，体现了"框架写入、业务读取"的职责划分。
对外 API：defineSyncApi<GetLaunchOptionsSync>('getLaunchOptionsSync', () => launchOptions)是 uts 定义同步 API 的标准方式——第一个参数是 API 名称，第二个参数是同步执行函数，直接返回模块内缓存的launchOptions。由于是纯同步读取，调用无需回调、立即返回结果。

类型契约：interface.uts

utssdk/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/通用链接方式启动时才非空，普通点击图标启动时返回null；
query是可选字段，类型为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.uvue：

onLaunch((res : OnLaunchOptions) => { updateGlobalData('launchOptions', res) ... })

典型场景：scheme/通用链接直达页面

应用冷启动通过 scheme 或通用链接进入时，这些启动参数是判断"从哪来、去哪页"的关键。仓库 src/App.uvue 给出了一个完整的 scheme/universal link 解析直达页面的范例：

scheme 格式约定为uniappx://redirect/pages/component/view/view?key=value（redirect后为页面路径）；
universal link 格式约定为https://uniappx.dcloud.net.cn/ulink/redirect.html?url=%2Fpages%2Fcomponent%2Fview%2Fview%3Fkey%3Dvalue（url参数值需做 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），仅供参考

企业官网建设流程全解析