学习卡片案例新特性接入

HarmonyOS 水果词语学习卡片——基于状态管理V2的层叠动画卡片实战指南

关键词：HarmonyOS、ArkTS、状态管理V2、@ComponentV2、Stack层叠布局、animateTo隐式动画、PanGesture拖动手势、Media Kit音频播放

适合人群：有ArkTS基础的HarmonyOS开发者，希望掌握状态管理V2迁移与高级UI交互实现

效果

一、前言

在儿童启蒙教育类应用中，"词语学习卡片"是一种直观且高效的交互形式。本文将以水果词语学习卡片为案例，基于 HarmonyOS 6.1 + ArkTS 平台，全面使用状态管理V2（@ComponentV2、@Local、@Param、@Event）重构原有的V1版本，同时深入讲解 Stack层叠布局、animateTo隐式动画、PanGesture拖动手势和Media Kit音频播放四大核心能力的实战应用。

通过本文，你将学会：

• 如何使用状态管理V2构建可维护的组件化架构
• 如何用Stack + offset + zIndex实现卡片层叠效果
• 如何用PanGesture + animateTo打造丝滑的卡片切换动画
• 如何用Media Kit的AVPlayer播放rawfile音频资源
• V1状态管理到V2的完整迁移对照表

二、环境准备

创建项目时选择 Empty Ability 模板，语言选择 ArkTS。

三、项目架构设计

3.1 目录结构

entry/src/main/
├── ets/
│ ├── constants/
│ │ └── CommonConstants.ets # 公共常量（尺寸、比例）
│ ├── entryability/
│ │ └── EntryAbility.ets # Ability入口，沉浸式窗口配置
│ ├── model/
│ │ └── FruitCardModel.ets # 水果数据模型 + 数据源
│ ├── pages/
│ │ ├── MainPage.ets # 主页面（@Entry + @ComponentV2）
│ │ └── SwiperStackComponent.ets # 层叠卡片组件（核心交互）
│ └── utils/
│ └── MediaPlayer.ets # Media Kit音频播放封装
├── resources/
│ ├── base/
│ │ ├── element/
│ │ │ ├── color.json # 主题色定义
│ │ │ └── string.json # 字符串资源
│ │ ├── media/ # 图片资源
│ │ │ ├── apple.png # 苹果
│ │ │ ├── banana.png # 香蕉
│ │ │ ├── watermelon.png # 西瓜
│ │ │ ├── orange.png # 橙子
│ │ │ ├── grape.png # 葡萄
│ │ │ ├── strawberry.png # 草莓
│ │ │ ├── peach.png # 桃子
│ │ │ ├── pear.png # 梨
│ │ │ ├── cherry.png # 樱桃
│ │ │ ├── chinese_pronunciation.png
│ │ │ └── english_pronunciation.png
│ │ └── profile/
│ │ └── main_pages.json # 页面路由注册
│ ├── dark/element/color.json # 深色模式颜色
│ └── rawfile/ # 音频原始文件
│ ├── apple.mp3 / appleChinese.mp3
│ ├── banana.mp3 / bananaChinese.mp3
│ ├── watermelon.mp3 / watermelonChinese.mp3
│ ├── orange.mp3 / orangeChinese.mp3
│ ├── grape.mp3 / grapeChinese.mp3
│ ├── strawberry.mp3 / strawberryChinese.mp3
│ ├── peach.mp3 / peachChinese.mp3
│ ├── pear.mp3 / pearChinese.mp3
│ └── cherry.mp3 / cherryChinese.mp3
└── module.json5 # 模块配置（横屏、设备类型）

3.2 模块职责划分

四、核心知识点详解

4.1 状态管理V2：从@State到@Local

HarmonyOS 6.1 推出的状态管理V2提供了更精确、更类型安全的状态管理方案。核心装饰器对照如下：

关键设计思想：V2 将V1中@Link的"双向绑定"拆分为 @Param（读）+ @Event（写），数据流向更加清晰明确，符合单向数据流的最佳实践。

4.2 Stack层叠布局

Stack是ArkUI中的层叠容器，子组件按照zIndex值从下到上堆叠。本项目利用Stack实现多张卡片的前后层叠效果：

Stack() {
ForEach(this.swiperData, (item, index) => {
// 卡片内容
})
}
.alignContent(Alignment.Center)

每张卡片通过以下属性控制视觉层级：

• offset({ x })：水平偏移，当前卡片居中，左右相邻卡片分别偏移±127vp
• zIndex：层级深度，越靠近当前卡片zIndex越高
• blur(12)：非当前卡片添加模糊效果，突出焦点

4.3 animateTo隐式动画

animateTo是ArkUI提供的隐式动画API，在闭包中修改状态变量，框架自动为受影响的UI属性生成平滑过渡动画：

