Skip to content

K
koishi-plugin-pics
Commit 86509ee5 authored by 迷子 (Maiko Tan)'s avatar 迷子 (Maiko Tan) Committed by GitHub
Browse files
Options

docs: renew readme

parent d010465c
Pipeline #11343 failed with stage
    in 4 minutes and 16 seconds
    Hide whitespace changes
    Inline Side-by-side
    Showing with 234 additions and 219 deletions
    CONTRIBUTING.md 0 → 100644
    View file @ 86509ee5
    ## 图源
    图源由其他 Koishi 插件提供。这些插件需要实现 `PicSource` 类，并使用 `ctx.pics.addSource(picSource, ctx)` 进行注入。
    ### 图源插件
    下面是一些开箱即用的图源。如果你希望你编写的图源插件在此处列出，欢迎提交 Pull Request 或发邮件给 `nanahira@momobako.com` 。
    * [`koishi-plugin-picsource-localfs`](https://github.com/koishijs/koishi-plugin-picsource-localfs) 本地文件图源。
    * [`koishi-plugin-picsource-lolicon`](https://github.com/koishijs/koishi-plugin-picsource-lolicon) [Lolicon](https://api.lolicon.app/ ) 图源。
    * [`koishi-plugin-picsource-heisi`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-heisi) 黑丝图源。
    * [`koishi-plugin-picsource-yande`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-yande) [Yande](https://yande.re/) 以及 [Konachan](https://konachan.com) 图源。
    ### 类定义
    图源插件推荐在 `package.json` 的 `keywords` 内写上 `required:pics` 以保证正确被 Koishi 插件市场搜索。
    ```ts
    export interface PicResult {
    // 图片 URL
    url: string;
    // 图片介绍，会一并出现在底部
    description?: string;
    }
    export class PicSource {
    // 构造函数传入 ctx 对象
    constructor(ctx: Context);
    // 图源的标签列表，使用 -s 参数匹配。
    tags: string[];
    // 图源权重，权重越大随机到的概率越大，默认 1
    weight: number;
    // 图源名称。
    name: string;
    // 图源介绍
    description: string;
    // 是否为默认图源。用户未指定参数时使用默认图源。
    isDefault: boolean;
    // 获取随机图片。 picTags 可能是空数组。
    randomPic(picTags: string[]): PicResult | Promise<PicResult>;
    // 图源启动时运行，可选
    onStartup(): Awaitable<void>;
    // 图源卸载时运行，可选
    onShutdown(): Awaitable<void>;
    }
    ```
    ### 插件示例
    #### 单图源
    ```ts
    import { Context } from "koishi";
    import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
    import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
    @RegisterSchema()
    export class Config extends PicSourceConfig {
    @SchemaProperty({ default: 10000 })
    code: number;
    }
    @DefinePlugin({ name: 'my-picsource', schema: Config })
    export default class MyPicSource extends PicSource implements LifecycleEvents {
    constructor(ctx: Context, config: Partial<Config>) {
    super(ctx);
    }
    @InjectConfig()
    private config: Config;
    @Inject(true)
    private pics: PicsContainer;
    async randomPic(tags: string[]) {
    return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
    }
    onApply() {
    this.config.applyTo(this);
    this.pics.addSource(this);
    }
    }
    ```
    #### 多图源
    ```ts
    import { Context } from "koishi";
    import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
    import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
    @RegisterSchema()
    export class InstanceConfig extends PicSourceConfig {
    @SchemaProperty({ default: 10000 })
    code: number;
    }
    @RegisterSchema()
    export class Config {
    constructor(config: Partial<InstanceConfig>[]) {}
    @SchemaProperty({ type: InstanceConfig })
    instances: InstanceConfig[];
    }
    export default class MyPicSourceInstance extends PicSource {
    constructor(ctx: Context, config: Partial<Config>) {
    super(ctx);
    config.applyTo(this);
    }
    async randomPic(tags: string[]) {
    return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
    }
    }
    @DefinePlugin({ name: 'my-picsource', schema: Config })
    export default class MyPicSource extends BasePlugin<Config> implements LifecycleEvents {
    @InjectConfig()
    private config: Config;
    @Inject(true)
    private pics: PicsContainer;
    onApply() {
    for (const instanceConfig of this.config.instances) {
    const instance = new MyPicSourceInstance(this.ctx, instanceConfig);
    this.pics.addSource(instance);
    }
    }
    }
    ```
    ### 开箱即用的 Schema 定义
    为了方便编写图源插件的配置部分，这里提供了一些开箱即用的配置文件 Schema 定义，可以从 `koishi-plugin-pics` 中导出。
    #### `PicSourceSchema`
    包含下列字段的 Schema 定义，方便创建图源插件的配置。
    ```ts
    export interface PicSourceInfo {
    // 图源的标签列表，使用 -s 参数匹配。
    tags: string[];
    // 图源权重，权重越大随机到的概率越大，默认 1
    weight: number;
    // 图源名称。
    name: string;
    // 图源介绍
    description: string;
    // 是否为默认图源。用户未指定参数时使用默认图源。
    isDefault: boolean;
    }
    ```
    同时 `PicSourceInfo` 也可以从 `koishi-plugin-pics` 中导出。
    #### `PicSourceConfig`
    [`schemastery-gen`](https://code.mycard.moe/3rdeye/schemastery-gen) 或 [`koishi-thirdeye`](https://code.mycard.moe/3rdeye/koishi-thirdeye) 用户可以使用 `PicSourceConfig` 类。插件的配置文件直接继承该类即可。
    > 继承 `PicSourceConfig` 的类需要手动使用 `@RegisterSchema()` 装饰器将自身注册为 Schema 定义。
    > `schemastery-gen` 包请**不要**使用 Webpack 打包。使用 Webpack 编写插件的用户请把该包列为 external 。
    ```ts
    export class PicSourceConfig {
    @SchemaProperty({ type: 'string', default: [], desc: '图源标签' })
    tags: string[];
    @SchemaProperty({ default: 1, desc: '图源权重' })
    weight: number;
    @SchemaProperty({ default: 1, desc: '图源名称', required: true })
    name: string;
    @SchemaProperty({ desc: '图源描述' })
    description?: string;
    @SchemaProperty({ desc: '是否为默认图源' })
    isDefault?: boolean;
    // 给目标对象注入上述对象。
    applyTo(target: PicSourceInfo) {
    target.tags ||= this.tags;
    target.weight ||= this.weight;
    target.name ||= this.name;
    target.description ||= this.description;
    target.isDefault = this.isDefault;
    }
    }
    ```
    \ No newline at end of file
    README.md
    View file @ 86509ee5
    ...@@ -4,14 +4,29 @@ Koishi 的随机图片插件 ...@@ -4,14 +4,29 @@ Koishi 的随机图片插件
    ## 安装 ## 安装
    ### npm 你可以选择通过 koishi 的插件市场安装本插件，也可以使用 npm 或 yarn 等包管理器安装。
    ### 插件市场
    如果你通过 koishi 的[模板项目](https://koishi.js.org/guide/introduction/template.html)创建了你的机器人项目，你可以直接从插件市场安装本插件。详情请参考[安装和配置插件](https://koishi.js.org/guide/introduction/template.html#%E5%AE%89%E8%A3%85%E5%92%8C%E9%85%8D%E7%BD%AE%E6%8F%92%E4%BB%B6)
    ### 包管理器
    推荐使用 yarn 安装插件，当然，也可以使用 npm 安装。
    ```bash ```bash
    # 如果你使用 yarn
    yarn add koishi-plugin-pics
    # 如果你使用 npm
    npm install koishi-plugin-pics npm install koishi-plugin-pics
    ``` ```
    ## 快速开始 ## 快速开始
    由于 pics 仅仅是一个随机图片的插件框架，你必须添加至少一个图源插件才能使用。此处以 [koishi-plugin-picsource-lolicon](https://npmjs.com/package/koishi-plugin-picsource-lolicon) 和 [koishi-plugin-picsource-yande](https://npmjs.com/package/koishi-plugin-picsource-yande) 为例，你可以在插件市场搜索相应的名字或者使用 yarn 直接安装。
    此外，在开始启动之前，你还需要添加一些配置，告诉 pics 插件有哪些图源插件可以使用，以及每个图源插件的配置。对于配置项的详细说明，请参考[配置](#配置)。
    ```yaml ```yaml
    # koishi.yml # koishi.yml
    plugins: plugins:
    ...@@ -92,24 +107,22 @@ pic.sources 查询全部的图源。 pic -s pixiv 查询含有 pixiv 标签的 ...@@ -92,24 +107,22 @@ pic.sources 查询全部的图源。 pic -s pixiv 查询含有 pixiv 标签的
    ## 配置 ## 配置
    koishi-plugin-pics 的配置仅有 `commandName` 一项，用于指定指令名称。 koishi-plugin-pics 的配置如下表所示：
    其余配置均在各图源中自定义。通常来说具有下面几个字段。 |:-:|:-:|:-:|:-:|
    |参数|类型|是否必选|描述|
    |commandName|string|否|指令名称，默认为 pic。|
    图源相关的配置由图源插件自定义，但 pics 插件会在其基础上添加以下几个字段：
    |:-:|:-:|:-:|:-:|
    |参数|类型|是否必选|描述|
    |name|string|是|图源名称|
    |tags|string[]|否|图源标签|
    |weight|number|否|图源权重，越大优先级越高|
    |description|string|否|图源的描述|
    |isDefault|boolean|否|是否默认图源，若设置为 false 或不设置，则需要通过 `-s` 选项指定图源才能调用|
    ```ts
    export interface PicSourceInfo {
    // 图源的标签列表，使用 -s 参数匹配。
    tags: string[];
    // 图源权重，权重越大随机到的概率越大，默认 1
    weight: number;
    // 图源名称。
    name: string;
    // 图源介绍
    description: string;
    // 是否为默认图源。用户未指定参数时使用默认图源。
    isDefault: boolean;
    }
    ```
    ```yaml ```yaml
    plugins: plugins:
    ...@@ -166,209 +179,9 @@ plugins: ...@@ -166,209 +179,9 @@ plugins:
    useOriginal: true useOriginal: true
    ``` ```
    ## 图源 ## 作为 koishi 服务提供接口
    图源由其他 Koishi 插件提供。这些插件需要实现 `PicSource` 类，并使用 `ctx.pics.addSource(picSource, ctx)` 进行注入。
    ### 图源插件
    下面是一些开箱即用的图源。如果你希望你编写的图源插件在此处列出，欢迎提交 Pull Request 或发邮件给 `nanahira@momobako.com` 。
    * [`koishi-plugin-picsource-localfs`](https://github.com/koishijs/koishi-plugin-picsource-localfs) 本地文件图源。
    * [`koishi-plugin-picsource-lolicon`](https://github.com/koishijs/koishi-plugin-picsource-lolicon) [Lolicon](https://api.lolicon.app/ ) 图源。
    * [`koishi-plugin-picsource-heisi`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-heisi) 黑丝图源。
    * [`koishi-plugin-picsource-yande`](https://code.mycard.moe/3rdeye/koishi-plugin-picsource-yande) [Yande](https://yande.re/) 以及 [Konachan](https://konachan.com) 图源。
    ### 类定义
    图源插件推荐在 `package.json` 的 `keywords` 内写上 `required:pics` 以保证正确被 Koishi 插件市场搜索。
    ```ts
    export interface PicResult {
    // 图片 URL
    url: string;
    // 图片介绍，会一并出现在底部
    description?: string;
    }
    export class PicSource {
    // 构造函数传入 ctx 对象
    constructor(ctx: Context);
    // 图源的标签列表，使用 -s 参数匹配。
    tags: string[];
    // 图源权重，权重越大随机到的概率越大，默认 1
    weight: number;
    // 图源名称。
    name: string;
    // 图源介绍
    description: string;
    // 是否为默认图源。用户未指定参数时使用默认图源。
    isDefault: boolean;
    // 获取随机图片。 picTags 可能是空数组。
    randomPic(picTags: string[]): PicResult | Promise<PicResult>;
    // 图源启动时运行，可选
    onStartup(): Awaitable<void>;
    // 图源卸载时运行，可选
    onShutdown(): Awaitable<void>;
    }
    ```
    ### 插件示例
    #### 单图源
    ```ts
    import { Context } from "koishi";
    import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
    import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
    @RegisterSchema()
    export class Config extends PicSourceConfig {
    @SchemaProperty({ default: 10000 })
    code: number;
    }
    @DefinePlugin({ name: 'my-picsource', schema: Config })
    export default class MyPicSource extends PicSource implements LifecycleEvents {
    constructor(ctx: Context, config: Partial<Config>) {
    super(ctx);
    }
    @InjectConfig()
    private config: Config;
    @Inject(true)
    private pics: PicsContainer;
    async randomPic(tags: string[]) {
    return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
    }
    onApply() {
    this.config.applyTo(this);
    this.pics.addSource(this);
    }
    }
    ```
    #### 多图源 `pics` 导出 `PicsContainer` 类作为 koishi 的服务，因此你可以在其他插件中通过 `ctx.pics` 访问其接口。例如，当你需要随机图片时，可以调用 `ctx.pics.randomPic()` 方法获取。
    ```ts
    import { Context } from "koishi";
    import { DefinePlugin, RegisterSchema, SchemaProperty, LifecycleEvents } from "koishi-thirdeye";
    import { PicSource, PicsContainer, PicSourceConfig } from "koishi-plugin-pics";
    @RegisterSchema()
    export class InstanceConfig extends PicSourceConfig {
    @SchemaProperty({ default: 10000 })
    code: number;
    }
    @RegisterSchema()
    export class Config {
    constructor(config: Partial<InstanceConfig>[]) {}
    @SchemaProperty({ type: InstanceConfig })
    instances: InstanceConfig[];
    }
    export default class MyPicSourceInstance extends PicSource {
    constructor(ctx: Context, config: Partial<Config>) {
    super(ctx);
    config.applyTo(this);
    }
    async randomPic(tags: string[]) {
    return { url: `https://cdn02.moecube.com:444/images/ygopro-images-zh-CN/${this.config.code}.jpg`, description: `${this.config.code}` };
    }
    }
    @DefinePlugin({ name: 'my-picsource', schema: Config })
    export default class MyPicSource extends BasePlugin<Config> implements LifecycleEvents {
    @InjectConfig()
    private config: Config;
    @Inject(true)
    private pics: PicsContainer;
    onApply() {
    for (const instanceConfig of this.config.instances) {
    const instance = new MyPicSourceInstance(this.ctx, instanceConfig);
    this.pics.addSource(instance);
    }
    }
    }
    ```
    ### 开箱即用的 Schema 定义
    为了方便编写图源插件的配置部分，这里提供了一些开箱即用的配置文件 Schema 定义，可以从 `koishi-plugin-pics` 中导出。
    #### `PicSourceSchema`
    包含下列字段的 Schema 定义，方便创建图源插件的配置。
    ```ts
    export interface PicSourceInfo {
    // 图源的标签列表，使用 -s 参数匹配。
    tags: string[];
    // 图源权重，权重越大随机到的概率越大，默认 1
    weight: number;
    // 图源名称。
    name: string;
    // 图源介绍
    description: string;
    // 是否为默认图源。用户未指定参数时使用默认图源。
    isDefault: boolean;
    }
    ```
    同时 `PicSourceInfo` 也可以从 `koishi-plugin-pics` 中导出。
    #### `PicSourceConfig`
    [`schemastery-gen`](https://code.mycard.moe/3rdeye/schemastery-gen) 或 [`koishi-thirdeye`](https://code.mycard.moe/3rdeye/koishi-thirdeye) 用户可以使用 `PicSourceConfig` 类。插件的配置文件直接继承该类即可。
    > 继承 `PicSourceConfig` 的类需要手动使用 `@RegisterSchema()` 装饰器将自身注册为 Schema 定义。
    > `schemastery-gen` 包请**不要**使用 Webpack 打包。使用 Webpack 编写插件的用户请把该包列为 external 。
    ```ts
    export class PicSourceConfig {
    @SchemaProperty({ type: 'string', default: [], desc: '图源标签' })
    tags: string[];
    @SchemaProperty({ default: 1, desc: '图源权重' })
    weight: number;
    @SchemaProperty({ default: 1, desc: '图源名称', required: true })
    name: string;
    @SchemaProperty({ desc: '图源描述' })
    description?: string;
    @SchemaProperty({ desc: '是否为默认图源' })
    isDefault?: boolean;
    // 给目标对象注入上述对象。
    applyTo(target: PicSourceInfo) {
    target.tags ||= this.tags;
    target.weight ||= this.weight;
    target.name ||= this.name;
    target.description ||= this.description;
    target.isDefault = this.isDefault;
    }
    }
    ```
    ## 提供服务
    `pics` 也作为服务导出。对于其他插件需要使用随机图片的场景，可以使用 `ctx.pics.randomPic()` 方法来获取随机图片。
    > 若不希望注册随机图片指令，可以使用 `ctx.never().plugin('koishi-plugin-pics')` 来禁用指令注册。 > 若不希望注册随机图片指令，可以使用 `ctx.never().plugin('koishi-plugin-pics')` 来禁用指令注册。
    ...@@ -396,3 +209,6 @@ export default class SomePlugin { ...@@ -396,3 +209,6 @@ export default class SomePlugin {
    } }
    } }
    ``` ```
    ## 贡献代码
    如果你想要向本插件贡献代码，或开发新的图源插件，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
    Markdown is supported
    0% or
    You are about to add 0 people to the discussion. Proceed with caution.
    Finish editing this message first!
    Please register or to comment