feat: 补充 supportedSearchType

docs/plugin/caution.md

@@ -20,7 +20,7 @@ const f = async () => {
 `PC` 版基本上没有语法不支持的情况。
 
 ## 网络请求
-在安卓端，网络请求默认会带一些headers，具体示例如下，其中前四项是固定值：
+在安卓端，网络请求默认会带一些 headers，具体示例如下，其中前四项是固定值：
 
 ```
 accept: application/json, text/plain, */*

docs/plugin/protocol.md

@@ -148,7 +148,7 @@ module.exports = {
 
 ### 插件版本号 (version) <Badge type="tip" text="可选" />
 
-插件版本号，可省略，默认值："0.0.0"版本。
+插件版本号，可省略，默认值：`"0.0.0"` 版本。
 
 需要遵循 [samver 格式](https://samver.org/)，如果在 APP 内更新插件，会依靠此字段判断插件版本号，并决定是否更新插件。
 
@@ -354,7 +354,7 @@ module.exports = {
 
 在插件中，你可以在任意一个地方调用：
 
-````javascript
+```javascript
 
 function someFunc(){
   const userVariables = env.getUserVariables(); // 返回 { test1: "", test2: "" }
@@ -373,9 +373,31 @@ module.exports = {
 
   // ...其他字段
 };
+```
+:::
+
+### 支持的搜索类型 (supportedSearchType) <Badge type="tip" text="可选" />
+
+此字段作为插件函数中 `search` 方法的辅助字段，用来说明插件支持的搜索类型。
+
+该字段是一个数组，取值是 `search` 方法支持的所有搜索类型 (`type`)，即：`"music", "sheet", "album", "artist", "lyric"`。
 
+::: tip
+- 如果填写此字段，则软件会认为 `search` 方法仅支持此字段支持的搜索类型。
+
+- 如果不填此字段，则软件会认为 `search` 方法支持所有的搜索类型。
+:::
+
+::: details 🌰 举个例子：
+```javascript
+module.exports = {
+  supportedSearchType: ["music", "album", "sheet", "artist", "lyric"]
+  // ...其他字段
+};
+```
 :::
 
+
 ## 插件函数
 
 > 在开始之前，你也可以先看一下 [typescript 文档](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#functions) 关于函数类型的部分。
@@ -398,14 +420,16 @@ module.exports = {
 async function pluginMethod() {
   return "字符串";
 }
-````
+```
 
 ### 搜索 (search)
 
 搜索函数，可省略。当用户在 app 内点击搜索、下拉刷新、触达搜索底部时调用。
 
 ::: warning
-`search` 函数缺失时，该插件不会出现在软件的搜索结果页中。
+- `search` 函数缺失时，该插件不会出现在软件的搜索结果页中。
+
+- 当插件中定义【支持的搜索类型】 (即`supportedSearchType`字段) 时，`search` 函数将会仅处理 `supportedSearchType` 中定义的类型。
 :::
 
 ::: details 函数签名
@@ -417,7 +441,7 @@ type SupportMediaItem = {
     album: IAlbumItem;
     artist: IArtistItem;
     sheet: IMusicSheetItem;
-    lyric: IMusicItem
+    lyric: IMusicItem;
 };
 interface ISearchResult<T extends SupportMediaType> {
     isEnd?: boolean;
@@ -444,15 +468,15 @@ type search = <T extends SupportMediaType>(
 | :-----: | :-----------------------------------------: | :--------------------------------------------------------------------- |
 | `query` |                  `string`                   | 搜索的关键词                                                           |
 | `page`  |                  `number`                   | 从 `1` 开始的页码                                                      |
-| `type`  | `"music" \| "album" \| "artist" \| "sheet"` | 搜索类型，取值为左侧四者之一；<br/> 含义依次为：歌曲、专辑、作者、歌单 |
+| `type`  | `"music" \| "album" \| "artist" \| "sheet" \| "lyric"` | 搜索类型，取值为左侧五者之一；<br/> 含义依次为：歌曲、专辑、作者、歌单、歌词 |
 
 - 返回值
 
 返回值是个 `Promise` 对象，其内容键值类型如下：
 | 键名 | 类型 | 说明 |
 | :-------------: | :-----------: | :---- |
 | `isEnd` | `boolean` | 搜索是否结束；如果 `isEnd` 被置为 `true`，说明当前已经到达最后一页；<br />此值如果不传，默认为 `true` |
-| `data` | `IMediaItem[]` | `data`的类型和入参中的搜索类型 `type` 有关。<br/> 如果搜索类型是`music`，`data`的类型是 `IMusicItem[]`；<br /> 如果搜索类型是`album`，`data`的类型是 `IAlbumItem[]`；<br /> 如果搜索类型是`artist`，`data`的类型是 `IArtistItem[]`；<br /> 如果搜索类型是`sheet`，`data`的类型是 `IMusicSheetItem[]`； |
+| `data` | `IMediaItem[]` | `data`的类型和入参中的搜索类型 `type` 有关。<br/> 如果搜索类型是`music`，`data`的类型是 `IMusicItem[]`；<br /> 如果搜索类型是`album`，`data`的类型是 `IAlbumItem[]`；<br /> 如果搜索类型是`artist`，`data`的类型是 `IArtistItem[]`；<br /> 如果搜索类型是`sheet`，`data`的类型是 `IMusicSheetItem[]`；<br/> 如果搜索类型是`lyric`，`data`的类型是 `IMusicItem[]`； |
 
 ::: tip
 `data` 对象数组中，无论数组的元素为何种类型，均会自动为每一个元素添加 `platform` 属性，其值为插件名。
@@ -499,6 +523,13 @@ module.exports = {
         data: [], // ArtistItem 类型的数组
       };
     }
+    // 搜索歌词
+    else if (type === "lyric") {
+      return {
+        isEnd: true,
+        data: [], // MusicItem 类型的数组
+      };
+    }
   },
 };
 ```
@@ -645,7 +676,7 @@ module.exports = {
 
 ### 获取歌词 (getLyric)
 
-获取歌词，可省略。切换歌曲时会调用。
+获取歌词，可省略。切换歌曲时会调用；搜索的歌词也会调用此函数获取具体歌词内容。
 
 ::: details 函数签名