如何5分钟上手svga-cj：HarmonyOS仓颉语言SVGA动画播放器快速入门教程
【免费下载链接】svga-cjsvga格式动画展示库项目地址: https://gitcode.com/Cangjie-TPC/svga-cj
svga-cj是一款专为 HarmonyOS 打造的SVGA 动画播放器库，使用仓颉语言（Cangjie）开发，能够解析.svga格式动画并在移动端进行本地渲染，支持播放、暂停、快进、跳帧、倍速等完整播放控制，新手5分钟即可将动效集成到自己的 App 中 🚀
一、svga-cj 是什么？能做什么？
svga-cj 是一个轻量级 SVGA 动画展示库（当前 release 版本 v1.3.0），核心特性包括：
| 特性 | 说明 |
|---|---|
| 📼 加载 SVGA 动画 | 支持 rawfile 中的.svga资源，本地解析渲染 |
| 🎮 播放控制 | 播放、暂停、停止、反向播放 |
| ⏩ 快进能力 | 按帧或按百分比跳转（stepToFrame/stepToPercentage） |
| 🔁 循环与倍速 | 可设置循环次数setLoops与倍速setCurRate |
| ✏️ 动态内容替换 | 通过setImage/setText替换动画中的图片与文本 |
⚠️ 目前仅支持 2.0 版本的 svga 资源，暂不支持带音频的动画。
二、准备工作：环境要求快速核对
集成前先确认开发环境（详见 README.md 的约束说明）：
- ✅ DevEco Studio6.1.1 Release（6.1.1.280）+ Cangjie Plugin 6.1.1 Beta1
- ✅ 仓颉编译器cjc v1.1.3
- ✅ 配置
CANGJIE_STDX_PATH环境变量（依赖三方库 stdx v1.1.3.1） - ✅ 自动拉取依赖：zlib4cj、protobuf4cj（构建脚本见 pre_protobuf_install.mjs）
获取项目源码：
git clone https://gitcode.com/Cangjie-TPC/svga-cj三、最快配置方法：4步把svga模块接入你的项目
第 1 步：拷贝模块。将仓库中的 svga/ 目录整体拷贝到你的应用项目根目录，并在项目build-profile.json5的modules字段注册模块：
{ "name": "svga", "srcPath": "./svga" }第 2 步：声明 npm 依赖。在entry/oh-package.json5的dependencies中添加：
"@cangjie-tpc/svga": "file:../svga"第 3 步：配置仓颉包。在entry/src/main/cangjie/cjpm.toml中添加：
[dependencies.svga] path = "${cangjie_tpc_svga}"第 4 步：导入即可使用。在业务代码中import svga.*与import svga.player.*，库的对外入口定义在 svga_player.cj。
四、SvgaPlayer 组件使用：一段代码跑起动效
参考示例工程入口 index.cj，核心只有几行：
var controller: SvgaController = SvgaController() public func build() { Column { SvgaPlayer(url: "angel.svga", abilitycontext: globalcontext.getOrThrow(), controller: controller) }.width(300).aspectRatio(1) }SvgaPlayer组件接收url（rawfile 中的 svga 资源路径）、abilitycontext（UI 上下文）和controller（播放器控制器）三个参数，组件内部自动完成解析、画布自适应缩放与播放（渲染逻辑见 renderer.cj，解析器见 parser.cj）。
常用控制器 API 清单：
| 场景 | 调用方法 |
|---|---|
| 加载并自动播放 | controller.load(source) |
| 暂停 / 停止 | pauseAnimation()/stopAnimation(clears) |
| 从第 N 帧 / 百分比跳转 | stepToFrame(frame)/stepToPercentage(pct) |
| 播放范围 | startAnimationWithRange(range) |
| 循环次数 / 倍速 | setLoops(3)/setCurRate(2.0) |
| 完成与进度回调 | onFinished { }/onPercentage { } |
循环、自动释放等默认参数通过SvgaPlayerProps构造SvgaController，完整接口文档请查阅 feature_api.md。
五、目录导航：快速定位源码与文档
- 📖 API 文档：doc/feature_api.md
- 📝 示例代码：entry/src/main/cangjie/（含 main_ability.cj 上下文初始化）
- 🧩 播放器核心：svga/src/main/cangjie/player/（svga_controller.cj、state_controller.cj）
- 🔄 版本记录：CHANGELOG.md
- 📦 构建配置：cjpm.toml
按以上步骤，你只需要 4 次配置 + 1 段代码，就能在 HarmonyOS 应用中流畅播放 SVGA 动画，快去试试吧 ✨
【免费下载链接】svga-cjsvga格式动画展示库项目地址: https://gitcode.com/Cangjie-TPC/svga-cj
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
