Update docs for Image, close #1940

This commit is contained in:
Him188 2022-03-21 13:04:24 +00:00
parent c76ec4209a
commit 91e3ebdd03

View File

@ -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.