鸿蒙 ArkTS 布局深入浅出：Panel 组件三种模式（Mini / Half / Full）完全解析 鸿蒙 ArkTS 布局深入浅出Panel 组件三种模式Mini / Half / Full完全解析前言在 HarmonyOS NEXTAPI 24的应用开发中UI 布局是绕不开的核心话题。ArkTS 作为鸿蒙原生声明式开发语言提供了一系列强大且易用的布局组件。其中Panel面板组件是一个非常实用的容器类控件——它从屏幕底部滑入支持三种高度模式切换广泛应用于播放器、设置面板、评论区域等需要「展开-收起」交互的场景。本文将围绕 Panel 的三种模式——Mini最小、Half半屏和Full全屏——展开详细讲解并附上完整可运行的示例代码帮助读者快速掌握这一布局利器。一、Panel 组件概述1.1 什么是 PanelPanel 是 ArkUI 提供的一种可拖拽、可切换高度模式的底部面板组件。与传统的 Dialog 或 BottomSheet 不同Panel 具有以下特性三种预设高度模式迷你、半屏、全屏可通过代码或手势切换内置拖拽条dragBar用户可直接拖拽面板边缘切换模式灵活的高度自定义每种模式均可独立设置高度值圆角和阴影支持视觉层次感强回调监听完善模式变化、可见性变化均可捕捉1.2 适用场景场景推荐模式说明音乐播放器迷你栏Mini展示歌曲名 播放控制按钮评论列表 / 弹幕面板Half半屏展示留出内容区域商品详情 / 文章阅读Full全屏沉浸式浏览设置选项 / 筛选器Half半屏表单操作后自动收起地图底部的路线面板Half → Full拖拽渐变展开二、Panel 三种模式详解Panel 的核心能力围绕PanelMode枚举展开。API 24 中该枚举的三个成员为PanelMode.Mini、PanelMode.Half、PanelMode.Full。注意早期 API如 API 11~12中枚举值名为MIN/HALF/FULL全大写API 24 统一为 PascalCase 风格Mini/Half/Full迁移时需相应调整。Mini 模式面板的最小高度形态由.miniHeight()属性控制单位为 vp。适用于展示简短的提示信息、播放器迷你控制栏、通知预览等轻量场景。Half 模式面板展开至屏幕约一半高度由.halfHeight()属性控制支持百分比与数值。适用于列表选择器、评论输入区域、配置选项面板等中等体量的内容。Full 模式面板几乎占满屏幕通常 90%~95%由.fullHeight()属性控制。适用于详情展示页面、编辑器和媒体全屏控制面板等需要大面积展示的场景。三种模式之间可以通过手势拖拽无缝切换体验流畅自然。三、项目实战三种模式切换演示3.1 核心代码实现以下为基于 API 24 的 Panel 演示页面的完整实现已通过hvigorw assembleApp编译验证。EntryComponentstruct PanelDemo{StateisPanelShow:booleanfalse;StatecurrentMode:PanelModePanelMode.Mini;StatemodeLabel:stringMini最小;privatereadonlymodeList:PanelMode[][PanelMode.Mini,PanelMode.Half,PanelMode.Full];privatereadonlymodeLabels:string[][Mini最小,Half半屏,Full全屏];switchToNextMode():void{constithis.modeList.indexOf(this.currentMode);constnext(i1)%this.modeList.length;this.currentModethis.modeList[next];this.modeLabelthis.modeLabels[next];}setMode(mode:PanelMode,label:string):void{this.currentModemode;this.modeLabellabel;if(!this.isPanelShow)this.isPanelShowtrue;}build(){Stack(){// 背景内容区域Column(){Text(Panel 三种模式演示).fontSize(24).fontWeight(FontWeight.Bold).margin({top:24});Text(当前模式${this.modeLabel}).fontSize(18).margin({top:12,bottom:24});// 方式一轮换切换Button(切换至下一模式).width(90%).height(48).type(ButtonType.Capsule).backgroundColor(#FF007AFF).fontColor(Color.White).onClick((){this.switchToNextMode();this.isPanelShowtrue;}).margin({bottom:24});// 方式二直接跳转Row(){Button(MIN).height(44).layoutWeight(1).type(ButtonType.Capsule).backgroundColor(this.currentModePanelMode.Mini?#FF007AFF:#FFCCCCCC).onClick(()this.setMode(PanelMode.Mini,Mini最小));Button(HALF).height(44).layoutWeight(1).type(ButtonType.Capsule).backgroundColor(this.currentModePanelMode.Half?#FF007AFF:#FFCCCCCC).onClick(()this.setMode(PanelMode.Half,Half半屏));Button(FULL).height(44).layoutWeight(1).type(ButtonType.Capsule).backgroundColor(this.currentModePanelMode.Full?#FF007AFF:#FFCCCCCC).onClick(()this.setMode(PanelMode.Full,Full全屏));}.width(90%).margin({bottom:24});}.width(100%).height(100%).backgroundColor(#FFF5F5F5);// Panel 组件Panel(this.isPanelShow){Column(){Text(▼ 向上拖拽可切换模式).fontSize(14).margin({top:8});Text(面板内容区).fontSize(20).fontWeight(FontWeight.Bold);Text(this.modeLabel).fontSize(28).fontColor(#FF007AFF);if(this.currentModePanelMode.Mini){this.modeDesc(Mini,面板仅展示最小高度内容。);}elseif(this.currentModePanelMode.Half){this.modeDesc(Half,面板展开至屏幕一半高度。);}else{this.modeDesc(Full,面板几乎填满整个屏幕。);}}.width(100%).padding({left:16,right:16,bottom:24});}.mode(this.currentMode).dragBar(true).miniHeight(200).halfHeight(50%).fullHeight(90%).backgroundColor(#FFFFFFFF).borderRadius(20).onChange((m:PanelMode):void{this.currentModem;constidxthis.modeList.indexOf(m);if(idx!-1)this.modeLabelthis.modeLabels[idx];}).onVisibleAreaChange([0.0,0.5,1.0],(v:boolean):void{this.isPanelShowv;}).shadow({radius:16,color:rgba(0,0,0,0.15),offsetX:0,offsetY:-4});}.width(100%).height(100%).alignContent(Alignment.Bottom);}BuildermodeDesc(title:string,desc:string):void{Column(){Text(title).fontSize(16).fontWeight(FontWeight.Medium);Text(desc).fontSize(14).fontColor(#FF666666).lineHeight(22);}.width(90%).padding(16).backgroundColor(#FFF0F4FF).borderRadius(12).margin({top:8,bottom:8});}}3.2 页面路由注册在resources/base/profile/main_pages.json中{src:[pages/Index,pages/PanelDemo]}四、核心 API 深度解读4.1 构造函数Panel(value:boolean)API 24 接受直接布尔值不再支持{ show: boolean }对象字面量。4.2 关键属性属性方法说明示例值.mode(PanelMode)设置面板高度模式PanelMode.Half.miniHeight(length)Mini 模式高度vp200.halfHeight(len | str)Half 模式高度50%或400.fullHeight(len | str)Full 模式高度90%或700.dragBar(boolean)显示拖拽条true4.3 回调事件回调说明参数.onChange(cb)模式切换时触发(PanelMode) void.onVisibleAreaChange(ratios, cb)可见比例变化时触发number[] callbackonVisibleAreaChange替代了旧版onVisibleChange需额外传入阈值数组如[0.0, 0.5, 1.0]。五、API 24 迁移对照从 API 11~12 迁移到 API 24 的核心变更旧 API11~12新 API24说明Panel({ show })Panel(bool)构造参数简化PanelMode.MINPanelMode.MiniPascalCase 统一PanelMode.HALFPanelMode.Half同上PanelMode.FULLPanelMode.Full同上.minHeight(v).miniHeight(v)属性重命名.onVisibleChange(cb).onVisibleAreaChange(ratios, cb)新增 ratios 参数import { PanelMode }无需 import全局类型六、最佳实践高度单位选择Mini 模式推荐使用固定 vp 值如200使内容紧凑可控Half / Full 模式推荐使用百分比字符串如50%自适应屏幕状态同步务必实现onChange回调将拖拽产生的模式变化同步到应用状态避免「按钮显示 Half 而面板实际已到 Full」的不一致。Stack 容器对齐Panel 从底部弹出包裹它的Stack容器应设为alignContent(Alignment.Bottom)。圆角与阴影为 Panel 添加顶部圆角和阴影可显著提升视觉层次.borderRadius(20) .shadow({ radius: 16, color: rgba(0,0,0,0.15), offsetX: 0, offsetY: -4 })七、扩展思路与 List 结合在 Panel 内部放置List实现可拖拽展开的评论列表或通知中心——最常用的生产级场景。配合动画结合animateTo在模式切换时添加内容自定义动画进一步提升体验。自定义拖拽条设置dragBar(false)用PanGesture自行实现拖拽手势区域配合onChange完成模式切换适合需要精致设计的场景。八、总结Panel 组件是 HarmonyOS NEXT 中极具实用价值的布局组件。它的三种高度模式——Mini、Half、Full——覆盖了从「轻量提示」到「全屏详情」的全场景需求。配合拖拽手势、灵活的样式定制和完备的回调体系开发者只需少量代码就能构建出体验流畅的底部面板交互。API 24 的命名变更虽然带来了一些迁移成本但统一后的 PascalCase 风格使代码更加规整与 ArkTS 整体语言风格保持一致。希望本文能帮助你在实际项目中高效地使用 Panel 组件。