文档开发者中心
我的

HarmonyOS 头像选择别再手写相册流程了:用 FunctionalButton 接入 CHOOSE_AVATAR

浏览86发布于2026-09-20 02:22北京

前言

做个人资料页时,「更换头像」看起来是个小功能,但真落到代码里,往往不止拉起相册这么简单。

如果自己用 picker.PhotoSelectPicker 实现,除了拿到图片 URI,还要考虑权限、用户取消、异常回调、不同设备上的拉起表现,以及头像裁剪后的显示效果。功能能做出来,但每个页面都重复写一遍,时间久了就很烦。

HarmonyOS 的 Scenario Fusion Kit 提供了 FunctionalButton,它把这类高频场景封装成了按钮能力。头像选择对应的是 functionalButtonComponentManager.OpenType.CHOOSE_AVATAR。页面里放一个按钮,绑定 onChooseAvatar 回调,选完后直接拿 data.avatarUri 更新 UI。

这篇文章不讲太泛的概念,只围绕一个完整例子:实现一个个人资料页,包含圆形头像展示、默认头像兜底、点击按钮选择头像、选择成功后即时刷新。

先看最终效果

这套流程里有三个关键点:

关键点 作用
openType: CHOOSE_AVATAR 告诉 FunctionalButton 当前按钮用于选择头像
onChooseAvatar 接收头像选择结果,拿到 avatarUri
@State 保存头像 URI,并驱动 ArkUI 自动刷新页面

只要这三处配对正确,头像选择功能基本就能跑通。

为什么不直接用 picker 拉相册

手写相册选择并不难,常见写法类似这样:

收起
自动换行
深色代码主题
复制
import { picker } from '@kit.CoreFileKit';

async selectAvatar() {
const photoSelectOptions = new picker.PhotoSelectOptions();
photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE;
photoSelectOptions.maxSelectNumber = 1;

const photoViewPicker = new picker.PhotoViewPicker();
try {
  const result = await photoViewPicker.select(photoSelectOptions);
  if (result.photoUris.length > 0) {
    this.avatarUri = result.photoUris[0];
  }
} catch (err) {
  // 这里还要继续补取消、异常、日志等逻辑
}
}

这段代码的问题不在于复杂,而在于它只是「选择图片」这一层。真正做头像功能时,还会遇到这些细节:

  • 用户拒绝权限或取消选择时,页面状态要不要恢复?
  • 拿到的 URI 为空时,Image 组件怎么兜底?
  • 按钮点击后是否需要 loading 或禁用态?
  • 不同设备上系统选择页的表现是否一致?
  • 后续如果换成手机号、地址、发票抬头等场景,是不是又要写一套?

如果只是普通图片选择,picker 当然没问题;但如果需求明确是「头像选择」,FunctionalButton + CHOOSE_AVATAR 更贴近场景。它把按钮触发、系统面板、结果回调这条链路封装好了,页面只需要处理拿到头像 URI 之后的 UI 状态。

FunctionalButton 适合解决什么问题

FunctionalButton 可以理解为一个带系统能力的按钮。它不像普通 Button 那样只负责点击事件,而是通过 openType 指定要拉起的系统场景。

在头像选择场景里,它做了几件事:

  • 根据 CHOOSE_AVATAR 拉起系统头像选择能力;
  • 通过 onChooseAvatar 返回选择结果;
  • 允许通过 ButtonConfig 自定义按钮样式;
  • 把场景能力和回调方法绑定起来,减少手写流程代码。

所以它解决的不是「能不能实现头像选择」,而是让这个功能少写样板代码、少踩适配坑。

导入模块

页面里需要用到两个 Kit:

收起
自动换行
深色代码主题
复制
import { FunctionalButton, functionalButtonComponentManager } from '@kit.ScenarioFusionKit'
import { hilog } from '@kit.PerformanceAnalysisKit'

这里分别对应:

  • FunctionalButton:场景化按钮组件本体,用在 ArkUI 页面中;
  • functionalButtonComponentManager:提供 OpenType、ButtonConfig、FunctionalButtonController 等配置能力;
  • hilog:用于记录选择失败或成功的日志,方便调试。

如果项目里只是快速验证功能,hilog 可以先少写;但实际项目建议保留错误日志,不然后面遇到「按钮点了没反应」时很难定位。

定义页面状态

头像选择功能至少需要一个状态:头像 URI。为了让 UI 表达更清楚,这里再加一个布尔值记录用户是否已经选择过头像。

收起
自动换行
深色代码主题
复制
const DOMAIN = 0x0000

