open-index/open-npm huggingface dataset:
npm package: @sunzan/universal-file-dl
Description: 通用文件流导出工具：自动解析文件名，兼容 fetch/axios，支持任意格式
Author: sunzan
Latest version: 0.1.0

## 文件流导出工具

通用浏览器端下载工具，兼容任意格式（以服务端返回为准），支持：
- 自动解析 `Content-Disposition` 得到文件名（兼容 `filename*` UTF-8 与 `filename`）
- 适配 `fetch` 与 `axios` 响应对象
- 直接传入 `Blob/ArrayBuffer/Uint8Array` 下载

### 安装/放置

可以直接复制 `src/utils/fileDownload.js`，或通过 npm 安装：

```bash
npm i universal-file-download
# 或
pnpm add universal-file-download
```

使用：

```js
import downloader, { downloadByFetch, downloadFromAxiosResponse } from 'universal-file-download';
```

### API

- `resolveFilename(headers, fallback?, url?)`：从响应头/URL 推断文件名
- `downloadFromFetchResponse(response, { filename? })`：基于 fetch `Response` 下载
- `downloadFromAxiosResponse(axiosResponse, { filename? })`：基于 axios 响应下载（需设置 `responseType`）
- `downloadByFetch(url, fetchInit?)`：直接传入 URL，用 fetch 请求并下载
- `downloadFromData(data, { filename, type? })`：从原始数据（Blob/ArrayBuffer/Uint8Array）下载

### 用法示例

#### 1) 使用 axios

```js
import axios from 'axios';
import downloader from './src/utils/fileDownload';

async function exportWithAxios() {
  const res = await axios.get('/api/export', {
    responseType: 'blob', // 或 'arraybuffer'
    params: { q: 'keyword' },
  });

  await downloader.downloadFromAxiosResponse(res, { filename: 'fallback.xlsx' });
}
```

#### 2) 使用 fetch（已拿到 Response）

```js
import { downloadFromFetchResponse } from './src/utils/fileDownload';

async function exportWithFetchResponse() {
  const res = await fetch('/api/export', { credentials: 'include' });
  await downloadFromFetchResponse(res, { filename: 'fallback.csv' });
}
```

#### 3) 使用 fetch 直接请求并下载

```js
import { downloadByFetch } from './src/utils/fileDownload';

async function exportByUrl() {
  await downloadByFetch('/api/export?type=zip', { filename: 'fallback.zip' });
}
```

#### 4) 从原始数据下载

```js
import { downloadFromData } from './src/utils/fileDownload';

async function exportFromData() {
  const data = new Uint8Array([1,2,3,4]);
  downloadFromData(data, { filename: 'demo.bin', type: 'application/octet-stream' });
}
```

### 服务器返回建议

- 设置正确的 `Content-Type`，例如 `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` 等
- 设置 `Content-Disposition`：
  - `attachment; filename="report.xlsx"`
  - 或 `attachment; filename*=UTF-8''%E6%8A%A5%E8%A1%A8.xlsx`

### 注意事项

- Safari/部分浏览器需要使用 Blob URL 触发下载，工具已处理
- 若服务端返回 JSON 错误体而非二进制，请在触发下载前根据项目约定先判断响应是否为文件（例如检查 `content-type` 是否包含 `application/json`），再做错误处理

### 演示页运行

无需构建工具，直接本地打开 demo 页面：

1. 用本机静态服务器（推荐）

```bash
npx http-server . -p 8080
# 或者：python3 -m http.server 8080
```

浏览器访问 `http://localhost:8080/demo/`，点击三个按钮进行测试。

2. 直接 file:// 打开

双击打开 `demo/index.html` 也可运行，但某些浏览器对 `module` + 相对路径在 `file://` 下有安全限制，建议使用本机静态服务器。