# @graphiql/plugin-collections 中文文档

规范地址：https://npmcn.com/package/%40graphiql/plugin-collections/

版本：1\.0\.1
npm 元数据更新时间：2026-11-02T02:59:33.114Z
中文译文更新时间：2026-11-16T22:49:35.251Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40graphiql/plugin-collections
原文对照：https://npmcn.com/package/%40graphiql/plugin-collections/?lang=original
项目主页：https://github.com/graphql/graphiql/tree/master/packages/graphiql-plugin-collections#readme
源码仓库：https://github.com/graphql/graphiql

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

- 包体积（解压后）：231 kB，58 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18 \|\| ^19，graphql ^16\.11\.0 \|\| ^17\.0\.0，react-dom ^18 \|\| ^19，@graphiql/react ^1\.0\.1
- 首次发布：2026-08-29T16:05:36.399Z
- 最新版本发布：2026-11-02T02:59:32.799Z
- 近 30 天下载量：57562（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

GraphiQL 的一端操作收藏插件 .

## 安装

```sh
npm install @graphiql/plugin-collections
```

也可以使用：`pnpm add @graphiql/plugin-collections`、`yarn add @graphiql/plugin-collections`、`bun add @graphiql/plugin-collections`

## README

# @ graphiql/ 插件收藏

GraphiQL 的一端操作收藏插件 。 将命名的 GraphQL 操作保存到收藏中, 并在稍后再使用它们, 并进行拖放重排, 剪贴板共享, 以及 JSON 导入/ 导出, 用 id 合并而不是复制 .

## 安装

```sh
npm install @graphiql/plugin-collections
```

确保端点的依赖性也被安装 :

```sh
npm install react react-dom graphql @graphiql/react
```

## 使用量

收藏插件默认在 GraphiQL 中安装, 所以未修改 `<GraphiQL>` 已显示收藏栏图标。 使用 `COLLECTIONS_PLUGIN` 当你通过一个习惯 `plugins` 阵列并想要保留默认的收藏配置。 使用 `collectionsPlugin(options)` 以提供自定义存储后端或限制用户可以做什么.

> **说明:** 传递 `plugins` 道具取代了默认的插件集,所以包括您想要的其他插件.

```jsx
import { GraphiQL } from 'graphiql';
import { createTransport } from '@graphiql/toolkit';
import { COLLECTIONS_PLUGIN } from '@graphiql/plugin-collections';
import 'graphiql/style.css';
import '@graphiql/plugin-collections/style.css';

const transport = createTransport({
  url: 'https://swapi-graphql.netlify.app/.netlify/functions/index',
});

function GraphiQLWithCollections() {
  return <GraphiQL transport={transport} plugins={[COLLECTIONS_PLUGIN]} />;
}
```

## 选项

```ts
collectionsPlugin({
  storage, // custom persistence backend; see below
  readOnly, // default false
  allowImportExport, // default true
  allowReplace, // default true
});
```