@Entry
@Component
struct Index {
@State avatarUri: string = ''
@State nickname: string = '用户昵称'
@State account: string = 'user@example.com'
@State hasSelectedAvatar: boolean = false

几个状态的作用如下:

状态 作用
avatarUri 保存选择完成后返回的头像地址
nickname 页面展示用昵称,真实项目里通常来自账号系统
account 页面展示用账号信息
hasSelectedAvatar 控制默认头像和用户头像的切换,也控制底部提示文案

有人可能会问:既然有 avatarUri,为什么还要 hasSelectedAvatar?

只用 avatarUri !== '' 也能实现,但语义没那么直观。hasSelectedAvatar 表达的是「用户是否完成过选择」这个业务状态,而 avatarUri 表达的是「当前头像资源地址」。两个状态分开后,后面扩展上传中、上传失败、审核中等状态会更容易。

搭页面骨架

页面结构很简单:外层 Column,顶部标题栏固定高度,下面用 Scroll 承载个人资料内容。

收起
自动换行
深色代码主题
复制
build() {
Column() {
  Row() {
    Text('个人资料')
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
      .fontColor('#333333')
  }
  .width('100%')
  .height(56)
  .padding({ left: 16, right: 16 })
  .justifyContent(FlexAlign.Center)
  .backgroundColor('#FFFFFF')

  Scroll() {
    Column() {
      // 头像展示区域
      // 头像设置区域
    }
    .width('100%')
  }
  .width('100%')
  .layoutWeight(1)
  .scrollBar(BarState.Off)
}
.width('100%')
.height('100%')
.backgroundColor('#F5F5F5')
}

这里有两个小细节:

  • 标题栏固定 56vp,内容区用 layoutWeight(1) 撑满剩余空间;
  • 内容区使用 Scroll,即使后面继续加昵称、签名、手机号等设置项,也不会挤出屏幕。

展示圆形头像

头像区域的代码如下:

收起
自动换行
深色代码主题
复制
Column() {
Stack() {
  if (this.hasSelectedAvatar && this.avatarUri !== '') {
    Image(this.avatarUri)
      .width(108)
      .height(108)
      .borderRadius(54)
      .objectFit(ImageFit.Cover)
      .border({ width: 2, color: '#E0E0E0' })
  } else {
    Image($r('app.media.startIcon'))
      .width(108)
      .height(108)
      .borderRadius(54)
      .objectFit(ImageFit.Cover)
      .border({ width: 2, color: '#E0E0E0' })
  }
}
.width(108)
.height(108)
.margin({ top: 32 })

Text(this.nickname)
  .fontSize(18)
  .fontWeight(FontWeight.Medium)
  .fontColor('#333333')
  .margin({ top: 16 })

Text(this.account)
  .fontSize(14)
  .fontColor('#999999')
  .margin({ top: 4 })
}
.width('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)

这里最容易被忽略的是头像裁剪。

width(108)、height(108)、borderRadius(54) 三个值要配套使用。宽高相等,圆角半径取宽高的一半,图片才会是标准圆形。如果圆角半径偏小,看起来就像圆角矩形;如果图片不是正方形,还要配合 objectFit(ImageFit.Cover),否则头像区域可能会留白。

条件渲染也建议写得保守一点:

收起
自动换行
深色代码主题
复制
if (this.hasSelectedAvatar && this.avatarUri !== '') {
Image(this.avatarUri)
} else {
Image($r('app.media.startIcon'))
}

这样即使回调里没有拿到有效 URI,页面也会继续显示默认头像,不会让 Image 组件去加载空字符串。

Stack 的作用是固定头像区域尺寸。头像在默认图和用户选择图之间切换时,外层布局不需要重新计算尺寸,视觉上会更稳。

接入 CHOOSE_AVATAR

核心代码在这里:

收起
自动换行
深色代码主题
复制
Column() {
Text('头像设置')
  .fontSize(16)
  .fontWeight(FontWeight.Medium)
  .fontColor('#333333')
  .margin({ bottom: 16 })

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
      }
    })
})

if (this.hasSelectedAvatar) {
  Text('头像已更新')
    .fontSize(12)
    .fontColor('#4CAF50')
    .margin({ top: 12 })
} else {
  Text('点击上方按钮选择头像')
    .fontSize(12)
    .fontColor('#999999')
    .margin({ top: 12 })
}
}
.width('100%')
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
.padding({ left: 24, right: 24 })

这段代码主要看三处。

openType 指定系统能力

收起
自动换行
深色代码主题
复制
openType: functionalButtonComponentManager.OpenType.CHOOSE_AVATAR

openType 决定这个 FunctionalButton 要做什么。这里使用 CHOOSE_AVATAR,按钮点击后就会进入头像选择场景。