this.getUIContext().animateTo({
duration: 300, // 动画时长300ms
}, () => {
this.onIndexChange(newIndex); // 修改索引，触发卡片位移动画
});

注意：在V2组件中，必须通过 this.getUIContext().animateTo() 调用，不能直接使用全局 animateTo()。

4.4 PanGesture拖动手势

PanGesture用于识别拖动手势，配合direction参数可限定拖动方向：

.gesture(
PanGesture({ direction: PanDirection.Horizontal })
.onActionStart((event: GestureEvent) => {
// event.offsetX < 0 表示向左滑动
this.startAnimation(event.offsetX < 0, 300);
})
)

4.5 Media Kit音频播放

Media Kit 提供的 AVPlayer 是HarmonyOS推荐的音视频播放器。本项目使用它播放 rawfile 目录下的 mp3 音频：

import { media } from '@kit.MediaKit';

// 创建播放器
let avPlayer = await media.createAVPlayer();

// 通过文件描述符设置音频源
let fileDescriptor = context.resourceManager.getRawFdSync('apple.mp3');
avPlayer.fdSrc = {
fd: fileDescriptor.fd,
offset: fileDescriptor.offset,
length: fileDescriptor.length
};

AVPlayer 的状态机流程：idle → initialized → prepared → playing → completed → stopped → idle

五、分步实现

Step 1：项目配置——module.json5

在module.json5中设置横屏模式和设备类型支持：

{
"module": {
"name": "entry",
"type": "entry",
"deviceTypes": ["phone", "tablet", "2in1"],
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"orientation": "landscape", // 横屏模式
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
// …
}
]
}
}

Step 2：沉浸式窗口配置——EntryAbility.ets

在onWindowStageCreate中实现全屏沉浸式布局，并将安全区域高度存入AppStorage：

import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

onWindowStageCreate(windowStage: window.WindowStage): void {
// 隐藏系统状态栏和导航栏
windowStage.getMainWindowSync().setWindowSystemBarEnable([]);

let windowClass: window.Window = windowStage.getMainWindowSync();

// 设置全屏布局
windowClass.setWindowLayoutFullScreen(true);

// 获取并存储安全区域高度
let avoidArea = windowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
AppStorage.setOrCreate('topRectHeight', avoidArea.topRect.height);

avoidArea = windowClass.getWindowAvoidArea(window.AvoidAreaType.TYPE_NAVIGATION_INDICATOR);
AppStorage.setOrCreate('bottomRectHeight', avoidArea.bottomRect.height);

// 加载主页面
windowStage.loadContent('pages/MainPage');
}

Step 3：数据模型设计——FruitCardModel.ets

定义水果卡片的数据接口和静态数据源：

/**
* 水果卡片数据接口
*/
export interface FruitCardModel {
id: number;
image: Resource;
pinyin: string;
chineseName: string;
englishName: string;
chineseAudioUrl: string;
englishAudioUrl: string;
}

/**
* 水果数据源：9种常见水果
* 苹果、香蕉、西瓜、橙子、葡萄、草莓、桃子、梨、樱桃
*/
export const FRUITS_DATA: FruitCardModel[] = [
{ id: 1, image: $r('app.media.apple'), pinyin: 'píng guǒ', chineseName: '苹 果', englishName: 'Apple', … },
{ id: 2, image: $r('app.media.banana'), pinyin: 'xiāng jiāo', chineseName: '香 蕉', englishName: 'Banana', … },
{ id: 3, image: $r('app.media.watermelon'), pinyin: 'xī guā', chineseName: '西 瓜', englishName: 'Watermelon', … },
{ id: 4, image: $r('app.media.orange'), pinyin: 'chéng zi', chineseName: '橙 子', englishName: 'Orange', … },
{ id: 5, image: $r('app.media.grape'), pinyin: 'pú tao', chineseName: '葡 萄', englishName: 'Grape', … },
{ id: 6, image: $r('app.media.strawberry'), pinyin: 'cǎo méi', chineseName: '草 莓', englishName: 'Strawberry', … },
{ id: 7, image: $r('app.media.peach'), pinyin: 'táo zi', chineseName: '桃 子', englishName: 'Peach', … },
{ id: 8, image: $r('app.media.pear'), pinyin: 'lí', chineseName: '梨', englishName: 'Pear', … },
{ id: 9, image: $r('app.media.cherry'), pinyin: 'yīng tao', chineseName: '樱 桃', englishName: 'Cherry', … },
];

设计说明：数据模型使用interface而非class，因为水果数据在运行期间不会动态修改，无需响应式追踪。这是V2开发中的一个重要优化思路——只为真正需要变化的数据添加状态装饰器。

Step 4：音频播放工具类——MediaPlayer.ets

