puniyu_element

消息元素处理库

概述

puniyu_element 是 puniyu 项目中用于处理各种消息元素的核心库。它提供了对文本、图片、文件、语音、视频、表情、@提醒、回复等消息元素的统一抽象和处理能力，支持序列化/反序列化以及原始格式转换。

核心组件

元素类型 (ElementType)

枚举定义了所有支持的消息元素类型：

At: @提醒元素
Reply: 回复元素
Text: 文本元素
Image: 图片元素
File: 文件元素
Record: 语音元素
Video: 视频元素
Face: 表情元素
Json: JSON 数据元素
Xml: XML 数据元素

元素结构体

每种元素类型都有对应的结构体：

AtElement: @提醒元素
- target_id: 目标用户ID
- name: 目标用户名（可选）
- 支持判断是否为@全体成员
FaceElement: 表情元素
- id: 表情ID
FileElement: 文件元素
- file: 文件路径/URL/base64
- file_id: 文件ID
- file_size: 文件大小
- file_name: 文件名
ImageElement: 图片元素
- file: 图片路径/URL/base64
- is_flash: 是否为闪照
- summary: 图片外显文本（可选）
JsonElement: JSON元素
- data: JSON数据
VideoElement: 视频元素
- file: 视频路径/URL/base64
- file_name: 视频文件名
RecordElement: 语音元素
- file: 语音路径/URL/base64
ReplyElement: 回复元素
- message_id: 回复的消息ID
TextElement: 文本元素
- text: 文本内容
XmlElement: XML元素
- data: XML数据

Elements 枚举

统一包装所有元素类型的枚举，包含所有具体元素类型，提供：

as_text(): 提取文本内容（如果是文本元素）
raw(): 转换为原始格式字符串

Message 结构体

表示完整消息，包含多个 Segment:

支持从 Vec<Segment>、单个 Segment 或字符串转换
实现 RawMessage trait

Segment 结构体(适配器使用的)

消息段结构，包含：

r#type: 元素类型
data: 元素数据（JSON格式）

Traits

RawMessage

提供 raw() 方法，将元素转换为原始格式字符串。

TextMessage

提供 text() 方法，提取文本内容。

便捷宏

element! 宏

用于快速创建各种元素：

// 文本元素
let text = element!(text, "Hello World");

// 图片元素
let image = element!(image, "http://example.com/image.jpg");

// @元素
let at = element!(at, "123456");

// @全体成员
let at_all = element!(at_all);

// 表情元素
let face = element!(face, 123);

// 回复元素
let reply = element!(reply, "message_id");

// 语音元素
let record = element!(record, "http://example.com/record.mp3");

// 文件元素
let file = element!(file, "http://example.com/file.pdf", "file_id", 1024, "document.pdf");

// 视频元素
let video = element!(video, "http://example.com/video.mp4", "video.mp4");

// JSON元素
let json = element!(json, r#"{"key": "value"}"#);

// XML元素
let xml = element!(xml, r#"<root>data</root>"#);

segment! 宏

用于快速创建消息段：

// 文本段
let text_segment = segment!(text, "Hello");

// @段
let at_segment = segment!(at, "123456");

使用示例

use puniyu_element::{element, Elements, Message, Segment};
use puniyu_element::ElementType;

// 创建文本元素
let text_element = element!(text, "Hello World");

// 创建包含多个元素的消息
let elements = vec![
    element!(text, "Hello "),
    element!(at, "123456"),
    element!(text, " Welcome!")
];

// 转换为消息
let message: Message = elements.into();

// 转换为原始格式
let raw_message = message.raw();

许可证

本项目采用 LGPL 许可证。

puniyu_element 0.1.1