docs: update development documentations (#211)

koishijs · Mar 25, 2024 · 07cfb38 · 07cfb38
1 parent 44c4d8f
commit 07cfb38
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 9 deletions.
diff --git a/docs/zh-CN/develop/api.md b/docs/zh-CN/develop/api.md
@@ -50,7 +50,6 @@ export abstract class ImageSource<Config extends ImageSource.Config = ImageSourc
 }
 ```
 
-
 ### `ImageSource.Query`
 
 ```ts
@@ -67,8 +66,16 @@ export interface Query {
 ```ts
 export type NsfwType = 'furry' | 'guro' | 'shota' | 'bl'
 
+export enum PreferSize {
+  Original = 'original',
+  Large = 'large',
+  Medium = 'medium',
+  Small = 'small',
+  Thumbnail = 'thumbnail',
+}
+
 export interface Result {
-  url: string
+  urls: Partial<Record<Exclude<PreferSize, 'original'>, string>> & { original: string }
   pageUrl?: string
   author?: string
   authorUrl?: string

diff --git a/docs/zh-CN/develop/service.md b/docs/zh-CN/develop/service.md
@@ -51,12 +51,19 @@ I miss You <br>
 
 `booru` 服务提供了 `register()` 方法，可以用于注册图源。
 
+:::warn
+如果你在开发图源插件，只需要继承 `ImageSource` 类，它会自动将自己注册到 `booru` 服务中。
+:::
+
+你也可以手动注册和注销图源，这在你需要动态注册图源时非常有用。
+
 ```ts
 import { Context } from 'koishi'
 
-class PixivSource extends ImageSource<Config> {
+class PixivSource {
   name = 'pixiv'
-  async get(query) {
+  languages = ['zh-CN', 'ja']
+  async get(query: ImageSource.Query): Promise<ImageSource.Result[]> {
     // ...
   }
 }

diff --git a/docs/zh-CN/develop/source.md b/docs/zh-CN/develop/source.md
@@ -15,7 +15,7 @@
 ```json
 {
   "peerDependencies": {
-    "booru": "^1.0.3"
+    "booru": "^1.2.0"
   }
 }
 ```
@@ -24,7 +24,7 @@
 
 ## 开发图源插件
 
-此处以简化版的 `lolicon` 插件为例，可以从 `https://api.lolicon.net/` 的 API 获取图片及元信息。
+此处以简化版的 `lolicon` 插件为例，可以从 `https://api.lolicon.net/` 的 API 获取图片及元信息。它的官方实现可以在 [这里](https://github.com/koishijs/koishi-plugin-booru/tree/main/packages/lolicon)。
 
 ```ts
 import { Context, Schema } from 'koishi'
@@ -63,10 +63,19 @@ class LoliconImageSource extends ImageSource<LoliconImageSource.Config> {
     }
 
     // 返回类型为 `Result` 的数组，可用字段可参考类型提示。
-    // 其中 `url` 字段是图片的地址，也可以是 `base64` 编码。
+    // 其中 `urls.*` 字段是图片的地址，也可以是 `base64` 编码。
+    // 其中 `original` 是必须字段，应当是原图尺寸的 URL。
+    // 另外还有 `large` (1200px) `medium` (600px) `small` (300px) `thumbnail` 等字段。
+    // 括号中为该尺寸的参考大小，如果图源不提供对应尺寸，可以忽略此字段。
     return resp.data.map((setu) => {
       return {
-        url: setu.urls.original,
+        urls: {
+          original: setu.urls.original,
+          large: setu.urls.regular,
+          medium: setu.urls.small,
+          small: setu.urls.thumb,
+          thumbnail: setu.urls.mini,
+        },
         title: setu.title,
         author: setu.author,
         nsfw: setu.r18,

diff --git a/packages/core/src/source.ts b/packages/core/src/source.ts
@@ -80,7 +80,7 @@ export namespace ImageSource {
   export interface Result {
     /** @deprecated Use `.urls.*` instead */
     url?: string
-    urls: Partial<Record<Exclude<PreferSize, 'origin'>, string>> & { original: string }
+    urls: Partial<Record<Exclude<PreferSize, 'original'>, string>> & { original: string }
     pageUrl?: string
     author?: string
     authorUrl?: string