羽球场边工具 HarmonyOS 元服务实战（01）：元服务工程与 installationFree 配置

一、先确认元服务能力属于模块而不是首页按钮场边临时组局时用户需要快速打开计分、排阵或费用计算而不是先理解一套完整应用的导航。这里的低摩擦入口并不是在页面上加一个“极速启动”文案而是由模块配置声明交付形态。把这一层写进 module.json5运行时首页只负责工具选择工程边界才清晰。],deliveryWithInstall:true,installationFree:true,metadata:[{name:client_id,value:6917606123842596563}],querySchemes:[https],pages:$profile:main_pages,abilities:[{name:EntryAbility,srcEntry:./ets/entryability/EntryAbility.ets,description:$string:EntryAbility_desc,icon:$media:icon,label:$string:EntryAbility_label,startWindowIcon:$media:startIcon,startWindowBackground:$color:start_window_background,exported:true,二、installationFree 与 deliveryWithInstall 表达什么entry 模块同时声明 deliveryWithInstall 与 installationFree。前者描述模块随安装交付后者允许系统按元服务能力处理入口两项都位于 module 级配置而不在 Index.ets 内部。若把它们误写成页面变量即使卡片仍能渲染也无法改变包的交付语义。参与者输入输出或约束模型或配置稳定标识、模式或模块字段给出可追溯的工程事实服务或系统能力经过归一化的请求返回明确结果或失败原因页面回读后的结果只渲染不保存第二份事实tablet],deliveryWithInstall:true,installationFree:true,metadata:[{name:client_id,value:6917606123842596563}],querySchemes:[https],pages:$profile:main_pages,abilities:[{name:EntryAbility,srcEntry:./ets/entryability/EntryAbility.ets,description:$string:EntryAbility_desc,icon:$media:icon,label:$string:EntryAbility_label,startWindowIcon:$media:startIcon,startWindowBackground:$color:start_window_background,三、首页工具如何避免承担分发判断Index 页展示“羽球场边工具”、主应用工具箱、计分器等内容并把点击分派到对应页面。它不判断安装包类型也不拼装安装请求。这样计分状态、配对结果和费用输入仍是本地工具功能分发和安装能力则由工程配置、签名及系统环境共同决定。constMAIN_APP_LINK:stringhttps://kuqideharmonyos.drcn.agconnect.link/2m4d;EntryComponentstruct Index{StaterecommendationExpanded:booleanfalse;StateshowJumpFailure:booleanfalse;StatejumpFailureMessage:string主应用链接暂不可用请稍后重试;openMainApp():void{constcontext:common.UIAbilityContextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;constowner:Indexthis;this.showJumpFailurefalse;constcompletionHandler:CompletionHandler{onRequestSuccess(elementName:bundleManager.ElementName,message:string):void{hilog.info(DOMAIN,JUMP_TAG,OpenLink completion success, message: %{public}s, element: %{public}s,message,JSON.stringify(elementName));},onRequestFailure(elementName:bundleManager.ElementName,message:string):void{hilog.error(DOMAIN,JUMP_TAG,OpenLink completion failure, message: %{public}s, element: %{public}s,message,JSON.stringify(elementName));owner.jumpFailureMessage主应用链接暂不可用请稍后重试;owner.showJumpFailuretrue;四、构建结果能验证哪些边界本次对当前工程执行 assembleHap 已成功说明配置能通过资源、ArkTS、打包与签名链路。构建成功并不等同于每个分发入口都在任意设备上可用实际系统入口还会受到设备支持、账号和平台配置影响。文章只把源码配置与构建结果作为工程事实不夸大为线上分发已完成。情况容易出现的错误本文采用的处理数据或配置缺项伪造默认成功状态停在可解释的失败或空态页面重进使用上一页残留对象从模型、服务或系统重新回读重复动作再写一遍相同业务事实由稳定入口或回调收敛import{AppColors,AppSizes,AppText}from../common/Theme;ComponentEntrystruct QuickScoringPage{StateplayerA:stringA队;StateplayerB:stringB队;StatescoreA:number0;StatescoreB:number0;Statehistory:ScoreMatch[][];StatefinishedText:string;addScore(team:string,delta:number):void{if(teamA){this.scoreAMath.max(0,this.scoreAdelta);}else{this.scoreBMath.max(0,this.scoreBdelta);}}reset():void{this.scoreA0;this.scoreB0;五、从入口到工具卡片的检查项检查时先读取打包后的 module.json 中 installationFree 是否保留再安装或启动正确 bundle确认首页展示计分、排阵、费用三类工具入口随后依次进入一个本地工具并返回首页确认页面导航没有承担安装判断。配图只展示可控设备中的主页不把它当作平台分发成功的证明。验收阶段实际动作回读重点前置确认启动正确 bundle 或打开目标页标题、入口与模块身份主题操作执行搜索、切换、完成或跳转服务/系统返回的结果重进检查返回、重启或切换范围后再进入事实没有依赖旧页面残留六、实现边界与维护顺序元服务入口的安装形态由模块配置决定主页专注计分、排阵和费用工具不把分发属性藏进页面点击逻辑。 新增需求时应先补齐模型、配置或服务合同再调整页面入口把同一个判断复制到多个组件短期看似方便后续会使结果无法回读。ArkTS 状态管理的基础机制可参考 HarmonyOS 官方文档。七、继续扩展时的约束元服务工程最容易混淆的是能构建与能被目标系统入口识别。前者由当前工程的依赖、资源和签名流程决定后者还依赖设备能力和平台配置。把两层分别写入验收记录既不贬低成功构建的价值也不会凭一个首页截图宣称所有分发条件已经成立。首页的角色是把用户带到计分、排阵和费用计算不应该顺便记录安装、分发或账户状态。场边操作通常节奏快导航层越少越好业务模块各自管理输入和结果用户从工具返回时才能保留清晰的上下文。新增原子服务能力时先检查模块声明、入口路由和打包产物再决定是否需要修改首页卡片。这个顺序把平台能力与产品功能隔离开能减少一次分发配置调整误伤比赛工具的风险。配置检查不要依赖文件名猜测是否为元服务要看实际 module.json5 的 module 声明和打包产物而不是目录名、图标名或首页文案。重命名项目不会改变 installationFree 的真实值复制模板也可能留下不匹配的配置。把配置字段列入构建前检查能在发布前发现这种表面一致、语义错误的问题。本地工具的启动验收启动后先确认 bundle 身份和主页标题再点击一个明确的工具卡片例如计分器。进入、操作、返回三个动作能证明路由与主页集成仍可用它不证明聚合链接或平台上架状态。不同结论使用不同证据是避免元服务文章夸大范围的关键。