Protocol Launcher

简体中文

English

简体中文

English

Appearance

OnSong ​

OnSong 是一款面向音乐人的数字歌本和 chord chart 应用。Protocol Launcher 允许你生成 OnSong URL scheme 链接。

使用 ​

有两种方式使用此库：

  • On-Demand 从子路径导入，有利于 tree-shaking 并保持包体积较小。
  • Full Import 从根包导入，写起来更方便，但会包含所有应用模块。

生产构建建议使用 On-Demand；快速脚本或演示可以使用 Full Import。

选择安装方式

按需加载
推荐使用。生产环境优化。
全量导入
使用便捷。适合快速脚本。

说明 ​

下面的 helper 与 OnSong 官方开发者文档中关于导入内容、打开歌曲、导出歌曲数据和执行 action 的 URL scheme 保持一致。这里只暴露官方记录的 onsong://、onsong://ImportData/...、onsong://open/songs、onsong://export/songs、onsong://action/list 和 onsong://action/<value> URL 形状。

OnSong 的 Open Song 和 Actions URL API 需要 OnSong 2020.8 或更高版本。importUrl() 接收 http:// 文件 URL，因为官方导入文档说明要把 http:// 部分替换成 onsong://；如果文件托管在 SSL 地址，官方说明应重定向到 https:// 位置。importData() 接收 Base64 编码后的文件数据，文件名扩展名很重要，因为 OnSong 会用它判断文件类型。

当前公开的 Open Song 页面提到导出结果可以包含额外 properties，但没有给出 query 参数名或完整 URL 语法。因此本模块不暴露 properties payload。

示例与测试使用合成的 song title、identifier、set name 和短 Base64 样例。不要公开受版权保护的歌词、完整乐谱内容，或真实用户曲库标识符。

打开 ​

On-Demand
ts
import { open } from 'protocol-launcher/onsong'

const url = open()

导入 URL ​

On-Demand
ts
import { importUrl } from 'protocol-launcher/onsong'

const url = importUrl({
  url: 'http://my.domain.com/files/go/here/Song%20Title.txt',
})

导入数据 ​

On-Demand
ts
import { importData } from 'protocol-launcher/onsong'

const url = importData({
  filename: 'My Song Title.pdf',
  base64Data: 'BASE_64_ENCODED_DATA_HERE',
})

打开歌曲 ​

On-Demand
ts
import { openSong } from 'protocol-launcher/onsong'

const url = openSong({
  song: 'be-still',
})

打开歌曲列表 ​

On-Demand
ts
import { openSongs } from 'protocol-launcher/onsong'

const url = openSongs({
  song: ['be-still', 'beautiful-life', 'changes'],
  index: 1,
})

导出歌曲 ​

On-Demand
ts
import { exportSongs } from 'protocol-launcher/onsong'

const url = exportSongs({
  collection: 'current',
  returnURL: 'http://mywebsite.com/receive?data=',
})

列出 Actions ​

On-Demand
ts
import { listActions } from 'protocol-launcher/onsong'

const url = listActions({
  returnURL: 'myapp://retrieve-actions/?data=',
})

执行 Action ​

On-Demand
ts
import { performAction } from 'protocol-launcher/onsong'

const url = performAction({
  action: 'SongSectionWasPressed',
  parameters: {
    sectionID: 'Chorus',
  },
})

生成的 URL ​

ts
open()
// => 'onsong://'

importUrl({
  url: 'http://my.domain.com/files/go/here/Song%20Title.txt',
})
// => 'onsong://my.domain.com/files/go/here/Song%20Title.txt'

importData({
  filename: 'My Song Title.pdf',
  base64Data: 'BASE_64_ENCODED_DATA_HERE',
})
// => 'onsong://ImportData/My%20Song%20Title.pdf?BASE_64_ENCODED_DATA_HERE'

openSong({ song: 'be-still' })
// => 'onsong://open/songs?song=be-still'

openSongs({
  song: ['be-still', 'beautiful-life', 'changes'],
  index: 1,
})
// => 'onsong://open/songs/?song=be-still&song=beautiful-life&song=changes&index=1'

exportSongs({
  collection: 'current',
  returnURL: 'http://mywebsite.com/receive?data=',
})
// => 'onsong://export/songs?collection=current&returnURL=http%3A%2F%2Fmywebsite%2Ecom%2Freceive%3Fdata%3D'

listActions()
// => 'onsong://action/list'

performAction({ action: 'PositionWasAdjusted', amount: 0.5 })
// => 'onsong://action/PositionWasAdjusted?amount=0.5'

参考资料 ​