HarmonyOS UIContext 详解从入门到实战摘要UIContext 是 ArkUI 框架中至关重要的上下文对象它提供了组件运行时获取系统信息、显示对话框、管理焦点、获取设备状态等核心能力。本文将全面解析 UIContext 的常用方法与使用场景并通过一个完整的交互面板示例演示如何在实际项目中运用 UIContext。效果一、UIContext 概述1.1 什么是 UIContextUIContext是 ArkUI 框架在组件生命周期中自动注入的上下文对象。每个组件实例都拥有自己独立的UIContext通过getUIContext()方法获取。UIContext 的核心价值在于解耦——组件无需直接依赖全局单例或系统 API而是通过 UIContext 这个中介访问系统服务这使得组件具备良好的可测试性和可移植性。1.2 获取方式在任何组件的方法中调用getUIContext()即可获取当前组件的 UIContext 实例ComponentV2struct MyComponent{build(){Button(获取上下文).onClick((){constcontextthis.getUIContext()// 使用 context 调用各种系统服务})}}二、核心方法详解2.1 显示对话框UIContext 提供了多种内置对话框方法可以直接在组件中调用方法说明showActionMenu()显示操作菜单showDatePickerDialog()显示日期选择对话框showTimePickerDialog()显示时间选择对话框showTextPickerDialog()显示文本选择对话框showAlertDialog()显示警告对话框日期选择示例this.getUIContext().showDatePickerDialog({start:newDate(2000-01-01),end:newDate(),selected:newDate(),lunar:false,onDateAccept:(value:Date){this.selectedDatevalue}})文本选择示例this.getUIContext().showTextPickerDialog({range:[选项A,选项B,选项C],selected:0,onAccept:(value:TextPickerResult){this.selectedTextvalue.valueasstring}})2.2 焦点管理方法说明getFocusController()获取焦点控制器setDefaultFocus()设置默认焦点this.getUIContext().getFocusController().requestFocus(targetId)2.3 获取系统信息方法返回值说明getMediaQuery()MediaQuery获取媒体查询对象getPromptAction()PromptAction获取提示操作对象getRouter()Router获取路由对象getWindowProperties()WindowProperties获取窗口属性获取屏幕信息示例constmediaQuerythis.getUIContext().getMediaQuery()constisLandscapemediaQuery.widthmediaQuery.height2.4 提示操作PromptAction通过getPromptAction()可以获取提示操作对象实现 Toast、AlertDialog 等交互constpromptActionthis.getUIContext().getPromptAction()// 显示 Toast 提示promptAction.showToast({message:操作成功,duration:2000})// 显示确认对话框promptAction.showDialog({title:确认,message:确定要删除这条记录吗,buttons:[{text:取消,color:Color.Gray},{text:确定,color:#1976D2}]}).then((result:PromptAction.ShowDialogSuccessResponse){if(result.index1){// 执行删除操作}})2.5 窗口与导航方法说明getWindowStage()获取窗口舞台对象getNavigation()获取 Navigation 导航栈getAppStorage()获取 AppStorage三、使用注意事项3.1 生命周期约束getUIContext()只能在组件的build()方法或事件回调中调用不要在组件的构造函数或属性初始化阶段调用在aboutToAppear()中可以安全调用3.2 与 AbilityContext 的区别对比项UIContextAbilityContext获取方式this.getUIContext()getContext(this)作用域UI 层面应用/能力层面典型用途对话框、焦点、动画网络请求、文件操作、权限申请3.3 最佳实践优先使用 UIContext在 UI 层面对话框、提示、焦点等优先使用 UIContext避免全局缓存UIContext 与组件实例绑定不应缓存到全局变量异步安全在异步回调中使用 UIContext 前检查组件是否仍然挂载四、实战示例多功能交互面板下面通过一个综合示例演示 UIContext 在实际项目中的多种用法。4.1 效果描述创建一个交互面板包含以下功能点击按钮显示日期选择器选择日期后在页面展示所选日期操作完成后显示 Toast 提示点击确认按钮弹出确认对话框4.2 完整代码EntryComponentV2struct UIContextDemo{LocalselectedDate:string未选择日期LocaltoastMessage:stringLocalconfirmResult:stringLocalshowDialog:booleanfalseLocalpickerRange:string[][主题A深海蓝,主题B森林绿,主题C星空紫]LocalselectedTheme:string未选择主题build(){Column(){// 页面标题Text(UIContext 交互面板).fontSize(22).fontWeight(FontWeight.Bold).margin({top:32,bottom:24})// 日期选择卡片Column(){Text( 日期选择).fontSize(16).fontWeight(FontWeight.Medium).margin({bottom:12})Row(){Text(this.selectedDate).fontSize(18).fontColor(#1976D2).layoutWeight(1)Button(选择日期).fontSize(14).backgroundColor(#1976D2).fontColor(Color.White).borderRadius(8).onClick((){this.getUIContext().showDatePickerDialog({start:newDate(2024-01-01),end:newDate(2026-12-31),selected:newDate(),lunar:false,disappearTextStyle:{color:Color.Gray,font:{size:14fp,weight:FontWeight.Normal}},textStyle:{color:#333333,font:{size:18fp,weight:FontWeight.Regular}},selectedTextStyle:{color:#1976D2,font:{size:22fp,weight:FontWeight.Bold}},onDateAccept:(value:Date){constyearvalue.getFullYear()constmonth(value.getMonth()1).toString().padStart(2,0)constdayvalue.getDate().toString().padStart(2,0)this.selectedDate${year}-${month}-${day}this.getUIContext().getPromptAction().showToast({message:日期选择成功,duration:1500})}})})}.width(100%)}.width(100%).padding(16).borderRadius(12).backgroundColor(#F5F5F5).margin({bottom:16})// 主题选择卡片Column(){Text( 主题选择).fontSize(16).fontWeight(FontWeight.Medium).margin({bottom:12})Row(){Text(this.selectedTheme).fontSize(18).fontColor(#2E7D32).layoutWeight(1)Button(选择主题).fontSize(14).backgroundColor(#2E7D32).fontColor(Color.White).borderRadius(8).onClick((){this.getUIContext().showTextPickerDialog({range:this.pickerRange,selected:0,canLoop:false,onAccept:(value:TextPickerResult){this.selectedThemevalue.valueasstringthis.getUIContext().getPromptAction().showToast({message:已选择${this.selectedTheme},duration:1500})},onCancel:(){this.getUIContext().getPromptAction().showToast({message:取消选择,duration:1500})}})})}.width(100%)}.width(100%).padding(16).borderRadius(12).backgroundColor(#F5F5F5).margin({bottom:16})// 确认对话框卡片Column(){Text(⚠️ 操作确认).fontSize(16).fontWeight(FontWeight.Medium).margin({bottom:12})Text(this.confirmResult).fontSize(14).fontColor(#666666).margin({bottom:12})Button(执行操作).width(100%).backgroundColor(#D32F2F).fontColor(Color.White).borderRadius(8).onClick((){constpromptActionthis.getUIContext().getPromptAction()promptAction.showDialog({title:操作确认,message:此操作不可逆确定要继续吗,buttons:[{text:取消,color:Color.Gray},{text:确定执行,color:#D32F2F}]}).then((result:PromptAction.ShowDialogSuccessResponse){if(result.index1){this.confirmResult✅ 操作已执行promptAction.showToast({message:操作成功,duration:1500})}else{this.confirmResult❌ 操作已取消}})})}.width(100%).padding(16).borderRadius(12).backgroundColor(#F5F5F5)}.width(100%).height(100%).padding({left:16,right:16}).backgroundColor(#FFFFFF)}}4.3 关键代码解析1. 日期选择器配置showDatePickerDialog接受一个配置对象其中关键属性包括start/end限制可选日期范围selected默认选中日期lunar是否显示农历disappearTextStyle/textStyle/selectedTextStyle自定义滚轮文字样式onDateAccept用户确认时的回调实际项目中的注意要点start和end的范围应覆盖所有示例数据的月份。例如示例数据覆盖了 2026年6月~7月则应设置为new Date(2020-01-01)到new Date(2030-12-31)确保用户可以选择任何有数据的月份。2. 文本选择器showTextPickerDialog可以展示自定义选项列表this.getUIContext().showTextPickerDialog({range:this.pickerRange,// 选项数组selected:0,// 默认选中索引canLoop:false,// 是否循环滚动onAccept:(value){...},// 确认回调onCancel:(){...}// 取消回调})3. 确认对话框通过getPromptAction().showDialog()实现自定义对话框支持多个按钮和异步回调promptAction.showDialog({title:操作确认,message:确定要执行此操作吗,buttons:[{text:取消,color:Color.Gray},{text:确定,color:#D32F2F}]}).then((result){// result.index 对应被点击的按钮索引})4. Toast 提示通过getPromptAction().showToast()显示简短提示常用于操作反馈this.getUIContext().getPromptAction().showToast({message:操作成功,duration:1500// 显示时长毫秒})五、UIContext 方法速查表类别方法用途对话框showDatePickerDialog()日期选择showTimePickerDialog()时间选择showTextPickerDialog()文本/列表选择showActionMenu()操作菜单提示getPromptAction().showToast()Toast 提示getPromptAction().showDialog()确认对话框getPromptAction().showActionMenu()弹出菜单焦点getFocusController()焦点控制媒体getMediaQuery()媒体查询路由getRouter()路由管理动画animateTo()显式动画六、总结UIContext 是 ArkUI 开发中连接系统服务与 UI 组件的桥梁。掌握以下要点即可应对绝大多数场景获取方式通过this.getUIContext()在组件方法中获取对话框能力日期选择、文本选择、确认对话框等内置对话框即调即用提示操作通过getPromptAction()获取 Toast、Dialog 等提示能力生命周期安全只在build()方法和事件回调中使用避免缓存到全局日期选择器范围start/end参数应覆盖项目中所有数据月份否则用户无法通过日期选择器跳转到有数据的月份深色主题适配使用disappearTextStyle、textStyle、selectedTextStyle自定义滚轮文字颜色以匹配深色主题配色参考文档HarmonyOS UIContext 官方文档HarmonyOS PromptAction 使用指南