diff --git a/docs/plugin/caution.md b/docs/plugin/caution.md
index 2b57bca..2ee17fe 100644
--- a/docs/plugin/caution.md
+++ b/docs/plugin/caution.md
@@ -20,7 +20,7 @@ const f = async () => {
`PC` 版基本上没有语法不支持的情况。
## 网络请求
-在安卓端,网络请求默认会带一些headers,具体示例如下,其中前四项是固定值:
+在安卓端,网络请求默认会带一些 headers,具体示例如下,其中前四项是固定值:
```
accept: application/json, text/plain, */*
diff --git a/docs/plugin/protocol.md b/docs/plugin/protocol.md
index c7c4f4a..3d34e54 100644
--- a/docs/plugin/protocol.md
+++ b/docs/plugin/protocol.md
@@ -148,7 +148,7 @@ module.exports = {
### 插件版本号 (version)
-插件版本号,可省略,默认值:"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)
+
+此字段作为插件函数中 `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 {
isEnd?: boolean;
@@ -444,7 +468,7 @@ type search = (
| :-----: | :-----------------------------------------: | :--------------------------------------------------------------------- |
| `query` | `string` | 搜索的关键词 |
| `page` | `number` | 从 `1` 开始的页码 |
-| `type` | `"music" \| "album" \| "artist" \| "sheet"` | 搜索类型,取值为左侧四者之一;
含义依次为:歌曲、专辑、作者、歌单 |
+| `type` | `"music" \| "album" \| "artist" \| "sheet" \| "lyric"` | 搜索类型,取值为左侧五者之一;
含义依次为:歌曲、专辑、作者、歌单、歌词 |
- 返回值
@@ -452,7 +476,7 @@ type search = (
| 键名 | 类型 | 说明 |
| :-------------: | :-----------: | :---- |
| `isEnd` | `boolean` | 搜索是否结束;如果 `isEnd` 被置为 `true`,说明当前已经到达最后一页;
此值如果不传,默认为 `true` |
-| `data` | `IMediaItem[]` | `data`的类型和入参中的搜索类型 `type` 有关。
如果搜索类型是`music`,`data`的类型是 `IMusicItem[]`;
如果搜索类型是`album`,`data`的类型是 `IAlbumItem[]`;
如果搜索类型是`artist`,`data`的类型是 `IArtistItem[]`;
如果搜索类型是`sheet`,`data`的类型是 `IMusicSheetItem[]`; |
+| `data` | `IMediaItem[]` | `data`的类型和入参中的搜索类型 `type` 有关。
如果搜索类型是`music`,`data`的类型是 `IMusicItem[]`;
如果搜索类型是`album`,`data`的类型是 `IAlbumItem[]`;
如果搜索类型是`artist`,`data`的类型是 `IArtistItem[]`;
如果搜索类型是`sheet`,`data`的类型是 `IMusicSheetItem[]`;
如果搜索类型是`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 函数签名