Scripting
文档
更新日志
隐私
文档
更新日志
隐私
简体中文

后台网络会话

BackgroundURLSession 提供在 Scripting app 中发起、恢复与查询「后台可持续」的下载与上传任务的能力。

可用性： 仅当脚本运行在主应用 (Script.env === "index") 时可用。

命名空间：BackgroundURLSession

1) startDownload(options): URLSessionDownloadTask

作用：启动一个新的后台下载任务。

签名

1function startDownload(options: {
2  url: string
3  destination: string
4  headers?: Record<string, string>
5  notifyOnFinished?: {
6    success: string
7    failure: string
8  }
9}): URLSessionDownloadTask

参数说明

  • url (string)：要下载的文件 URL。
  • destination (string)：下载完成后保存的目标文件路径。
  • headers (Record<string, string>, 可选)：HTTP 请求头。
  • notifyOnFinished ({ success: string, failure: string }, 可选)：下载完成后是否发送本地通知, success 为成功通知标题，failure 为失败通知标题。

返回值

  • URLSessionDownloadTask：下载任务对象（任务会自动启动）。

示例

1const task = BackgroundURLSession.startDownload({
2  url: 'https://example.com/file.zip',
3  destination: '/var/mobile/Containers/.../Downloads/file.zip',
4  headers: { 'User-Agent': 'Scripting/1.0' },
5  notifyOnFinished: {
6    success: '下载成功',
7    failure: '下载失败'
8  }
9})
10
11// 开始下载
12task.resume()
13
14// 监听进度与完成事件
15task.onProgress = d => console.log('进度：', d.progress)
16task.onFinishDownload = (err, info) => {
17  if (!err) console.log('下载完成，文件保存于：', info.destination)
18}

2) resumeDownload(options): URLSessionDownloadTask

作用：从断点续传数据恢复一个下载任务。

签名

1function resumeDownload(options: {
2  resumeData: Data
3  destination: string
4  notifyOnFinished?: {
5    success: string
6    failure: string
7  }
8}): URLSessionDownloadTask

参数说明

  • resumeData (Data)：通过 cancelByProducingResumeData() 获取的断点数据。
  • destination (string)：下载完成后的目标保存路径。
  • notifyOnFinished ({ success: string, failure: string }, 可选)：下载完成后是否发送本地通知, success 为成功通知标题，failure 为失败通知标题。

返回值

  • URLSessionDownloadTask：下载任务对象（任务会自动启动）。

示例

1const task = BackgroundURLSession.resumeDownload({
2  resumeData,
3  destination: '/.../Downloads/file.zip',
4  notifyOnFinished: true
5})
6
7// 开始续传
8task.resume()
9
10task.onFinishDownload = (err, info) => {
11  if (!err) console.log('续传完成：', info.destination)
12}

3) getDownloadTasks(): Promise<URLSessionDownloadTask[]>

作用：获取当前系统中仍存在的后台下载任务。 脚本被终止或重启后，可通过该方法重新获取任务实例并重新设置回调。

签名

1function getDownloadTasks(): Promise<URLSessionDownloadTask[]>

返回值

  • Promise<URLSessionDownloadTask[]>：下载任务对象数组。

示例

1const tasks = await BackgroundURLSession.getDownloadTasks()
2for (const task of tasks) {
3  console.log('任务ID:', task.id, '状态:', task.state)
4  task.onComplete = err => {
5    if (err) console.error('下载失败：', err)
6  }
7}

4) startUpload(options): URLSessionUploadTask

作用：启动一个新的后台上传任务。

签名

1function startUpload(options: {
2  filePath: string
3  toURL: string
4  method?: string
5  headers?: Record<string, string>
6  notifyOnFinished?: {
7    success: string
8    failure: string
9  }
10}): URLSessionUploadTask

参数说明

  • filePath (string)：要上传的本地文件路径。
  • toURL (string)：服务器目标 URL。
  • method (string, 可选，默认 "POST")：HTTP 请求方法。
  • headers (Record<string, string>, 可选)：HTTP 请求头。
  • notifyOnFinished ({ success: string, failure: string }, 可选)：上传完成后是否发送本地通知, success 为成功通知标题，failure 为失败通知标题。

返回值

  • URLSessionUploadTask：上传任务对象（任务会自动启动）。

示例

1const task = BackgroundURLSession.startUpload({
2  filePath: '/.../upload.bin',
3  toURL: 'https://api.example.com/upload',
4  method: 'PUT',
5  headers: { Authorization: 'Bearer token' },
6  notifyOnFinished: {
7    success: '上传成功',
8    failure: '上传失败'
9  }
10})
11
12// 开始上传
13task.resume()
14
15task.onComplete = err => {
16  if (!err) console.log('上传完成')
17  else console.error('上传失败：', err)
18}

5) resumeUpload(options): URLSessionUploadTask

作用：恢复一个可续传的上传任务。

签名

1function resumeUpload(options: {
2  resumeData: Data
3  notifyOnFinished?: {
4    success: string
5    failure: string
6  }
7}): URLSessionUploadTask

参数说明

  • resumeData (Data)：先前上传任务失败时生成的续传数据。
  • notifyOnFinished ({ success: string, failure: string }, 可选)：上传完成后是否发送本地通知, success 为成功通知标题，failure 为失败通知标题。

返回值

  • URLSessionUploadTask：新的上传任务对象（任务会自动启动）。

示例

1const task = BackgroundURLSession.resumeUpload({
2  resumeData,
3  notifyOnFinished: {
4    success: '上传成功',
5    failure: '上传失败'
6  }
7})
8
9// 开始续传
10task.resume()
11
12task.onComplete = err => {
13  if (!err) console.log('上传续传完成')
14}

6) getUploadTasks(): Promise<URLSessionUploadTask[]>

作用：获取系统中仍存在的后台上传任务，用于脚本重启后恢复任务状态与回调。

签名

1function getUploadTasks(): Promise<URLSessionUploadTask[]>

返回值

  • Promise<URLSessionUploadTask[]>：上传任务数组。

示例

1const tasks = await BackgroundURLSession.getUploadTasks()
2for (const t of tasks) {
3  console.log('任务ID:', t.id, '状态:', t.state)
4  t.onComplete = err => {
5    if (err) console.error('上传失败：', err)
6  }
7}

使用说明与建议

  • 暂停与恢复： 如果调用了 task.suspend() 暂停任务，则可通过 task.resume() 恢复。
  • 断点续传： 下载任务可通过 cancelByProducingResumeData() 生成续传数据；上传任务是否支持续传取决于服务器。
  • 任务恢复： 当脚本被系统终止后，后台任务仍会继续。重新启动脚本后，可使用 getDownloadTasks() 或 getUploadTasks() 取回并重新绑定事件回调。
  • 通知提示： notifyOnFinished 仅影响任务完成时的本地通知显示，不影响任务执行流程。
大纲