MediaPlayer是基于Media Kit AVPlayer封装的单例播放器，核心设计：

export default class MediaPlayer {
private static instance: MediaPlayer | null;
public avPlayer: media.AVPlayer | null = null;
public static audioUrl: string = '';
public static isPlaying: boolean = false;

public static async getInstance(): Promise<MediaPlayer> {
if (!MediaPlayer.instance) {
MediaPlayer.instance = new MediaPlayer();
}
return MediaPlayer.instance;
}

public async getAVPlayer(context: common.UIAbilityContext): Promise<media.AVPlayer> {
if (!this.avPlayer) {
this.avPlayer = await media.createAVPlayer();
this.setupCallbacks(this.avPlayer, context);
}
return this.avPlayer;
}
}

关键逻辑在 setupCallbacks 中监听 stateChange 事件，实现自动化的状态流转：

idle（设置fdSrc）→ initialized（自动prepare）→ prepared（自动play）→ playing

Step 5：层叠卡片组件——SwiperStackComponent.ets（核心）

这是整个项目最核心的组件，集中体现了V2状态管理、Stack布局、手势识别和动画的综合运用。

5.1 V2状态声明

@ComponentV2
export struct SwiperStackComponent {
// V2: @Param 替代 V1的 @Prop（父→子单向同步）
@Param currentIndex: number = 0;
@Param swiperData: FruitCardModel[] = [];

// V2: @Event 替代 V1的回调prop（子→父事件通知）
@Event onIndexChange: (value: number) => void = () => {};

private halfCount: number = Math.floor(FRUITS_DATA.length / 2);
private uiContext = this.getUIContext();
private context = this.getUIContext().getHostContext() as common.UIAbilityContext;
}

V1→V2 关键变化：原来V1中@Link currentIndex既读又写，V2拆分为@Param（读）和@Event（写），数据流向一目了然。

5.2 卡片位置计算

/** 计算图片层级系数：当前=0，左=-1，右=1 */
getImgCoefficients(index: number): number {
const coefficient: number = this.currentIndex – index;
const tempCoefficient: number = Math.abs(coefficient);
if (tempCoefficient <= this.halfCount) {
return coefficient;
}
// 环形排列：超出半圈范围的卡片需要折返计算
const dataLength: number = this.swiperData.length;
let tempOffset: number = dataLength – tempCoefficient;
if (tempOffset <= this.halfCount) {
return coefficient > 0 ? –tempOffset : tempOffset;
}
return 0;
}

/** 计算水平偏移：当前卡片0，左右相邻±127vp */
getOffSetX(index: number): number {
let offsetIndex = this.getImgCoefficients(index);
return Math.abs(offsetIndex) === 1 ? –127 * offsetIndex : 0;
}

5.3 动画驱动切换

startAnimation(isLeft: boolean, duration: number): void {
this.uiContext.animateTo({ duration }, () => {
let dataLength = this.swiperData.length;
let tempIndex = isLeft
? this.currentIndex + 1
: this.currentIndex – 1 + dataLength;
// 通过@Event通知父组件更新@Local currentIndex
this.onIndexChange(tempIndex % dataLength);
});
}

执行流程：PanGesture触发 → startAnimation() → animateTo闭包中调用onIndexChange → 父组件@Local currentIndex更新 → 新值通过@Param回流到子组件 → 卡片offset/zIndex/blur变化产生动画。

5.4 Stack渲染结构

build() {
Column() {
Stack() {
ForEach(this.swiperData, (item: FruitCardModel, index: number) => {
Column({ space: (index !== this.currentIndex ? 10 : 20) }) {
// 图片 + 拼音 + 中文名 + 英文名
// 中文发音按钮 + 英文发音按钮 + 序号
}
.offset({ x: this.getOffSetX(index) })
.blur(index !== this.currentIndex ? 12 : 0)
.zIndex(/* 层级计算 */)
.width(CommonConstants.LARGE_WIDTH)
.height(index !== this.currentIndex ? 240 : 340);
}, (item: FruitCardModel, index: number) => item.id.toString());
}
.gesture(
PanGesture({ direction: PanDirection.Horizontal })
.onActionStart((event: GestureEvent) => {
this.startAnimation(event.offsetX < 0, 300);
})
)
.alignContent(Alignment.Center);
}
}

重要：ForEach必须提供稳定的keyGenerator，这里使用item.id.toString()作为唯一键值，确保列表渲染性能最优。

Step 6：主页面组装——MainPage.ets

