From 0a5fc17e6a0ec385cc100dbd243cf5a996fdd1da Mon Sep 17 00:00:00 2001 From: lyswhut Date: Thu, 9 Nov 2023 10:54:22 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/desktop/custom-source.md | 41 ++++++++++++++++++++++++----------- docs/mobile/custom-source.md | 23 +++++++++++--------- docs/mobile/license.md | 2 +- 3 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/desktop/custom-source.md b/docs/desktop/custom-source.md index 53266631..9191a23e 100644 --- a/docs/desktop/custom-source.md +++ b/docs/desktop/custom-source.md @@ -51,7 +51,7 @@ const apis = { // info.type：音乐质量，可能的值有128k / 320k / flac / flac24bit（取决于初始化时对应源传入的qualitys值中的一个）， // info.musicInfo：音乐信息对象，里面有音乐ID、名字等信息 on(EVENT_NAMES.request, ({ source, action, info }) => { - // 回调必须返回 Promise 对象 + // 被调用时必须返回 Promise 对象 switch (action) { // action 为 musicUrl 时需要在 Promise 返回歌曲 url case 'musicUrl': @@ -63,8 +63,8 @@ on(EVENT_NAMES.request, ({ source, action, info }) => { }) // 脚本初始化完成后需要发送inited事件告知应用 +// 注意：初始化事件被发送前，执行脚本的过程中出现任何错误将视为脚本初始化失败 send(EVENT_NAMES.inited, { - status: true, // 初始化成功 or 失败 openDevTools: false, // 是否打开开发者工具，方便用于调试脚本 sources: { // 当前脚本支持的源 kw: { // 支持的源对象，可用key值：kw/kg/tx/wy/mg @@ -94,7 +94,7 @@ send(EVENT_NAMES.inited, { ``` - `@name `：源的名字，建议不要过长，24个字符以内 -- `@description `：源的描述，建议不要过长，36个字符以内，可不填，不填时必须保留 @description +- `@description `：源的描述，建议不要过长，36个字符以内，可不填，不填时可以删除 @description - `@version`：源的版本号，可不填，不填时可以删除 @version - `@author `：脚本作者名字，可不填，不填时可以删除 @author - `@homepage `：脚本主页，可不填，不填时可以删除 @homepage @@ -105,7 +105,22 @@ send(EVENT_NAMES.inited, { ### `globalThis.lx.version` -自定义源API版本，API变更时此版本号将会更改（新增于v1.14.0之后） +自定义源API版本，API变更时此版本号将会更改 + +### `globalThis.lx.env` + +自定义源运行环境，PC端将固定是 `desktop` + +### `globalThis.lx.currentScriptInfo` + +当前自定义源脚本信息（导入时在头部解析到的）： + +- `globalThis.lx.currentScriptInfo.name`：源名字，即 `@name` 的内容 +- `globalThis.lx.currentScriptInfo.description`：源描述，即 `@description` 的内容 +- `globalThis.lx.currentScriptInfo.version`：源版本，即 `@version` 的内容 +- `globalThis.lx.currentScriptInfo.author`：源作者，即 `@author` 的内容 +- `globalThis.lx.currentScriptInfo.homepage`：源主页，即 `@homepage` 的内容 +- `globalThis.lx.currentScriptInfo.rawScript`：源原始代码 ### `globalThis.lx.EVENT_NAMES` @@ -113,10 +128,11 @@ send(EVENT_NAMES.inited, { | 事件名 | 描述 | --- | --- -| `inited` | 脚本初始化完成后发送给应用的事件名，发送该事件时需要传入以下信息：`{status, sources, openDevTools}`
`status`：初始化结果（`true`成功，`false`失败）
`openDevTools`：是否打开DevTools，此选项可用于开发脚本时的调试
`sources`：支持的源信息对象，
`sources[kw/kg/tx/wy/mg].name`：源的名字（目前非必须）
`sources[kw/kg/tx/wy/mg].type`：源类型，目前固定值需为`music`
`sources[kw/kg/tx/wy/mg].actions`：支持的actions，由于目前只支持`musicUrl`，所以固定传`['musicUrl']`即可
`sources[kw/kg/tx/wy/mg].qualitys`：该源支持的音质列表，有效的值为`['128k', '320k', 'flac', 'flac24bit']`，该字段用于控制应用可用的音质类型 +| `inited` | 脚本初始化完成后发送给应用的事件名，发送该事件时需要传入以下信息：`{ sources, openDevTools }`
`openDevTools`：是否打开DevTools，此选项可用于开发脚本时的调试
`sources`：支持的源信息对象，
`sources[kw/kg/tx/wy/mg].name`：源的名字（目前非必须）
`sources[kw/kg/tx/wy/mg].type`：源类型，目前固定值需为`music`
`sources[kw/kg/tx/wy/mg].actions`：支持的actions，由于目前只支持`musicUrl`，所以固定传`['musicUrl']`即可
`sources[kw/kg/tx/wy/mg].qualitys`：该源支持的音质列表，有效的值为`['128k', '320k', 'flac', 'flac24bit']`，该字段用于控制应用可用的音质类型 | `request` | 应用API请求事件名，回调入参：`handler({ source, action, info})`，回调必须返回`Promise`对象
`source`：音乐源，可能的值取决于初始化时传入的`sources`对象的源key值
`info`：请求附加信息，内容根据`action`变化
`action`：请求操作类型，目前只有`musicUrl`，即获取音乐URL链接，需要在 Promise 返回歌曲 url，`info`的结构：`{type, musicInfo}`，`info.type`：音乐质量，可能的值有`128k` / `320k` / `flac` / `flac24bit`（取决于初始化时对应源传入的`qualitys`值中的一个），`info.musicInfo`：音乐信息对象，里面有音乐ID、名字等信息 -| `updateAlert` | 显示源更新弹窗，发送该事件时的参数：`{log, updateUrl}`
`log`：更新日志，必传，字符串类型，内容可以使用`\n`换行，最大长度1024，超过此长度后将被截取超出的部分
`updateUrl`：更新地址，用于引导用户去该地址更新源，选传，需为http协议的url地址，最大长度1024
此事件每次运行脚本只能调用一次（源版本v1.2.0新增）
例子：`lx.send(lx.EVENT_NAMES.updateAlert, { log: 'hello world', updateUrl: 'https://xxx.com' })` +| `updateAlert` | 显示源更新弹窗，发送该事件时的参数：`{log, updateUrl}`
`log`：更新日志，必传，字符串类型，内容可以使用`\n`换行，最大长度1024，超过此长度后将被截取超出的部分
`updateUrl`：更新地址，用于引导用户去该地址更新源，选传，需为http协议的url地址，最大长度1024
此事件每次运行脚本只能调用一次
例子：`lx.send(lx.EVENT_NAMES.updateAlert, { log: 'hello world', updateUrl: 'https://xxx.com' })` +**注意：初始化事件被发送前，执行脚本的过程中出现任何错误将视为脚本初始化失败** ### `globalThis.lx.on` @@ -125,12 +141,12 @@ send(EVENT_NAMES.inited, { ```js /** * @param event_name 事件名 - * @param handler 事件处理回调 -- 注意：注册的回调必须返回 Promise 对象 + * @param handler 事件处理回调 -- 注意：注册的回调在被调用时必须返回 Promise 对象 */ globalThis.lx.on(event_name, handler) ``` -**注意：** 注册的回调必须返回 `Promise` 对象。 +**注意：** 注册的回调在被调用时必须返回 `Promise` 对象。 ### `globalThis.lx.send` @@ -163,20 +179,19 @@ const cancelHttp = globalThis.lx.request(url, options, callback) 应用提供给脚本的工具方法： - `globalThis.lx.utils.buffer.from`：对应Node.js的 `Buffer.from` -- `globalThis.lx.utils.buffer.bufToString`：Buffer转字符串 `bufToString(buffer, format)`，`format`对应Node.js `Buffer.toString`的参数（v1.14.0之后新增） +- `globalThis.lx.utils.buffer.bufToString`：Buffer转字符串 `bufToString(buffer, format)`，`format`对应Node.js `Buffer.toString`的参数 - `globalThis.lx.utils.crypto.aesEncrypt`：AES加密 `aesEncrypt(buffer, mode, key, iv)` - `globalThis.lx.utils.crypto.md5`：MD5加密 `md5(str)` - `globalThis.lx.utils.crypto.randomBytes`：生成随机字符串 `randomBytes(size)` - `globalThis.lx.utils.crypto.rsaEncrypt`：RSA加密 `rsaEncrypt(buffer, key)` -- `globalThis.lx.utils.zlib.inflate`：解压 `inflate(buffer: Buffer) => Promise`（API版本v1.3.0新增） -- `globalThis.lx.utils.zlib.deflate`：压缩 `deflate(buffer: Buffer) => Promise`（API版本v1.3.0新增） +- `globalThis.lx.utils.zlib.inflate`：解压 `inflate(buffer: Buffer) => Promise` +- `globalThis.lx.utils.zlib.deflate`：压缩 `deflate(buffer: Buffer) => Promise` ### PC端自定义源与移动端自定义源的区别 -- 移动端 `init` 事件无 `openDevTools` 选项 +- 移动端 `inited` 事件无 `openDevTools` 选项 - 移动端 `lx.utils` 的某些方法不可用，对于不可用或部分可用的方法，背后会有括号说明 - 移动端只有极少部分宿主环境API可用，详情看 可用宿主环境API 说明 -- 移动端新增了 `lx.env` 与 `lx.currentScriptInfo` - 移动端由于预加载脚本与自定义脚本运行在同一个环境下，出于对预加载脚本的安全性考虑，除了 `Function.prototype.toString`、`Function.prototype.toLocaleString`、`Object.prototype.toString` 外的其他JavaScript内置属性都会被冻结，所以类似 `Array.prototype.push = ...` 的代码都将无效，但扩展内置对象的行为是允许的，例如：`Array.prototype.myPush = ...` 以上是自定义源功能在PC端与移动端的区别，目前仅提供以上工具方法，如果需要其他方法可以开issue讨论。 diff --git a/docs/mobile/custom-source.md b/docs/mobile/custom-source.md index 1b052044..86bbf991 100644 --- a/docs/mobile/custom-source.md +++ b/docs/mobile/custom-source.md @@ -53,7 +53,7 @@ const apis = { // info.type：音乐质量，可能的值有128k / 320k / flac / flac24bit（取决于初始化时对应源传入的qualitys值中的一个）， // info.musicInfo：音乐信息对象，里面有音乐ID、名字等信息 on(EVENT_NAMES.request, ({ source, action, info }) => { - // 回调必须返回 Promise 对象 + // 被调用时必须返回 Promise 对象 switch (action) { // action 为 musicUrl 时需要在 Promise 返回歌曲 url case 'musicUrl': @@ -65,8 +65,8 @@ on(EVENT_NAMES.request, ({ source, action, info }) => { }) // 脚本初始化完成后需要发送inited事件告知应用 +// 注意：初始化事件被发送前，执行脚本的过程中出现任何错误将视为脚本初始化失败 send(EVENT_NAMES.inited, { - status: true, // 初始化成功 or 失败 sources: { // 当前脚本支持的源 kw: { // 支持的源对象，可用key值：kw/kg/tx/wy/mg name: '酷我音乐', @@ -95,7 +95,7 @@ send(EVENT_NAMES.inited, { ``` - `@name `：源的名字，建议不要过长，24个字符以内 -- `@description `：源的描述，建议不要过长，36个字符以内，可不填，不填时必须保留 @description +- `@description `：源的描述，建议不要过长，36个字符以内，可不填，不填时可以删除 @description - `@version`：源的版本号，可不填，不填时可以删除 @version - `@author `：脚本作者名字，可不填，不填时可以删除 @author - `@homepage `：脚本主页，可不填，不填时可以删除 @homepage @@ -118,6 +118,10 @@ send(EVENT_NAMES.inited, { - `globalThis.lx.currentScriptInfo.name`：源名字，即 `@name` 的内容 - `globalThis.lx.currentScriptInfo.description`：源描述，即 `@description` 的内容 +- `globalThis.lx.currentScriptInfo.version`：源版本，即 `@version` 的内容 +- `globalThis.lx.currentScriptInfo.author`：源作者，即 `@author` 的内容 +- `globalThis.lx.currentScriptInfo.homepage`：源主页，即 `@homepage` 的内容 +- `globalThis.lx.currentScriptInfo.rawScript`：源原始代码 ### `globalThis.lx.EVENT_NAMES` @@ -125,10 +129,11 @@ send(EVENT_NAMES.inited, { | 事件名 | 描述 | --- | --- -| `inited` | 脚本初始化完成后发送给应用的事件名，发送该事件时需要传入以下信息：`{status, sources}`
`status`：初始化结果（`true`成功，`false`失败）
`sources`：支持的源信息对象，
`sources[kw/kg/tx/wy/mg].name`：源的名字（目前非必须）
`sources[kw/kg/tx/wy/mg].type`：源类型，目前固定值需为`music`
`sources[kw/kg/tx/wy/mg].actions`：支持的actions，由于目前只支持`musicUrl`，所以固定传`['musicUrl']`即可
`sources[kw/kg/tx/wy/mg].qualitys`：该源支持的音质列表，有效的值为`['128k', '320k', 'flac', 'flac24bit']`，该字段用于控制应用可用的音质类型 +| `inited` | 脚本初始化完成后发送给应用的事件名，发送该事件时需要传入以下信息：`{ sources }`
`sources`：支持的源信息对象，
`sources[kw/kg/tx/wy/mg].name`：源的名字（目前非必须）
`sources[kw/kg/tx/wy/mg].type`：源类型，目前固定值需为`music`
`sources[kw/kg/tx/wy/mg].actions`：支持的actions，由于目前只支持`musicUrl`，所以固定传`['musicUrl']`即可
`sources[kw/kg/tx/wy/mg].qualitys`：该源支持的音质列表，有效的值为`['128k', '320k', 'flac', 'flac24bit']`，该字段用于控制应用可用的音质类型 | `request` | 应用API请求事件名，回调入参：`handler({ source, action, info})`，回调必须返回`Promise`对象
`source`：音乐源，可能的值取决于初始化时传入的`sources`对象的源key值
`info`：请求附加信息，内容根据`action`变化
`action`：请求操作类型，目前只有`musicUrl`，即获取音乐URL链接，需要在 Promise 返回歌曲 url，`info`的结构：`{type, musicInfo}`，`info.type`：音乐质量，可能的值有`128k` / `320k` / `flac` / `flac24bit`（取决于初始化时对应源传入的`qualitys`值中的一个），`info.musicInfo`：音乐信息对象，里面有音乐ID、名字等信息 | `updateAlert` | 显示源更新弹窗，发送该事件时的参数：`{log, updateUrl}`
`log`：更新日志，必传，字符串类型，内容可以使用`\n`换行，最大长度1024，超过此长度后将被截取超出的部分
`updateUrl`：更新地址，用于引导用户去该地址更新源，选传，需为http协议的url地址，最大长度1024
此事件每次运行脚本只能调用一次（源版本v1.2.0新增）
例子：`lx.send(lx.EVENT_NAMES.updateAlert, { log: 'hello world', updateUrl: 'https://xxx.com' })` +**注意：初始化事件被发送前，执行脚本的过程中出现任何错误将视为脚本初始化失败** ### `globalThis.lx.on` @@ -137,12 +142,12 @@ send(EVENT_NAMES.inited, { ```js /** * @param event_name 事件名 - * @param handler 事件处理回调 -- 注意：注册的回调必须返回 Promise 对象 + * @param handler 事件处理回调 -- 注意：注册的回调被调用时必须返回 Promise 对象 */ globalThis.lx.on(event_name, handler) ``` -**注意：** 注册的回调必须返回 `Promise` 对象。 +**注意：** 注册的回调在被调用时必须返回 `Promise` 对象。 ### `globalThis.lx.send` @@ -185,15 +190,13 @@ const cancelHttp = globalThis.lx.request(url, options, callback) ### 可用宿主环境API -- `setTimeout` -- `window` （运行环境本身无`window`对象，但为了兼容PC端例子中读取`window`对象的写法，而将它映射到 `globalThis` 对象，所以实际上它指向的是运行环境的全局对象） +- `setTimeout` / `clearTimeout` ### 移动端自定义源与PC端自定义源的区别 -- 移动端 `init` 事件无 `openDevTools` 选项 +- 移动端 `inited` 事件无 `openDevTools` 选项 - 移动端 `lx.utils` 的某些方法不可用，对于不可用或部分可用的方法，背后会有括号说明 - 移动端只有极少部分宿主环境API可用，详情看 可用宿主环境API 说明 -- 移动端新增了 `lx.env` 与 `lx.currentScriptInfo` - 移动端由于预加载脚本与自定义脚本运行在同一个环境下，出于对预加载脚本的安全性考虑，除了 `Function.prototype.toString`、`Function.prototype.toLocaleString`、`Object.prototype.toString` 外的其他JavaScript内置属性都会被冻结，所以类似 `Array.prototype.push = ...` 的代码都将无效，但扩展内置对象的行为是允许的，例如：`Array.prototype.myPush = ...` 以上是自定义源功能在移动端与PC端的区别，目前仅提供以上工具方法及宿主API，如果需要其他方法可以开issue讨论。 diff --git a/docs/mobile/license.md b/docs/mobile/license.md index 3b278bf8..fc5a91a5 100644 --- a/docs/mobile/license.md +++ b/docs/mobile/license.md @@ -17,7 +17,7 @@ title: 许可协议 1.2 本项目本身没有获取某个音频数据的能力，本项目使用的在线音频数据来源来自软件设置内“音乐来源”设置所选择的“源”返回的在线链接。例如播放某首歌，本项目所做的只是将希望播放的歌曲名字、歌手名字等信息传递给“源”，若“源”返回了一个链接，则本项目将认为这就是该歌曲的音频数据而进行使用，至于这是不是正确的音频数据本项目无法校验其准确性，所以使用本项目的过程中可能会出现希望播放的音频与实际播放的音频不对应或者无法播放的问题。 -1.3 本项目内置的“试听接口”源的工作原理是尝试直接从对应官方平台公开服务器获取音频连接（与未登录状态在官方平台APP获取的歌曲链接相同），所以若某首歌若无法在处于未登录状态的官方平台APP播放，则理论上“试听接口”源也无法播放该歌曲。 +1.3 本项目内置的“试听接口”源的工作原理是尝试直接从对应官方平台公开服务器获取免费歌曲的音频连接（与未登录状态在官方平台APP获取的歌曲链接相同），所以若某首歌若无法在处于未登录状态的官方平台APP播放，则理论上“试听接口”源也无法播放该歌曲。 1.4 本项目的非官方平台数据（例如我的收藏列表）来自使用者本地系统或者使用者连接的同步服务，本项目不对这些数据的合法性、准确性负责。