# @apollo/explorer 中文文档

规范地址：https://npmcn.com/package/%40apollo/explorer/

版本：3\.7\.4
npm 元数据更新时间：2026-01-22T17:29:59.253Z
中文译文更新时间：2026-11-06T11:03:19.703Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apollo/explorer
原文对照：https://npmcn.com/package/%40apollo/explorer/?lang=original
项目主页：https://github.com/apollographql/embeddable-explorer/explorer#readme
源码仓库：https://github.com/apollographql/embeddable-explorer/explorer

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

- 包体积（解压后）：188 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，use-deep-compare-effect ^1\.8\.1
- 首次发布：2022-02-25T17:04:36.173Z
- 最新版本发布：2025-09-30T19:05:52.911Z
- 近 30 天下载量：26901（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 0 个）

## 中文简介

此 repo 主机为 Aporo Studio 的可嵌入探索器的源文件

## 安装

```sh
npm install @apollo/explorer
```

也可以使用：`pnpm add @apollo/explorer`、`yarn add @apollo/explorer`、`bun add @apollo/explorer`

## README

# 阿波罗工作室可嵌入式探索器

此 repo 主机为 Aporo Studio 的可嵌入探索器的源文件

[使用详情见文件](https://www.apollographql.com/docs/studio/embed-explorer/)

## 使用 [@ apollo/ 探索 npm 软件包](https://www.npmjs.com/package/@apollo/explorer)

您可以下载 @ apollo/ explorer npm 软件包 `npm install @apollo/explorer`。然后,可以导入阿波罗爆炸类或阿波罗爆炸等组件:

```
import { ApolloExplorer } from '@apollo/explorer';
import { ApolloExplorer } from '@apollo/explorer/react';
```

当你呼叫嵌入式爆炸器 构造器与一个 `target` 您的应用程序中的 html div 中, 探索者将在此元素中以 iframe 显示 。 检查所有的 [配置选项](https://www.apollographql.com/docs/studio/explorer/embed-explorer/#options) 你的图表.

### 反应

```
import { ApolloExplorer } from '@apollo/explorer/react';

function App() {

  return (
    <ApolloExplorer
      graphRef='acephei@current',
      endpointUrl='https://acephei-gateway.herokuapp.com',
      initialState={{
        document: `query Example {
me {
  id
}
}`,
        variables: {
          test: 'abcxyz',
        },
        displayOptions: {
          showHeadersAndEnvVars: true,
        },
      }}
    />
  );
}
```

### 香草联署材料

```
import { ApolloExplorer } from '@apollo/explorer';

function App() {

  ...
  new ApolloExplorer({
      target: '#embeddableExplorer',
      graphRef: 'acephei@current',
      endpointUrl: 'https://acephei-gateway.herokuapp.com',
      initialState: {
        document: `query Example {
me {
  id
}
}`,
        variables: {
          test: 'abcxyz',
        },
        displayOptions: {
          showHeadersAndEnvVars: true,
        },
      },
  })
  ...

}

...
// style the iframe for your site
<style>
  iframe {
    height: 100%;
    width: 100%;
    border: none;
  }
</style>
<div id="embeddableExplorer" />
```

### 原始 cdn 主机 umd 文件的实例

-   [嵌入已注册的公共图](https://npmcn.com/package/%40apollo/explorer/src/examples/graphRef.html)
-   [直接通过计划使用](https://npmcn.com/package/%40apollo/explorer/src/examples/manualSchema.html)

## 开发嵌入式探索器

`cd` 输入 `packages/explorer` 运行 `npm run build:umd` 用于构建嵌入式爆炸器在窗口被曝光的 umd 文件.

打开 `examples/embeddedExplorer/localDevelopmentExample.html` 测试您的变化。 (如果来源未设定, 请运行本地DevelopmentExample.html from `Live Server`(中文(简体) )

安装 `Live Server` 扩展到 `localDevelopmentExample.html` 点击“Go Live” ![Screen Shot 2022-04-27 at 4 34 53 PM](https://user-images.githubusercontent.com/16390269/165626464-8252abcd-2577-4d97-90a8-f487da807a64.png)

### 以反应为例开发嵌入式探索器

`cd` 输入 `packages/explorer` 运行 `npm run build:cjs-esm` 来构建 Cjs & esm 文件,其中阿波罗Explorer & 阿波罗Explorer React 被命名为导出.

我们有一个反应例应用, 使用我们的阿波罗爆炸器反应组件 使嵌入式探索器 位于src/examples/ react-example。 举个例子, `npm run build` 财务报告和审定财务报表 `npm run start` 内 `react-example`。在重建新的更改前,请确保删除 .parcel-cache 文件夹。 (TODO去掉包裹缓存)

### 序列图

#### 直接通过计划连接到未注册的图表

```mermaid
sequenceDiagram
    participant Parent as Parent Page
    participant Embed as Embedded Explorer

    note over Parent: Render iframe loading embed and start listening for messages.
    Parent->>Embed: Embed loads with initial state <br>(gql operation, variables, headers, persistence preference etc) <br>in the query params of the iframe.
    note over Embed: Loaded and sets initial state<br> from query params.
    note over Embed: Start listening for messages

    Embed->>Parent: Handshake message asking for schema
    Parent->>Embed: Responds with schema

    note over Embed: Loads in given schema to explorer

    Embed --> Parent: Set up finished
    
    note over Embed: User submits operation
    Embed->>Parent: Send request contents
    note over Parent: Makes actual network request via `handleRequest()`
    Parent->>Embed: Send network response back
    note over Embed: Processes and renders response
```

#### 通过认证连接到已注册的图表

```mermaid
sequenceDiagram
    participant Parent as Parent Page
    participant Embed as Embedded Explorer
    participant Login as Studio Login Page at <br>studio.apollographql.com

    note over Parent: Render iframe loading embed and start listening for messages.
    Parent->>Embed: Embed loads with initial state <br>(gql operation, variables, headers, persistence preference etc) <br>in the query params of the iframe.
    note over Embed: Loaded and sets initial state<br> from query params.
    note over Embed: Start listening for messages

    Embed->>Parent: Handshake message asking for graphRef, <br>account id & account invite token if provided
        
    Parent->>Embed: Responds with graphRef, account id, account invite token

    Embed->>Parent: Authentication message asking for second half of<br> authentication token from parent page local storage

    alt when parent page has authentication token or graph is public
        Parent->>Embed: Responds with half auth token<br> from parent page local storage
    else when parent page doesn't have authentication token
        note over Embed: Renders login page
        note over Embed: User clicks 'login' on embed
        Embed ->>Login: Embed opens a new tab to <br>login page via window.open
        note over Login: Asks user to authenticate and<br> authorize this embed to use account
        note over Login: User accepts
        note over Login: Login page generates new <br>Studio API Key for this user
        Login ->> Embed: Sends Studio API Key over <br>postMessage via window.opener
        note over Embed: Splits key in 2, <br>stores half in local storage
        Embed ->> Parent: Sends other half of key to parent page
        note over Parent: Stores half of key in local storage
        Parent->>Embed: Responds with half auth token<br> from parent page local storage
    end


    note over Embed: Merges half key from parent page & half from embed local storage. <br>Uses this key for all future requests to Studio backend.

    note over Embed: Loads in schema & operation <br>collections for given graphRef from Studio servers

    Parent --> Login: Set up finished
    
    note over Embed: User submits operation
    Embed->>Parent: Send request contents
    note over Parent: Makes actual network request via `handleRequest()`
    Parent->>Embed: Send network response back
    note over Embed: Processes and renders response
```

## 常见问题

### @apollo/explorer 是什么？

此 repo 主机为 Aporo Studio 的可嵌入探索器的源文件

### 如何安装 @apollo/explorer？

在项目目录运行 npm install @apollo/explorer，或使用 pnpm add / yarn add / bun add。

### @apollo/explorer 支持 TypeScript 吗？

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

### @apollo/explorer 支持 ESM 还是 CommonJS？

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

### @apollo/explorer 可以商用吗？

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

### @apollo/explorer 的下载量有多少？

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

### @apollo/explorer 还在维护吗？

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