@Entry
@ComponentV2
struct MainPage {
@Local currentIndex: number = 0;
@Local topRectHeight: number = 0;
private uiContext = this.getUIContext();

aboutToAppear(): void {
// @StorageProp 不兼容 @ComponentV2，改用 AppStorage.get() 手动读取
let topHeight = AppStorage.get<number>('topRectHeight');
if (topHeight !== undefined) {
this.topRectHeight = topHeight;
}
}

build() {
Flex({ direction: FlexDirection.Row }) {
SwiperStackComponent({
currentIndex: this.currentIndex,
swiperData: FRUITS_DATA,
onIndexChange: (value: number) => {
this.currentIndex = value;
}
});
}
.safeAreaPadding({ top: this.uiContext.px2vp(this.topRectHeight) })
.height('100%')
.width('100%')
.backgroundColor($r('app.color.orange'));
}
}

重要提示：@StorageProp 和 @StorageLink 是V1专属装饰器，不兼容 @ComponentV2。在V2组件中，需要通过 @Local + AppStorage.get() 在 aboutToAppear() 中手动读取全局存储值。

V2模式下的父子数据流：

MainPage (@Local currentIndex)
│
├── 读取方向 ──→ SwiperStackComponent (@Param currentIndex)
│
└── 写入方向 ←── SwiperStackComponent (@Event onIndexChange)

Step 7：资源配置

color.json（base）：

{
"color": [
{ "name": "orange", "value": "#FFB74D" },
{ "name": "dark_orange", "value": "#E65100" },
{ "name": "blue", "value": "#0A59F7" }
]
}

color.json（dark）：深色模式自动适配：

{
"color": [
{ "name": "orange", "value": "#FF8F00" },
{ "name": "dark_orange", "value": "#BF360C" },
{ "name": "blue", "value": "#448AFF" }
]
}

六、V1 vs V2 完整对照表

以下是在本项目中实际发生的V1→V2迁移对照：

为什么V2要拆分@Link？

V1的@Link同时承担读和写的职责，违反了单向数据流原则。V2将其拆分：

• @Param：子组件只能读取父组件传来的值，不能直接修改
• @Event：子组件通过事件机制请求父组件修改值

这种设计让数据流向变得可预测、可追踪，极大降低了状态管理的复杂度。

七、关键代码深度解析

7.1 环形卡片排列算法

本项目的卡片排列是一个环形队列模型。以3张卡片为例：

索引: 0 1 2
位置: 当前 右边 左边（环形回绕）

getImgCoefficients的核心思路是：

这个算法保证了无论多少张卡片，始终只有当前卡片和左右相邻卡片可见，其余卡片zIndex=0被遮挡。

7.2 animateTo + @Event 的协同时序

用户左滑
└─→ PanGesture.onActionStart
└─→ startAnimation(isLeft=true, 300)
└─→ animateTo({ duration: 300 })
└─→ this.onIndexChange(1) // 通知父组件
└─→ MainPage: this.currentIndex = 1 // @Local更新
└─→ SwiperStackComponent: @Param currentIndex = 1 // 回流
└─→ 每张卡片的offset/zIndex/blur重新计算
└─→ 框架生成300ms平滑过渡动画

7.3 MediaPlayer状态机自动流转

当设置fdSrc时，AVPlayer的状态机自动流转，无需手动调用prepare()和play()：

// stateChange回调中的自动流转逻辑
case 'idle':
if (MediaPlayer.audioUrl !== '') {
avPlayer.fdSrc = avFileDescriptor; // idle → initialized
}
break;
case 'initialized':
avPlayer.prepare(); // initialized → prepared
break;
case 'prepared':
avPlayer.play(); // prepared → playing
break;

八、资源文件准备清单

在正式运行前，需要准备以下资源文件：

提示：音频文件可使用微软 Edge TTS 免费生成，中文语音用 zh-CN-XiaoxiaoNeural，英文语音用 en-US-JennyNeural。图片可从免费图标网站下载或使用 AI 生成。

九、总结与扩展

9.1 技术要点回顾

9.2 扩展建议

• 增加水果种类：在FRUITS_DATA中追加数据即可，环形排列算法自动适配
• 添加翻转动画：点击卡片使用rotate+animateTo展示背面详细信息
• 学习进度记录：使用@Provider/@Consumer跨组件共享已学/未学状态
• 发音高亮效果：播放音频时同步高亮对应的发音按钮
• 适配竖屏模式：通过断点检测（@StorageProp('breakpoint')）切换横竖屏布局

网站下载或使用 AI 生成。

九、总结与扩展

9.1 技术要点回顾

9.2 扩展建议

• 增加水果种类：在FRUITS_DATA中追加数据即可，环形排列算法自动适配
• 添加翻转动画：点击卡片使用rotate+animateTo展示背面详细信息
• 学习进度记录：使用@Provider/@Consumer跨组件共享已学/未学状态
• 发音高亮效果：播放音频时同步高亮对应的发音按钮
• 适配竖屏模式：通过断点检测（@StorageProp('breakpoint')）切换横竖屏布局