这一步不要写错。如果 openType 不是 CHOOSE_AVATAR,后面的 onChooseAvatar 就算写了,也不一定会按预期触发。

ButtonConfig 控制按钮样式

收起
自动换行
深色代码主题
复制
styleConfig: new functionalButtonComponentManager.ButtonConfig()
.type(ButtonType.Normal)
.fontSize(16)
.fontColor('#FFFFFF')
.backgroundColor('#007DFF')
.borderRadius(24)
.width(200)
.height(48)

FunctionalButton 不是只能用系统默认样式。通过 ButtonConfig,可以像配置普通按钮一样调整字体、背景色、圆角和尺寸。

这里按钮高度是 48vp,圆角设为 24vp,得到一个胶囊按钮。宽度固定为 200vp,是为了避免在不同父容器宽度下被拉伸得过宽。

onChooseAvatar 处理结果

收起
自动换行
深色代码主题
复制
.onChooseAvatar((err, data) => {
if (err) {
  hilog.error(DOMAIN, 'AvatarTag',
    'Failed to choose avatar, error: %{public}d %{public}s', err.code, err.message)
  return
}

if (data && data.avatarUri) {
  this.avatarUri = data.avatarUri!
  this.hasSelectedAvatar = true
}
})

err 分支一定要先处理。用户取消选择、系统能力异常、其他失败情况,都可能进入这里。这里直接 return,避免后面继续读 data。

成功分支里,也不要默认 data.avatarUri 一定有值。更稳妥的写法是先判断:

收起
自动换行
深色代码主题
复制
if (data && data.avatarUri) {
this.avatarUri = data.avatarUri!
this.hasSelectedAvatar = true
}

avatarUri 更新后,ArkUI 会根据 @State 自动刷新使用它的 UI。hasSelectedAvatar 变成 true 后,头像展示区从默认图切到用户选择的头像,底部提示也从「点击上方按钮选择头像」变成「头像已更新」。

完整源码

下面这段代码可以直接放到 entry/src/main/ets/pages/Index.ets 里验证:

收起
自动换行
深色代码主题
复制
import { FunctionalButton, functionalButtonComponentManager } from '@kit.ScenarioFusionKit'
import { hilog } from '@kit.PerformanceAnalysisKit'

const DOMAIN = 0x0000

@Entry
@Component
struct Index {
@State avatarUri: string = ''
@State nickname: string = '用户昵称'
@State account: string = 'user@example.com'
@State hasSelectedAvatar: boolean = false

build() {
  Column() {
    Row() {
      Text('个人资料')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)
        .fontColor('#333333')
    }
    .width('100%')
    .height(56)
    .padding({ left: 16, right: 16 })
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#FFFFFF')

    Scroll() {
      Column() {
        Column() {
          Stack() {
            if (this.hasSelectedAvatar && this.avatarUri !== '') {
              Image(this.avatarUri)
                .width(108)
                .height(108)
                .borderRadius(54)
                .objectFit(ImageFit.Cover)
                .border({ width: 2, color: '#E0E0E0' })
            } else {
              Image($r('app.media.startIcon'))
                .width(108)
                .height(108)
                .borderRadius(54)
                .objectFit(ImageFit.Cover)
                .border({ width: 2, color: '#E0E0E0' })
            }
          }
          .width(108)
          .height(108)
          .margin({ top: 32 })

          Text(this.nickname)
            .fontSize(18)
            .fontWeight(FontWeight.Medium)
            .fontColor('#333333')
            .margin({ top: 16 })

          Text(this.account)
            .fontSize(14)
            .fontColor('#999999')
            .margin({ top: 4 })
        }
        .width('100%')
        .justifyContent(FlexAlign.Center)
        .alignItems(HorizontalAlign.Center)

        Divider()
          .width('90%')
          .color('#F0F0F0')
          .margin({ top: 24, bottom: 24 })

        Column() {
          Text('头像设置')
            .fontSize(16)
            .fontWeight(FontWeight.Medium)
            .fontColor('#333333')
            .margin({ bottom: 16 })

          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
                }
              })
          })

          if (this.hasSelectedAvatar) {
            Text('头像已更新')
              .fontSize(12)
              .fontColor('#4CAF50')
              .margin({ top: 12 })
          } else {
            Text('点击上方按钮选择头像')
              .fontSize(12)
              .fontColor('#999999')
              .margin({ top: 12 })
          }
        }
        .width('100%')
        .justifyContent(FlexAlign.Center)
        .alignItems(HorizontalAlign.Center)
        .padding({ left: 24, right: 24 })
      }
      .width('100%')
    }
    .width('100%')
    .layoutWeight(1)
    .scrollBar(BarState.Off)
  }
  .width('100%')
  .height('100%')
  .backgroundColor('#F5F5F5')
}
}

