本文记录一次完整的鸿蒙应用开发实践：从创建空的 HarmonyOS 7 项目开始，借助华为云码道 CodeArts 代码智能体生成头像设置页面，再将代码同步回本地并完成运行验证。

文章重点不只是“让智能体写代码”，而是把需求拆成可验收的页面结构、交互流程和技术约束，让生成结果更接近一个可以运行和继续维护的项目。

一键开通华为云码道 CodeArts：
https://developer.huaweicloud.com/codeartsco.html?source=dmzntgwatomgit1&sourcead=dmzntgwatomgithd

案例背景与最终目标

本次案例实现一个适用于“个人中心”或“账号设置”场景的头像设置页面。用户打开页面后，可以看到当前头像、昵称或账号信息，以及一个用于更换头像的入口。
点击入口后，通过 Scenario Fusion Kit 提供的 ChooseAvatarButton 拉起系统头像选择能力。用户完成选择后，组件通过 onSelected 回调返回头像 URI，页面再把 URI 保存到状态变量中，并刷新 Image 组件。
页面需要满足以下结果：

1. 未选择头像时，显示默认头像或占位图。
2. 点击更换入口后，能够拉起系统头像选择页面。
3. 选择成功后，能够接收并保存头像 URI。
4. 页面状态更新后，头像立即刷新。
5. 头像以圆形展示，并且能够居中裁剪、适配不同尺寸的图片。
6. 页面布局适配手机屏幕，不因固定宽度导致内容溢出。

这类需求看起来比较简单，但它同时涉及 ArkUI 页面布局、组件组合、状态管理、回调处理和资源配置。对于代码生成工具来说，如果只给出一句“帮我做一个头像选择页面”，生成结果往往会遗漏其中一部分。因此，提示词必须把功能、技术约束和验收条件写清楚。
该项目开源地址：HarmonyOS头像选择

整体实现流程

本次实践采用以下流程：

创建 HarmonyOS 7 空项目
        ↓
提交到 AtomGit 仓库
        ↓
进入华为云码道 CodeArts
        ↓
选择适合 ArkTS 的代码模型
        ↓
选择目标仓库并提交详细提示词
        ↓
等待智能体生成并提交代码
        ↓
查看提交记录并拉取到本地
        ↓
运行项目，按照验收标准检查页面

这里有一个重要的前提：代码智能体负责提高实现效率，但不能替代编译、运行和人工验收。生成的代码是否真正可用，最终仍然要以本地构建结果和设备运行效果为准。

前期准备：创建项目并提交到仓库

创建 HarmonyOS 7 空项目

首先在本地创建一个空的 HarmonyOS 7 项目。本次示例使用 ArkTS 和 ArkUI 声明式 UI，项目采用 Stage 模型。

项目初始阶段不需要提前实现业务页面，保留能够正常编译的空模板即可。这样做的好处是：

• 智能体可以基于真实的项目目录和配置文件修改代码；
• 生成的文件会落在目标工程中，而不是停留在一段独立代码里；
• 后续可以直接通过 Git 查看变更并回退提交。

提交到 AtomGit

将本地空项目提交到 AtomGit 仓库。提交前建议确认以下内容：

• 工程能够在本地正常打开；
• 项目使用的 SDK、编译工具和 API 版本明确；
• 默认分支名称与后续拉取命令一致；
• 仓库中没有提交无关的构建产物或本地缓存文件。

如下图所示，先将本地的空模板提交到 AtomGit：

为什么要先写清楚提示词

一个可执行的技术提示词，至少应包含四部分：

部分	需要回答的问题	本案例中的内容
项目目标	要做什么页面或功能？	个人资料页中的头像选择
技术约束	必须使用哪些框架、组件和模型？	ArkTS、ArkUI、Stage、Scenario Fusion Kit
交互流程	用户点击后发生什么？	拉起选择页、回调返回 URI、刷新头像
验收标准	怎样判断生成结果合格？	能运行、能选择、能更新、能适配

提示词中还应该明确哪些方案不能使用。例如，本案例要求必须使用 ChooseAvatarButton，不能使用普通 Button 模拟头像选择入口。这个限制很重要，否则智能体可能只生成一个静态按钮，页面看起来像完成了，实际上并没有接入系统能力。

使用 CodeArts 生成项目代码

打开华为云码道，选择 GLM-5.2-ArkTS-SPARK 模型。模型介绍中提到，它针对鸿蒙代码和开发知识进行了增训，所以这次 ArkTS 页面开发就选了它。

在仓库选择处，选择刚才创建的项目仓库，使智能体能够基于该仓库更新代码并提交变更。

本次使用的项目提示词

下面是本次提交给代码智能体的完整提示词,可直接拿去复用哦~~

请基于 HarmonyOS ArkTS + ArkUI 生成一个完整示例项目，项目名称为“ChooseAvatarButton”，该项目需要在所选择的仓库中更新对应的代码。

