Home > sculp-js > crossOriginDownload

crossOriginDownload() function

下载跨域资源并触发浏览器保存，支持请求头、XHR 进度和取消。

Signature:

export declare function crossOriginDownload(url: string, filename: string, options?: CrossOriginDownloadParams): Promise<void>;

Parameters

Parameter	Type	Description
url	string	GET 请求地址，服务端必须允许 CORS。
filename	string	保存时建议使用的文件名。
options	CrossOriginDownloadParams	(Optional) 可选配置；默认 auto，无进度回调时优先 fetch。

Returns:

Promise<void>

触发保存并清理临时资源后兑现的 Promise。 下载失败时以 CrossOriginDownloadError 拒绝；onProgress 抛错时以原异常拒绝。

Remarks

文件完整接收为 Blob 后触发保存；进度完成或 Promise 兑现均不表示已写入磁盘。 使用 await 或 then/catch 处理结果，不再支持成功、失败回调。

Example 1

基础下载并处理失败：

import { crossOriginDownload } from 'sculp-js/download';

try {
  await crossOriginDownload('/api/export', 'report.xlsx');
} catch (error) {
  console.error('下载失败', error);
}

Example 2

鉴权与进度，auto 自动使用 XHR，总量未知时展示已接收字节数：

import { crossOriginDownload } from 'sculp-js/download';

try {
  await crossOriginDownload('/api/export', 'report.xlsx', {
    headers: { Authorization: 'Bearer YOUR_TOKEN' },
    onProgress({ loaded, percent, done }) {
      if (done) console.log('接收完成，准备保存');
      else if (percent !== undefined) console.log(`已下载 ${percent.toFixed(1)}%`);
      else console.log(`已接收 ${loaded} 字节`);
    }
  });
} catch (error) {
  console.error('下载失败', error);
}

Example 3

用户取消；触发浏览器保存后 abort 无效：

import { crossOriginDownload, CrossOriginDownloadError } from 'sculp-js/download';

const controller = new AbortController();
const cancelButton = document.querySelector<HTMLButtonElement>('#cancel-download');
const cancel = () => controller.abort();
cancelButton?.addEventListener('click', cancel);
try {
  await crossOriginDownload('/api/export', 'report.xlsx', { signal: controller.signal });
} catch (error) {
  if (error instanceof CrossOriginDownloadError && error.code === 'ABORTED') {
    console.log('下载已取消');
  } else {
    console.error('下载失败', error);
  }
} finally {
  cancelButton?.removeEventListener('click', cancel);
}

Example 4

通过 Promise 链处理成功和失败：

import { crossOriginDownload } from 'sculp-js/download';

crossOriginDownload('/api/export', 'report.xlsx')
  .then(() => console.log('已触发保存'))
  .catch(error => console.error('下载失败', error));