Spicetify 项目中使用 Platform API 操作 Spotify 播放列表

概述

在开发基于 Spicetify 的 Spotify 客户端扩展时，操作播放列表是一个常见需求。本文将详细介绍如何使用 Spicetify 提供的 Platform API 来添加和删除播放列表中的曲目，避免直接调用 Spotify Web API 时可能遇到的问题。

问题背景

许多开发者尝试通过 Spicetify 的 CosmosAsync 直接调用 Spotify Web API 来操作播放列表，例如使用 POST 请求向播放列表添加曲目。然而，这种方法经常会遇到 "Resolver not found" 的错误（错误代码 -1），这通常是因为 Spotify 客户端内部有更优化的实现方式。

解决方案：使用 Platform API

Spicetify 提供了访问 Spotify 客户端原生功能的 Platform API，这是操作播放列表更可靠的方式。以下是具体实现方法：

添加曲目到播放列表

async function addTrackToPlaylist(playlistUri, trackUri) {
    await Spicetify.Platform.PlaylistAPI.add(
        playlistUri, 
        [trackUri], 
        {after: 1, before: 0}
    );
}

参数说明：

• playlistUri: 目标播放列表的 Spotify URI（格式如 spotify:playlist:6LFlf3kk62MioxGw7Dy0ZC）
• trackUri: 要添加的曲目 Spotify URI（格式如 spotify:track:0OG11VjhfTx04bHarpaTaN）
• 第三个参数是位置选项，after 和 before 指定曲目添加的位置

从播放列表移除曲目

async function removeTrackFromPlaylist(playlistUri, trackUri) {
    await Spicetify.Platform.PlaylistAPI.remove(
        playlistUri, 
        [{uri: trackUri, uid: ""}]
    );
}

参数说明：

• playlistUri: 目标播放列表的 Spotify URI
• 第二个参数是包含要移除曲目信息的数组，每个元素需要包含 uri 和 uid 属性

为什么推荐使用 Platform API

1. 更高的可靠性：Platform API 直接调用 Spotify 客户端的原生功能，避免了 Web API 可能遇到的限制和错误。

2. 更好的性能：由于绕过了网络请求，操作通常更快且更稳定。

3. 一致性：与 Spotify 客户端自身使用的相同 API，确保行为一致。

注意事项

1. Platform API 由 Spotify 维护，Spicetify 只是提供了访问这些 API 的途径。这意味着 API 可能会随 Spotify 客户端的更新而变化。

2. 目前 Platform API 的文档较少，开发者需要通过探索 Spicetify.Platform 对象来了解可用功能。

3. 未来 Spicetify v3 版本将提供更完善的类型定义和文档支持。

总结

对于需要在 Spicetify 扩展中操作 Spotify 播放列表的开发者，推荐使用 Platform API 而非直接调用 Web API。这种方法更可靠、性能更好，且与客户端行为一致。虽然目前文档有限，但通过本文提供的示例，开发者可以快速实现播放列表的添加和删除功能。

随着 Spicetify 项目的发展，未来版本将提供更完善的 Platform API 文档和类型支持，进一步简化开发流程。