项目目标：
实现一个用于个人中心或账号设置场景的头像设置页面。用户进入页面后，可以看到当前头像区域、昵称/账号信息区域，以及一个用于更换头像的按钮。点击按钮后，通过 Scenario Fusion Kit 拉起系统头像选择能力，支持从华为账号头像或其他头像来源中选择头像。用户选中头像后，页面应自动接收返回的头像 URI，并将该头像更新展示为当前头像。头像展示区域需要支持基础的圆形裁剪、居中显示和缩放适配，保证不同尺寸图片都能正常呈现。

技术要求：
使用 ArkTS 语言和 ArkUI 声明式 UI 开发，项目采用 Stage 模型。页面中需要导入 `@kit.ScenarioFusionKit`，使用 `ChooseAvatarButton` 实现头像选择入口，并将其声明在 `FunctionalButton` 容器中。通过 `onSelected` 回调获取用户选择后的头像 URI，将 URI 保存到页面状态变量中，并使用 ArkUI 的 `Image` 组件展示该头像。头像未选择前展示默认头像占位图或默认图标区域，选择成功后立即刷新为新头像。

页面结构要求：
页面整体模拟“账号设置/个人资料”界面，包含顶部标题“个人资料”、当前头像展示区、用户昵称展示区、头像更换区域和必要的状态提示。视觉风格应简洁、现代，适合 HarmonyOS 原生应用体验。头像区域建议使用圆形展示，尺寸约 96vp 到 120vp，图片需通过 `objectFit(ImageFit.Cover)` 或等效方式实现裁剪缩放效果。更换头像按钮应放在头像附近，用户能明确感知点击后会选择或更换头像。

核心交互流程：
1. 页面首次打开时显示默认头像。
2. 用户点击“更换头像”按钮。
3. 调用 `ChooseAvatarButton` 拉起头像选择页。
4. 用户选择头像后触发 `onSelected` 回调。
5. 从回调中获取头像 URI。
6. 将 URI 赋值给页面状态变量。
7. `Image` 组件自动刷新并展示新头像。
8. 图片展示需要保持圆形裁剪和缩放适配。

代码实现要求：
生成可运行的 ArkTS 页面代码，包含必要的 `import`、`@Entry`、`@Component`、`@State`、`build()` 页面结构和 `onSelected` 回调逻辑。代码中需要体现 `ChooseAvatarButton`、`FunctionalButton`、`Image` 的组合使用。状态变量建议命名为 `avatarUri`，类型需要符合 ArkTS 静态类型要求，例如 `string` 或 `string | undefined`。如果未选择头像，则展示默认资源图片，例如 `$r('app.media.default_avatar')`；如果已选择头像，则展示选择返回的 URI。

需要注意：
不要使用普通 `Button` 模拟头像选择能力，必须使用 Scenario Fusion Kit 的 `ChooseAvatarButton`。不要只写伪代码，要给出完整 ArkUI 页面示例。需要考虑头像 URI 为空、选择取消、选择成功后的 UI 更新。页面布局需适配手机屏幕，宽度使用百分比或 `vp` 单位，避免硬编码导致溢出。代码应尽量简洁清晰，符合 HarmonyOS ArkTS 开发规范。

验收标准：
1. 点击头像更换入口后，能够拉起头像选择页面。
2. 用户选择头像后，`onSelected` 能获取返回的头像 URI。
3. 页面状态能够保存该 URI。
4. `Image` 组件能够正确展示用户选择的头像。
5. 头像展示具备圆形裁剪和缩放适配效果。
6. 未选择头像时有默认头像展示。
7. 页面整体符合个人中心或账号设置场景，交互路径清晰。
8. 代码结构完整，可直接放入 HarmonyOS ArkTS 页面中使用。

请输出：
1. 完整 ArkTS 页面代码。
2. 关键实现说明。
3. 可能需要配置的资源说明，例如默认头像资源。
4. 简要说明 `ChooseAvatarButton` 与 `onSelected` 的工作流程。

提交提示词并等待生成

将提示词提交给码道后，等待智能体分析项目结构、生成代码并提交到仓库。

生成结束后，不要只根据智能体的回复判断成功。应继续检查仓库提交记录、变更文件和本地编译结果。

页面实现中需要关注的技术点

ChooseAvatarButton 功能按钮

