# @apollosproject/canvas-embeds 中文文档

规范地址：https://npmcn.com/package/%40apollosproject/canvas-embeds/

版本：2\.1\.2951
npm 元数据更新时间：2026-11-07T03:26:15.536Z
中文译文更新时间：2026-11-06T11:02:02.107Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apollosproject/canvas-embeds
原文对照：https://npmcn.com/package/%40apollosproject/canvas-embeds/?lang=original
项目主页：https://github.com/ApollosProject/apollos-admin#readme
源码仓库：https://github.com/ApollosProject/apollos-admin

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

- 包体积（解压后）：8.6 MB，4 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：32 个
- 首次发布：2025-02-07T14:28:57.210Z
- 最新版本发布：2026-11-07T03:26:15.367Z
- 近 30 天下载量：63651（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：2951（近 12 个月 2280 个）

## 中文简介

阿波罗反弹嵌入部件

## 安装

```sh
npm install @apollosproject/canvas-embeds
```

也可以使用：`pnpm add @apollosproject/canvas-embeds`、`yarn add @apollosproject/canvas-embeds`、`bun add @apollosproject/canvas-embeds`

## README

# 阿波罗嵌入

阿波罗回放 Embeds 是预建的,可再使用的组件,旨在无缝地整合入Webflow等第三方网站. 这些部件为认证、内容输入和搜索功能提供了功能,创造了跨平台的统一和互动的用户经验.

* * *

## 从阿波罗嵌入开始

### 1\. 在您的网站上添加脚本标记

为了启用"阿波罗之嵌入",在您的网站代码中包含以下脚本和样式表. 对于Webflow用户,请将其添加到 **自定义代码** 下一节 **页脚代码**数字 :

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.css"
/>
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
></script>
```

### 3\. 了解嵌入模式

阿波罗嵌入式有三种主要模式:

-   阿波罗站点模式
-   容器模式
-   遗留模式

#### 阿波罗站点模式

在阿波罗斯站点模式中,所有站点都嵌入了外部阿波罗站点的链接. 该模式被推荐给希望保持跨平台的一致用户体验的用户,它是所有嵌入的默认模式.

#### 容器模式

在集装箱模式中,在主机网站的集装箱内显示嵌入层. 这个模式被推荐给那些想要在提供阿波罗函数的同时将用户保留在自己网站上的用户. 该模式还使用户能够将阿波罗斯的内容清理地整合到他们的网站上,同时应用自定义风格.

为启用容器模式,添加 `data-apollos-path="/apollos"` 脚本标签属性 :

```html
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-route="/apollos"
></script>
```

在主机网站上,浏览任何种子或内容将导航到 `/apollos` 路径。 此路径( 可自定义) 应包含 `div` 带身份证 `apollos-widget-container` 以显示嵌入内容。 这个容器的样式应与主机网站的设计相匹配.

#### 遗留模式

在"遗产模式"(Legacy Modal Mode)中,嵌入在主机网站上的模式窗口中显示. 这个模式被推荐给那些想要在提供阿波罗函数的同时将用户保留在自己网站上的用户. 所有嵌入将显示在一个模式窗口中,通过URL搜索参数跟踪导航状态.

要启用遗留模式,请添加 `data-apollos-modal="true"` 脚本标签属性 :

```html
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-modal="true"
></script>
```

### 4\. 添加嵌入式集装箱

导航到您的站点构建器( 如 Webflow)并添加一个 `div` 用于您计划使用的每个嵌入的元素。 支持嵌入 :

-   Auth – 用户认证
-   特色Feed——配乐内容素材
-   搜索 — 经典 Algolia 搜索和配置 UI

每个 `div` 必须包括 `apollos-widget` 课.

示例

```html
<!-- Auth -->
<div class="apollos-widget" data-type="Auth" data-church="example_church"></div>

<!-- FeatureFeed -->
<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
></div>

<!-- Search (Algolia) -->
<div
  class="apollos-widget"
  data-type="Search"
  data-hide-apollos-auth="true"
  data-church="example_church"
  data-search-profile-size="365px"
></div>

```

![Webflow embed example](https://user-images.githubusercontent.com/2528817/231847323-53430bca-f2fd-4d2c-b7ee-90948fb694b5.png)

* * *

### 5\. 自定义带有属性的嵌入物

使用 `data-attributes` (或 **自定义属性** 在Webflow中),以自定义每个嵌入体的行为和外观.

| **属性** | **说明** |
| --- | --- |
| `data-type` | 其中一个: `Auth`, (中文(简体) ), `FeatureFeed`, (中文(简体) ), `Search`。 。 。 . |
| `data-church` | 教会弹壳(例如, `bayside`) (中文(简体) ). |
| `data-search-profile-size` | (Search) 剖面模式的宽度. |
| `data-hide-apollos-auth` | (Search) 隐藏剖面/auth UI. |
| `data-feature-feed` | (FeatureFeed) 种子的ID来显示. |

嵌入的地物示例:

```html
<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
  data-feature-feed="FeatureFeed:unique-id"
  data-modal="true"
