 完全指南：UniApp 对象、globalData 与全局方法调用)
示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载getApp()是 uni-app x 中获取当前应用实例的核心 API通过它可以在任意页面或 uts 插件中访问App.uvue暴露的全局方法与全局数据。本文以 docs/api/get-app.md 为骨架结合当前仓库中 App.uvue、store/index.uts 及 hello-uvue 示例工程 的源码实现系统讲解getApp()的返回值结构、HBuilderX 4.31 前后的行为差异、UniApp对象上各属性与方法的能力边界并给出可直接运行的完整实战示例。读完本文你将掌握通过getApp().vm调用 App 全局方法、通过getApp().globalData读写全局数据的标准姿势以及 Android 原生上下文、鸿蒙 Ability 获取和整应用重启等进阶能力。getApp() 的作用与演进getApp()函数用于获取当前应用实例通过该实例可以调用App.uvue中methods里定义的方法详见下文全局方法调用一节。自 HBuilderX 4.31 起该 API 的行为发生了重要变化理解这段演进是正确使用它的前提HBuilderX 4.31 以前getApp()返回的是 Vue 实例且无法在 uts 插件中使用。HBuilderX 4.31新增UniApp对象用于管理 appgetApp()返回UniApp对象原来的 Vue 实例则作为UniApp对象的vm属性提供。这一设计的核心动机是UniApp对象可在 uts 插件和 uvue 页面中同时使用但vm属性及其相关的globalData仍然只能在 uvue 页面中使用。换言之getApp()在 uts 插件里拿到的只是不依赖 Vue 运行时的原生层应用对象而页面中才能进一步触达 Vue 实例层。从仓库源码可以印证这套分层结构hello-uvue 示例的 index 页面 中的自动化测试同时使用了两种访问路径const checkGlobalData () : boolean { const app getApp() const globalData app.globalData // 直接访问 UniApp.globalData return globalData.str globalData str globalData.num 1 globalData.boolean } const checkLaunchPath () : boolean { const app getApp() return app.vm!.checkLaunchPath() // 通过 vm 调用 App.uvue 暴露的方法 }使用限制getApp()只能在script中调用不能直接在模板中使用。若在模板表达式里需要应用实例数据应先在script中取值再绑定到页面响应式状态。UniApp对象可同时在 uts 插件和 uvue 页面中使用vm属性及其相关的globalData仍然只能在 uvue 页面中使用。getApp 兼容性getApp()本身及各能力在不同平台上的支持情况如下√表示支持x表示不支持数字表示支持的 HBuilderX 版本号| Web | 微信小程序 | Android | Android(Vapor) UTS 插件 | iOS | iOS(VDOM) UTS 插件 | iOS(Vapor) UTS 插件 | HarmonyOS | | :- | :- | :- | :- | :- | :- | :- | :- | | 4.0 | √ | √ | x | √ | 4.31 | x | 4.61 |可以看到getApp()在 Web、微信小程序、Android、iOS 及 HarmonyOS4.61等主流平台上均可用而 Vapor 渲染引擎的 UTS 插件场景目前尚未支持。返回值UniApp 对象getApp()的返回类型为 UniApp。UniApp 的属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | vm | ComponentPublicInstance | 否 | Web: 4.31; 微信小程序: x; Android: 4.31; Android(Vapor) UTS 插件: x; iOS: 4.31; iOS UTS 插件: x; HarmonyOS: 4.61 | App vue 实例对象 | | globalData | RecordK, T | 是 | Web: 4.31; 微信小程序: x; Android: 4.31; Android(Vapor) UTS 插件: x; iOS: 4.31; iOS(Vapor) UTS 插件: x; HarmonyOS: 4.61 | 全局对象 | |$vm| ComponentPublicInstance | 否 | Web: 4.31; 微信小程序: x; Android: 4.31; Android(Vapor) UTS 插件: x; iOS: 4.31; iOS UTS 插件: x; HarmonyOS: 4.61 | App vue 实例对象已废弃仅为了向下兼容保留|要点解读globalData为必选属性是存放应用级全局数据的容器vm与$vm为可选属性。vm与废弃的$vm指向同一 App Vue 实例新代码统一使用vm$vm的存在只是为了旧代码平滑迁移。ComponentPublicInstance对应选项式 API 中的组件实例类型可参考 选项式 API 文档 中的定义。在微信小程序端vm/$vm/globalData均为 x不支持这是 uni-app x 与原生微信小程序框架在应用实例模型上的差异点跨端开发时需注意。从源码看 globalData 的典型组织方式在当前仓库的 src/store/index.uts 中GlobalData被定义为一个覆盖多种数据类型的结构可作为定义自己globalData的模板export type GlobalData { str: string num: number bool: boolean obj: UTSJSONObject null: string | null arr: number[] set: Setstring map: Mapstring, any fun: () string launchOptions: OnLaunchOptions showOptions: OnShowOptions }对应的初始化在 同文件的 state 定义 中并提供了updateGlobalData(key, value)方法按 key 更新各字段src/store/index.uts#L188-L224。这种类型定义 集中初始化 按 key 更新的模式既保证了类型安全也便于在App.uvue与页面之间共享。另外hello-uvue 工程的 App.uvue 演示了另一种声明方式——通过defineOptions直接声明globalDatadefineOptions({ globalData: { str: globalData str, num: 1, boolean: true } })两种方式殊途同归页面里都可以用getApp().globalData读取例如上文checkGlobalData测试所验证的globalData.str globalData str globalData.num 1 globalData.boolean。UniApp 的方法UniApp对象除了属性外还提供了几个面向原生能力的方法均可在 uts 插件与 uvue 页面中使用。getAndroidApplication(): Application获取 Android 应用Application上下文。兼容性| Web | 微信小程序 | Android(VDOM) | Android(Vapor) | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | x | x | 4.31 | x | x | x |返回值ApplicationAndroid 应用上下文对象。该方法的典型用途是在页面中获取 Android 原生上下文以调用原生 API。示例来自 docs/api/get-app.md 的完整示例代码运行于 Android 且非 Vapor 引擎时// #ifdef APP-ANDROID !VUE3-VAPOR const getAndroidApplication () : boolean { const app getApp() data.androidApplication app.getAndroidApplication() return data.androidApplication ! null } // #endif注意示例代码用条件编译APP-ANDROID !VUE3-VAPOR限定平台与兼容性表格中仅 Android(VDOM) 4.31 支持完全对应。getHarmonyAbility(): UIAbility获取鸿蒙应用Ability实例对应 HarmonyOS 的 UIAbility即应用入口能力。兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS(VDOM) | HarmonyOS(Vapor) | | :- | :- | :- | :- | :- | :- | | x | x | x | x | 4.61 | x |返回值UIAbility鸿蒙 Ability 实例。仅在 HarmonyOS(VDOM) 且 HBuilderX 4.61 可用在 uts 插件中获取后可用于访问鸿蒙侧的原生能力。restart(url?: string): void重启应用。兼容性| Web | 微信小程序 | Android(VDOM) | Android(Vapor) | iOS(VDOM) | iOS(Vapor) | HarmonyOS | | :- | :- | :- | :- | :- | :- | :- | | x | x | x | 5.31 | x | 5.31 | x |参数| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | url | string | 否 | Web: x; 微信小程序: x; HarmonyOS: x | 重启后打开的页面地址 |restart()目前仅在 iOS(VDOM)、iOS(Vapor) 的 5.31 版本可用可传入url指定重启后要打开的页面Web、微信小程序、HarmonyOS 不支持该能力。完整示例读写 globalData 与调用 App 全局方法以下完整示例来自 docs/api/get-app.md对应官方演示工程的 get-app 页面。它演示了getApp()的三个核心用法读取globalData、更新globalData、通过vm调用App.uvue中定义的方法并配合 src/store/index.uts 的updateGlobalData实现数据更新template !-- #ifdef APP -- scroll-view styleflex: 1; padding-bottom: 20px !-- #endif -- view stylepadding-bottom: 20px page-head titlegetApp/page-head view classuni-padding-wrap button clickgetGlobalDataget globalData/button template v-ifdata.originGlobalData.str.length text classuni-common-mt bold初始的 globalData:/text text classuni-common-mtglobalData string: {{ data.originGlobalData.str }}/text text classuni-common-mtglobalData number: {{ data.originGlobalData.num }}/text text classuni-common-mtglobalData boolean: {{ data.originGlobalData.bool }}/text text classuni-common-mtglobalData object: {{ data.originGlobalData.obj }}/text text classuni-common-mtglobalData null: {{ data.originGlobalData.null }}/text text classuni-common-mtglobalData array: {{ data.originGlobalData.arr }}/text text classuni-common-mtglobalData Set: {{ data.originGlobalData.set }}/text text classuni-common-mtglobalData Map: {{ data.originGlobalData.map }}/text text classuni-common-mtglobalData fun 返回值: {{ data.originGlobalDataFuncRes }}/text /template button clicksetGlobalData classuni-common-mt set globalData /button template v-ifdata.newGlobalData.bool text classuni-common-mt bold更新后的 globalData:/text text classuni-common-mtglobalData string: {{ data.newGlobalData.str }}/text text classuni-common-mtglobalData number: {{ data.newGlobalData.num }}/text text classuni-common-mtglobalData boolean: {{ data.newGlobalData.bool }}/text text classuni-common-mtglobalData object: {{ data.newGlobalData.obj }}/text text classuni-common-mtglobalData null: {{ data.newGlobalData.null }}/text text classuni-common-mtglobalData array: {{ data.newGlobalData.arr }}/text text classuni-common-mtglobalData Set: {{ data.newGlobalData.set }}/text text classuni-common-mtglobalData Map: {{ data.newGlobalData.map }}/text text classuni-common-mtglobalData fun 返回值: {{ data.newGlobalDataFuncRes }}/text /template text classuni-common-mt点击按钮调用 App.uvue methods/text text classuni-common-mtincreaseLifeCycleNum 方法/text button classuni-common-mt click_increaseLifeCycleNum increase lifeCycleNum /button text classuni-common-mtlifeCycleNum: {{ data.lifeCycleNum }}/text !-- #ifdef APP-ANDROID !VUE3-VAPOR -- button classuni-common-mt clickgetAndroidApplication getAndroidApplication /button text classuni-common-mtandroidApplication is null: {{ data.androidApplication null }}/text !-- #endif -- /view /view !-- #ifdef APP -- /scroll-view !-- #endif -- /template script setup languts import { state, setLifeCycleNum, updateGlobalData } from /store/index.uts type MyGlobalData { str : string, num : number, bool : boolean, obj : UTSJSONObject, null : string | null, arr : number[], set : string[], map : UTSJSONObject, fun : () string } type DataType { originGlobalData: MyGlobalData; originGlobalDataFuncRes: string; newGlobalData: MyGlobalData; newGlobalDataFuncRes: string; lifeCycleNum: number; androidApplication: any | null; } const data reactive({ originGlobalData: { str: , num: 0, bool: false, obj: { str: , num: 0, bool: false }, null: null, arr: [] as number[], set: [] as string[], map: {}, fun: () : string }, originGlobalDataFuncRes: , newGlobalData: { str: , num: 0, bool: false, obj: { str: , num: 0, bool: false }, null: null, arr: [] as number[], set: [] as string[], map: {}, fun: () : string }, newGlobalDataFuncRes: , lifeCycleNum: 0, androidApplication: null } as DataType) const getGlobalData () { data.originGlobalData.str state.globalData.str data.originGlobalData.num state.globalData.num data.originGlobalData.bool state.globalData.bool data.originGlobalData.obj state.globalData.obj data.originGlobalData.null state.globalData.null data.originGlobalData.arr state.globalData.arr state.globalData.set.forEach((value : string) { data.originGlobalData.set.push(value) }) state.globalData.map.forEach((value : any, key : string) { data.originGlobalData.map[key] value }) data.originGlobalData.fun state.globalData.fun data.originGlobalDataFuncRes data.originGlobalData.fun() } const setGlobalData () { updateGlobalData(str, new globalData str) updateGlobalData(num, 100) updateGlobalData(bool, true) updateGlobalData(obj,{ str: new globalData obj str, num: 200, bool: true }) updateGlobalData(null, not null) updateGlobalData(arr, [1, 2, 3]) updateGlobalData(set, new Set([a, b, c])) updateGlobalData(map, new Mapstring, any([ [a, 1], [b, 2], [c, 3] ])) updateGlobalData(fun, () : string { return new globalData fun }) data.newGlobalData.str state.globalData.str data.newGlobalData.num state.globalData.num data.newGlobalData.bool state.globalData.bool data.newGlobalData.obj state.globalData.obj data.newGlobalData.null state.globalData.null data.newGlobalData.arr state.globalData.arr console.log(state.globalData.arr,state.globalData.arr) console.log(state.globalData.set,state.globalData.set) state.globalData.set.forEach((value : string) { data.newGlobalData.set.push(value) }) state.globalData.map.forEach((value : any, key : string) { data.newGlobalData.map[key] value }) data.newGlobalData.fun state.globalData.fun data.newGlobalDataFuncRes data.newGlobalData.fun() } const _increaseLifeCycleNum () { const app getApp() app.vm!.increaseLifeCycleNum() data.lifeCycleNum state.lifeCycleNum } // 自动化测试 const setLifeCycleNumFunc (num : number) { setLifeCycleNum(num) } // #ifdef APP-ANDROID !VUE3-VAPOR const getAndroidApplication () : boolean { const app getApp() data.androidApplication app.getAndroidApplication() return data.androidApplication ! null } // #endif onReady(() { data.lifeCycleNum state.lifeCycleNum }) defineExpose({ data, getGlobalData, setGlobalData, _increaseLifeCycleNum, setLifeCycleNumFunc, // #ifdef APP-ANDROID !VUE3-VAPOR getAndroidApplication // #endif }) /script style .bold { font-weight: bold; } .hr { border-bottom: 1px solid #ccc; } /style示例要点拆解_increaseLifeCycleNum中app.vm!.increaseLifeCycleNum()即通过getApp()调用App.uvue中定义的全局方法的标准写法非空断言!表示信任vm一定存在页面环境满足该前提。该示例对应本仓库 src/App.uvue 中increaseLifeCycleNum的定义与导出const increaseLifeCycleNum () { setLifeCycleNum(state.lifeCycleNum 100) console.log(App increaseLifeCycleNum) } defineExpose({ increaseLifeCycleNum, })updateGlobalData的实现见 src/store/index.uts#L188-L224它通过 switch 按 key 对globalData各字段赋值并支持Set、Map、函数等复杂类型。全局方法调用appmethods上文的示例中getApp()后调用了App.uvue里定义的increaseLifeCycleNum方法。在 HBuilderX 4.31 中getApp()返回值调整为UniApp类型后调用App.uvue中定义的全局方法需要做如下调整| 版本 | 调用方式 | | :- | :- | | 4.31 之前 |getApp().methodName()| | 4.31 及之后 |getApp().vm?.methodName()|即必须经由vm属性才能触达 App Vue 实例上暴露的方法。仓库示例工程中同样遵循这一写法例如 hello-uvue 的 App.uvue 在onAppShow中通过getApp()?.vm?.globalPropertiesStr读取全局属性index 页面 通过app.vm!.checkLaunchPath()与app.vm!.checkAppMixin()调用 App 暴露的测试方法。配套的App.uvue侧需要将方法通过defineExpose暴露出去见 src/App.uvue#L181-L183页面侧才能通过vm调用如果App.uvue中没有defineExpose则相应方法对外不可见。结合源码的纵深解读调用链与数据流把文档、示例与仓库源码串起来可以梳理出getApp()相关的完整调用链应用启动App.uvue的onLaunch被触发src/App.uvue#L8-L57其中把启动参数写入globalData.launchOptions并调用checkSystemTheme()等初始化逻辑。数据初始化globalData的初始值在 src/store/index.uts#L70-L93 的state中统一声明字符串、数字、布尔、UTSJSONObject、数组、Set、Map、函数、启动参数等页面与App.uvue共享同一个state单例。页面访问任意页面const app getApp()拿到UniApp对象直接读app.globalData或通过app.vm!.xxx()调用App.uvue用defineExpose暴露的全局方法。数据更新通过updateGlobalData(key, value)修改globalData后页面读取到的数据同步更新示例中setGlobalData里还通过state.globalData.set.forEach、state.globalData.map.forEach遍历Set/Map后回填到本地响应式数据。原生能力需要 AndroidApplication或鸿蒙UIAbility时分别调用app.getAndroidApplication()仅 Android(VDOM)与app.getHarmonyAbility()仅 HarmonyOS(VDOM)实现从 uni-app x 业务层触达原生层。这一数据流与调用链在 examples/hello-uvue 工程中有完整实现可供对照阅读入口 App.uvue、首页 pages/index/index.uvue 中的checkGlobalData、checkLaunchPath、checkAppMixin三个自动化测试方法即是对上述三条访问路径的运行时验证。通用类型GeneralCallbackResultgetApp()相关文档末尾还给出了一个通用回调结果类型定义| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |该类型是 uni-app x 中各类异步 API 回调结果的基础类型统一通过errMsg字段描述错误信息在接口统一性与错误处理规范中广泛复用。总结与最佳实践围绕getApp()可以沉淀出以下实践建议优先访问globalData跨页面、跨模块共享的应用级数据放在globalData中页面侧通过getApp().globalData.xxx读取对Set、Map等容器类型遍历后再回填到页面本地数据参考示例中的写法避免直接引用造成的响应式问题。调用 App 全局方法必须走vmHBuilderX 4.31 一律使用getApp().vm?.methodName()或app.vm!.methodName()并在App.uvue中通过defineExpose显式暴露旧代码中getApp().methodName()的写法需要迁移。留意平台差异vm/globalData在微信小程序端不可用getAndroidApplication()仅 Android(VDOM)getHarmonyAbility()仅 HarmonyOS(VDOM) 4.61restart()仅 iOS 5.31。涉及这些能力的代码建议用条件编译包裹。仅限 script 中使用getApp()不能出现在模板中模板需要的数据提前在script setup中取出存入响应式变量。废弃属性不复用$vm仅为向下兼容保留新代码统一使用vm。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x App.uvue 主组件完全指南应用生命周期、globalData 全局变量、全局方法与全局样式uni app x App.uvue 主组件完全指南应用生命周期、globalData 全局变量、全局方法与全局样式 App.uvue 是 uni app x示例工程前端移动开发跨平台uni-app x 全局变量与状态管理实战globalData、Pinia 与全局 reactive 变量uni app x 全局变量与状态管理实战globalData、Pinia 与全局 reactive 变量 导读 本文围绕 uni app x 的全局数据共享示例工程前端移动开发跨平台uni-app x UTS 内置对象 Uint16Array 完全指南构造、属性与全部实例方法详解uni app x UTS 内置对象 Uint16Array 完全指南构造、属性与全部实例方法详解 本篇指南系统讲解 uni app x 的 UTS 语言中内示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
