HarmonyOS ArkTS 中的枚举：enum 完全使用指南与最佳实践

文章目录前言一、为什么要用枚举和常量1.1 魔法值的危害1.2 本项目 Constants.ets 的设计二、TypeScript 枚举enum2.1 数字枚举2.2 字符串枚举2.3 常量枚举const enum三、项目 Constants.ets 深度解析3.1 查看 Constants 的使用模式3.2 为什么用 class 而不是 namespace 或 const四、综合实战用枚举重构状态管理4.1 加载状态枚举化总结前言在 HarmonyOS 项目中你是否见过代码里散落着16、0.5、100%、GasStationPage这样的魔法值它们的意思令人困惑修改时还容易遗漏。枚举enum和常量类是解决这一问题的利器。本项目的Constants.ets就是一个标准的常量管理方案——本篇结合项目实践深入讲解 TypeScript 枚举和常量模式。一、为什么要用枚举和常量1.1 魔法值的危害// ❌ 错误示范魔法值满天飞if(status2){// 2 是什么谁知道moveCamera(16);// 16 是缩放级别还是别的showDialog(loading);// loading 这个字符串到处重复}// ✅ 正确示范使用常量/枚举if(statusStationStatus.OPEN){// 一目了然moveCamera(MapConstants.DEFAULT_ZOOM);showDialog(DialogType.LOADING);}1.2 本项目 Constants.ets 的设计本项目将所有魔法值集中管理// Constants.ets节选exportclassConstants{// 字体大小staticreadonlyFONT_SIZE_1414;staticreadonlyFONT_SIZE_1616;staticreadonlyFONT_SIZE_2020;// 间距staticreadonlySPACE_66;staticreadonlySPACE_88;staticreadonlySPACE_1212;staticreadonlySPACE_1616;// 百分比尺寸staticreadonlyFULL_PERCENT100%;staticreadonlyPERCENT_7070%;// 路由名称// ...}这种设计的优势修改方便只需改一处全局生效可读性强FONT_SIZE_16比16更清晰避免拼写错误IDE 自动补全不用担心写错二、TypeScript 枚举enum2.1 数字枚举// 数字枚举默认从0开始自增enumGasStationStatus{Unknown0,// 未知状态Open1,// 营业中Closed2,// 已关闭Temporary3// 临时停业}// 使用functiongetStatusText(status:GasStationStatus):string{switch(status){caseGasStationStatus.Open:return营业中;caseGasStationStatus.Closed:return已关闭;caseGasStationStatus.Temporary:return临时停业;default:return未知;}}constmyStatus:GasStationStatusGasStationStatus.Open;console.log(myStatus);// 输出: 1数字值console.log(GasStationStatus[1]);// 输出: Open反向映射console.log(getStatusText(myStatus));// 输出: 营业中2.2 字符串枚举// 字符串枚举更语义化适合用于路由名称、事件名称等enumPageName{MainMainPage,GasStationGasStationPage,SettingsSettingsPage,DetailStationDetailPage}enumMapEventName{MarkerClickmarkerClick,LocationClickmyLocationButtonClick,MapClickmapClick}// 使用functionnavigateTo(page:PageName,pageInfos:NavPathStack):void{pageInfos.pushPathByName(page,null);}// 替代之前的字符串字面量navigateTo(PageName.GasStation,this.pageInfos);// 等价于: this.pageInfos.pushPathByName(GasStationPage, null)提示字符串枚举没有反向映射功能不能通过值找到键名但调试时打印值更直观推荐在路由名称、事件名等场景使用。2.3 常量枚举const enum// const enum编译时直接内联值运行时无额外对象性能更好constenumZoomLevel{City12,District14,Street16,Building18,Max21}// 编译后ZoomLevel.Street 直接被替换为 16functionsetZoom(level:ZoomLevel):void{mapController.setZoom(level);// 实际上是 mapController.setZoom(16)}三、项目 Constants.ets 深度解析3.1 查看 Constants 的使用模式// Constants.ets完整示例基于项目实际结构重建exportclassConstants{// 字体 staticreadonlyFONT_SIZE_1414;staticreadonlyFONT_SIZE_1616;staticreadonlyFONT_SIZE_2020;staticreadonlyFONT_WEIGHT_400400;staticreadonlyFONT_WEIGHT_500500;staticreadonlyFONT_WEIGHT_700700;// 行高 staticreadonlyLINE_HEIGHT_1919;staticreadonlyLINE_HEIGHT_2121;staticreadonlyLINE_HEIGHT_2727;// 间距 staticreadonlySPACE_66;staticreadonlySPACE_88;staticreadonlySPACE_1212;staticreadonlySPACE_1616;staticreadonlyPADDING_LEFT_1212;staticreadonlyPADDING_LEFT_1616;staticreadonlyPADDING_RIGHT_1212;staticreadonlyPADDING_RIGHT_1616;staticreadonlyPADDING_TOP_88;staticreadonlyMARGIN_LEFT_1616;staticreadonlyMARGIN_RIGHT_1616;// 尺寸 staticreadonlyFULL_PERCENT100%;staticreadonlyPERCENT_7070%;staticreadonlyGAS_STATION_IMAGE_WIDTH48;staticreadonlyGAS_STATION_IMAGE_HEIGHT48;staticreadonlyIMAGE_NEXT_WIDTH16;staticreadonlyIMAGE_NEXT_HEIGHT16;staticreadonlyIMAGE_BACK_WIDTH24;staticreadonlyIMAGE_BACK_HEIGHT24;// 布局 staticreadonlyBORDER_RADIUS12;staticreadonlyBORDER_RADIUS_1616;staticreadonlySTROKE_WIDTH0.5;staticreadonlyONE1;staticreadonlyLAY_OUT_WEIGHT1;// 高度 staticreadonlyHEIGHT_8080;staticreadonlyPAGE_BUILDER_HEIGHT80;staticreadonlyMY_BUILDER_HEIGHT85%;staticreadonlyMY_BUILDER_COLUMN_HEIGHT50%;staticreadonlyBIND_SHEET_HEIGHT200;// 动画/定时 staticreadonlyTIME500;// 地图 staticreadonlyPOSITION_TOP48;}3.2 为什么用 class 而不是 namespace 或 const方案写法优缺点classstatic readonlyConstants.FONT_SIZE_16✅ 可组织、可 import、IDE 补全好namespaceNS.FONT_SIZE_16✅ 类似效果略显繁琐顶层constexport const FONT_SIZE_16 16✅ 最简单但容易命名冲突enumFontSize.SIZE_16✅ 适合有限值域状态、类型项目选择class static readonly是因为所有常量聚合在一个类下方便按模块组织import { Constants } from ...使用方便IDE 输入Constants.会显示所有可选常量四、综合实战用枚举重构状态管理4.1 加载状态枚举化// 定义枚举enumLoadStatus{Idleidle,// 初始状态Loadingloading,// 加载中Successsuccess,// 成功Emptyempty,// 数据为空Errorerror// 失败}enumSortOrder{ByDistancedistance,ByPriceprice,ByRatingrating}enumStationBrand{All全部,Sinopec中国石化,CNPC中国石油,Shell壳牌,BPBP}// 使用枚举的组件EntryComponentstruct EnumDemoPage{StateloadStatus:LoadStatusLoadStatus.Idle;StatesortOrder:SortOrderSortOrder.ByDistance;StateselectedBrand:StationBrandStationBrand.All;// 状态文本映射getStatusText():string{conststatusMap:RecordLoadStatus,string{[LoadStatus.Idle]:等待加载,[LoadStatus.Loading]:加载中...,[LoadStatus.Success]:加载成功,[LoadStatus.Empty]:暂无数据,[LoadStatus.Error]:加载失败};returnstatusMap[this.loadStatus];}getStatusColor():string{constcolorMap:RecordLoadStatus,string{[LoadStatus.Idle]:#999999,[LoadStatus.Loading]:#1A6FF5,[LoadStatus.Success]:#52C41A,[LoadStatus.Empty]:#FA8C16,[LoadStatus.Error]:#FF4D4F};returncolorMap[this.loadStatus];}build(){Column({space:16}){// 状态显示Text(this.getStatusText()).fontSize(18).fontWeight(FontWeight.Bold).fontColor(this.getStatusColor())// 品牌筛选枚举驱动Scroll(){Row({space:8}){ForEach(Object.values(StationBrand),(brand:string){Text(brand).fontSize(13).fontColor(this.selectedBrandbrandasStationBrand?#FFFFFF:#666666).padding({left:12,right:12,top:6,bottom:6}).backgroundColor(this.selectedBrandbrandasStationBrand?#1A6FF5:#F0F0F0).borderRadius(16).onClick((){this.selectedBrandbrandasStationBrand;})})}.padding({left:16})}.scrollable(ScrollDirection.Horizontal).scrollBar(BarState.Off)// 排序选项枚举驱动Row({space:8}){ForEach([{key:SortOrder.ByDistance,label:按距离},{key:SortOrder.ByPrice,label:按价格},{key:SortOrder.ByRating,label:按评分},],(item:Recordstring,string){Text(item[label]asstring).fontSize(13).fontColor(this.sortOrderitem[key]asSortOrder?#1A6FF5:#666666).fontWeight(this.sortOrderitem[key]asSortOrder?FontWeight.Bold:FontWeight.Normal).onClick((){this.sortOrderitem[key]asSortOrder;})})}// 模拟加载状态切换Row({space:8}){ForEach(Object.values(LoadStatus),(status:string){Button(status).fontSize(11).height(30).backgroundColor(#F0F0F0).fontColor(#333333).borderRadius(15).onClick((){this.loadStatusstatusasLoadStatus;})})}}.padding(20).width(100%).height(100%).backgroundColor(#F5F7FA)}}总结枚举和常量是消灭魔法值、提升代码可读性的利器。enum适合有限值域的类型状态、排序、品牌class static readonly适合聚合大量项目级常量本项目 Constants.ets 的方案。合理运用枚举不仅让代码意图清晰还能借助 TypeScript 类型系统在编译时发现错误——这正是静态类型语言的核心价值所在。