></div>
```

![Auth embed attributes](https://user-images.githubusercontent.com/2528817/231847542-aa13eb07-2d7f-400b-bec5-3983ef3ac559.png)

![FeatureFeed embed attributes](https://user-images.githubusercontent.com/2528817/231847773-9698dc62-3ca8-4814-ad33-63204fb5f625.png)

* * *

### 6\. 理解教会障碍

教堂的弹壳独有地识别显示内容的组织. 如果你不确定你的弹壳,请联系开发商或管理员.

> \[注\] 替换 `[INSERT_CHURCH_SLUG_HERE]` 与您的教堂的独特标识(或 **弹片**) (中文(简体) ). 需要帮助获得教堂涕丸的,联系开发商.

* * *

## 对于开发者

### 背景情况

这个软件包原本是 [`apollos-embeds`](https://github.com/ApollosProject/apollos-embeds) 数据库,涉及前端代码、组件和GraphQL查询的重大重复。 为了统一我们的网络前端开发,我们创造了 `canvas-ui-web` 作为 [组件库](https://github.com/ApollosProject/apollos-admin/blob/dc2bb76699dcef8a6cdc67922f63c0b9eb08e594/packages/canvas-ui-web)编辑 `apollos-embeds` 项目已移入此存储库,以便与我们的其他网络平台共存.

原始版本为 `web-embeds` 在很大程度上依赖于模式表述。 这个新软件包保留了模式的选择性使用,同时鼓励用户导航到运行于此的阿波罗微站点 [新网页](https://github.com/ApollosProject/apollos-admin/blob/dc2bb76699dcef8a6cdc67922f63c0b9eb08e594/apps/web)。 。 。 .

### 如何运作

嵌入被捆绑为 `index.js` 财务报告和审定财务报表 `index.css` 输入 `/widget` 文件夹,并通过 jsDelivr 分发。 通过将这些内容纳入网页,用户可以访问这些嵌入地. 设置 `apollos-widget` 页面上的 div 触发了网络嵌入功能.

* * *

### 地方发展

要在本地操作此软件包, 请确保您有有效的 **特性种子标识**启用 `index.html` 以实例进行测试。 记住在同一页上嵌入来自不同教堂的会引发冲突,所以确保每页只使用一所教堂. 你应该跑 `apollos-cluster` 以及这整个回放 通过运行 `yarn dev`。 。 。 .

#### 本地测试嵌入

使用 `index.html` 用于测试的文件。 打开 `http://localhost:5174` 在浏览器中查看更改.

嵌入测试的示例 :

```html
<div
  data-type="FeatureFeed"
  data-church="apollos_demo"
  data-feature-feed="FeatureFeed:caf294f0-cd0e-4486-95e7-fa11bd5fb1c5"
  data-modal="true"
  class="apollos-widget"
></div>
```

要测试更改, 打开 `http://localhost:5174` 在您的浏览器中.

* * *

### 发布更新/ 快取缓存

此软件包在合并到主机时自动部署. 如果您希望手动部署:

1.  `cd apps/web-embeds`
2.  跳出版本( 默认 patch ) : `yarn bump` (或 `yarn bump:minor` 编号 : `yarn bump:major`) (中文(简体) ). 您可能想咨询国家防范机制,以检查上一个部署的版本(它将与软件包.json中的版本不同).
3.  发布软件包 : `npm publish --access public` (自动运行) `prepublishOnly`/建设)
4.  Npm 显示新版本后, 清洗 jsDelivr so `@latest` 立即更新 : `yarn flush`
5.  (可选)点击 `https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.js` 以验证新捆绑已送达

跳过发布步骤意味着即使repo包含更新的代码,用户仍然会下载上个版本,并跳过冲洗步骤会延迟传播直到jsDelivr的缓存到期.

* * *

### 缓存

为了在本地开发中测试缓存,请通过注释 : `x-cache-me-not` 标题在 :

[src/客户/apolos ApiLink.js (中文(简体) )](https://npmcn.com/package/%40apollosproject/canvas-embeds/src/client/apollosApiLink.js)

```javascript
'x-cache-me-not': 1,
```

### jsDelivr 缓存中断

如果您需要强制 jsDelivr 获取文件的最新版本, 您可以通过访问文件 URL 的子域来手动清除缓存 。 此命令从 jsDelivr 的 CDN 中清除文件的缓存版本 .

```bash
yarn flush
```

* * *

### 高级配置

#### 支持的嵌入和属性

| **嵌入类型** | **密钥属性** |
| --- | --- |
| `Auth` | `data-church` |
| `FeatureFeed` | `data-church`, (中文(简体) ), `data-feature-feed` |
| `Search` | `data-church`, (中文(简体) ), `data-search-profile-size` |
|  | `data-hide-apollos-auth` |

#### 路径运行

对于高级路由选项,使用:

-   `data-use-path-router="true"` 用于启用基于路径的路由.
-   `data-apollos-id-param="true"` 用于自定义的ID处理.

## 常见问题

### @apollosproject/canvas-embeds 是什么？

阿波罗反弹嵌入部件

### 如何安装 @apollosproject/canvas-embeds？

在项目目录运行 npm install @apollosproject/canvas-embeds，或使用 pnpm add / yarn add / bun add。

### @apollosproject/canvas-embeds 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apollosproject\_\_canvas-embeds 是否存在。

### @apollosproject/canvas-embeds 支持 ESM 还是 CommonJS？

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

### @apollosproject/canvas-embeds 可以商用吗？

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

### @apollosproject/canvas-embeds 的下载量有多少？

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

### @apollosproject/canvas-embeds 还在维护吗？

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