# @bytetrade/files-core 中文文档

规范地址：https://npmcn.com/package/%40bytetrade/files-core/

版本：0\.2\.9
npm 元数据更新时间：2026-10-28T03:38:34.644Z
中文译文更新时间：2026-11-08T22:10:27.195Z
软件包许可：GPL-3\.0-or-later

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bytetrade/files-core
原文对照：https://npmcn.com/package/%40bytetrade/files-core/?lang=original
项目主页：https://github.com/beclab/olares-files-picker/tree/main/packages/files-core#readme
源码仓库：https://github.com/beclab/olares-files-picker

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，679 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-08-21T13:39:32.210Z
- 最新版本发布：2026-10-28T03:38:34.438Z
- 近 30 天下载量：2144（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

文件 API 类型、 传输和浏览会话—— 无框架

## 安装

```sh
npm install @bytetrade/files-core
```

也可以使用：`pnpm add @bytetrade/files-core`、`yarn add @bytetrade/files-core`、`bun add @bytetrade/files-core`

## README

# @ bytetrade/ 文件分数

无框架文件 API:范围化服务,纯驱动协议,运输,路径帮助和浏览会话. 没有Vue,Pinia,或者Quasar.

## 条目

| 导入 | 目录 |
| --- | --- |
| `@bytetrade/files-core` | 全平面,包括范围服务和纯驱动协议 |
| `@bytetrade/files-core/base` | 类型,配置,会话,路径,i18n - **没有** 服务或驱动程序执行。 更喜欢当主机供应自己的 `FilesBrowserClient` (取取文件夹者有. |

## 配置

```ts
import {
  configureFiles,
  setFilesLocale,
  setFilesI18n
} from '@bytetrade/files-core/base';

configureFiles({
  baseURL: 'https://…',
  token: () => getAccessToken(),
  transport: myAxiosLikeTransport,
  browser: myFilesBrowserClient
});

setFilesLocale('zh-CN');
// Optional: forward to the host app's i18n so every language is covered.
setFilesI18n((key, params) => i18n.t(key, params));
```

### 内建 i18n

无 `setFilesI18n`,仅限 **联合国** 财务报告和审定财务报表 **中文** 船名目录 [`src/i18n.ts`](https://npmcn.com/package/%40bytetrade/files-core/src/i18n.ts)。支持更多本地语言的主机必须注入翻译器.

### 文件浏览器

驱动 UI( 文件夹拾取器、 自定义浏览器) 执行的主机 `FilesBrowserClient` 然后通过 `configureFiles({ browser })`(b) 会议(《公约》缔约方会议)`BrowseSession` 编号 : `getBrowseSession(id)`)是UI订阅的导航权威;客户端是UI如何要求主机加载菜单,打开路径,创建目录,并返回/前进.

### 会话自有浏览 (0.2.2)

为每个 UI 实例配置装入器一次, 然后订阅其状态 :

```ts
const session = getBrowseSession(instanceId);
session.configureLoader({
  scope: () => `${accountId}|${filesEndpoint}`,
  load: async (path, { signal, cursor }) => {
    const response = await listDirectory(path, { signal, cursor });
    return { listing: response.listing, nextCursor: response.nextCursor };
  }
});
await session.open(path);
await session.retry();
await session.loadNextPage();
```

装货者拥有取消、Stale-response检查和限值的入门检查 缓存。 范围改变明确的列表、选择、菜单、面包屑和历史; 主机应该调用 `syncScope()` 以立即清除. 被忽略的运输中断仍不能造成后期结果. `warm(path)` 仅限 填充缓存,绝不改变可见路径或装入状态.

`status` 区分闲置、装入、成功装入(包括空置)和 失败; 错误已正常化 `FilesError`s. 页面失效保留 完好无损的物品 `pagination.error`. 只有在运输时才运行 返回光标;未页后端不得创建。 刷新保存 按资源身份选择,并应用最新会话排序.

导航、排序和选择要经过会话方法。 反应主机 项目会话状态进入他们的商店; 他们不能给旧商店水分 重新列出为活动请求. `hydrate` 保留主机菜单/首选项 和外部提供的清单。 专门的寄存器壳查询可以是 通过 `open(path, { load })`; 重试重用该查询. `dispose()` 取消数 请求和热身; `removeBrowseSession(id)` 丢掉之前先处理.

### 主机自有转移发动机(0.2.3)

`FilesTransferRuntime` 提供用于上传和 下载任务。 主机通过 `adapter`,持久性,a 稳定 `scope` 识别账户和远程机器。 局域网路线和标志 旋转不应改变这种身份. `ready` 正在等待开始或 恢复; 适配器检查 `context.assertCurrent()` 同步准备后 在把工作交给本地人之前.

`execute` 已接受返回, 已拒绝, 已恢复正常 `FilesError`,或替换 当所有者范围/命令已替换此作品时。 明确命令取消所有 重试计时器 。 暂停/取消/完成后的后进度被忽略;完成 清扫一回. `reset()` 中止应用程序生命周期,同时允许新的周期; `dispose()` 永久释放运行时间 .

`restoreFilesTransfer` 根据引擎重新启动, resets 坚持字节任务 在保留后端最后敲定任务的同时保留能力. `FilesTransferLane` 序列化和连接文件夹周期而不陷入僵局的再入空文件 结业. `FilesTransferManifest` 分析递增的 UTF-8 NDJSON / SSE 列表, 包括没有新行的最后记录,拒绝错误的输入.

目录叶使用 `entryKind: 'directory'`· ; `isFolder` 继续队列父 旗帜。 可选 `transferScope`, (中文(简体) ), `uploadRoot`, (中文(简体) ), `downloadRoot`,以及 `manifestComplete` 字段允许主机在不更改遗留数据库enums的情况下恢复意图. 空条目通过 `FilesService.createEmptyFile` 编号 : `ensureDirectory`· ; `resolveDirectory` 锁定选中的不透明 ID 下的 Google 目录名称 . 原始相对名称必须由主机路径适配器精确编码一次.

### 账户基础设施

`createFilesInfrastructureService(dependencies)` 组合账户侧 API `nodes`, (中文(简体) ), `libraries`, (中文(简体) ), `cloudAccounts`, (中文(简体) ), `mounts`,以及 `menus`运输,当前 范围、翻译、提供者支持和独立功能门 注射过 服务不读取 UI 选择、路线、存储、对话框或 持续存储。 所有服务器请求接受取消并拒绝键入 错误.

-   图书馆上市记录不可更改 `libraryReference` 数值。 重命名/删除使用 这些参考资料;创建图书馆需要明确的账户范围. 共享列表失败不会成为空列表, 失败的删除不会成为空列表 被认为是成功的。 API的仓库名称仍为文字名称 边界.
-   使用云账户查询 `/api/accounts`过滤器 类型,并附加账户所有权。 文件页面保持此列表与 设置集成列表,并在账户/视图后必须丢弃回复 变化.
-   需要挂载 `createFilesNodeReference(name, scope)`. SMB/NFS发现 返回时 `{ kind: 'paths', paths }`; 仅 `{ kind: 'mounted' }` 表示一个 成功挂载 。 多步对话框必须带有相同的节点引用 在每一个步骤。 历史和卸载呼叫也使用此参考; 卷 名字被编码一次.
-   `menus.listGroup` 使用库/账户构成明确的来源 服务、独立的共同/同步门和主机标签。 东道主自己装入, 重试,出版和本土本地同步状态.
-   节点 HTTP 读取纯度并拒绝失败/成形结果 。 过渡 节点缓存帮助仍然种子主机运行时间, 但检查两个机器/账户 缓存身份和请求范围 围绕 Aync 工作 。 书写有序列;a 延迟缓存读取或失败的旧请求无法覆盖新账户 地貌学.

使用共享节点缓存协调器的主机应当提供 `configureFiles({ scope: currentFilesScope })`. 遗产帮扶者 服务; 管理通知属于主机。 NFS, 常见和同步 保留单独的特性回调而不是假设新的服务器最小值 .

### 股份管理

`createFilesShareService(dependencies)` 管理内部、公共和SMB股份. 创建和每个文件的搜索 接受抓取 `FileReference`; 现有份额 业务接受 `createShareReference(id, scope)`。清单结果包含 引用所以在账户或服务器切换后无法重用旧行 . 撤销会删除一个共享记录,从不调用文件删除 API.

东道方提供运输、现有范围、源能力和独立 共享特性门 。 服务在发送前检查范围和取消 已完成。 包括"零"在内的会员权限明确通过. 查询 返回时 `null` 仅用于缺额;运输、商业和不良反应 拒绝错误 `FilesError` 而不是返回空列表或错误的成功 .

`createFilesShareAccessService` 处理密码认证和元数据 公用链接在一个共享主线下。 它不能调用账户管理. 主机必须通过服务器端点键入缓存符并共享ID,验证元数据 在进入被保护页面之前,并取消导航变化时的请求.

遗产 `commonShareAPI` 只保留旧的只读上市桥 演示文稿适配器。 其管理和公共认证方法被取消.

### 资源元数据和内容(0.2.4)

`createFilesService(dependencies).metadata` 接受捕获 `FileReference` 对象用于 `getMd5`, (中文(简体) ), `getPermission`, (中文(简体) ), `setPermission`, (中文(简体) ), `usage`, (中文(简体) ), `readText`, (中文(简体) ), `writeText`,以及 `resolveMedia`。 。 。 . `resourceUrl` 构建范围化原始/审查URL; 它是 URL 描述符,而不是 HTTP 请求 。 路径带有生名并编码 一次在 URL 边界。 公共 URL 需要捕获共享主和 当前符号。 ID-aware Google 读取验证路径仍然识别对象 在使用后端基于名的原始端点之前.

每个同步操作都接受 `AbortSignal`,检查范围 在派遣之后,又加以否认 `FilesError` 失败。 缺少元数据从不返回 错误的监视器。 主机拥有通知,必须在 关闭或更改所选文件。 保存时保留打开的引用; 永远不要从后面的选中重建保存的目的地 .

文本读取强制文本响应,所以 JSON 外观内容仍为文字. 写作 保存所提供的文本,包括空内容和周围的白空间. 云内容仍然不支持; 独立的主机功能门和 仍然适用只读权限。 同步媒体元数据解析 `raw_path` 与文本内容分开。 用法消耗了递增的NDJSON并需要 完成标记, 拒绝不正确、 负或短的总数并停止 取消时即时闲置读者.

`Origin.openPreview`, (中文(简体) ), `formatFileContent`, (中文(简体) ), `onSaveFile`,以及 `uploadEmptyFile` 为: 已删除。 其他主机集成仍保留遗留的演示 URL 格式; 文件与LarePass预览/编辑流程使用元数据服务.

## 构建

从寄存器根中运行这些内容, 以便工作空间链接解析 :

```bash
npm install
npm run build --workspace @bytetrade/files-core
npm test --workspace @bytetrade/files-core
```

产出土地 `assets/` (吉他/再生成). 出版部门重建 通过包 `prepack` 钩.

## 0.2 移徙

-   文件v1云账户和直接传输路径被删除. 云账户 通过 `GET /api/accounts`; S3/ Dropbox 下载使用 `/api/raw`。 。 。 . Tencent's removed 直接上载/下载协议 现在升起 `unsupported`。 。 。 . 它的enum和传输元数据格式仍然可供存储行使用.
-   独立共享/共同后端功能门仍由主机提供。 他们 不是替代文件协议.
-   商业失败总是拒绝. `noToast` 仅控制通知; `inspectBusinessError` 不再接受 `throwError`. 上山选举业务 代码300仍然是成功的结果.
-   接着 `FilesError` 检查 `code`, (中文(简体) ), `status`, (中文(简体) ), `businessCode`, (中文(简体) ), `retryable` 财务报告和审定财务报表 `cause`。 。 。 . `ErrorResponse` 现在扩展 `FilesError` 并保留其反应. 注销和账户/端点更改不会产生用户通知.
-   `fetchNodeList` 拒绝失败的请求 。 背景缓存刷新处理它 自己拒绝;等待新地形的呼叫者必须处理失败.
-   新业务合同明确接受 `FileReference` 值,而非活动 浏览器位置或所选索引 。 引用带有源代码、账户 或共享范围、终点和原始路径段或不透明的提供者ID. Google的参考文献需要识别码. `fileReferenceFromLocation` 明确解码 当前路由导向 `FileLocation` 一次; 供应 `resourceId` 为谷歌.
-   文件能力定义于 `types/capabilities`批量作业合同 明确表明部分成功。 新合同提供了基础 用于下一次每次驱动服务迁移; 资源调用者使用范围化服务; 每次驱动代码只使用格式显示数据.

取取文件夹者必须使用匹配的 0.2 释放 。 它使用相同的核心类型 尽管它的UI没有改变,它的独立建立核心.

## 6.2.1 业务服务

`createFilesService` 执行针对本地人的明确业务合同 驱动/数据/Common、节点扫描快取/外部、同步、Google/S3/Dropbox和共享 资源。 提供传送器,电流镜解器和源解器. 复制/移动还需要一个明确的调度-节点解析器。 服务 不读取窗口位置、剪贴板、活动菜单、所选索引或 进度通知。 独立后端功能门仍然是主机能力.

```ts
const service = createFilesService({
  transport,
  scope: currentScope,
  resolveSource: sourceId => sources.get(sourceId),
  nodeForSource: source => source.context.node || masterNode
});
const listing = await service.list({ directory, signal });
await service.createDirectory({ parent: directory, name: 'Documents' });
const result = await service.copy({ files: [listing.entries[0].reference], destination });
// result.pending contains accepted server jobs, not completed copies.
// Register each job with the host's existing task queue; retain result.failed.
```

-   `delete` 组合 **来源和父**,并在 后端报告失败 。 未知的运输故障并不意味着 失败的小组中的任何成员都会成功.
-   `copy`编号 :`move` 返回已接受的工作 `pending`,已完成 `succeeded` 和错误 `failed`。取消和账户/端点更改保持不变 从经营失败。 跨范围引用在发送前被拒绝.
-   变异反应的使用 `FileMutationResult`。空后端写入回复 不要伪造大小/时间戳、相撞后缀名称或新的Google ID。 刷新打电话者 变异后的明确目录; `refresh` 可在产生时提供.
-   Google 参考文献保持其不透明的ID,可选原始 `pathSegments` v2 基于路径的写法需要。 支持只列出ID目录列表. 基于路径的Google突变验证独有性和被捕获的ID第一; 2; 模糊名称失败 `conflict` 而不是选择任意的对象. 身份识别重命名通行证 `driveId` 转到后端.
-   公共股票需要匹配的股票本金和每个请求的令牌. 撤销股份仍然是单独的股份管理业务;这绝不意味着 删除共享源文件 。 十分钱仍然得不到支持.
-   `Origin` 及其子类不再暴露 `copy`, (中文(简体) ), `paste`, (中文(简体) ), `move`, (中文(简体) ), `action`, (中文(简体) ), `createDir`, (中文(简体) ), `renameItem` 或者说 `deleteItem`。旧的通知相连接的粘贴 删除执行器 。 使用服务并让主机自行通知/任务.

`FilesResourceListing.providerData` 是用于 现有的主机格式化器。 它不会改变服务身份或操作 参数。 菜单/存储/节点弹壳,显示格式并浏览会议 国家有意在资源服务之外单独迁移. 取取文件夹者使用匹配的0.2.7放出和对等依赖.

### 议定书清理(0.2.7)

`Origin`, (中文(简体) ), `DriveAPI`, (中文(简体) ), `dataAPIs`,则 `files`编号 :`seahub` 命名空间,以及过时的 CRUD,库,账号,共享列表和使用桥接被删除. 选择 `createDriveProtocol(driveType, options)` 带有明确的驱动类型。 协议只转换路径,URL和传输演示文稿数据;它们不读取页面状态,提出请求,选择节点或触摸DOM. 选项抓取端点,共享符号,库名和主机模式. 文件夹上载元数据明确接收其父传输.

使用 `createFilesService` 用于资源和元数据, `createFilesShareService` 分享,和 `createFilesInfrastructureService` 账户业务. `createFilesUploadService` 接受带有被捕获的节点/图书馆的有范围上传目标,并处理上传链接并恢复取消和范围检查的抵消。 主机代码拥有文件选择,寄存器导航,任务完成更新和归档任务协调. 归档密码提示和任务传输仍在 `ArchiveAPI` 等待单独的档案服务迁移。 独立的地物出入口不变.

### 档案和ACL服务(0.2.8)

`createFilesService(deps).archive` 拥有压缩、取出、流出条目和条目文本/blob读取。 输入使用 `FileReference` 身份,输出任务包括其范围和节点,可选节点引用必须匹配文件的自有节点. 支持本地驱动器; 任务不能跨越缓存/ 外部节点 。 独立 `archiveEnabled` callback 保留服务器特性 gating 。 名称是原始资源名称; 字符% 序列不再被解码 .

归档请求从不打开对话框、重试密码或显示通知 。 主机捕获了密码业务代码,并重试了相同的捕获操作. 预览消费者接受NDJSON/SSE记录,在召回和身体完成前检查身份,在完成记录时停止,在流产时取消阅读器. 密码只在请求头中行走 .

`createFilesService(deps).acl` 读取和更新顶级通用/外部目录访问。 它验证目标身份,响应条目和赠款,并共享资源服务的取消,范围检查和出错合同. 纯洁 `isAclTopLevel` 财务报告和审定财务报表 `isAclManager` 援助人员可以继续工作。 主机将缓存用户列表绑入账户并装入它们的端点.

`ArchiveAPI`, (中文(简体) ), `getAcl`, (中文(简体) ), `updateAcl`, (中文(简体) ), `loadAclManager`, (中文(简体) ), `fetchUserList` 和全球 `onNeedPassword` 配置调用已被删除 。 应用程序协调员拥有密码提示,请求寿命和任务队列持续性.

### 空挂载历史 (0. 2. 9)

`mounts.history` 接受后端 `null` 空历史响应和返回 `[]`。空数组仍然有效;网络故障和错误的历史记录仍然拒绝。 匹配 [文件拾取器-wc@0.2.9](mailto:files-picker-wc@0.2.9) 发布将移动选择器与主应用 UI相匹配.

## 常见问题

### @bytetrade/files-core 是什么？

文件 API 类型、 传输和浏览会话—— 无框架

### 如何安装 @bytetrade/files-core？

在项目目录运行 npm install @bytetrade/files-core，或使用 pnpm add / yarn add / bun add。

### @bytetrade/files-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bytetrade/files-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bytetrade/files-core 可以商用吗？

@bytetrade/files-core 使用 GPL-3\.0-or-later 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以 GPL-3\.0 兼容许可开源，并附带专利与反锁定条款。仅内部使用不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @bytetrade/files-core 的下载量有多少？

根据 npm 官方下载统计，@bytetrade/files-core 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,144 次，日均约 71 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bytetrade/files-core 还在维护吗？

最新版本 0\.2\.9 发布于 2026/10/28（11 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。