# @epilot/journey-embed-sdk 中文文档

规范地址：https://npmcn.com/package/%40epilot/journey-embed-sdk/

版本：0\.5\.0
npm 元数据更新时间：2026-11-10T09:29:09.447Z
中文译文更新时间：2026-11-13T23:53:47.046Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40epilot/journey-embed-sdk
原文对照：https://npmcn.com/package/%40epilot/journey-embed-sdk/?lang=original
项目主页：https://docs.epilot.io/docs/journeys/sdk
源码仓库：https://gitlab.com/e-pilot/product/journey/journey-embed

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

- 包体积（解压后）：184 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-04-22T10:41:18.355Z
- 最新版本发布：2026-06-10T14:56:22.538Z
- 近 30 天下载量：2832（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

在外部网站上嵌入电子驾驶跑道的流利构建器 SDK 支持

## 安装

```sh
npm install @epilot/journey-embed-sdk
```

也可以使用：`pnpm add @epilot/journey-embed-sdk`、`yarn add @epilot/journey-embed-sdk`、`bun add @epilot/journey-embed-sdk`

## README

# @ epilot/ journey- embed- sdk

用于嵌入的流利构建器 SDK [电子驾驶](https://epilot.cloud/) 外出网站的出行. 支持单个可链式API后的两个渲染后端:

-   **`<iframe>`** ——加强风格隔离,一行多行.
-   **`<epilot-journey>` 网络组件** ——在"阴影DOM"中使性能和无障碍性得到更好的提升.

## 安装

```bash
npm install @epilot/journey-embed-sdk
# or
yarn add @epilot/journey-embed-sdk
# or
pnpm add @epilot/journey-embed-sdk
```

## 使用量

### Bundler (ESM / CJS) (英语)

```ts
import { Epilot } from '@epilot/journey-embed-sdk'

const $epilot = new Epilot()

$epilot
  .embed('<your-journey-id>')
  .asWebComponent()
  .mode('inline')
  .append('#embed-target')
```

### 反应(有参考文献)

安置方法`append`, (中文(简体) ), `prepend`, (中文(简体) ), `before`, (中文(简体) ), `after`)接受CSS选择器 **或者说** 一个直接 `HTMLElement`。这意味着你可以通过 `ref.current` 不需要给目标一个身份或阶级.

```tsx
import { useEffect, useRef } from 'react'
import { Epilot, type Embedding } from '@epilot/journey-embed-sdk'

const $epilot = new Epilot()

export function JourneyEmbed({ journeyId }: { journeyId: string }) {
  const targetRef = useRef<HTMLDivElement | null>(null)
  const embeddingRef = useRef<Embedding | null>(null)

  useEffect(() => {
    if (!targetRef.current) return

    embeddingRef.current = $epilot
      .embed(journeyId)
      .asWebComponent()
      .mode('inline')
      .append(targetRef.current)

    return () => {
      embeddingRef.current?.remove()
      embeddingRef.current = null
    }
  }, [journeyId])

  return <div ref={targetRef} />
}
```

这个 `.remove()` 在清理中调用元素并撕下所有的 SDK 听器, 所以组件是安全的挂载, 卸载, 并重挂而不漏出.

### 通过 CDN 浏览器

同步 :

```html
<script src="https://embed.journey.epilot.io/sdk/bundle.js"></script>
<script>
  $epilot.embed('<your-journey-id>').asWebComponent().append('#embed-target')
</script>
```

同步——使用 `onReady` 队列使您的页面可以不阻塞地加载 SDK :

```html
<head>
  <script>
    ;(function (h, o, u, n, d) {
      h = h[d] = h[d] || {
        q: [],
        onReady: function (c) {
          h.q.push(c)
        }
      }
      d = o.createElement(u)
      d.async = 1
      d.src = n
      n = o.getElementsByTagName(u)[0]
      n.parentNode.insertBefore(d, n)
    })(
      window,
      document,
      'script',
      'https://embed.journey.epilot.io/sdk/bundle.js',
      '$epilot'
    )
  </script>
</head>
<body>
  <!-- rest of your page -->
  <script>
    window.$epilot.onReady(function (epilot) {
      epilot.embed('<your-journey-id>').asWebComponent().append('#embed-target')
    })
  </script>
</body>
```

## API 密码

见文件全文 [docs.epilot.io/docs/journeys/sdk](https://docs.epilot.io/docs/journeys/sdk)。 。 。 .

### 快速引用

| 方法 | 目的 |
| --- | --- |
| `.asIframe()` 编号 : `.asWebComponent()` | 选后端. |
| `.mode('inline' | 'full-screen')` | 显示模式 。 默认为 `inline`。 。 。 . |
| `.topBar(bool)` | 显示/隐藏了Journey上行栏. |
| `.scrollToTop(bool)` | 在步道导航上向上滚动. |
| `.closeButton(bool)` | 显示/隐藏关闭按钮 . |
| `.contextData({...})` | 将关键/价值数据传送给旅游。 接受 `string` 或者说 `number` 值(数被强制字符串). |
| `.dataInjectionOptions({...})` | 预填字段和/或设置起步步. |
| `.name(string)` | 嵌入元素的可访问名称 . |
| `.testId(string)` | 设定 `data-testid` 测试的元素. |
| `.id(string)` | 设定 `id` 关于元素。 安置前打电话. |
| `.isFullScreenEntered(bool)` | 进入/退出全屏程序. |
| `.append` 编号 : `.prepend` 编号 : `.before` 编号 : `.after` | DOM定位——链条末端. |
| `.el()` | 返回被注入的元素. |
| `.remove()` | 删除元素并拆掉听众 . |

### 配置

`new Epilot(options?)` 接受:

| 选项 | 类型 | 默认 | 目的 |
| --- | --- | --- | --- |
| `baseUrl` | `string` | `'https://journey.epilot.io'` | Journey应用软件的基础 URL. |
| `webComponentScriptUrl` | `string` | —— 说 | 明确覆盖 `<epilot-journey>` 脚本 URL. 在本地 dev 中有用 . |
| `debug` | `boolean` | `false` | 启用 `iframe-resizer` 动词伐木. |

## 许可证

麻省理工学院电子驾驶股份有限公司

## 常见问题

### @epilot/journey-embed-sdk 是什么？

在外部网站上嵌入电子驾驶跑道的流利构建器 SDK 支持

### 如何安装 @epilot/journey-embed-sdk？

在项目目录运行 npm install @epilot/journey-embed-sdk，或使用 pnpm add / yarn add / bun add。

### @epilot/journey-embed-sdk 支持 TypeScript 吗？

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

### @epilot/journey-embed-sdk 支持 ESM 还是 CommonJS？

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

### @epilot/journey-embed-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @epilot/journey-embed-sdk 可以商用吗？

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

### @epilot/journey-embed-sdk 的下载量有多少？

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

### @epilot/journey-embed-sdk 还在维护吗？

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