HarmonyOS 手持弹幕官方教程复现技术笔记

这篇笔记基于华为官方“零基础 2 小时完成第一个鸿蒙应用：手持弹幕”的学习路径整理。目标不是复述教程步骤，而是把一次可复现的 HarmonyOS NEXT 入门实践拆成工程检查点：环境是否正确、页面如何组织、状态如何驱动 UI、哪些地方容易写成不可维护代码。

“手持弹幕”适合作为第一篇复现项目，原因很直接：它的业务足够小，能把注意力集中在 ArkTS、ArkUI、页面状态、预览调试和真机运行这些基础能力上；同时它又有动态显示、样式配置、横竖屏体验等真实 UI 问题，不会停留在只显示一段文本的玩具示例。

一、复现目标

这次复现要得到一个最小但完整的 HarmonyOS 应用：

  1. 首页或设置页用于输入弹幕文本，并配置字号、颜色、滚动速度等参数。
  2. 展示页以更适合手持展示的方式渲染弹幕内容。
  3. 页面之间通过明确的数据结构传参，而不是依赖全局变量。
  4. 所有 UI 变化都由状态驱动，避免手工操作 DOM 或命令式刷新界面。
  5. 代码结构能继续扩展，例如后续加入预设模板、历史记录、横屏锁定或多设备流转。

复现完成后，重点验收三件事：

  • 能在 DevEco Studio 中正常编译、预览和运行。
  • 修改设置项后，展示页能得到确定的显示结果。
  • 代码里能清楚地区分“数据模型、页面状态、界面描述、导航跳转”。

二、官方资料对应关系

我把官方资料分成四层来看：

层级 官方资料对应能力 在手持弹幕中的作用
入门教程 华为开发者联盟 HarmonyOS 应用开发入口中的“手持弹幕”教程 给出第一个应用的复现路径
开发语言 ArkTS 官方入门 理解类型、类、对象和函数约束
UI 框架 ArkUI 与声明式开发文档 理解组件、状态和布局
页面组织 Navigation / NavDestination 文档 理解页面栈、目的页和生命周期

这四层的关系很重要。教程告诉你“先写什么、后写什么”；ArkTS 和 ArkUI 解释“为什么这样写”；Navigation 解决“页面多起来之后怎么组织”。如果只按教程敲代码，很容易完成一遍但无法迁移到自己的项目。

三、环境准备检查

复现前先做环境检查，避免把工具链问题误判为代码问题。

1. DevEco Studio

确认 DevEco Studio 已经安装，并且 SDK、模拟器或真机调试环境可用。华为开发者平台将 DevEco Studio 定位为 HarmonyOS 应用及元服务开发的一站式平台，包含代码开发、编译构建和调测能力。

建议检查：

  • SDK 已按目标 API 版本安装。
  • 项目能正常完成 Gradle Sync。
  • 预览器可以打开 ArkUI 页面。
  • 如果使用真机，开发者模式、USB 调试、签名配置都已完成。

2. 工程创建

入门复现建议使用 ArkTS 工程模板，不要从复杂模板开始。第一轮复现的目标是理解应用结构，而不是一次性引入网络、数据库、账号、推送等能力。

重点看这些目录：

entry/
  src/main/
    ets/
      entryability/
      pages/
    module.json5

其中 ets 是 ArkTS 页面和业务代码的主要位置，module.json5 则描述模块、Ability 和页面入口等配置。入门阶段至少要知道：页面代码能显示出来，不只取决于 .ets 文件，也取决于模块配置和入口 Ability。

四、数据模型：先约束弹幕配置

手持弹幕虽然界面简单，但不要把所有参数散落在页面变量里。建议先抽出一个配置模型：

export class BannerSettings {
  text: string = 'HarmonyOS NEXT'
  fontSize: number = 72
  speed: number = 1
  textColor: string = '#FFFFFF'
  backgroundColor: string = '#000000'
}

这样做有三个好处：

  1. 页面传参只传一个结构，不会出现多个参数顺序错乱。
  2. 后续保存历史记录时，可以直接序列化这个对象。
  3. 编译期能发现字段名和类型错误，符合 ArkTS 强调静态检查的开发思路。

这里不要偷懒使用 any。入门项目越小，越应该训练类型边界；否则项目一复杂，就会把问题留到运行期。

五、页面拆分：设置页和展示页分开

手持弹幕至少可以拆成两个页面：

  • Index：编辑弹幕内容和显示参数。
  • BannerDisplay：只负责展示最终效果。

这是一条很实用的边界：设置页处理输入，展示页处理阅读。不要在展示页里继续塞大量表单逻辑，也不要让设置页承担动画展示职责。

页面跳转时，建议传递明确的 BannerSettings，展示页只读取参数并渲染。

const settings = new BannerSettings()
settings.text = this.text
settings.fontSize = this.fontSize
settings.speed = this.speed

