uni-app getLaunchOptionsSync 與 getEnterOptionsSync應(yīng)用啟動參數(shù)獲取與直達(dá)頁面開發(fā)實(shí)戰(zhàn)指南【免費(fèi)下載鏈接】uni-appA cross-platform framework using Vue.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/un/uni-app導(dǎo)讀uni-app 框架為跨端應(yīng)用提供了同步獲取啟動參數(shù)的能力uni.getLaunchOptionsSync()返回應(yīng)用首次啟動對應(yīng)App.onLaunch時的完整參數(shù)uni.getEnterOptionsSync()返回本次啟動/從后臺回到前臺對應(yīng)App.onShow時的完整參數(shù)。兩者組合可支撐“Scheme/AppLink 直達(dá)頁面”“渠道歸因統(tǒng)計(jì)”“分享回流追蹤”等核心業(yè)務(wù)場景。本文基于開源倉庫 uni-app 的官方 API 文檔與uni-getLaunchOptionsSync、uni-getEnterOptionsSync兩個 UTS 插件源碼系統(tǒng)講解 API 返回值結(jié)構(gòu)、平臺兼容性、原生端 Scheme/AppLink 配置方式、典型示例代碼與自動化測試驗(yàn)證幫助你在 App、小程序、Web 多端統(tǒng)一落地啟動參數(shù)處理邏輯。說明倉庫內(nèi)docs/api/get-launch-options-sync.md已遷移至docs/api/launch.md本文即基于該目標(biāo)文檔整理擴(kuò)充。一、API 概覽兩個同步 API 的分工1.1 uni.getLaunchOptionsSync()獲取首次啟動時的參數(shù)返回值與App.onLaunch的回調(diào)參數(shù)一致僅在應(yīng)用冷啟動時產(chǎn)生。| 平臺 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | 4.0 | 4.41 | 3.91 | 4.11 | 4.61 |1.2 uni.getEnterOptionsSync()獲取本次啟動時的參數(shù)返回值與App.onShow的回調(diào)參數(shù)一致。兩者區(qū)別相當(dāng)于應(yīng)用生命周期中onLaunch與onShow的區(qū)別onLaunch只在冷啟動時觸發(fā)一次onShow在每次應(yīng)用從后臺激活到前臺都會觸發(fā)因此getEnterOptionsSync適合處理“后臺切前臺”以及“通過 Scheme/AppLink 從外部拉起”的動態(tài)場景。| 平臺 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | 4.0 | 4.41 | 4.25 | 4.25 | 4.61 |應(yīng)用生命周期onLaunch/onShow的完整說明可參見 應(yīng)用生命周期文檔。二、返回值結(jié)構(gòu)與類型定義getLaunchOptionsSync()返回類型為OnLaunchOptionsgetEnterOptionsSync()返回類型為OnShowOptions兩者字段結(jié)構(gòu)一致。字段的官方定義見 getLaunchOptionsSync 接口定義。2.1 核心字段說明| 名稱 | 類型 | 必備 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | path | string | 是 | Web: 4.0; 微信小程序: 4.41; Android: 3.91; iOS: 4.11; HarmonyOS: 4.61 | 首次啟動或本次啟動時的頁面路徑與App.onLaunch/App.onShow回調(diào)參數(shù)一致 | | appScheme | string | 否 | Android/iOS(VDOM): 4.25; Vapor: 5.25; HarmonyOS(VDOM): 4.81; Vapor: 5.25; Web/微信小程序: 不支持 | 啟動時的 Scheme即通過自定義 URL Scheme 拉起應(yīng)用時攜帶的 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 參數(shù)UTSJSONObject 類型說明見 UTSJSONObject | | apiCategory | string | 否 | 微信小程序: 4.41基礎(chǔ)庫 2.20.0 | API 類別 | | forwardMaterials | any | 否 | 微信小程序: 4.41 | 打開的文件信息數(shù)組僅從聊天素材場景scene 為 1173打開時攜帶 | | hostExtraData | OnLaunchOptionsHostExtraData | 否 | 微信小程序: 4.41 | 宿主傳遞的數(shù)據(jù)第三方 App 中運(yùn)行小程序時返回 | | referrerInfo | OnLaunchOptionsReferrerInfo | 否 | 微信小程序: 4.41 | 來源信息從另一個小程序、公眾號或 App 進(jìn)入時返回否則返回{}| | scene | number | 否 | 微信小程序: 4.41 | 場景值 | | chatType | number | 否 | 微信小程序: 4.41 | 從微信群聊/單聊打開小程序時的聊天類型 | | shareTicket | string | 否 | 微信小程序: 4.41 | 分享票據(jù) |2.2 子對象字段詳解apiCategory 合法值微信小程序?qū)質(zhì) 合法值 | 含義 | | :- | :- | | default | 默認(rèn)類別 | | nativeFunctionalized | 原生功能化視頻號直播商品、商品櫥窗等場景打開的小程序 | | browseOnly | 僅瀏覽朋友圈快照頁等場景打開的小程序 | | embedded | 內(nèi)嵌通過打開半屏小程序能力打開的小程序 | | chatTool | 聊天工具通過打開聊天工具能力打開的小程序 |hostExtraData 字段微信小程序?qū)質(zhì) 名稱 | 類型 | 必備 | 描述 | | :- | :- | :- | :- | | host_scene | string | 否 | 宿主 App 對應(yīng)的場景值 |referrerInfo 字段微信小程序?qū)質(zhì) 名稱 | 類型 | 必備 | 描述 | | :- | :- | :- | :- | | appId | string | 否 | 來源小程序、公眾號或 App 的 appId | | extraData | IAnyObject | 否 | 來源小程序傳過來的數(shù)據(jù)scene 為 1037 或 1038 時支持 |chatType 合法值微信小程序?qū)質(zhì) 合法值 | 含義 | | :- | :- | | 1 | 微信聯(lián)系人單聊 | | 2 | 企業(yè)微信聯(lián)系人單聊 | | 3 | 普通微信群聊 | | 4 | 企業(yè)微信互通群聊 |從類型定義可以看出appScheme與appLink在源碼中聲明為string | null且僅在 App 端VDOM 4.25/Vapor 5.25支持query聲明為可選UTSJSONObjectApp 全平臺支持而apiCategory、forwardMaterials、hostExtraData、referrerInfo、scene、chatType、shareTicket等字段僅在微信小程序端由宿主注入屬于小程序生態(tài)特有的啟動上下文。三、源碼級實(shí)現(xiàn)原理同步 API 的數(shù)據(jù)從哪來getLaunchOptionsSync與getEnterOptionsSync分別由兩個獨(dú)立的 UTS 插件實(shí)現(xiàn)位于倉庫src/uni_modules/目錄下。3.1 getLaunchOptionsSync 的實(shí)現(xiàn)uni-getLaunchOptionsSync 插件主實(shí)現(xiàn)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 }, )關(guān)鍵實(shí)現(xiàn)要點(diǎn)默認(rèn)值兜底在框架尚未寫入真實(shí)啟動參數(shù)前l(fā)aunchOptions初始化為{ path: __uniConfig.entryPagePath, query: {} }即應(yīng)用配置的首頁路徑entryPagePath來自 pages.json保證任何時機(jī)調(diào)用都有合理返回值。同步返回通過defineSyncApi聲明為同步 API直接返回內(nèi)存中緩存的launchOptions對象無需等待異步回調(diào)。寫入入口setLaunchOptionsSync由框架在應(yīng)用冷啟動完成參數(shù)組裝后調(diào)用將真實(shí)的OnLaunchOptions覆蓋到模塊內(nèi)部變量這正是“返回值與App.onLaunch回調(diào)參數(shù)一致”的機(jī)制來源。3.2 getEnterOptionsSync 的實(shí)現(xiàn)uni-getEnterOptionsSync 插件主實(shí)現(xiàn) 采用了完全一致的實(shí)現(xiàn)模式僅默認(rèn)值類型換為OnShowOptions、寫入函數(shù)為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 共享同一套“默認(rèn)值兜底 setter 覆蓋 同步讀取”模式它們的差異完全體現(xiàn)在框架何時調(diào)用 settersetLaunchOptionsSync在冷啟動時寫入setEnterOptionsSync在每次 onShow 時寫入。UTS 插件本身通過 uni_modules 機(jī)制按平臺編譯Android 編譯為 Kotlin、iOS 編譯為 Swift、鴻蒙編譯為 ArkTS、Web/小程序編譯為 JavaScript插件結(jié)構(gòu)說明詳見 uni-getLaunchOptionsSync 插件 readme。四、Scheme 與 AppLink 直達(dá)頁面配置文檔明確指出如果應(yīng)用通過Scheme或AppLink通用鏈接啟動可以通過上述 API 獲取相應(yīng)參數(shù)。配置方式分為兩層manifest.json 可視化配置在 HBuilderX 的 manifest 中配置 Scheme 與 AppLink原生配置文件兜底也可在原生AndroidManifest.xml、iOS 的Info.plist、鴻蒙的 json5 中直接配置倉庫根目錄可見 AndroidManifest.xml、Info.plist。配置均需打包后生效。若開發(fā)“直達(dá)頁面”功能外部鏈接直接打開應(yīng)用內(nèi)指定頁面一般需要在應(yīng)用的onShow生命周期中監(jiān)聽并處理見 App 生命周期 onShow 說明。核心判斷邏輯是啟動時從path判斷目標(biāo)頁面從query解析業(yè)務(wù)參數(shù)從appScheme/appLink確認(rèn)外部來源渠道。倉庫示例工程 App.uvue 展示了onLaunch中接收OnLaunchOptions的典型用法將啟動參數(shù)寫入全局 storeupdateGlobalData(launchOptions, res)、上報uni.report統(tǒng)計(jì)、按需處理隱私彈窗等。其中g(shù)etRedirectUrl函數(shù)src/App.uvue即解析 scheme/universal link 以決定是否跳轉(zhuǎn)直達(dá)頁面的實(shí)現(xiàn)可作為落地參考。五、完整示例代碼以下示例取自倉庫示例工程src/pages/API/get-launch-options-sync/get-launch-options-sync.uvue同時參考文檔內(nèi)嵌示例可直接在頁面中運(yùn)行。5.1 獲取首次啟動參數(shù)getLaunchOptionsSynctemplate page-head titlegetLaunchOptionsSync/page-head view classuni-padding-wrap button clickgetLaunchOptionsSyncgetLaunchOptionsSync/button view classuni-common-mt text應(yīng)用本次啟動路徑/text text stylemargin-top: 5px{{ data.launchOptionsPath }}/text /view view classuni-common-mt text應(yīng)用本次啟動/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要點(diǎn)說明調(diào)用uni.getLaunchOptionsSync()后可直接讀取path、appScheme、appLink、query等字段示例通過JSON.stringify(launchOptions, null, 2)格式化展示完整返回compareOnLaunchRes將該 API 的結(jié)果與App.onLaunch寫入全局 store 的state.globalData.launchOptions逐字段比對用于驗(yàn)證“返回值與 onLaunch 回調(diào)一致”的文檔承諾全局 store 的類型定義見 src/store/index.uts。5.2 獲取本次啟動參數(shù)getEnterOptionsSynctemplate page-head titlegetEnterOptionsSync/page-head view classuni-padding-wrap view classuni-common-mt text應(yīng)用本次啟動路徑/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實(shí)際工程中g(shù)etEnterOptionsSync更適合與onShow生命周期配合在每次從后臺回到前臺或外部拉起時重新讀取參數(shù)并做路由分發(fā)文檔建議直達(dá)頁面邏輯放在 onShow 中處理。六、自動化測試驗(yàn)證倉庫為上述兩個 API 提供了對應(yīng)的自動化測試見 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 結(jié)果一致, async () { const page await program.navigateTo(PAGE_PATH) await page.waitFor(view) const pageData await page.data(data) expect(pageData.testResult).toBe(true) }) })測試覆蓋兩個關(guān)鍵斷言正常取值導(dǎo)航到示例頁并調(diào)用getLaunchOptionsSync后返回的path應(yīng)與首頁路徑一致data.checked true一致性校驗(yàn)getLaunchOptionsSync()的返回與App.onLaunch回調(diào)寫入全局 store 的launchOptions逐字段相等data.testResult true從測試層面鎖定了文檔所述“返回值與 App.onLaunch 的回調(diào)參數(shù)一致”的行為契約。getEnterOptionsSync的對應(yīng)測試位于 get-enter-options-sync.test.js邏輯同構(gòu)校驗(yàn)其與App.onShow回調(diào)參數(shù)的一致性。七、實(shí)戰(zhàn)場景與選型建議| 場景 | 推薦 API | 原因 | | :- | :- | :- | | 冷啟動渠道歸因統(tǒng)計(jì)首次打開來源 | getLaunchOptionsSync | 只關(guān)心應(yīng)用首次啟動時的 path/query/appScheme/appLink | | Scheme/AppLink 直達(dá)頁面 | getEnterOptionsSync onShow | 外部拉起可能發(fā)生在應(yīng)用已運(yùn)行后臺切前臺時需每次 onShow 讀取 | | 微信小程序場景值統(tǒng)計(jì) | 兩者均可小程序端 | 可讀取 scene/chatType/apiCategory/referrerInfo 等宿主注入字段 | | 判斷是否從首頁正常進(jìn)入 | getLaunchOptionsSync | 對比path與首頁路徑如pages/tabBar/component |注意事項(xiàng)appScheme/appLink字段有嚴(yán)格平臺限制Web 與微信小程序端不支持返回null僅 App 端 VDOM 4.25/Vapor 5.25、HarmonyOS 4.81 可用query的類型為UTSJSONObject取值后可繼續(xù)用 JSON 解析提取業(yè)務(wù)參數(shù)文檔中“如果應(yīng)用通過 scheme 或 applink 啟動可通過本 API 獲取相應(yīng)參數(shù)”的前提是原生側(cè)配置已完成且打包生效referrerInfo在非來源場景下返回空對象{}讀取其子字段前應(yīng)先判空。八、總結(jié)uni.getLaunchOptionsSync()與uni.getEnterOptionsSync()是 uni-app 應(yīng)用感知自身“從何而來、去往何頁”的標(biāo)準(zhǔn)入口前者覆蓋冷啟動場景對應(yīng)onLaunch后者覆蓋每次前臺展示場景對應(yīng)onShow二者共享OnLaunchOptions/OnShowOptions結(jié)構(gòu)配合原生 Scheme/AppLink 配置即可低成本實(shí)現(xiàn)跨端直達(dá)頁面與啟動歸因。結(jié)合倉庫中 UTS 插件源碼默認(rèn)值兜底 setter 覆蓋 defineSyncApi 同步讀取的實(shí)現(xiàn)模式與自動化測試返回參數(shù)與生命周期回調(diào)一致性斷言開發(fā)者可以放心地在業(yè)務(wù)中同步讀取啟動參數(shù)并在多端統(tǒng)一維護(hù)同一套處理邏輯。相關(guān)接口文檔與示例代碼位于 docs/api/launch.md、示例頁面 與 getEnterOptionsSync 示例?！久赓M(fèi)下載鏈接】uni-appA cross-platform framework using Vue.js項(xiàng)目地址: https://gitcode.com/gh_mirrors/un/uni-app創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考