@songloft/client-sdk 2.12.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +99 -0
- package/dist/index.cjs +75 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +133 -0
- package/dist/index.d.ts +133 -0
- package/dist/index.js +48 -0
- package/dist/index.js.map +1 -0
- package/package.json +49 -0
package/README.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# @songloft/client-sdk
|
|
2
|
+
|
|
3
|
+
Songloft **客户端 SDK**:让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力——改写正在播放队列、控制播放、订阅播放状态等。
|
|
4
|
+
|
|
5
|
+
> 与 [`@songloft/plugin-sdk`](../plugin-sdk) 的区别:`plugin-sdk` 面向**服务端 QuickJS 运行时**(`songloft.*` 全局,跑在后端);本包面向**客户端 webview 页面**(`window.SongloftPlugin.*`,跑在 Flutter 客户端里打开的插件网页中)。
|
|
6
|
+
|
|
7
|
+
## 适用范围
|
|
8
|
+
|
|
9
|
+
- ✅ **Songloft Flutter 客户端**(Android / iOS / macOS / Windows / Linux)的 webview 中打开的插件页面
|
|
10
|
+
- ✅ **Web 端「Tab 内嵌插件页」**(宿主 iframe,走 postMessage 桥接)
|
|
11
|
+
- ❌ **Web 端「全屏插件页」**(在新浏览器标签独立打开,无宿主父窗口)—— `isClient()` 返回 `false`
|
|
12
|
+
- ❌ 服务端 QuickJS 运行时(用 `@songloft/plugin-sdk`)
|
|
13
|
+
|
|
14
|
+
> 无论走哪条链路,调用前都请用 `isClient()` / `host.isAvailable()` 先检测——不可用时调用会抛错。
|
|
15
|
+
|
|
16
|
+
运行时能力由宿主客户端注入到 `window.SongloftPlugin`。本包是**类型层 + 便捷封装**:所有调用都委托注入的全局对象,不含独立运行时。因此新能力可能受客户端版本限制,请在 `plugin.json` 设置合适的 `minHostVersion`,并用 `host.getInfo().capabilities` 做能力协商。
|
|
17
|
+
|
|
18
|
+
## 安装
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @songloft/client-sdk
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## 用法
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { player, host, isClient } from '@songloft/client-sdk';
|
|
28
|
+
|
|
29
|
+
// 调用前先 feature-detect
|
|
30
|
+
if (isClient()) {
|
|
31
|
+
// 用歌曲 id 替换正在播放队列并从第 0 首开始播
|
|
32
|
+
await player.setQueue([101, 102, 103], { startIndex: 0 });
|
|
33
|
+
|
|
34
|
+
// 追加到队列末尾(不打断当前播放)
|
|
35
|
+
await player.addToQueue([104]);
|
|
36
|
+
|
|
37
|
+
// 读取当前状态
|
|
38
|
+
const state = await player.getState();
|
|
39
|
+
console.log(state.current_song?.title, state.is_playing);
|
|
40
|
+
|
|
41
|
+
// 订阅播放状态变更(返回取消订阅函数)
|
|
42
|
+
const off = player.onStateChange((s) => {
|
|
43
|
+
console.log('当前第', s.current_index, '首');
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
// 能力协商
|
|
47
|
+
const info = await host.getInfo();
|
|
48
|
+
if (info.capabilities.includes('player')) {
|
|
49
|
+
/* ... */
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
> 歌曲以 **id** 传入(宿主权威)。插件通过服务端 `songs.create` 创建的远程歌曲已持久化、带 id,可直接入队。
|
|
55
|
+
|
|
56
|
+
免构建的 vanilla 插件也可直接用注入的全局对象(无需引入本包,仅少了类型提示):
|
|
57
|
+
|
|
58
|
+
```html
|
|
59
|
+
<script>
|
|
60
|
+
window.SongloftPlugin.player.setQueue([101, 102]);
|
|
61
|
+
</script>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## API
|
|
65
|
+
|
|
66
|
+
### `isClient(): boolean`
|
|
67
|
+
|
|
68
|
+
同步检测当前是否运行在支持原生桥接的 Songloft 客户端 webview 内。
|
|
69
|
+
|
|
70
|
+
### `host`
|
|
71
|
+
|
|
72
|
+
- `host.isAvailable(): boolean` —— 同 `isClient()`
|
|
73
|
+
- `host.getInfo(): Promise<HostInfo>` —— 宿主版本 / 平台 / 能力列表
|
|
74
|
+
|
|
75
|
+
### `player`
|
|
76
|
+
|
|
77
|
+
| 方法 | 说明 |
|
|
78
|
+
|------|------|
|
|
79
|
+
| `getState()` | 获取播放器状态快照 |
|
|
80
|
+
| `setQueue(ids, { startIndex?, sourcePlaylistId? })` | 替换整个队列并播放 |
|
|
81
|
+
| `addToQueue(ids)` | 追加到队列末尾(去重,不播放) |
|
|
82
|
+
| `insertToQueue(index, id)` | 指定位置插入(不播放) |
|
|
83
|
+
| `removeFromQueue(index)` | 移除指定下标 |
|
|
84
|
+
| `reorderQueue(oldIndex, newIndex)` | 重排 |
|
|
85
|
+
| `clearQueue()` | 清空 |
|
|
86
|
+
| `play(id?)` | 播放指定歌曲 / 恢复播放 |
|
|
87
|
+
| `pause()` / `togglePlay()` | 暂停 / 切换 |
|
|
88
|
+
| `next()` / `prev()` | 下一首 / 上一首 |
|
|
89
|
+
| `seek(seconds)` | 跳转进度 |
|
|
90
|
+
| `setVolume(0-100)` | 音量 |
|
|
91
|
+
| `setPlayMode(mode)` | `order`/`loop`/`single`/`random`/`singlePlay` |
|
|
92
|
+
| `playPlaylistById(id)` | 直接播放服务端歌单 |
|
|
93
|
+
| `onStateChange(cb)` | 订阅状态变更,返回取消订阅函数 |
|
|
94
|
+
|
|
95
|
+
完整类型见包内 `.d.ts`(`ClientSong` / `ClientPlayerState` / `HostInfo` / `PlayMode` 等)。
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
Apache-2.0
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/index.ts
|
|
21
|
+
var index_exports = {};
|
|
22
|
+
__export(index_exports, {
|
|
23
|
+
host: () => host,
|
|
24
|
+
isClient: () => isClient,
|
|
25
|
+
player: () => player
|
|
26
|
+
});
|
|
27
|
+
module.exports = __toCommonJS(index_exports);
|
|
28
|
+
var NOT_AVAILABLE_MSG = "[@songloft/client-sdk] \u5BBF\u4E3B\u5BA2\u6237\u7AEF\u6865\u63A5\u4E0D\u53EF\u7528\uFF1A\u8BF7\u786E\u4FDD\u63D2\u4EF6\u9875\u5728 Songloft \u5BA2\u6237\u7AEF\uFF08\u975E Web\uFF09\u7684 webview \u4E2D\u6253\u5F00\uFF0C\u4E14\u5BA2\u6237\u7AEF\u7248\u672C\u652F\u6301\u5BA2\u6237\u7AEF SDK\u3002\u53EF\u7528 isClient() \u9884\u5148\u68C0\u6D4B\u3002";
|
|
29
|
+
function getGlobal() {
|
|
30
|
+
return typeof window !== "undefined" ? window.SongloftPlugin : void 0;
|
|
31
|
+
}
|
|
32
|
+
function isClient() {
|
|
33
|
+
const g = getGlobal();
|
|
34
|
+
return !!(g && g.host && typeof g.host.isAvailable === "function" && g.host.isAvailable());
|
|
35
|
+
}
|
|
36
|
+
function requirePlayer() {
|
|
37
|
+
const g = getGlobal();
|
|
38
|
+
if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);
|
|
39
|
+
return g.player;
|
|
40
|
+
}
|
|
41
|
+
function requireHost() {
|
|
42
|
+
const g = getGlobal();
|
|
43
|
+
if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);
|
|
44
|
+
return g.host;
|
|
45
|
+
}
|
|
46
|
+
var player = {
|
|
47
|
+
getState: () => requirePlayer().getState(),
|
|
48
|
+
setQueue: (ids, options) => requirePlayer().setQueue(ids, options),
|
|
49
|
+
addToQueue: (ids) => requirePlayer().addToQueue(ids),
|
|
50
|
+
insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),
|
|
51
|
+
removeFromQueue: (index) => requirePlayer().removeFromQueue(index),
|
|
52
|
+
reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),
|
|
53
|
+
clearQueue: () => requirePlayer().clearQueue(),
|
|
54
|
+
play: (id) => requirePlayer().play(id),
|
|
55
|
+
pause: () => requirePlayer().pause(),
|
|
56
|
+
togglePlay: () => requirePlayer().togglePlay(),
|
|
57
|
+
next: () => requirePlayer().next(),
|
|
58
|
+
prev: () => requirePlayer().prev(),
|
|
59
|
+
seek: (seconds) => requirePlayer().seek(seconds),
|
|
60
|
+
setVolume: (volume) => requirePlayer().setVolume(volume),
|
|
61
|
+
setPlayMode: (mode) => requirePlayer().setPlayMode(mode),
|
|
62
|
+
playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),
|
|
63
|
+
onStateChange: (handler) => requirePlayer().onStateChange(handler)
|
|
64
|
+
};
|
|
65
|
+
var host = {
|
|
66
|
+
isAvailable: () => isClient(),
|
|
67
|
+
getInfo: () => requireHost().getInfo()
|
|
68
|
+
};
|
|
69
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
70
|
+
0 && (module.exports = {
|
|
71
|
+
host,
|
|
72
|
+
isClient,
|
|
73
|
+
player
|
|
74
|
+
});
|
|
75
|
+
//# sourceMappingURL=index.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// native 客户端走 flutter_inappwebview.callHandler,Web 端 Tab 内嵌插件页走 iframe\n// postMessage。本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 Tab 内嵌插件页(iframe)内有效;\n// - Web 端全屏插件页(新标签独立打开、无宿主父窗口)、或宿主版本过旧时,\n// `isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgKA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;","names":[]}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/** 播放模式(与宿主一致)。 */
|
|
2
|
+
type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';
|
|
3
|
+
/**
|
|
4
|
+
* 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。
|
|
5
|
+
* 只列出常用字段;宿主可能返回更多字段。
|
|
6
|
+
*/
|
|
7
|
+
interface ClientSong {
|
|
8
|
+
id: number;
|
|
9
|
+
type: 'local' | 'remote' | 'radio';
|
|
10
|
+
title: string;
|
|
11
|
+
artist?: string;
|
|
12
|
+
album?: string;
|
|
13
|
+
duration?: number;
|
|
14
|
+
url?: string;
|
|
15
|
+
cover_url?: string;
|
|
16
|
+
lyric_url?: string;
|
|
17
|
+
is_live?: boolean;
|
|
18
|
+
[key: string]: unknown;
|
|
19
|
+
}
|
|
20
|
+
/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */
|
|
21
|
+
interface ClientPlayerState {
|
|
22
|
+
/** 正在播放队列 */
|
|
23
|
+
queue: ClientSong[];
|
|
24
|
+
/** 当前歌曲在队列中的下标;无歌曲时为 -1 */
|
|
25
|
+
current_index: number;
|
|
26
|
+
/** 当前歌曲;无歌曲时为 null */
|
|
27
|
+
current_song: ClientSong | null;
|
|
28
|
+
is_playing: boolean;
|
|
29
|
+
/** 当前播放进度(秒) */
|
|
30
|
+
current_time: number;
|
|
31
|
+
/** 当前歌曲总时长(秒) */
|
|
32
|
+
duration: number;
|
|
33
|
+
/** 音量 0-100 */
|
|
34
|
+
volume: number;
|
|
35
|
+
play_mode: PlayMode;
|
|
36
|
+
/** 队列来源的服务端歌单 id(如有) */
|
|
37
|
+
source_playlist_id?: number | null;
|
|
38
|
+
}
|
|
39
|
+
/** 宿主信息与能力协商结果(`host.getInfo()`)。 */
|
|
40
|
+
interface HostInfo {
|
|
41
|
+
/** 客户端应用版本,如 "2.12.0" */
|
|
42
|
+
version: string;
|
|
43
|
+
/** 运行平台:android / ios / macos / windows / linux / web */
|
|
44
|
+
platform: string;
|
|
45
|
+
/** 宿主支持的能力命名空间,如 ["player"],用于向前兼容的能力协商 */
|
|
46
|
+
capabilities: string[];
|
|
47
|
+
}
|
|
48
|
+
/** `setQueue` 的可选参数。 */
|
|
49
|
+
interface SetQueueOptions {
|
|
50
|
+
/** 从队列的哪一首开始播放,默认 0 */
|
|
51
|
+
startIndex?: number;
|
|
52
|
+
/** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */
|
|
53
|
+
sourcePlaylistId?: number;
|
|
54
|
+
}
|
|
55
|
+
/** 宿主客户端能力:播放器命名空间。 */
|
|
56
|
+
interface SongloftPluginPlayer {
|
|
57
|
+
/** 获取当前播放器状态快照 */
|
|
58
|
+
getState(): Promise<ClientPlayerState>;
|
|
59
|
+
/** 用歌曲 id 列表替换整个正在播放队列并开始播放 */
|
|
60
|
+
setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;
|
|
61
|
+
/** 追加歌曲到队列末尾(去重,不改变当前播放) */
|
|
62
|
+
addToQueue(ids: number[]): Promise<void>;
|
|
63
|
+
/** 在队列指定位置插入一首歌(不触发播放) */
|
|
64
|
+
insertToQueue(index: number, id: number): Promise<void>;
|
|
65
|
+
/** 移除队列中指定下标的歌曲 */
|
|
66
|
+
removeFromQueue(index: number): Promise<void>;
|
|
67
|
+
/** 重排队列 */
|
|
68
|
+
reorderQueue(oldIndex: number, newIndex: number): Promise<void>;
|
|
69
|
+
/** 清空队列 */
|
|
70
|
+
clearQueue(): Promise<void>;
|
|
71
|
+
/** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */
|
|
72
|
+
play(id?: number): Promise<void>;
|
|
73
|
+
/** 暂停 */
|
|
74
|
+
pause(): Promise<void>;
|
|
75
|
+
/** 播放/暂停切换 */
|
|
76
|
+
togglePlay(): Promise<void>;
|
|
77
|
+
/** 下一首 */
|
|
78
|
+
next(): Promise<void>;
|
|
79
|
+
/** 上一首 */
|
|
80
|
+
prev(): Promise<void>;
|
|
81
|
+
/** 跳转到指定进度(秒) */
|
|
82
|
+
seek(seconds: number): Promise<void>;
|
|
83
|
+
/** 设置音量 0-100 */
|
|
84
|
+
setVolume(volume: number): Promise<void>;
|
|
85
|
+
/** 设置播放模式 */
|
|
86
|
+
setPlayMode(mode: PlayMode): Promise<void>;
|
|
87
|
+
/** 直接播放服务端歌单(按歌单 id) */
|
|
88
|
+
playPlaylistById(playlistId: number): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* 订阅播放状态变更。返回取消订阅函数。
|
|
91
|
+
* 注意:状态推送经过节流,`current_time` 可能不是每秒更新。
|
|
92
|
+
*/
|
|
93
|
+
onStateChange(handler: (state: ClientPlayerState) => void): () => void;
|
|
94
|
+
}
|
|
95
|
+
/** 宿主客户端能力:host 命名空间。 */
|
|
96
|
+
interface SongloftPluginHost {
|
|
97
|
+
/** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */
|
|
98
|
+
isAvailable(): boolean;
|
|
99
|
+
/** 获取宿主信息与能力列表 */
|
|
100
|
+
getInfo(): Promise<HostInfo>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* 注入到页面的 `window.SongloftPlugin` 全局对象。
|
|
104
|
+
* 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,
|
|
105
|
+
* 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。
|
|
106
|
+
*/
|
|
107
|
+
interface SongloftPluginGlobal {
|
|
108
|
+
host?: SongloftPluginHost;
|
|
109
|
+
player?: SongloftPluginPlayer;
|
|
110
|
+
getTheme?(): 'light' | 'dark';
|
|
111
|
+
onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;
|
|
112
|
+
apiGet?(path: string): Promise<unknown>;
|
|
113
|
+
apiPost?(path: string, body: unknown): Promise<unknown>;
|
|
114
|
+
apiPut?(path: string, body: unknown): Promise<unknown>;
|
|
115
|
+
apiDelete?(path: string): Promise<unknown>;
|
|
116
|
+
[key: string]: unknown;
|
|
117
|
+
}
|
|
118
|
+
declare global {
|
|
119
|
+
interface Window {
|
|
120
|
+
SongloftPlugin?: SongloftPluginGlobal;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* 是否运行在支持原生桥接的 Songloft 客户端 webview 内。
|
|
125
|
+
* 调用任何 player/host 方法前建议先检测。
|
|
126
|
+
*/
|
|
127
|
+
declare function isClient(): boolean;
|
|
128
|
+
/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */
|
|
129
|
+
declare const player: SongloftPluginPlayer;
|
|
130
|
+
/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */
|
|
131
|
+
declare const host: SongloftPluginHost;
|
|
132
|
+
|
|
133
|
+
export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, host, isClient, player };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/** 播放模式(与宿主一致)。 */
|
|
2
|
+
type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';
|
|
3
|
+
/**
|
|
4
|
+
* 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。
|
|
5
|
+
* 只列出常用字段;宿主可能返回更多字段。
|
|
6
|
+
*/
|
|
7
|
+
interface ClientSong {
|
|
8
|
+
id: number;
|
|
9
|
+
type: 'local' | 'remote' | 'radio';
|
|
10
|
+
title: string;
|
|
11
|
+
artist?: string;
|
|
12
|
+
album?: string;
|
|
13
|
+
duration?: number;
|
|
14
|
+
url?: string;
|
|
15
|
+
cover_url?: string;
|
|
16
|
+
lyric_url?: string;
|
|
17
|
+
is_live?: boolean;
|
|
18
|
+
[key: string]: unknown;
|
|
19
|
+
}
|
|
20
|
+
/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */
|
|
21
|
+
interface ClientPlayerState {
|
|
22
|
+
/** 正在播放队列 */
|
|
23
|
+
queue: ClientSong[];
|
|
24
|
+
/** 当前歌曲在队列中的下标;无歌曲时为 -1 */
|
|
25
|
+
current_index: number;
|
|
26
|
+
/** 当前歌曲;无歌曲时为 null */
|
|
27
|
+
current_song: ClientSong | null;
|
|
28
|
+
is_playing: boolean;
|
|
29
|
+
/** 当前播放进度(秒) */
|
|
30
|
+
current_time: number;
|
|
31
|
+
/** 当前歌曲总时长(秒) */
|
|
32
|
+
duration: number;
|
|
33
|
+
/** 音量 0-100 */
|
|
34
|
+
volume: number;
|
|
35
|
+
play_mode: PlayMode;
|
|
36
|
+
/** 队列来源的服务端歌单 id(如有) */
|
|
37
|
+
source_playlist_id?: number | null;
|
|
38
|
+
}
|
|
39
|
+
/** 宿主信息与能力协商结果(`host.getInfo()`)。 */
|
|
40
|
+
interface HostInfo {
|
|
41
|
+
/** 客户端应用版本,如 "2.12.0" */
|
|
42
|
+
version: string;
|
|
43
|
+
/** 运行平台:android / ios / macos / windows / linux / web */
|
|
44
|
+
platform: string;
|
|
45
|
+
/** 宿主支持的能力命名空间,如 ["player"],用于向前兼容的能力协商 */
|
|
46
|
+
capabilities: string[];
|
|
47
|
+
}
|
|
48
|
+
/** `setQueue` 的可选参数。 */
|
|
49
|
+
interface SetQueueOptions {
|
|
50
|
+
/** 从队列的哪一首开始播放,默认 0 */
|
|
51
|
+
startIndex?: number;
|
|
52
|
+
/** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */
|
|
53
|
+
sourcePlaylistId?: number;
|
|
54
|
+
}
|
|
55
|
+
/** 宿主客户端能力:播放器命名空间。 */
|
|
56
|
+
interface SongloftPluginPlayer {
|
|
57
|
+
/** 获取当前播放器状态快照 */
|
|
58
|
+
getState(): Promise<ClientPlayerState>;
|
|
59
|
+
/** 用歌曲 id 列表替换整个正在播放队列并开始播放 */
|
|
60
|
+
setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;
|
|
61
|
+
/** 追加歌曲到队列末尾(去重,不改变当前播放) */
|
|
62
|
+
addToQueue(ids: number[]): Promise<void>;
|
|
63
|
+
/** 在队列指定位置插入一首歌(不触发播放) */
|
|
64
|
+
insertToQueue(index: number, id: number): Promise<void>;
|
|
65
|
+
/** 移除队列中指定下标的歌曲 */
|
|
66
|
+
removeFromQueue(index: number): Promise<void>;
|
|
67
|
+
/** 重排队列 */
|
|
68
|
+
reorderQueue(oldIndex: number, newIndex: number): Promise<void>;
|
|
69
|
+
/** 清空队列 */
|
|
70
|
+
clearQueue(): Promise<void>;
|
|
71
|
+
/** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */
|
|
72
|
+
play(id?: number): Promise<void>;
|
|
73
|
+
/** 暂停 */
|
|
74
|
+
pause(): Promise<void>;
|
|
75
|
+
/** 播放/暂停切换 */
|
|
76
|
+
togglePlay(): Promise<void>;
|
|
77
|
+
/** 下一首 */
|
|
78
|
+
next(): Promise<void>;
|
|
79
|
+
/** 上一首 */
|
|
80
|
+
prev(): Promise<void>;
|
|
81
|
+
/** 跳转到指定进度(秒) */
|
|
82
|
+
seek(seconds: number): Promise<void>;
|
|
83
|
+
/** 设置音量 0-100 */
|
|
84
|
+
setVolume(volume: number): Promise<void>;
|
|
85
|
+
/** 设置播放模式 */
|
|
86
|
+
setPlayMode(mode: PlayMode): Promise<void>;
|
|
87
|
+
/** 直接播放服务端歌单(按歌单 id) */
|
|
88
|
+
playPlaylistById(playlistId: number): Promise<void>;
|
|
89
|
+
/**
|
|
90
|
+
* 订阅播放状态变更。返回取消订阅函数。
|
|
91
|
+
* 注意:状态推送经过节流,`current_time` 可能不是每秒更新。
|
|
92
|
+
*/
|
|
93
|
+
onStateChange(handler: (state: ClientPlayerState) => void): () => void;
|
|
94
|
+
}
|
|
95
|
+
/** 宿主客户端能力:host 命名空间。 */
|
|
96
|
+
interface SongloftPluginHost {
|
|
97
|
+
/** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */
|
|
98
|
+
isAvailable(): boolean;
|
|
99
|
+
/** 获取宿主信息与能力列表 */
|
|
100
|
+
getInfo(): Promise<HostInfo>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* 注入到页面的 `window.SongloftPlugin` 全局对象。
|
|
104
|
+
* 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,
|
|
105
|
+
* 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。
|
|
106
|
+
*/
|
|
107
|
+
interface SongloftPluginGlobal {
|
|
108
|
+
host?: SongloftPluginHost;
|
|
109
|
+
player?: SongloftPluginPlayer;
|
|
110
|
+
getTheme?(): 'light' | 'dark';
|
|
111
|
+
onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;
|
|
112
|
+
apiGet?(path: string): Promise<unknown>;
|
|
113
|
+
apiPost?(path: string, body: unknown): Promise<unknown>;
|
|
114
|
+
apiPut?(path: string, body: unknown): Promise<unknown>;
|
|
115
|
+
apiDelete?(path: string): Promise<unknown>;
|
|
116
|
+
[key: string]: unknown;
|
|
117
|
+
}
|
|
118
|
+
declare global {
|
|
119
|
+
interface Window {
|
|
120
|
+
SongloftPlugin?: SongloftPluginGlobal;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* 是否运行在支持原生桥接的 Songloft 客户端 webview 内。
|
|
125
|
+
* 调用任何 player/host 方法前建议先检测。
|
|
126
|
+
*/
|
|
127
|
+
declare function isClient(): boolean;
|
|
128
|
+
/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */
|
|
129
|
+
declare const player: SongloftPluginPlayer;
|
|
130
|
+
/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */
|
|
131
|
+
declare const host: SongloftPluginHost;
|
|
132
|
+
|
|
133
|
+
export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, host, isClient, player };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// src/index.ts
|
|
2
|
+
var NOT_AVAILABLE_MSG = "[@songloft/client-sdk] \u5BBF\u4E3B\u5BA2\u6237\u7AEF\u6865\u63A5\u4E0D\u53EF\u7528\uFF1A\u8BF7\u786E\u4FDD\u63D2\u4EF6\u9875\u5728 Songloft \u5BA2\u6237\u7AEF\uFF08\u975E Web\uFF09\u7684 webview \u4E2D\u6253\u5F00\uFF0C\u4E14\u5BA2\u6237\u7AEF\u7248\u672C\u652F\u6301\u5BA2\u6237\u7AEF SDK\u3002\u53EF\u7528 isClient() \u9884\u5148\u68C0\u6D4B\u3002";
|
|
3
|
+
function getGlobal() {
|
|
4
|
+
return typeof window !== "undefined" ? window.SongloftPlugin : void 0;
|
|
5
|
+
}
|
|
6
|
+
function isClient() {
|
|
7
|
+
const g = getGlobal();
|
|
8
|
+
return !!(g && g.host && typeof g.host.isAvailable === "function" && g.host.isAvailable());
|
|
9
|
+
}
|
|
10
|
+
function requirePlayer() {
|
|
11
|
+
const g = getGlobal();
|
|
12
|
+
if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);
|
|
13
|
+
return g.player;
|
|
14
|
+
}
|
|
15
|
+
function requireHost() {
|
|
16
|
+
const g = getGlobal();
|
|
17
|
+
if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);
|
|
18
|
+
return g.host;
|
|
19
|
+
}
|
|
20
|
+
var player = {
|
|
21
|
+
getState: () => requirePlayer().getState(),
|
|
22
|
+
setQueue: (ids, options) => requirePlayer().setQueue(ids, options),
|
|
23
|
+
addToQueue: (ids) => requirePlayer().addToQueue(ids),
|
|
24
|
+
insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),
|
|
25
|
+
removeFromQueue: (index) => requirePlayer().removeFromQueue(index),
|
|
26
|
+
reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),
|
|
27
|
+
clearQueue: () => requirePlayer().clearQueue(),
|
|
28
|
+
play: (id) => requirePlayer().play(id),
|
|
29
|
+
pause: () => requirePlayer().pause(),
|
|
30
|
+
togglePlay: () => requirePlayer().togglePlay(),
|
|
31
|
+
next: () => requirePlayer().next(),
|
|
32
|
+
prev: () => requirePlayer().prev(),
|
|
33
|
+
seek: (seconds) => requirePlayer().seek(seconds),
|
|
34
|
+
setVolume: (volume) => requirePlayer().setVolume(volume),
|
|
35
|
+
setPlayMode: (mode) => requirePlayer().setPlayMode(mode),
|
|
36
|
+
playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),
|
|
37
|
+
onStateChange: (handler) => requirePlayer().onStateChange(handler)
|
|
38
|
+
};
|
|
39
|
+
var host = {
|
|
40
|
+
isAvailable: () => isClient(),
|
|
41
|
+
getInfo: () => requireHost().getInfo()
|
|
42
|
+
};
|
|
43
|
+
export {
|
|
44
|
+
host,
|
|
45
|
+
isClient,
|
|
46
|
+
player
|
|
47
|
+
};
|
|
48
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// native 客户端走 flutter_inappwebview.callHandler,Web 端 Tab 内嵌插件页走 iframe\n// postMessage。本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 Tab 内嵌插件页(iframe)内有效;\n// - Web 端全屏插件页(新标签独立打开、无宿主父窗口)、或宿主版本过旧时,\n// `isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n"],"mappings":";AAgKA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;","names":[]}
|
package/package.json
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@songloft/client-sdk",
|
|
3
|
+
"version": "2.12.2",
|
|
4
|
+
"description": "Client SDK for Songloft webview plugin pages — call Flutter host APIs (player queue, etc.)",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"import": "./dist/index.js",
|
|
10
|
+
"require": "./dist/index.cjs"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"types": "./dist/index.d.ts",
|
|
14
|
+
"main": "./dist/index.cjs",
|
|
15
|
+
"module": "./dist/index.js",
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md"
|
|
19
|
+
],
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "tsup",
|
|
22
|
+
"test": "echo \"no tests yet\" && exit 0",
|
|
23
|
+
"typecheck": "tsc --noEmit"
|
|
24
|
+
},
|
|
25
|
+
"devDependencies": {
|
|
26
|
+
"tsup": "^8.0.0",
|
|
27
|
+
"typescript": "^5.7.0"
|
|
28
|
+
},
|
|
29
|
+
"keywords": [
|
|
30
|
+
"songloft",
|
|
31
|
+
"plugin",
|
|
32
|
+
"client",
|
|
33
|
+
"sdk",
|
|
34
|
+
"webview"
|
|
35
|
+
],
|
|
36
|
+
"repository": {
|
|
37
|
+
"type": "git",
|
|
38
|
+
"url": "git+https://github.com/songloft-org/plugin-toolchain.git",
|
|
39
|
+
"directory": "packages/client-sdk"
|
|
40
|
+
},
|
|
41
|
+
"homepage": "https://github.com/songloft-org/plugin-toolchain/tree/main/packages/client-sdk#readme",
|
|
42
|
+
"bugs": {
|
|
43
|
+
"url": "https://github.com/songloft-org/plugin-toolchain/issues"
|
|
44
|
+
},
|
|
45
|
+
"license": "Apache-2.0",
|
|
46
|
+
"publishConfig": {
|
|
47
|
+
"access": "public"
|
|
48
|
+
}
|
|
49
|
+
}
|