前言
在做 Flutter for OpenHarmony 的社交或客服类应用时,除了 WebSocket 传输本身,如何规范定义'消息(Message)'的数据结构以及处理复杂的对话状态,往往决定了项目的后期维护性。bavard 是一个专为高度语义化聊天交互设计的协议封装库,它能让开发者在鸿蒙端以更具逻辑感的对象模型来驱动对话流。
核心原理
架构拆解
bavard 将一次完整的对话拆解为三个核心要素:'参与者(Participants)'、'话题(Topics)'和'原子消息(Discrete Messages)'。它内置了一套状态机,负责驱动从用户输入、机器人分析到流式回复的全过程。
graph TD
A["Hmos 用户 UI 输入"] -->|封装为 bavard Action| B["Bavard 核心处理器"]
B -->|路由至 Handler| C["机器人 / 服务端响应算子"]
C -->|生成 Response Packet| D["Bavard 消息流同步器"]
D -->|UI 模型映射| E["Hmos 聊天气泡显示"]
subgraph 核心特征
F["多角色支持 (User/Bot/Agent)"]
G["自定义负载 (Payload)"]
H["对话上下文保持"]
end
为什么选择它?
- 语义化强:代码读起来像是在描述业务过程(如
Chat.ask()对应Response.reply()),降低了新人的理解门槛。 - 状态感知:原生支持'正在输入'、'已读回执'等社交原语,省去了手动维护 Boolean 开关的麻烦。
- 扩展灵活:不仅支持纯文本,通过 Payload 还能轻松扩展定位卡片、商品链接或文件附件。
- 无 UI 束缚:纯 Dart 逻辑实现,你可以自由将其适配给鸿蒙 NEXT 的任意 UI 组件,无论是长列表还是瀑布流都能无缝对接。
鸿蒙基础适配
依赖配置
由于 bavard 属于逻辑层通信协议的抽象,无需额外安装系统级包。只需在 pubspec.yaml 中添加依赖:
dependencies:
bavard: ^1.0.0
配置完成后,建议将其作为'通讯中台(Messaging Middleware)',负责所有外部通讯数据的预处理和状态编排。
核心 API 概览
| 类名 | 说明 |
|---|---|
BavardClient | 消息客户端主实例,管理所有订阅的 Topic |
BavardParticipant | 定义参与者的身份(昵称、头像、角色等) |
BavardMessage | 核心消息体对象,可携带丰富的 Metadata |
onEvent | 用于监听对话中的关键动作反馈(如加入、退出事件) |
初始化示例
下面这段代码展示了如何在鸿蒙端侧创建一个会话并发送一条带元数据的测试消息。注意这里我们定义了系统的版本信息,方便后续调试。
import 'package:bavard/bavard.dart';
void startOpenHarmonySocialSession() {
final chat = BavardClient();
// 创建一个鸿蒙端侧的参与者
final user = BavardParticipant(
id: 'hmos_001',
name: 'OpenHarmony 专家',
);
// 发送一条带特定元数据的测试消息
chat.send(BavardMessage(
sender: user,
content: '你好,这是来自鸿蒙分布式设备的问候!',
metadata: {
'system': 'Hmos Next',
'version': '11.0.1',
},
));
print('鸿蒙对话流已成功初始化并介入');
}