本案例的关键点是使用 Scenario Fusion Kit 提供的 ChooseAvatarButton。普通 Button 只能提供点击事件，不能自动拉起系统头像选择能力。使用指定组件后，页面需要关注的是组件放置位置、回调接收和状态刷新,码道生成的示例代码如下:

  // 使用 FunctionalButton + CHOOSE_AVATAR 实现头像选择
            FunctionalButton({
              params: {
                openType: functionalButtonComponentManager.OpenType.CHOOSE_AVATAR,
                label: '更换头像',
                styleOption: {
                  styleConfig: new functionalButtonComponentManager.ButtonConfig()
                    .type(ButtonType.Normal)
                    .fontSize(16)
                    .fontColor('#FFFFFF')
                    .backgroundColor('#007DFF')
                    .borderRadius(24)
                    .width(200)
                    .height(48)
                }
              },
              controller: new functionalButtonComponentManager.FunctionalButtonController()
                .onChooseAvatar((err, data) => {
                  if (err) {
                    hilog.error(DOMAIN, 'AvatarTag',
                      'Failed to choose avatar, error: %{public}d %{public}s', err.code, err.message)
                    return
                  }
                  hilog.info(DOMAIN, 'AvatarTag', 'Succeeded in choosing avatar')
                  if (data && data.avatarUri) {
                    this.avatarUri = data.avatarUri!
                    this.hasSelectedAvatar = true
                  }
                })
            })

推荐把功能入口放在 FunctionalButton 容器中，并让它靠近头像展示区域。这样用户可以明确知道点击后会更换头像，而不是把头像图片本身误认为普通图片浏览区域。

头像 URI 应该交给状态变量管理

头像选择完成后，回调返回的 URI 不应该只在回调函数内部使用，而应保存到页面状态变量，例如 avatarUri。状态变量发生变化后，ArkUI 会触发相关 UI 重新构建，Image 组件即可展示新图片。

页面逻辑可以抽象为：

初始状态：avatarUri 为空
        ↓
展示默认头像
        ↓
用户选择头像
        ↓
onSelected 返回 URI
        ↓
更新 avatarUri
        ↓
Image 根据新 URI 刷新

如果回调返回空值，或用户取消选择，则应继续保留原头像，不要把页面强制刷新成空白区域。这里也是验收时需要重点检查的边界情况。

图片裁剪与尺寸适配

头像通常使用圆形展示，常见处理包括：

• 外层容器设置固定的宽高，例如 96vp 到 120vp；
• 使用圆形裁剪，避免图片超出头像区域；
• 使用 ImageFit.Cover 或等效方式填充容器；
• 通过布局间距保证昵称、按钮和头像之间有足够的点击区域；
• 不使用过多固定的屏幕宽度，避免小屏设备发生溢出。

ImageFit.Cover 会优先保证容器被图片填满，超出部分会被裁剪，因此更适合头像场景。若使用完整显示的适配方式，图片可能出现留白，头像圆形区域的视觉效果会不稳定。

默认资源是页面可运行的前提

如果代码使用 $r('app.media.default_avatar')，项目中必须存在对应资源。生成代码后，需要确认：

1. 默认头像文件已经放入正确的资源目录；
2. 资源名称与代码中的 $r 引用完全一致；
3. 资源格式和工程当前 SDK 支持情况匹配；
4. 头像选择成功后，URI 分支不会继续错误地使用默认资源。

资源缺失是这类示例最容易被忽略的问题之一。代码本身看起来完整，但构建时仍可能因为资源引用不存在而失败。

项目验收与本地运行

检查远程提交

如下图所示，项目生成完成后，可以打开 AtomGit 仓库查看提交记录，确认代码确实已经提交。

查看提交时建议重点关注：

• 是否修改了正确的页面文件；
• 是否新增或引用了默认头像资源；
• 是否出现与本案例无关的大量文件变更；
• 提交信息是否能说明本次修改内容。

拉取到本地

确认远程代码提交完成后，在本地项目目录执行：

git pull origin master

代码拉取成功之后,可以尝试运行项目进行本地验证。

按清单验收页面

运行项目后，按照下面的清单逐项验证：

验收项	检查内容
初始展示	页面打开后是否有默认头像、标题和用户信息
入口组件	是否使用 ChooseAvatarButton，而不是普通 Button
系统跳转	点击更换入口后能否拉起头像选择能力
回调数据	选择成功后是否收到有效头像 URI
状态更新	avatarUri 更新后，页面是否立即刷新
取消处理	取消选择或 URI 为空时，原头像是否保持不变
图片显示	是否圆形裁剪、居中显示、尺寸适配
屏幕适配	小屏或不同尺寸设备上是否出现溢出
资源配置	默认头像资源是否存在且能够正常构建

如下图所示，项目运行后可以查看最终效果：

总结

本次案例的核心不是单纯调用一个代码生成模型，而是建立了一条相对完整的开发链路：

• 用可运行的 HarmonyOS 空项目作为代码生成基础；
• 通过 AtomGit 保存工程和提交记录；
• 在提示词中同时描述功能目标、技术约束、交互步骤和验收标准；
• 使用 ChooseAvatarButton 接入系统头像选择能力；
• 通过 onSelected 获取头像 URI，并交给 ArkUI 状态变量驱动页面刷新；
• 通过本地拉取、编译和设备运行完成最终验收。

对于类似的 ArkTS 页面开发，建议不要只描述“想要什么界面”，还要明确“必须使用什么 API”“数据如何流转”“异常情况怎么处理”以及“怎样才算完成”。需求越具体，代码生成结果越容易落到真实工程中，也越方便后续排查和维护。