ESFramework 开发手册（17） －－ 聊天消息渲染
本文介绍ESFramework （v7.2+）内置的聊天消息渲染器 -- ESFramework.Extensions.ChatRendering.IChatRender，使用它能让开发者轻松实现类似于微信聊天消息的渲染效果。
IChatRender 支持 Windows、Linux（包括国产OS）。在Windows平台上提供了基于 WinForm 和基于 WPF 的实现，Linux上则提供了基于Avalonia 和 基于CPF.NET 的实现。
IChatRender 的渲染Demo效果如下图所示（该Demo源码可于文末下载）：
一. 支持的聊天消息类型
IChatRender 支持渲染的聊天消息类型包括：
（01）文本表情混排。
（02）图片，GIF 动图。
（03）文件传输进度及控制。
（04）个人名片、群名片。
（05）引用消息。
（06）语音消息。
（07）语音通话。
（08）视频通话。
（09）撤回消息、删除消息。
（10）可扩展自定义消息类型。
二. IChatRender 接口定义
1. IChatRender 方法
/// <summary> /// 渲染名片 /// </summary> /// <param name="msgID">聊天记录ID</param> /// <param name="userID">发送者</param> /// <param name="cardUserID">名片上的个人ID</param> /// <param name="index">插入聊天记录的位置，默认是放到最后面</param> void AddChatItemCard(string msgID ,string userID, string cardUserID ,int? index = null); /// <summary> /// 渲染文件 /// </summary> /// <param name="fileName">文件名称</param> /// <param name="fileSize">文件大小</param> /// <param name="state">文件状态</param> void AddChatItemFile(string msgID, string userID, string fileName, ulong fileSize, FileTransState state, int? index = null); /// <summary> /// 渲染图片 /// </summary> /// <param name="image">图像</param> /// <param name="imgSize">图像大小</param> /// <param name="observerable">默认传null</param> void AddChatItemImage(string msgID, string userID, object image, Size imgSize ,IProgressObserverable observerable = null, int? index = null); /// <summary> /// 渲染文本表情 /// </summary> /// <param name="text">内容，在渲染文本的内容中用 [000]来代表第一个表情，[001]即是二个表情，以此类推</param> /// <param name="referenced">引用内容可以是文本、图片、文件或名片</param> /// <param name="textColor">文字颜色</param> void AddChatItemText(string msgID, string userID, string text, ReferencedChatMessage referenced = null, Color? textColor = null, int? index = null); /// <summary> /// 渲染悄悄话，默认显示内容—>> 悄悄话 /// </summary> void AddChatItemSnap(string msgID, string userID, int? index = null); /// <summary> /// 渲染语音消息 /// </summary> /// <param name="audioMessageSecs">语音时长</param> /// <param name="audioMessage">语音短信</param> void AddChatItemAudio(string msgID, string userID, int audioMessageSecs, object audioMessage, int? index = null); /// <summary> /// 渲染多媒体通话类型 /// </summary> /// <param name="duration">通话时长</param> /// <param name="isAudioCommunicate">通话类型(语音/视频)</param> void AddChatItemMedia(string msgID, string userID, string duration, bool isAudioCommunicate, int? index = null); /// <summary> /// 渲染系统消息 /// </summary> /// <param name="msg">系统消息内容</param> void AddChatItemSystemMessage(string msg, int? index = null); /// <summary> /// 渲染消息的发送时间 /// </summary> /// <param name="dt">发送时间</param> void AddChatItemTime(DateTime dt, int? index = null); /// <summary> /// 自己撤回消息 /// </summary> void RecallChatMessage(string msgID); /// <summary> /// 其他用户撤回消息 /// </summary> /// <param name="operatorName">操作者</param> void RecallChatMessage(string msgID ,string operatorName); /// <summary> /// 删除对应的记录 /// </summary> void RemoveChatMessage(string msgID);
2. IChatRender 事件
/// <summary> /// 当操作抛出异常时，触发此事件。 /// </summary> event Action<Exception> ExceptionOccured; /// <summary> /// 当名片被点击时，触发此事件。参数：MessageID - CardUserID /// </summary> event Action<string,string> CardClicked; /// <summary> /// 当悄悄话被点击时，触发此事件。参数：MessageID /// </summary> event Action<string> SnapClicked; /// <summary> /// 当悄悄话被点击时，触发此事件。参数：MessageID - Image /// </summary> event Action<string ,object> ImageClicked; /// <summary> /// 当某个语音消息被单击时，触发此事件。 参数：MessageID - AudioMessage /// </summary> event Action<string, object> AudioMessageClicked; /// <summary> /// 当某用户的头像被点击时，触发此事件。参数：UserID /// </summary> event Action<string> HeadImageClicked; /// <summary> /// 当多媒体消息被点击时，触发此事件。参数：UserID /// </summary> event Action<string> CommunicateClicked; /// <summary> /// 当需要显示聊天消息的右键菜单时，触发此事件。参数：Position - ChatMessageType - MessageID /// </summary> event Action<Point, ChatMessageType, string> ContextMenuCalled; /// <summary> /// 当需要显示头像的右键菜单时，触发此事件。参数：Position - UserID /// </summary> event Action<Point, string> HeadImageContextMenuCalled; /// <summary> /// 当ChatItem被点击时，触发此事件。参数：ChatMessageType - MessageID /// </summary> event Action<ChatMessageType, string> ChatItemClicked;
三. 创建 IChatRender 实例
可以通过调用ESFramework.Extensions.ChatRendering.ChatRenderFactory 的静态方法 CreateChatRender 创建一个 IChatRender 实例。
1.创建 ChatRender
/// <param name="provider">提供必要的信息给聊天渲染器</param> /// <param name="ctrl">要在其表面渲染的UI控件</param> /// <param name="myID">自己的ID</param> /// <param name="destID">对方ID、或群ID</param> /// <param name="isGroup">群聊/单聊</param> /// <returns></returns> public static IChatRender CreateChatRender(IRenderDataProvider provider, IChatControl ctrl, string myID, string destID, bool isGroup);
第一个参数 IRenderDataProvider 用于在 IChatRender 渲染时，能从该接口获取必要的信息（如用户的头像、名称、表情图片等）。
第二个参数 则是要在其表面进行渲染的UI控件。
2.IRenderDataProvider 接口
/// <summary> /// 实现该接口，以提供必要的信息给聊天消息渲染器。 /// </summary> public interface IRenderDataProvider { /// <summary> /// 获取发言人要显示的名称。 /// </summary> string GetSpeakerDisplayName(string speakerID); /// <summary> /// 获取用户的名称。 /// </summary> string GetUserName(string userID); /// <summary> /// 获取发言人要显示的头像。 /// </summary> object GetUserHeadImage(string userID); /// <summary> /// 根据文件的扩展名获取对应文件类型的图标。 /// </summary> object GetImageOfFileType(string fileExtendName); object GetImageOfSendFailed(); /// <summary> /// 获取视频通话图标。 /// </summary> object GetImageOfVideoCall(); /// <summary> /// 获取语音通话图标。 /// </summary> object GetImageOfAudioCall(); /// <summary> /// 当接收文件时，文件的存储路径。 /// </summary> /// <param name="fileName">要接收的文件名</param> string GetFilePathToSave(string fileName); /// <summary> /// 获取表情字典。key：表情编号，value：表情图片。 /// </summary> Dictionary<int, object> GetEmotions(); }
GetEmotions 方法返回的表情字典，其Key表示表情编号，是从零开始递增的。
五. 扩展自定义消息渲染
如果需要渲染自定义的消息，可以调用 IChatRender 的 AddChatItemCustomized 方法插入要渲染的自定义消息。
/// <summary> /// 插入要渲染的自定义消息。 /// </summary> void AddChatItemCustomized(IChatItem item, int? index = null);
自定义的消息可以从 BaseChatItem 继承，然后override复写其几个方法就可以了。具体可以参见文末demo源码中的自定义消息渲染的实现。
六. Demo 源码下载
ChatRenderDemo 源码链接 1： Linux 端（Avalonia） 源码
ChatRenderDemo 源码链接 2： Windows 端 + Linux 端（CPF.NET） 源码
源码2 的解决方案中包括三个项目：
（1）ChatRenderDemo.WPF： 该Demo的Windows端（基于WPF）。
（2）ChatRenderDemo.WinForm： 该Demo的Windows端（基于WinForm）。
（3）ChatRenderDemo.Linux： 该Demo的Linux客户端（基于.NetCore），支持在统信UOS、银河麒麟等国产OS上运行。
注：
（1）Linux 端内置的是x86/x64非托管so库，若需要其它架构的so，请联系我们免费获取。
（2）该Demo使用了 ESFramework.Boosts 扩展库，该扩展库的最新源码可 到此下载。
-----------------------------------------------------------------------------------------------------------------------------------------------
Q Q：168757008
