mirror of
https://github.com/mamoe/mirai.git
synced 2025-03-05 00:10:13 +08:00
Update docs for Image, close #1940
This commit is contained in:
parent
c76ec4209a
commit
91e3ebdd03
@ -29,15 +29,16 @@ import net.mamoe.mirai.Bot
|
||||
import net.mamoe.mirai.IMirai
|
||||
import net.mamoe.mirai.Mirai
|
||||
import net.mamoe.mirai.contact.Contact
|
||||
import net.mamoe.mirai.contact.Contact.Companion.sendImage
|
||||
import net.mamoe.mirai.contact.Contact.Companion.uploadImage
|
||||
import net.mamoe.mirai.event.events.MessageEvent
|
||||
import net.mamoe.mirai.message.code.CodableMessage
|
||||
import net.mamoe.mirai.message.data.Image.Builder
|
||||
import net.mamoe.mirai.message.data.Image.Key.IMAGE_ID_REGEX
|
||||
import net.mamoe.mirai.message.data.Image.Key.IMAGE_RESOURCE_ID_REGEX_1
|
||||
import net.mamoe.mirai.message.data.Image.Key.IMAGE_RESOURCE_ID_REGEX_2
|
||||
import net.mamoe.mirai.message.data.Image.Key.isUploaded
|
||||
import net.mamoe.mirai.message.data.Image.Key.queryUrl
|
||||
import net.mamoe.mirai.utils.*
|
||||
import net.mamoe.mirai.utils.ExternalResource.Companion.sendAsImageTo
|
||||
import net.mamoe.mirai.utils.ExternalResource.Companion.uploadAsImage
|
||||
|
||||
/**
|
||||
@ -45,22 +46,58 @@ import net.mamoe.mirai.utils.ExternalResource.Companion.uploadAsImage
|
||||
*
|
||||
*
|
||||
* 最推荐的存储方式是存储图片原文件, 每次发送图片时都使用文件上传.
|
||||
* 在上传时服务器会根据其缓存情况回复已有的图片 ID 或要求客户端上传. 详见 [Contact.uploadImage]
|
||||
* 在上传时服务器会根据其缓存情况回复已有的图片 ID 或要求客户端上传.
|
||||
*
|
||||
* ### 根据 ID 构造图片
|
||||
* - [Image.fromId]. 在 Kotlin, 更推荐使用顶层函数 `val image = Image("id")`
|
||||
* # 获取 [Image] 实例
|
||||
*
|
||||
* ### 上传和发送图片
|
||||
* - [Contact.uploadImage] 上传 [资源文件][ExternalResource] 并得到 [Image] 消息
|
||||
* - [Contact.sendImage] 上传 [资源文件][ExternalResource] 并发送返回的 [Image] 作为一条消息
|
||||
* ## 根据 ID 构造图片
|
||||
*
|
||||
* - [ExternalResource.uploadAsImage]
|
||||
* - [ExternalResource.sendAsImageTo]
|
||||
* - [Contact.sendImage]
|
||||
* ID 格式查看 [Image.imageId]. 通过 ID 构造的图片若未存在于服务器中, 发送后在客户端将不能正常显示. 可通过 [Image.isUploaded] 检查图片是否存在于服务器.
|
||||
* [Image.isUploaded] 需要除了 ID 以外其他参数, 如 [width], [size] 等, 因此不建议通过 ID 构造图片, 而是使用 [Builder] 构建, 以提供详细参数.
|
||||
*
|
||||
* ### 下载图片
|
||||
* - [Image.queryUrl] 扩展函数. 查询图片下载链接
|
||||
* - [IMirai.queryImageUrl] 查询图片下载链接 (Java 使用)
|
||||
* 使用 [Image.fromId]. 在 Kotlin, 也可以使用顶层函数 `val image = Image("id")`.
|
||||
*
|
||||
* ### 在 Kotlin 通过 ID 构造图片
|
||||
* ```
|
||||
* // 根据喜好选择
|
||||
* val image = Image.fromId("id")
|
||||
* val image2 = Image("id")
|
||||
* ```
|
||||
*
|
||||
* ### 在 Java 通过 ID 构造图片
|
||||
* ```java
|
||||
* Image image = Image.fromId("id")
|
||||
* ```
|
||||
*
|
||||
* ## 使用 [Builder] 构建图片
|
||||
*
|
||||
* [Image] 提供 [Builder] 构建方式, 可以指定 [width], [height] 等额外参数. 请尽可能提供这些参数以提升图片发送的成功率和 [Image.isUploaded] 的准确性.
|
||||
*
|
||||
* ## 上传图片资源获得 [Image]
|
||||
*
|
||||
* 使用 [Contact.uploadImage], 将 [ExternalResource] 上传得到 [Image].
|
||||
*
|
||||
* 也可以使用 [ExternalResource.uploadAsImage] 扩展.
|
||||
*
|
||||
* # 发送图片消息
|
||||
*
|
||||
* 在获取实例后, 将图片元素连接到[消息链][MessageChain]即可发送. 图片可以与[纯文本][PlainText]等其他 [MessageContent] 混合使用 (在同一[消息链][MessageChain]中).
|
||||
*
|
||||
* # 下载图片
|
||||
*
|
||||
* 通过[事件][MessageEvent]等方式获取到 [Image] 实例后, 使用 [Image.queryUrl] 查询得到图片的下载地址, 自行使用 HTTP 客户端下载.
|
||||
*
|
||||
* # 其他查询
|
||||
*
|
||||
* ## 查询图片是否已存在于服务器
|
||||
*
|
||||
* 使用 [Image.isUploaded]. 当图片在服务器上存在时返回 `true`, 这意味着图片可以直接发送.
|
||||
*
|
||||
* 服务器通过 [Image.md5] 鉴别图片. 当图片已经存在于服务器时, [Contact.uploadImage] 会更快返回 (仍然需要进行网络请求), 不会上传图片数据.
|
||||
*
|
||||
* ## 检测图片 ID 合法性
|
||||
*
|
||||
* 使用 [Image.IMAGE_ID_REGEX].
|
||||
*
|
||||
* ## mirai 码支持
|
||||
* 格式: [mirai:image:*[Image.imageId]*]
|
||||
@ -71,7 +108,6 @@ import net.mamoe.mirai.utils.ExternalResource.Companion.uploadAsImage
|
||||
@Serializable(Image.Serializer::class)
|
||||
@NotStableForInheritance
|
||||
public interface Image : Message, MessageContent, CodableMessage {
|
||||
|
||||
/**
|
||||
* 图片的 id.
|
||||
*
|
||||
@ -376,6 +412,7 @@ public enum class ImageType(
|
||||
BMP("bmp"),
|
||||
JPG("jpg"),
|
||||
GIF("gif"),
|
||||
|
||||
//WEBP, //Unsupported by pc client
|
||||
APNG("png"),
|
||||
UNKNOWN("gif"); // bad design, should use `null` to represent unknown, but we cannot change it anymore.
|
||||
|
Loading…
Reference in New Issue
Block a user