​AvatarView 详解：支持 Coil/Glide 的 Android 头像组件库

AvatarView 详解：支持 Coil/Glide 的 Android 头像组件库

社交、通讯、协作类 App 里，头像是个高频又琐碎的组件——要支持圆形 / 圆角、边框、在线状态点、首字母兜底，还要能在一个头像里塞多张图（比如群聊头像）。GetStream/avatarview-android（AvatarView）把这些都打包好了，并同时支持 Coil 与 Glide 两种图片引擎。本文从依赖、基础用法、分块风格、视觉定制到 Stream Chat 集成，讲清怎么用。

1、项目概述

AvatarView 是 Stream（getstream.io）出品的 Android 头像组件，仓库约 435 Star、28 Fork，采用 Apache 2.0 协议，当前版本 1.0.7，托管在 Maven Central，group 为 io.getstream。它把头像加载、边框、状态指示、首字母、分块多图整合进一个控件，并支持两种图片引擎。

能力一览：

        - 头像加载 + 边框（含渐变）+ 状态指示 + 首字母兜底 + 分块多图

        - 支持 Coil（官方推荐）与 Glide 两种引擎

        - 可选集成 Stream Chat SDK，直接绑定用户与频道头像

2、两种图片引擎与依赖

官方推荐使用 Coil 版（avatarview-coil）；如果项目已重度使用 Glide，也可选 Glide 版（avatarview-glide）。两者 API 一致，切换成本低。

// 推荐：Coil 版（内部已包含 Coil，无需另引）
implementation "io.getstream:avatarview-coil:1.0.7"

// 或：Glide 版
implementation "io.getstream:avatarview-glide:1.0.7"

接入要点：

1. 根 build.gradle 的 repositories 加入 mavenCentral

2. 模块依赖按现有图片栈选 avatarview-coil 或 avatarview-glide

3. coil 版内部已自带 Coil，不必再单独引入

4. 两个版本共用同一套 loadImage API，按需切换

3、基础用法：声明与加载

先在布局里声明 AvatarView 并配置常用属性，再在代码里用 loadImage 加载图片。

<io.getstream.avatarview.AvatarView
    android:layout_width="110dp"
    android:layout_height="110dp"
    app:avatarViewBorderColor="@color/yellow"
    app:avatarViewBorderWidth="3dp"
    app:avatarViewIndicatorEnabled="true"
    app:avatarViewIndicatorPosition="bottomRight"
    app:avatarViewShape="circle" />

// data 支持 String / Uri / HttpUrl / File / DrawableRes / Drawable / Bitmap
avatarView.loadImage(data)

// 带占位图与回调
avatarView.loadImage(
        data = data,
        placeholder = drawable,
        onStart = { /* 开始请求 */ },
        onComplete = { /* 请求完成 */ }
)

使用要点：

1. XML 用 io.getstream.avatarview.AvatarView，宽高建议固定 dp

2. 通过 app:avatarView* 系列属性配置边框、指示、形状等

3. 代码里 loadImage(data) 加载，data 类型灵活，URL / 文件 / 资源皆可

4. 可选传 placeholder 与 onStart / onComplete 回调，控制加载体验

4、分块风格：一个头像放多张图

群聊、多人会话常用"多图头像"，AvatarView 原生支持，把多张图打包成列表传给 loadImage 即可，默认最多 4 张。

// 分块风格：最多 4 张，自动拼到一个头像里
avatarView.loadImage(data = listOf(url1, url2, url3, url4))

分块要点：

1. 把多张图打包成 listOf(...) 传给 loadImage，组件自动分块

2. 用 app:avatarViewMaxSectionSize="4" 限制分块上限（默认 4）

3. 适合群聊头像、多人协作卡片等场景，省去自己拼图

4. 单图与多图共用同一个 loadImage API，按 data 类型自动切换

5、视觉定制：边框、形状、指示与首字母

AvatarView 的视觉属性非常丰富，基本覆盖了头像常见的定制需求。