容易踩的坑

openType 和回调必须配套

FunctionalButton 的 openType 和 controller 回调是对应关系。头像选择必须使用:

收起
自动换行
深色代码主题
复制
openType: functionalButtonComponentManager.OpenType.CHOOSE_AVATAR

并配套:

收起
自动换行
深色代码主题
复制
.onChooseAvatar((err, data) => {
// 处理头像选择结果
})

如果把 openType 写成其他场景,或者把回调写成 onGetPhoneNumber、onChooseAddress,按钮可能能显示出来,但点击后拿不到头像结果。

常见对应关系可以参考这个表:

openType 对应回调
CHOOSE_AVATAR onChooseAvatar
GET_PHONE_NUMBER onGetPhoneNumber
CHOOSE_ADDRESS onChooseAddress
CHOOSE_INVOICE_TITLE onChooseInvoiceTitle
LAUNCH_APP onLaunchApp

写这类代码时,我建议先写 openType,再立刻写对应回调,别隔很远补,否则很容易改着改着就不匹配。

avatarUri 为空时别直接渲染

不要只判断 data:

收起
自动换行
深色代码主题
复制
// 不建议
if (data) {
this.avatarUri = data.avatarUri!
this.hasSelectedAvatar = true
}

更稳的写法是判断到 avatarUri:

收起
自动换行
深色代码主题
复制
// 推荐
if (data && data.avatarUri) {
this.avatarUri = data.avatarUri!
this.hasSelectedAvatar = true
}

原因很简单:Image('') 没有业务意义,还可能导致头像区域空白。头像这种用户强感知区域,宁可继续显示默认图,也不要渲染一个无效资源。

默认头像资源要提前准备

示例里用了:

收起
自动换行
深色代码主题
复制
Image($r('app.media.startIcon'))

这要求项目资源里存在 startIcon。如果你的项目没有这个资源,要么替换成自己的默认头像资源,要么新增一张默认头像图。否则代码逻辑没问题,但页面会因为资源不存在而报错。

还能扩展到哪些场景

CHOOSE_AVATAR 只是 FunctionalButton 的一个场景。类似的系统能力还有:

  • GET_PHONE_NUMBER:获取或验证手机号;
  • CHOOSE_ADDRESS:选择收货地址;
  • CHOOSE_INVOICE_TITLE:选择发票抬头;
  • LAUNCH_APP:拉起指定应用;
  • OPEN_SETTING:打开授权设置页;
  • CHOOSE_LOCATION:选择位置。

这些场景的接入方式很像:换一个 openType,再换对应的回调方法。真正需要注意的是业务状态怎么设计,而不是按钮本身怎么写。

比如地址选择场景,拿到结果后通常要更新收货人、手机号、详细地址;手机号场景则要考虑登录态、绑定态和服务端校验。FunctionalButton 只负责把系统能力拉起来,业务闭环还是要自己处理。

小结

用 FunctionalButton 实现头像选择,核心代码其实就几行:

收起
自动换行
深色代码主题
复制
FunctionalButton({
params: {
  openType: functionalButtonComponentManager.OpenType.CHOOSE_AVATAR,
  label: '更换头像'
},
controller: new functionalButtonComponentManager.FunctionalButtonController()
  .onChooseAvatar((err, data) => {
    if (data && data.avatarUri) {
      this.avatarUri = data.avatarUri!
      this.hasSelectedAvatar = true
    }
  })
})

我的建议是:如果只是普通图片选择,继续用 picker;如果业务语义就是「选择头像」,优先考虑 FunctionalButton + CHOOSE_AVATAR。它能少写一批重复逻辑,也能让页面代码更聚焦在状态和展示上。

最后再记两点:openType 和回调方法必须匹配;avatarUri 一定要判空后再交给 Image。这两个细节处理好,头像选择这块基本就稳了。

收藏
0
回复
3
分享
全部评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
前言
先看最终效果
为什么不直接用 picker 拉相册
FunctionalButton 适合解决什么问题
导入模块
定义页面状态
搭页面骨架
展示圆形头像
接入 CHOOSE_AVATAR
openType 指定系统能力
ButtonConfig 控制按钮样式
onChooseAvatar 处理结果
完整源码
容易踩的坑
openType 和回调必须配套
avatarUri 为空时别直接渲染
默认头像资源要提前准备
还能扩展到哪些场景
小结
了解社区公约,与您携手共创和谐专业的开发者社区。