| 选项 | 默认 | 效果 |
| --- | --- | --- |
| `storage` | 本地调试器 | 习惯 `CollectionsStorage` (见 [自定义存储](https://npmcn.com/package/%40graphiql/plugin-collections/#readme-custom-storage)) (中文(简体) ). |
| `readOnly` | `false` | 隐藏每个写入负担( 创建、 重命名、 删除、 重排序、 保存、 导入) 。 导出和复制保存可用,这样用户仍然可以共享. |
| `allowImportExport` | `true` | 何时 `false`,隐藏导入/导出对话框按钮并关闭粘贴/投放导入. |
| `allowReplace` | `true` | 何时 `false`,隐藏破坏性的"取代一切"导入模式,并只保留合并. |

## 导入和合并行为

收藏品及其内的操作都带有稳定的UUID来活过进出口. 导入时, 插件会用 id 来调节, 而不是重复 :

-   新增行动. 一个你已经拥有的操作 被更新在任何你保存它的地方, 即使你已经移动到不同的收藏。 缺失的父收藏被重新创建 .
-   重新导入一个不变的导出没有任何作用,所以你永远不会得到复制件.
-   当收到的操作与本地副本不同时, 对话框会允许您应用修改, 保存您的版本, 或一次审查每个操作 。 合并从不删除 .

一个操作也可以自己与"Copy操作"共享. 它作为一品收发信封出行,并用其母收发信封印出,因此收发信人可以在进口时重新收发.

## 自定义存储

持久性可以通过 `CollectionsStorage` 接口 :

```ts
type CollectionsStorage = {
  storageKey?: string;
  load(): Promise<Collection[]>;
  save(collections: Collection[]): Promise<void>;
};
```

默认写到 `localStorage` 键下 `graphiql:collections`。要使用不同的密钥,请通过导出时的适配器 `createLocalStorageAdapter` 工厂:

```ts
import {
  collectionsPlugin,
  createLocalStorageAdapter,
} from '@graphiql/plugin-collections';

const collections = collectionsPlugin({
  storage: createLocalStorageAdapter('my-key'),
});
```

用自己的服务(REST,一个数据库,一个团队共享的商店)支持收藏,执行接口并传出为 `storage`数字 :

```ts
import { collectionsPlugin } from '@graphiql/plugin-collections';
import type {
  Collection,
  CollectionsStorage,
} from '@graphiql/plugin-collections';

const apiStorage: CollectionsStorage = {
  async load() {
    const res = await fetch('/api/collections');
    return (await res.json()) as Collection[];
  },
  async save(collections) {
    const response = await fetch('/api/collections', {
      method: 'PUT',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(collections),
    });
    if (!response.ok) {
      throw new Error(`Saving collections failed (${response.status})`);
    }
  },
};

const collections = collectionsPlugin({ storage: apiStorage });
```

`load()` 当面板首次挂起时运行一次. `save()` 在突变后收到完整的收藏列表。 对于工具栏或键盘保存,其承诺必须在写入承诺后解决. 拒绝会使操作变得肮脏并显示GraphiQL中的一个错误. 其他收藏编辑动作仍然会立即更新UI.

### 团队共享后端和同步

该插件对冲突解决或同步没有意见; 它存在于您的存储适配器中 。 因为每次操作和收集都有一个稳定的ID,你的适配器可以相接地播放 `save()` 然而,无论这是否是一个简单的后端写作,还是最后写成的政策,还是像Yjs 或 Autommerge 这样的 CRDT , 都需要作出快照和调和。 插件本身在可序列模型上保留 CRUD UI.

该插件不会自行对远程更改作出反应. 当您的后端报告外部变化时, 请打电话 `reload()` 重读存储并刷新 UI :

```ts
import { collectionsStore } from '@graphiql/plugin-collections';

await collectionsStore.getState().actions.reload();
```

## 程序访问

该商店及其反应钩被导出用于程序访问:

```ts
import {
  collectionsStore, // the vanilla zustand store
  useCollectionsStore, // React hook: useCollectionsStore(selector)
} from '@graphiql/plugin-collections';

const { actions } = collectionsStore.getState();

// Replace the in-memory collections (e.g. after merging remote state).
// Does NOT write back to storage.
actions.setCollections(nextCollections);

// Re-read from the configured storage and refresh the UI.
await actions.reload();
```

`actions` 还暴露了整个 CRUD 表面( 第 1 段)`createCollection`, (中文(简体) ), `addItem`, (中文(简体) ), `updateItem`, (中文(简体) ), `deleteItem`, (中文(简体) ), `moveItem`, (中文(简体) ), `renameCollection`,等等) `exportCollections` 编号 : `exportCollection` 编号 : `exportItem` 和两个阶段 `analyzeImport` 编号 : `applyImport`。 。 。 .

## 出口

-   `COLLECTIONS_PLUGIN` ——默认插件配置
-   `collectionsPlugin(options?)` — 自定义配置的插件厂
-   `collectionsStore`, (中文(简体) ), `useCollectionsStore` - 商店及其反应钩
-   `createLocalStorageAdapter(key)`, (中文(简体) ), `localStorageAdapter` 内置储存
-   `CollectionsSaveDialog` — 保存对话框组件
-   类型 : `Collection`, (中文(简体) ), `CollectionItem`, (中文(简体) ), `CollectionsStorage`, (中文(简体) ), `CollectionsConfig`, (中文(简体) ), `ActiveOperation`

## 常见问题

### @graphiql/plugin-collections 是什么？

GraphiQL 的一端操作收藏插件 \.

### 如何安装 @graphiql/plugin-collections？

在项目目录运行 npm install @graphiql/plugin-collections，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）、graphql（^16\.11\.0 \|\| ^17\.0\.0）、react-dom（^18 \|\| ^19）、@graphiql/react（^1\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @graphiql/plugin-collections 支持 TypeScript 吗？

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

### @graphiql/plugin-collections 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @graphiql/plugin-collections 可以商用吗？

@graphiql/plugin-collections 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @graphiql/plugin-collections 的下载量有多少？

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

### @graphiql/plugin-collections 还在维护吗？

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

