mirai-core-api/net.mamoe.mirai.message.data/Image

Image

@Serializable(with = Image.Serializer::class)

interface Image : Message, MessageContent, CodableMessage

自定义表情 (收藏的表情) 和普通图片.

最推荐的存储方式是存储图片原文件, 每次发送图片时都使用文件上传. 在上传时服务器会根据其缓存情况回复已有的图片 ID 或要求客户端上传.

获取 Image 实例

根据 ID 构造图片

ID 格式查看 Image.imageId. 通过 ID 构造的图片若未存在于服务器中, 发送后在客户端将不能正常显示. 可通过 Image.isUploaded 检查图片是否存在于服务器. Image.isUploaded 需要除了 ID 以外其他参数, 如 width, size 等, 因此不建议通过 ID 构造图片, 而是使用 Builder 构建, 以提供详细参数.

使用 Image.fromId. 在 Kotlin, 也可以使用顶层函数 val image = Image("id").

在 Kotlin 通过 ID 构造图片

// 根据喜好选择
val image = Image.fromId("id")
val image2 = Image("id")

在 Java 通过 ID 构造图片

Image image = Image.fromId("id")

使用 Builder 构建图片

Image 提供 Builder 构建方式, 可以指定 width, height 等额外参数. 请尽可能提供这些参数以提升图片发送的成功率和 Image.isUploaded 的准确性.

上传图片资源获得 Image

使用 Contact.uploadImage, 将 ExternalResource 上传得到 Image.

也可以使用 ExternalResource.uploadAsImage 扩展.

发送图片消息

在获取实例后, 将图片元素连接到消息链即可发送. 图片可以与纯文本等其他 MessageContent 混合使用 (在同一消息链中).

下载图片

通过事件等方式获取到 Image 实例后, 使用 Image.queryUrl 查询得到图片的下载地址, 自行使用 HTTP 客户端下载.

其他查询

查询图片是否已存在于服务器

使用 Image.isUploaded. 当图片在服务器上存在时返回 true, 这意味着图片可以直接发送.

服务器通过 Image.md5 鉴别图片. 当图片已经存在于服务器时, Contact.uploadImage 会更快返回 (仍然需要进行网络请求), 不会上传图片数据.

检测图片 ID 合法性

使用 Image.IMAGE_ID_REGEX.

mirai 码支持

格式: [mirai:image:Image.imageId]

Types

AsStringSerializer

object AsStringSerializer : KSerializer<Image>

Builder

class Builder

Image 构建器.

FallbackSerializer

@MiraiInternalApi

open class FallbackSerializer(serialName: String) : KSerializer<Image>

Key

object Key : AbstractMessageKey<Image>

Serializer

object ~~Serializer~~ : KSerializer<Image>

Functions

appendMiraiCodeTo

@MiraiExperimentalApi

abstract fun appendMiraiCodeTo(builder: StringBuilder)

contentEquals

open fun contentEquals(another: String, ignoreCase: Boolean = false): Boolean

判断内容是否与 another 相等.

open fun contentEquals(another: Message, ignoreCase: Boolean = false): Boolean

判断内容是否与 another 相等即 this 与 another 的 contentToString 相等.

open fun contentEquals(another: Message, ignoreCase: Boolean = false, strict: Boolean = false): Boolean

判断内容是否与 another 相等即 this 与 another 的 contentToString 相等.

contentToString

abstract fun contentToString(): String

转为接近官方格式的字符串, 即 "内容". 如 At(member) + "test" 将转为 "@QQ test".

flash

inline fun Image.flash(): FlashImage

将普通图片转换为闪照.

followedBy

open fun followedBy(tail: Message): MessageChain

将 this 和 tail 连接.

isContentBlank

fun Message.isContentBlank(): Boolean

当消息内容为空白时返回 true.

isContentEmpty

fun Message.isContentEmpty(): Boolean

当消息内容为空时返回 true.

isUploaded

suspend fun Image.isUploaded(bot: Bot): Boolean

当图片在服务器上存在时返回 true, 这意味着图片可以直接发送给 contact.

plus

open operator fun plus(another: Array<out Message>): MessageChain

创建一个消息链, 将 another 连接到这个消息的尾部. 这不会改变本 Message, 而是会创建新的 MessageChain 实例. 返回的 MessageChain 实例的第一个元素为本 Message, 随后为按顺序的 another 中的元素.

open operator fun plus(another: CharSequence): MessageChain

open operator fun plus(another: String): MessageChain

@JvmName(name = "plusIterableString")

open operator fun plus(another: Iterable<String>): MessageChain

open operator fun plus(another: Iterable<Message>): MessageChain

open operator fun plus(another: Sequence<Message>): MessageChain

open operator fun plus(another: Message): MessageChain

open operator fun plus(another: MessageChain): MessageChain

open operator fun plus(another: SingleMessage): MessageChain

plus

suspend operator fun Message.plus(another: Flow<Message>): MessageChain

将 another 按顺序连接到这个消息的尾部.

queryUrl

suspend fun Image.queryUrl(): String

查询原图下载链接.

repeat

fun Message.repeat(count: Int): MessageChain

将此消息元素按顺序重复 count 次.

sendTo

inline suspend fun <C : Contact> Message.sendTo(contact: C): MessageReceipt<C>

将 this 发送给指定联系人

serializeToMiraiCode

open fun serializeToMiraiCode(): String

转换为 mirai 码.

serializeToMiraiCode

@JvmStatic

fun CodableMessage.serializeToMiraiCode(): String

转换得到 mirai 码.

times

operator fun Message.times(count: Int): MessageChain

将此消息元素按顺序重复 count 次.

toForwardMessage

@JvmOverloads

fun Message.toForwardMessage(sender: User, time: Int = currentTimeSeconds().toInt(), displayStrategy: ForwardMessage.DisplayStrategy = DisplayStrategy): ForwardMessage

@JvmOverloads

fun Message.toForwardMessage(senderId: Long, senderName: String, time: Int = currentTimeSeconds().toInt(), displayStrategy: ForwardMessage.DisplayStrategy = DisplayStrategy): ForwardMessage

转换为 ForwardMessage

toMessageChain

fun Message.toMessageChain(): MessageChain

toString

abstract override fun toString(): String

得到包含 mirai 消息元素代码的, 易读的字符串. 如 At(member) + "test" 将转为 "[mirai:at:qqId]test".

Properties

content

val Message.content: String

Message.contentToString 的捷径

height

abstract val height: Int

图片的高度 (px), 当无法获取时为 0

imageId

abstract val imageId: String

图片的 id.

imageType

abstract val imageType: ImageType

图片的类型, 当无法获取时为未知 ImageType.UNKNOWN

isEmoji

open val isEmoji: Boolean

判断该图片是否为 动画表情

md5

open val md5: ByteArray

图片文件 MD5. 可用于 isUploaded.

size

abstract val size: Long

图片的大小（字节）, 当无法获取时为 0. 可用于 isUploaded.

width

abstract val width: Int

图片的宽度 (px), 当无法获取时为 0