跳到主要内容

会话列表（Config 部分自定义 UI）

会话列表通过 RCKConvoConfig 进行部分自定义 UI，覆盖 AppBar、头像、标题、最后一条消息、时间、未读角标、免打扰图标、单元格样式、元素布局、侧滑操作、整体列表等。以下为所有可用配置及字段说明，并提供常见使用示例。

入口组件​

  • 组件：RCKConvoPage
  • 配置：RCKConvoConfig

总览：RCKConvoConfig（会话列表整体配置）​

包含以下子配置：

  • appBarConfig: 顶部导航栏配置（详见下文“AppBar 配置”）
  • avatarConfig: 头像配置
  • titleConfig: 标题（会话名）配置
  • lastMessageConfig: 最后一条消息配置
  • timeConfig: 时间配置
  • unreadBadgeConfig: 未读角标配置
  • muteIconConfig: 免打扰图标配置
  • itemConfig: 单元格容器与分割线配置
  • layoutConfig: 各元素在单元格内的布局位置与间距
  • slidableConfig: 侧滑操作配置（置顶/删除/免打扰/自定义）
  • listConfig: 列表级别配置（搜索、分页、背景等）

AppBar 配置（RCKConvoAppBarConfig）​

  • height（double）: AppBar 高度
  • padding（EdgeInsets）: AppBar 内边距
  • centerTitle（bool）: 标题是否居中
  • automaticallyImplyLeading（bool）: 是否自动添加返回按钮
  • backgroundConfig（BackgroundConfig）: 背景（颜色/图片/渐变/边框/圆角/阴影）
  • leadingConfig（LeadingConfig）: 左侧区域（图标/文本/点击/内边距/最大宽度等）
  • titleConfig（AppbarTitleConfig）: 标题文本、样式、前后缀图标、间距、内边距、对齐
  • actionsConfig（ActionsConfig）: 右侧操作项列表、间距、内边距、对齐

BackgroundConfig 字段：color、image（DecorationImage）、gradient、border、borderRadius、boxShadow

LeadingConfig 字段：icon（Widget?）、text（String?）、textStyle、textOverflow、spacing、onPressed、padding、maxWidth

AppbarTitleConfig 字段：text、textStyle、textOverflow、prefixIcon、suffixIcon、spacing、padding、maxWidth、alignment（MainAxisAlignment）

ActionsConfig 字段：items（List<ActionItem>）、spacing、padding、maxWidth、alignment

ActionItem 字段：icon（Widget，必填）、text、textStyle、textOverflow、spacing、onPressed、padding

示例：

Dart
RCKConvoPage(
  config: RCKConvoConfig(
    appBarConfig: RCKConvoAppBarConfig(
      titleConfig: AppbarTitleConfig(text: '会话'),
      leadingConfig: LeadingConfig(
        icon: const Icon(Icons.arrow_back),
        onPressed: () => Navigator.pop(context),
      ),
      actionsConfig: ActionsConfig(items: [
        ActionItem(icon: const Icon(Icons.add), onPressed: () {/* ... */}),
      ]),
    ),
  ),
)

头像配置（RCKAvatarConfig）​

  • shape（AvatarShape）: 头像形状。可选：circle、rectangle、roundedRect
  • size（double）: 头像尺寸（有效范围 32–64）
  • borderRadius（double）: 圆角大小（shape 为 roundedRect 时生效）
  • borderColor（Color?）: 边框颜色
  • borderWidth（double?）: 边框宽度
  • backgroundColor（Color?）: 头像背景色
  • badgeOffset（Offset?）: 未读角标相对头像的偏移

示例：

Dart
avatarConfig: const RCKAvatarConfig(
  shape: AvatarShape.circle,
  size: 48,
)

标题配置（RCKConvoTitleConfig）​

  • fontSize（double）: 字体大小
  • color（Color?）: 字体颜色
  • fontWeight（FontWeight）: 字重
  • maxLines（int）: 最大行数
  • showSuffix（bool）: 是否展示标题后缀
  • suffixIcon（IconData?）: 后缀图标
  • suffixText（String?）: 后缀文本
  • suffixTextStyle（TextStyle?）: 后缀文本样式

示例：

Dart
titleConfig: const RCKConvoTitleConfig(fontSize: 16, maxLines: 1)

最后一条消息配置（RCKLastMessageConfig）​

  • fontSize（double）: 字体大小
  • color（Color）: 字体颜色
  • fontWeight（FontWeight）: 字重
  • maxLines（int）: 最大行数
  • customTypeText（Map<Type, String>?）: 自定义消息类型提示文案（覆盖默认映射）

默认映射示例：图片/语音/位置/文件/视频/GIF/撤回 等类型会显示为类似"[图片]""[语音]"等文案

示例：

Dart
lastMessageConfig: RCKLastMessageConfig(
  maxLines: 1,
  customTypeText: const { /* Type → 文案 */ },
)

时间配置（RCKTimeConfig）​

  • fontSize（double）: 字体大小
  • color（Color）: 颜色
  • fontWeight（FontWeight）: 字重
  • formatter（String Function(int timestamp)?）: 自定义时间格式化器

示例：

Dart
timeConfig: RCKTimeConfig(
  formatter: (ts) => DateTime.fromMillisecondsSinceEpoch(ts).toString(),
)

