主题包
接口列表
| 方法 | 路径 | 说明 |
|---|---|---|
PUT | /settings/theme-catalog-url | 更新主题目录 URL |
GET | /settings/theme-catalog-url | 获取主题目录 URL |
POST | /theme-packs | 导入主题包 |
GET | /theme-packs | 列出主题包 |
DELETE | /theme-packs/{themeID} | 删除主题包 |
GET | /theme-packs/{themeID} | 获取主题包详情 |
PUT | /theme-packs/active | 设置激活主题包 |
DELETE | /theme-packs/active | 恢复默认主题 |
GET | /theme-packs/active | 获取激活主题包 |
POST | /theme-packs/catalog/install | 从在线目录安装主题包 |
POST | /theme-packs/catalog/refresh | 获取在线主题目录 |
PUT /settings/theme-catalog-url
更新主题目录 URL
设置主题目录的远程 URL，同时清除本地目录缓存。URL 不能为空
需要认证
此接口需要 Bearer Token 认证
请求体
包含 url 字段的 JSON 对象
类型： object
响应
200 - 更新后的目录 URL
类型： map[string]string
400 - URL 为空或请求格式错误
类型： map[string]string
内容类型
- 请求：
application/json - 响应：
application/json
GET /settings/theme-catalog-url
获取主题目录 URL
返回当前配置的主题目录远程 URL，未配置时返回默认值
需要认证
此接口需要 Bearer Token 认证
响应
200 - 当前目录 URL
类型： map[string]string
内容类型
- 响应：
application/json
POST /theme-packs
导入主题包
接收 .songloft-theme JSON 内容，验证后存入。相同 ID 的主题包会被更新。
需要认证
此接口需要 Bearer Token 认证
请求体
主题包 JSON（完整 .songloft-theme 文件内容）
类型： object
响应
200 - 导入成功
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
data | ThemePackData | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
400 - 格式错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
GET /theme-packs
列出主题包
返回所有已安装的主题包列表
需要认证
此接口需要 Bearer Token 认证
响应
200 - 主题包列表
类型： ThemePackListItem[]
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
数组元素结构：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
内容类型
- 响应：
application/json
DELETE /theme-packs/{themeID}
删除主题包
删除指定主题包，若为当前激活主题则同时恢复默认
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
themeID | string | 是 | 主题包 ID |
响应
200 - 删除成功
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
404 - 主题包不存在
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json
GET /theme-packs/{themeID}
获取主题包详情
返回主题包的完整信息，含主题配置数据
需要认证
此接口需要 Bearer Token 认证
路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
themeID | string | 是 | 主题包 ID |
响应
200 - 主题包详情
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
data | ThemePackData | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
404 - 主题包不存在
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 响应：
application/json
PUT /theme-packs/active
设置激活主题包
将指定主题包设为当前使用的主题
需要认证
此接口需要 Bearer Token 认证
请求体
激活请求
类型： object
响应
200 - 设置成功
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
400 - 请求格式错误
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
404 - 主题包不存在
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
DELETE /theme-packs/active
恢复默认主题
清除当前激活的主题包，恢复为默认主题
需要认证
此接口需要 Bearer Token 认证
响应
200 - 已恢复默认主题
类型： SuccessResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
message | string | 否 | 成功信息 示例: "操作成功" |
内容类型
- 响应：
application/json
GET /theme-packs/active
获取激活主题包
返回当前激活的主题包详情，无激活主题时返回 null
需要认证
此接口需要 Bearer Token 认证
响应
200 - 激活主题包（可为 null）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
data | ThemePackData | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
内容类型
- 响应：
application/json
POST /theme-packs/catalog/install
从在线目录安装主题包
下载远程主题包 JSON，验证 SHA-256 后导入
需要认证
此接口需要 Bearer Token 认证
请求体
安装请求
类型： object
响应
200 - 安装成功
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
author | string | 否 | |
created_at | string | 否 | |
data | ThemePackData | 否 | |
description | string | 否 | |
id | integer | 否 | |
name | string | 否 | |
schema_version | integer | 否 | |
theme_id | string | 否 | |
updated_at | string | 否 | |
version | string | 否 |
400 - 校验失败
类型： ErrorResponse
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
detail | string | 否 | 详细错误信息（可选） 示例: "详细错误信息" |
error | string | 否 | 错误信息 示例: "操作失败" |
内容类型
- 请求：
application/json - 响应：
application/json
POST /theme-packs/catalog/refresh
获取在线主题目录
从远程 URL 获取主题目录索引，并标注各主题的安装状态
需要认证
此接口需要 Bearer Token 认证
请求体
目录请求
类型： object
响应
200 - 目录响应
类型： object
内容类型
- 请求：
application/json - 响应：
application/json