主要属性：

        - 形状：avatarViewShape（circle / rounded_rect）+ avatarViewBorderRadius

        - 边框：avatarViewBorderColor / BorderWidth；渐变边框用 avatarViewBorderColorArray（颜色数组）

        - 状态指示：indicatorEnabled / Color / BorderColor / Position / SizeCriteria，支持自定义 drawable

        - 首字母：avatarViewInitials + BackgroundColor / TextColor / TextSize / TextStyle

        - 占位：avatarViewPlaceholder / avatarViewErrorPlaceholder

<io.getstream.avatarview.AvatarView
    android:layout_width="110dp"
    android:layout_height="110dp"
    app:avatarViewShape="rounded_rect"
    app:avatarViewBorderRadius="21dp"
    app:avatarViewBorderColor="@color/white"
    app:avatarViewBorderWidth="3dp"
    app:avatarViewIndicatorEnabled="true"
    app:avatarViewIndicatorColor="@color/green"
    app:avatarViewIndicatorPosition="bottomRight"
    app:avatarViewInitials="AB"
    app:avatarViewInitialsTextStyle="bold" />

定制要点：

1. circle 适合常规头像，rounded_rect + BorderRadius 适合圆角方形

2. 渐变边框先在 colors.xml 定义颜色数组，再用 avatarViewBorderColorArray 引用

3. 状态指示常配合在线状态、未读红点使用

4. 无图时用首字母兜底，避免出现空白头像

6、自定义加载与 Stream Chat 集成

进阶场景下，可以接管 Bitmap 生成，或直接对接 Stream Chat。

自定义加载：

        - 实现 AvatarBitmapFactory 的 loadAvatarBitmap，用 AvatarCoil.setAvatarBitmapFactory 注册

        - Coil 版还可在 loadImage 尾随 lambda 里加 crossfade、transformations、lifecycle 等

Stream Chat 集成：

// 额外引入 io.getstream:avatarview-stream-integration:1.0.7
AvatarCoil.setAvatarBitmapFactory(StreamAvatarBitmapFactory(context))

// 绑定当前用户头像
val currentUser = ChatClient.instance().getCurrentUser()
avatarView.setUserData(currentUser)

// 或直接绑定频道（群聊）头像
avatarView.setChannel(channel)

集成要点：

1. 自定义加载时，实现 AvatarBitmapFactory 并用 AvatarCoil 注册

2. Stream Chat 项目引入 stream-integration，用 StreamAvatarBitmapFactory 一键接入

3. setUserData 绑定用户头像，setChannel 绑定频道头像

4. 普通项目无需该模块，核心库即可独立使用

7、使用建议与注意事项

使用建议：

        - 新项目优先 avatarview-coil，与 Coil 生态保持一致

        - 头像尺寸建议固定 dp，避免列表滚动时布局抖动

        - 用首字母兜底 + 占位图，改善无图与加载中的体验

        - 群头像直接用分块风格，省去自己拼 Bitmap

注意事项：

        - 分块上限为 4（avatarViewMaxSectionSize），超出需自行裁剪

        - 切换 Coil / Glide 时，依赖与 BitmapFactory 要同步更换

        - stream-integration 需与所用 Stream Chat SDK 版本兼容

        - RTL 布局可用相关属性进行适配

8、总结

AvatarView 是 Stream 出品的 Android 头像组件，435 Star、Apache 2.0、版本 1.0.7。它把头像加载、边框（含渐变）、状态指示、首字母兜底、分块多图（最多 4 张）整合到一个控件，支持 Coil（推荐）与 Glide 两种引擎，并可一键集成 Stream Chat。

对于社交、通讯、协作类 App，按现有图片栈选 avatarview-coil 或 glide，用 loadImage 加载、用 avatarView* 属性定制视觉、用分块风格做群头像；Stream Chat 项目则直接走 stream-integration，是快速实现专业头像体验的必要方案。