// 伪代码：实际调用以当前项目的 Navigation 封装为准
this.pathStack.pushPath({
  name: 'BannerDisplay',
  param: settings
})

实际工程里要根据当前模板选择路由方式。如果项目使用 Navigation，就应该把页面作为 NavDestination 管理；如果是更基础的页面路由，也要保持“参数对象清晰、页面职责清晰”的原则。

六、Navigation 的理解重点

HarmonyOS 的 Navigation 不只是“跳页面”的按钮工具。它更像页面结构容器：页面栈、目的页、生命周期和不同设备宽度下的显示方式，都可以在这一层组织。

复现手持弹幕时，不一定一开始就要写复杂的分栏模式，但要提前建立三个概念：

1. 页面栈

设置页进入展示页，本质是向页面栈压入一个目的页。返回时再弹出。这样页面之间的关系是结构化的，而不是到处写硬编码路径。

2. 目的页

NavDestination 更适合承载一个独立页面。展示页可以在进入时读取参数，在离开时释放动画或计时任务。

3. 生命周期

如果展示页存在滚动动画、定时器或高频刷新，必须考虑页面隐藏和退出时的释放。入门项目也要形成习惯：页面不可见后，不应该继续消耗资源。

七、状态驱动 UI：不要把 UI 当成手工刷新的结果

ArkUI 的核心体验是声明式 UI。你描述“状态是什么，界面应该长什么样”，框架负责在状态变化时更新界面。

设置页可以维护这些状态：

@State text: string = 'HarmonyOS NEXT'
@State fontSize: number = 72
@State speed: number = 1
@State textColor: string = '#FFFFFF'
@State backgroundColor: string = '#000000'

然后在 build() 中描述输入组件、预览区域和按钮。不要把状态变化写成“找到某个控件，然后改它的属性”。那是传统命令式 UI 的思路，不适合 ArkUI。

实践中要注意：

  • 真正影响界面的数据才放进状态变量。
  • 临时计算值可以用普通变量或函数得到。
  • 不要在 build() 里做复杂耗时计算。
  • 如果动画或定时器依赖状态，要设计好停止条件。

八、展示页的性能边界

手持弹幕的展示页看起来只是文字移动，但它天然容易触发性能问题：字号大、颜色强、滚动连续、可能横屏展示。入门阶段至少要守住以下边界：

  1. 不在 UI 线程做耗时计算。
  2. 不在高频动画中频繁创建临时对象。
  3. 页面隐藏或退出时停止动画、计时器或任务。
  4. 参数变化通过状态触发，不手工堆叠多个刷新入口。
  5. 先保证布局简单，再考虑动效复杂度。

草稿中提到的 SmartGC、可变刷新率、多线程等方向，可以作为后续性能学习主题；但在这篇复现笔记里，我更建议先把可控的工程边界做好。入门项目最容易犯的错不是性能优化不够高级，而是没有清晰的状态和生命周期。

九、我的复现检查清单

复现完成后，我会按下面顺序检查：

编译检查

  • 工程可以正常 Sync。
  • 没有 ArkTS 类型错误。
  • 页面注册和入口配置正确。
  • 真机或模拟器能启动应用。

功能检查

  • 默认弹幕文本能显示。
  • 修改文本后展示页同步更新。
  • 修改字号、颜色、速度后效果符合预期。
  • 返回设置页后能继续编辑。

架构检查

  • 弹幕配置有明确模型。
  • 设置页和展示页职责分离。
  • 页面传参有类型边界。
  • 展示页退出时没有遗留动画或任务。

体验检查

  • 大字号不截断关键文字。
  • 横屏或宽屏下布局仍可用。
  • 背景和文字对比度足够。
  • 操作按钮不会遮挡展示内容。

十、这次复现得到的工程结论

这类官方入门教程的价值，不只是教你写出第一个页面，而是帮助建立 HarmonyOS NEXT 的开发心智：

  • ArkTS 负责把数据结构和类型边界立住。
  • ArkUI 负责用状态描述界面。
  • Navigation 负责组织页面关系和生命周期。
  • DevEco Studio 负责把开发、预览、构建和调试串起来。

“手持弹幕”项目规模很小，但它包含了移动应用最常见的闭环：输入、配置、跳转、展示、返回、再编辑。只要这一轮复现能做到结构清楚，后续再学习网络请求、数据持久化、分布式能力和 AI Agent 场景时，就不会把所有复杂度混在一个页面里。

后续扩展方向

下一步可以在这个项目上继续做四类扩展：

  1. 配置持久化：保存最近使用的弹幕文本和样式。
  2. 模板化：预设“会议提示”“现场应援”“临时通知”等模板。
  3. 多端适配：针对手机、平板、折叠屏调整设置区和展示区布局。
  4. Agent 辅助生成：让 AI agent 根据场景自动生成短句、颜色和展示节奏。

这些扩展都不应该破坏当前的边界：数据模型独立、页面职责清楚、状态驱动 UI、生命周期可控。

参考资料