未读角标配置（RCKUnreadBadgeConfig）​

  • backgroundColor（Color）: 未读角标背景色
  • muteBackgroundColor（Color）: 免打扰时背景色
  • textColor（Color）: 文本颜色
  • fontSize（double）: 字体大小
  • position（BadgePosition）: 显示位置。可选：avatarTopRight（头像右上）、itemRight（单元格右侧）
  • width（double）: 宽度（默认约 42）
  • height（double）: 高度（默认约 21）
  • overflowText（String）: 超过 99 的显示文本（默认 99+）

示例：

Dart
unreadBadgeConfig: const RCKUnreadBadgeConfig(
  position: BadgePosition.itemRight,
)

免打扰图标配置（RCKMuteIconConfig）​

  • show（bool）: 是否显示免打扰图标
  • icon（String）: 图标资源路径（默认取主题图标）
  • size（double）: 图标大小（默认约 16）
  • color（Color）: 图标颜色（默认取主题颜色）
  • position（MuteIconPosition）: 位置。titleSuffix（标题后缀）、titlePrefix、avatarTopRight、messagePrefix

示例：

Dart
muteIconConfig: const RCKMuteIconConfig(show: true)

单元格样式配置（RCKItemConfig）​

  • height（double）: 单元格高度（默认约 76）
  • backgroundColor（Color?）: 背景色
  • pinnedBackgroundColor（Color?）: 置顶背景色
  • dividerColor（Color?）: 分割线颜色
  • dividerIndent（double）: 分割线左缩进
  • dividerEndIndent（double）: 分割线右缩进
  • dividerHeight（double）: 分割线高度（默认约 1）
  • padding（EdgeInsets）: 单元格内边距（默认左右含一定内边距）
  • cellSpacing（double）: 单元格之间额外间距

示例：

Dart
itemConfig: const RCKItemConfig(
  height: 72,
  dividerColor: Color(0xFFEFEFEF),
)

元素布局配置（RCKLayoutConfig）​

  • avatarPosition（ItemElementPosition）: 头像位置
  • titlePosition（ItemElementPosition）: 标题位置
  • messagePosition（ItemElementPosition）: 消息位置
  • timePosition（ItemElementPosition）: 时间位置
  • unreadPosition（ItemElementPosition）: 未读角标位置
  • horizontalSpacing（double）: 元素水平间距（默认约 16）
  • verticalSpacingEnd（double）: 尾部元素垂直间距（默认约 8）
  • verticalSpacingContent（double）: 标题与内容竖向间距（默认约 4）

ItemElementPosition 可选：left、right、topLeft、topRight、bottomLeft、bottomRight、center、topRightCorner、bottomRightCorner、avatarTopRight

示例：

Dart
layoutConfig: const RCKLayoutConfig(
  horizontalSpacing: 16,
  unreadPosition: ItemElementPosition.itemRight,
)

侧滑操作配置（RCKSlidableConfig / RCKSlidableActionConfig）​

  • enabled（bool）: 是否启用侧滑
  • actions（List<RCKSlidableActionConfig>）: 操作按钮，建议 1–3 个

RCKSlidableActionConfig 字段：

  • label（String）: 文本
  • iconPath（String）: 图标路径
  • undoIconPath（String?）: 撤销图标路径（用于"置顶/取消置顶"等）
  • backgroundColor（Color）: 背景色
  • foregroundColor（Color）: 前景（文字/图标）颜色
  • actionType（SlidableActionType）: 动作类型（pin/delete/mute/custom）
  • autoClose（bool）: 点击后是否自动收起侧滑

预置操作构造：RCKSlidableActionConfig.pin()、delete()、mute()

示例：

Dart
slidableConfig: RCKSlidableConfig(
  actions: [
    RCKSlidableActionConfig.pin(),
    RCKSlidableActionConfig.delete(),
    // RCKSlidableActionConfig.mute(),
  ],
)

列表配置（RCKListConfig）​

  • showSearchBar（bool）: 是否显示搜索框
  • emptyText（String）: 空列表提示文案（默认"暂无消息"）
  • enablePullToRefresh（bool）: 是否支持下拉刷新
  • pageSize（int）: 分页大小（默认 20）
  • backgroundColor（Color?）: 列表背景色

示例：

Dart
listConfig: const RCKListConfig(
  showSearchBar: true,
  pageSize: 20,
)

综合示例（推荐起步配置）​

Dart
RCKConvoPage(
  config: RCKConvoConfig(
    appBarConfig: RCKConvoAppBarConfig(
      titleConfig: AppbarTitleConfig(text: '会话'),
    ),
    avatarConfig: const RCKAvatarConfig(shape: AvatarShape.circle, size: 48),
    titleConfig: const RCKConvoTitleConfig(fontSize: 16, maxLines: 1),
    lastMessageConfig: RCKLastMessageConfig(maxLines: 1),
    timeConfig: RCKTimeConfig(),
    unreadBadgeConfig: const RCKUnreadBadgeConfig(position: BadgePosition.itemRight),
    muteIconConfig: const RCKMuteIconConfig(show: true),
    itemConfig: const RCKItemConfig(height: 72),
    layoutConfig: const RCKLayoutConfig(horizontalSpacing: 16),
    slidableConfig: RCKSlidableConfig(actions: [
      RCKSlidableActionConfig.pin(),
      RCKSlidableActionConfig.delete(),
    ]),
    listConfig: const RCKListConfig(showSearchBar: true, pageSize: 20),
  ),
)

需要完全自定义 UI 外观（如自定义 itemBuilder）时，请参考：会话列表 Builders

最后于 更新