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 函数签名