HarmonyOS应用开发实战：猫猫大作战-Hero 共享元素概念、bindElements 双页面绑定、AnimationParams 转场参数、与

前言前面我们用animation/animateTo做了组件内动画——位置补间、缩放弹跳。但有种「跨页面」动画做不了点击列表里的猫咪小图跳到详情页大图小图「飞」到大图位置平滑放大——这种「同一元素在两个页面间连续过渡」就是Hero 共享元素动画。HarmonyOS 提供bindElementsAnimationParams机制实现。本篇以「猫猫大作战」点击棋盘上的猫跳到详情页为预演场景把Hero 共享元素概念、bindElements 双页面绑定、AnimationParams 转场参数、与 transition 转场的差异四大要点讲透。提示本系列不讲 ArkTS 础语法与环境搭建假设你已跟完第 1–56 篇。本篇是阶段三第七篇。一、场景拆解点击猫咪跳详情页「猫猫大作战」当前猫咪只在棋盘内渲染第 16、43 篇。玩家想点击某只猫跳到详情页显示该猫的等级/得分/位置——并且小图飞到大图位置平滑放大视觉连贯。跳转不用 Hero 是这样点击棋盘小猫60×60 ↓ 瞬间切页面 详情页大猫200×200出现在屏幕中央痛点瞬间切页面小图和大图视觉断裂玩家感觉「弹窗」而非「飞过去」。用 Hero 的效果点击棋盘小猫60×60位置 x120,y240 ↓ Hero 共享元素动画 小猫图从 (120,240,60×60) 平滑过渡到 (中央,200×200) ↓ 过渡完成 详情页大猫图200×200在中央关键经验Hero 共享元素 同一元素在两页面间连续过渡——小图「飞」到大图位置视觉连贯不断裂。二、Hero 共享元素概念2.1 什么是共享元素「共享元素」是 Material Design 提出的概念两个页面看起来「共享」了同一个 UI 元素——A 页面有个小图B 页面有个大图跳转时小图平滑过渡成大图玩家感觉这个「图」是同一个只是换了位置和大小。2.2 HarmonyOS 的 Hero 实现HarmonyOS 的 Hero 机制核心三步A 页面源元素绑bindElements标记「我是 Hero 源」。B 页面目标元素绑同名bindElements标记「我是 Hero 目标」。路由跳转时ArkUI 检测到同名绑定自动从源位置/大小补间到目标位置/大小。2.3 与 transition 转场的区别维度Hero 共享元素transition 转场范围单个元素跨页面整个页面进/出效果小图飞到大图页面淡入/滑动绑定bindElements 双页面同名transition 装在页面适合列表→详情图跳转页面路由切换关键经验Hero 管「单个元素跨页面」transition 管「整页面进/出」——本系列第 58 篇会专讲 transition。两者常配合用Hero 做关键元素过渡transition 做页面整体淡入。三、bindElements 双页面绑定3.1 源页面绑定棋盘小猫// 来源entry/src/main/ets/pages/Index.ets GameView() 棋盘 ForEach(this.cats, (cat: Cat) { Column() { Text(CatConfig[cat.level].emoji).fontSize(CatConfig[cat.level].size * 0.5) } .width(CatConfig[cat.level].size).height(CatConfig[cat.level].size) .borderRadius(CatConfig[cat.level].size / 2) .backgroundColor(CatConfig[cat.level].color) .position({ x: cat.x * 60, y: cat.y * 60 }) // ← Hero 源绑定cat.id 唯一标识 .bindElements(cat_${cat.id}, this.heroAnimation) .onClick(() { // 跳详情页传 cat.id this.navigateToDetail(cat.id); }) }, (cat: Cat) cat.id)3.2 目标页面绑定详情页大猫// 来源entry/src/main/ets/pages/CatDetailPage.ets Component export struct CatDetailPage { Prop catId: string; State cat: Cat | null null; aboutToAppear() { this.cat this.loadCat(this.catId); } build() { Column() { // 大猫图Hero 目标绑定同名 cat_${catId} Column() { Text(CatConfig[this.cat.level].emoji).fontSize(100) } .width(200).height(200) .borderRadius(100) .backgroundColor(CatConfig[this.cat.level].color) .bindElements(cat_${this.catId}, this.heroAnimation) // ← 同名绑定 /* ... 详情信息 ... */ } } }3.3 bindElements 参数.bindElements(key: string, animation: AnimationParams)参数含义key共享元素唯一键源和目标必须同名animationAnimationParams 转场动画参数关键经验bindElements 的 key 源和目标必须同名——ArkUI 靠同名匹配拼错就断裂为瞬切。四、AnimationParams 转场参数4.1 定义动画参数import { AnimationParams, Curve } from kit.ArkUI; private heroAnimation: AnimationParams { duration: 400, curve: Curve.EaseInOut, onFinish: () { console.info(Hero 过渡完成); } };4.2 参数字段字段含义推荐值duration过渡时长300–500mscurve缓动曲线EaseInOutdelay延迟开始0onFinish完成回调可选实战经验Hero duration 300–500ms 最佳——太短像瞬切太长拖沓。4.3 共用 AnimationParams// 多个共享元素用同一套动画参数 private heroAnimation: AnimationParams { duration: 400, curve: Curve.EaseInOut }; // 源页面 .bindElements(cat_${cat.id}, this.heroAnimation) .bindElements(score_${cat.id}, this.heroAnimation) // 多个共享元素 // 目标页面 .bindElements(cat_${this.catId}, this.heroAnimation) .bindElements(score_${this.catId}, this.heroAnimation)五、实战点击猫咪跳详情页5.1 路由配置新建entry/src/main/resources/base/profile/router.json或用现有的{ router: { catDetail: { path: catDetail, component: CatDetailPage } } }5.2 Index 源页面绑定// 来源entry/src/main/ets/pages/Index.etsHero 改造后 import { AnimationParams, Curve } from kit.ArkUI; import { router } from kit.ArkUI; Entry Component struct Index { State gameState: GameState GameState.IDLE; State cats: Cat[] []; /* ... 其他 state */ // Hero 动画参数本篇重点 private heroAnimation: AnimationParams { duration: 400, curve: Curve.EaseInOut, onFinish: () { console.info(Hero 过渡完成); } }; private gameEngine: GameEngine new GameEngine(); private readonly cols: number[] [0, 1, 2, 3, 4]; /* startGame / pauseGame / resumeGame / endGame / handleColumnClick / clearTimers / formatTime / aboutToDisappear 筑略 */ // 跳详情页 navigateToDetail(catId: string) { router.pushUrl({ url: catDetail, params: { catId: catId } }); } Builder GameView() { Column() { this.GameHUD() Column() { Row() { /* 预告区 */ } Stack() { /* 棋盘背景 */ ForEach(this.cats, (cat: Cat) { Column() { Text(CatConfig[cat.level].emoji).fontSize(CatConfig[cat.level].size * 0.5) } .width(CatConfig[cat.level].size).height(CatConfig[cat.level].size) .borderRadius(CatConfig[cat.level].size / 2) .backgroundColor(CatConfig[cat.level].color) .justifyContent(FlexAlign.Center) .position({ x: cat.x * 60 (60 - CatConfig[cat.level].size) / 2, y: cat.y * 60 (60 - CatConfig[cat.level].size) / 2 }) .animation({ duration: 100, curve: Curve.Linear }) // ← Hero 源绑定本篇重点 .bindElements(cat_${cat.id}, this.heroAnimation) .onClick(() { this.navigateToDetail(cat.id); // 跳详情页 }) }, (cat: Cat) cat.id) /* 列点击层 */ } .width(GameConfig.BOARD_WIDTH * GameConfig.CELL_SIZE) .height(GameConfig.BOARD_HEIGHT * GameConfig.CELL_SIZE) .borderRadius(12).clip(true).backgroundColor(#D6EEF5) }.alignItems(HorizontalAlign.Center) Spacer() Row() { /* 底部控制栏 */ } .width(100%).padding({ left: 24, right: 24, bottom: 24, top: 12 }) } .width(100%).height(100%) .linearGradient({ direction: GradientDirection.Bottom, colors: [[#E8F4F8, 0.0], [#D6EEF5, 0.5], [#C9E8F2, 1.0]] }) .alignItems(HorizontalAlign.Center) } /* GameHUD / MainMenuView / PauseOverlay / GameOverOverlay / StatItem 筑略 */ }5.3 CatDetailPage 目标页面新建entry/src/main/ets/pages/CatDetailPage.etsimport { AnimationParams, Curve } from kit.ArkUI; import { router } from kit.ArkUI; import { Cat, CatConfig, CatLevel } from ../components/GameTypes; Component export struct CatDetailPage { Prop catId: string; State cat: Cat | null null; // Hero 动画参数与源页面一致 private heroAnimation: AnimationParams { duration: 400, curve: Curve.EaseInOut, onFinish: () { console.info(Hero 过渡完成); } }; aboutToAppear() { // 加载猫咪数据简化从参数恢复 const params router.getParams() as Recordstring, string; this.catId params.catId; this.cat this.loadCat(this.catId); } loadCat(catId: string): Cat { // 简化模拟加载 return { id: catId, level: 2, x: 1, y: 3, falling: false } as Cat; } build() { Column() { // 返回按钮 Row() { Text(← 返回) .fontSize(16).fontColor(#3498DB) .onClick(() { router.back(); }) } .width(100%).height(56).padding({ left: 16 }) // 大猫图Hero 目标绑定本篇重点 Column() { Text(CatConfig[this.cat.level].emoji).fontSize(100) } .width(200).height(200) .borderRadius(100) .backgroundColor(CatConfig[this.cat.level].color) .justifyContent(FlexAlign.Center) .shadow({ radius: 20, color: rgba(0,0,0,0.3), offsetY: 10 }) .bindElements(cat_${this.catId}, this.heroAnimation) // ← 同名绑定 .margin({ top: 40, bottom: 40 }) // 详情信息 Column() { Text(ID: ${this.cat.id}).fontSize(16).fontColor(#2C3E50).margin({ bottom: 8 }) Text(等级: ${CatLevel[this.cat.level]}).fontSize(16).fontColor(#2C3E50).margin({ bottom: 8 }) Text(位置: 第 ${this.cat.x 1} 列, 第 ${this.cat.y 1} 行) .fontSize(16).fontColor(#2C3E50).margin({ bottom: 8 }) Text(下落状态: ${this.cat.falling ? 下落中 : 已停}) .fontSize(16).fontColor(#7F8C8D) } .alignItems(HorizontalAlign.Start) .padding({ left: 32, right: 32 }) Spacer() // 操作按钮 Row() { Button(关闭).onClick(() { router.back(); }) .width(120).height(44) .fontSize(16).fontColor(#FFFFFF).backgroundColor(#95A5A6) .borderRadius(22) } .padding({ bottom: 32 }) } .width(100%).height(100%) .backgroundColor(#FFFFFF) } }5.4 触发流程玩家点击棋盘上的小猫60×60位置 x120,y240。navigateToDetail(cat.id)调router.pushUrl跳详情页。ArkUI 检测到源页面bindElements(cat_cat_0, ...)和目标页面bindElements(cat_cat_0, ...)同名。Hero 动画触发小猫图从 (120,240,60×60) 用 400ms EaseInOut 补间到 (中央,200×200)。过渡完成详情页大猫图在中央稳定显示。玩家点「返回」router.back反向 Hero 动画大图飞回小图位置。六、多个共享元素6.1 同时绑定多个// 源页面猫咪小图 等级标签都做共享元素 ForEach(this.cats, (cat: Cat) { Column() { /* 猫咪图 */ } .bindElements(cat_${cat.id}, this.heroAnimation) // 共享 1图 Text(Lv.${cat.level}) .bindElements(level_${cat.id}, this.heroAnimation) // 共享 2标签 }, (cat: Cat) cat.id) // 目标页面大猫图 大等级标签 Column() { /* 大猫图 */ } .bindElements(cat_${this.catId}, this.heroAnimation) // 同名 Text(Lv.${this.cat.level}).fontSize(40) .bindElements(level_${this.catId}, this.heroAnimation) // 同名关键经验多个共享元素用不同 key 同前缀——cat_xxx和level_xxx跳转时各自独立补间。6.2 多元素协调动画多个共享元素用同一AnimationParams同时过渡时长一致视觉协调。七、踩坑提示7.1 源和目标 key 不一致// ❌ 错误源 key 是 cat_0目标 key 是 cat_1不匹配瞬切无 Hero .bindElements(cat_${cat.id}, ...) // 源cat_0 .bindElements(cat_${this.catId 1}, ...) // 目标cat_1错 // ✅ 正确key 完全一致 .bindElements(cat_${cat.id}, ...) .bindElements(cat_${this.catId}, ...) // 同名7.2 忘在目标页面绑 bindElements// ❌ 错误源绑了目标没绑跳转瞬切无 Hero // 源 .bindElements(cat_${cat.id}, ...) // 目标忘绑 // ✅ 正确源和目标都绑同名 .bindElements(cat_${cat.id}, ...) // 源 .bindElements(cat_${this.catId}, ...) // 目标7.3 AnimationParams 源目标不一致// ⚠️ 源和目标 AnimationParams duration 不同可能导致过渡不同步 // 源duration 400 // 目标duration 300 // 建议保持一致 // ✅ 正确共用同一套参数 private heroAnimation: AnimationParams { duration: 400, curve: Curve.EaseInOut }; // 源和目标都用 this.heroAnimation7.4 bindElements 绑在不可过渡的属性// ❌ 错误绑在文本内容变化上Hero 不补间文本 Text(this.cat.id) .bindElements(cat_${this.cat.id}, ...) // 文本内容不可补间 // ✅ 正确绑在可视元素上图、背景、尺寸 Column() { Text(emoji) } .bindElements(cat_${this.cat.id}, ...)7.5 忘路由跳转// ❌ 错误绑了 bindElements 但没调 router.pushUrlHero 不触发 .bindElements(cat_${cat.id}, ...) .onClick(() { /* 忘了 router.pushUrl */ }) // ✅ 正确跳转时 Hero 自动触发 .onClick(() { this.navigateToDetail(cat.id); })八、调试技巧console.info在 onFinish追 Hero 过渡完成时机。瞬切无 Hero 排查检查源和目标 key 是否同名检查是否都绑了 bindElements检查是否调了路由跳转。过渡不流畅排查检查 AnimationParams duration/curve检查源和目标参数是否一致。DevEco Animation Inspector查看 Hero 过渡过程。九、性能与最佳实践源和目标 bindElements key 必须同名——ArkUI 靠同名匹配拼错瞬切。源和目标 AnimationParams 保持一致——duration/curve 不同会不同步。duration 300–500ms 最佳——太短像瞬切太长拖沓。多个共享元素用不同 key——cat_xxx、level_xxx各自独立补间。Hero 管「单个元素跨页面」transition 管「整页面进/出」——常配合用。绑在可视元素上——图、背景、尺寸可补间文本内容不可。十、阶段三进度51–57本篇是阶段三「交互与动画」第 7 篇篇主题核心要点51onTouch手势三阶段52onHover悬停反馈53onKeyEvent键盘/遥控按键54bindContextMenu上下文菜单55animateTo显式动画触发56animation隐式补间57本篇Hero共享元素跨页面连续动画接下来第 58–60 篇会覆盖transition 转场、Spring 弹性物理、Hero Style Player。总结本篇我们从 Hero 共享元素切入掌握了共享元素概念同一元素跨页面连续过渡、bindElements 双页面同名绑定、AnimationParams 转场参数duration/curve、**与 transition 转场的差异单元素 vs 整页面**四大要点并给出了点击猫咪跳详情页的完整 Hero 改造代码。核心要点bindElements 源目标同名AnimationParams 保持一致duration 300–500msHero 管单元素 transition 管整页面。下一篇我们将拆解 transition——转场路由进入/退出动画。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源「猫猫大作战」项目源码本仓库entry/src/main/ets/pages/Index.ets、entry/src/main/ets/pages/CatDetailPage.etsArkUI Hero 共享元素官方指南bindElements API 官方文档AnimationParams 转场参数官方文档HarmonyOS 路由与页面动画最佳实践开源鸿蒙跨平台社区HarmonyOS 开发者官方文档首页系列索引本仓库articles/INDEX.md