# @gobistories/gobi-web-integration 中文文档

规范地址：https://npmcn.com/package/%40gobistories/gobi-web-integration/

版本：6\.19\.13
npm 元数据更新时间：2026-10-16T07:37:48.148Z
中文译文更新时间：2026-11-16T17:43:06.171Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gobistories/gobi-web-integration
原文对照：https://npmcn.com/package/%40gobistories/gobi-web-integration/?lang=original
项目主页：https://www.gobistories.com/developers
源码仓库：https://bitbucket.org/gobiapp/gobi-web-integration

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

- 包体积（解压后）：1 MB，176 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2019-04-09T14:24:52.239Z
- 最新版本发布：2026-10-16T07:37:48.017Z
- 近 30 天下载量：19935（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：274（近 12 个月 6 个）

## 中文简介

这个图书馆会让你把你的戈壁故事放到你的网站上.

## 安装

```sh
npm install @gobistories/gobi-web-integration
```

也可以使用：`pnpm add @gobistories/gobi-web-integration`、`yarn add @gobistories/gobi-web-integration`、`bun add @gobistories/gobi-web-integration`

## README

# Gobi 网络整合

欢迎来到戈壁网络集成。 这个图书馆会让你把你的戈壁故事放到你的网站上 如果你没有 戈壁的故事还在我们这里 [工作室](https://studio.gobistories.com/) 获取我们的生产工具.

## 故事泡泡( Demo)

为了方便测试最常用的选项,请访问我们中的代码片段编辑器 [工作室](https://studio.gobistories.com/)。 。 。 .

## 解答问题( F)

#### 泡泡不出来

见取受具. 你能发现任何错误吗? 试着理解他们。 如果图书馆里好像有窃听器,请 给我们发邮件.

#### 维多或缩略图不播放,我看到内容安全政策出错

您可能看到一个类似于 :

```
Refused to load media from 'https://res.cloudinary.com/gobi-technologies-as/...' because it violates the following
Content Security Policy directive: ...
```

如果是的话,您需要更新您的 `Content-Security-Policy` 要包含的 HTTP 信头 `blob:` 以及我们使用的来源.

我们图书馆使用的资料来源是:

-   [https://api.gobistories.com/ 页面存档备份,存于互联网档案馆](https://api.gobistories.com/)
-   [https://widget.gobistories.com/ (原始内容存档于2017-09-29)](https://widget.gobistories.com/)
-   [https://res.cloudinary.com/gobi-technology-as/ 互联网档案馆的存檔,存档日期2013-12-21](https://res.cloudinary.com/gobi-technologies-as/)

使用倒计时示例 `default-src`数字 :

```
default-src 'self' blob: <your other sources> https://widget.gobistories.com https://api.gobistories.com https://res.cloudinary.com/gobi-technologies-as/;
```

使用更严格的获取指令的例子 :

```
script-src 'self': <your other sources> https://widget.gobistories.com/;
connect-src 'self': <your other sources> https://api.gobistories.com/;
media-src 'self' blob: <your other sources> https://res.cloudinary.com/gobi-technologies-as/;
img-src 'self' blob: <your other sources> https://res.cloudinary.com/gobi-technologies-as/;
```

#### 我的页面滚动打开一个故事

如果您的页面在打开一个故事时向上滚动, 这通常是由 HTML 标记的高度样式引起的 你的页面。 删除或替换为 `min-height` 解决了问题.

## 技术文件

### 故事泡泡

在您的页面和内容中添加气泡需要三个步骤:

1.  装入脚本
2.  在要泡泡的地方添加占位符元素
3.  给我们的代码来创建泡沫

你可以在我们内部生成所需的代码 [工作室](https://studio.gobistories.com/),或提及 (b) 与《京都议定书》第三条第1款有关的问题.

#### **与 Gobi. discover () 添加泡泡**

这是在你页面上添加故事泡沫的推荐方式. 在要泡泡的地方添加您的占位符 添加 `gobi-stories` 分类和指定使用数据属性的选项:

```html
<div
  class="gobi-stories"
  data-gobi-stories="story-id another-story-id"
  data-gobi-kebab-cased-option="value"
  data-gobi-some-other-kebab-cased-option="value"
></div>
```

如果您想要配置标题或缩略图 URLs 每个故事, 您可以把它们作为儿童元素添加 :

```html
<div class="gobi-stories" data-gobi-kebab-cased-option="value" data-gobi-some-other-kebab-cased-option="value">
  <div data-gobi-story="story-id" data-gobi-title="About Us"></div>
  <div data-gobi-story="another-story-id" data-gobi-title="Our Product" data-gobi-thumbnail-url="..."></div>
</div>
```

注意,您可以通过使用 HTML 中的新行或添加 `\n` 与标题本身.

见 **泡泡选项** 区域。 注意选项应转换为 _kebab 案件_ 财务报告和审定财务报表 前缀为 `data-gobi-`。 。 。 .

你可以装入我们的脚本然后运行 `gobi.discover()`数字 :

```html
<head>
  <script src="https://widget.gobistories.com/gwi/6" async onload="gobi.discover()"></script>
</head>
```

您可以通过全局选项来发现( ) 用于页面上所有泡泡的默认值 . 见 **泡泡选项** 更多信息:

```js
gobi.discover({
  bubbleSize: '120px',
  color: 'blue',
});
```

全球选项不会被单个嵌入选项所压倒,就会被使用.

#### **添加带有内含脚本的泡泡**

另一种将戈壁故事添加到您页面的方法是使用内置的javascript.

```html
<head>
  <script src="https://widget.gobistories.com/gwi/6"></script>
</head>
<body>
  <div id="container"></div>
  <script>
    new gobi.Bubbles({
      container: '#container',
      stories: [
        {
          id: 'story-key',
          title: 'Some Title',
        },
        {
          id: 'another-story-key',
          title: 'Some Another Title',
        },
      ],
    });
  </script>
</body>
```

### 创建独立玩家

也可以在网页上直接显示故事播放器,而不使用泡泡.

```html
<head>
  <script src="https://widget.gobistories.com/gwi/6"></script>
</head>
<body>
  <div id="container"></div>
  <script>
    new gobi.Player({
      container: '#player-container',
      storyId: 'story-key',
      on: {
        videoPlay: function() {
          console.log('played the video!');
        },
      },
    });
  </script>
</body>
```

见 **玩家选项** 详细情况.

#### 作为软件包安装

[![npm version](https://badge.fury.io/js/%40gobistories%2Fgobi-web-integration.svg)](https://badge.fury.io/js/%40gobistories%2Fgobi-web-integration)

开发者可能更喜欢将Gobi Web集成安装为包依赖:

```sh
npm install --save @gobistories/gobi-web-integration
```

```js
import { Bubbles } from '@gobistories/gobi-web-integration';

// Create bubbles
new Bubbles({
  container: '#container',
  bubbleSize: '200px',
});

// Create a Player
new Player({
  container: '#container',
  storyName: 'story-id',
  playerOptions: {
    on: {
      videoPlay: function() {
        console.log('played the video!');
      },
    },
  },
});
```

### 浏览器支持

图书馆将在Chrome、Firefox、Safari和Opera工作。 库让用户在 IE 中查看故事, 但是 UX 与现代浏览器相比,功能可能有些有限.

### 嵌入选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| 集装箱 | `#gobi-here` | **需要输入 Javascript .** 弦乐 HTML Element 查询选择器。 装入模块的容器. |
| 颜色 | `#15d6ea` | 任何有效的 Css 颜色值 (# 000, rgb (.), rgba (.)) 。 故事泡周围边框的颜色. |
| 气泡大小 | `96px` | 有效的 Css 大小值, 除了% (10px, 10vw...) 。 相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. |
| 隐藏标题 | `false` | 布尔. 如果为真, 隐藏气泡标题( 默认为假) |
| 动画 泡泡声 | `false` | 布尔. 让气泡成为动画. |
| 关闭 | `false` | 布尔. 添加样式,在屏幕收窄时,允许横向系列的气泡被包裹到新行上. |
| 滚动 | `true` | 布尔. 在页面或母容器中不匹配故事时显示滚动条 . |
| 高度移动 | `true` | 布尔. 添加允许进行全屏幕弹出样式 。 只用移动电话 |
| 显示PlayIcon | `false` | 布尔. 在气泡内添加播放图标 |
| 游戏IconUrl | 未定义 | 可选字符串将显示游戏泡沫中给定的图标 . |
| 对齐 | `center` | 弦乐 有效值为"左","右","后","起","中心". 它横向设置了气泡的对接 |
| 自动搜索 | `false` | 布尔. 在结尾启用或禁用向下个故事的过渡 |
| 全屏显示器 | `false` | 布尔. 在弹出模式下打开时设定为真以删除玩家的所有边距 |
| 无阴影 | `false` | 布尔. 设置为真, 当玩家在弹出模式下打开时不应用页面背景阴影 |
| 标题 | `12px` | 有效的 Css 大小值 。 默认情况下,根据12px到36px之间的气泡Size选择一个大小. |
| 标题 | `black` | 任何有效的 Css 颜色值 (# 000, rgb (.), rgba (.)) 。 气泡标题文字的颜色. |
| 标题家庭 | 未定义 | 有效的 Css 字体姓氏 。 默认从文档中继承. |
| 标题 | 未定义 | 有效的 Css 字体重量 。 默认从文档中继承. |
| 继承 TextFont 家庭 | `false` | 布尔. 是否将字体家族从页面中继承到 big 标题 . |
| 继承文本样式 | `false` | 布尔. 是否将字体家族,字体大小,字体重量和颜色从页面中继承到气泡标题. |
| zindex 数据 | `2000000` | 号码。 打开时将玩家的优先级置于其他内容之上. |
| 已装入 | `function` | 函数 。 当所有的泡泡装上后叫起. |
| 关闭 | `function` | 函数 。 当所有的弹出 关闭. |
| **故事** | `[]` | **需要输入 Javascript .** 阵阵. 故事数据. |
| 故事\[0.n\].id |  | **要求.** 弦乐 故事的定点火. |
| 故事 \[0...n\]. title |  | 弦乐 更改特定故事的标题文本 . |
| 故事 \[0.n\]. thumbnailUrl |  | 弦乐 覆盖用于气泡的图像. |
| 故事 \[0...n\]. bulbbleSrc |  | **堕地.** 别名 `thumbnailUrl`。 。 。 . |
| 玩家选项 | `{}` | 对象. 打开时向玩家提供选项. 见 **玩家选项** 详细情况. |

## 活动

`on.loaded` 是一个控制器,因为它是第一个参数。 见 **方案** 更多信息.

## 嵌入式玩家

创建玩家并返回一个界面来管理它,以及倾听它的事件.

### 玩家选项

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| 集装箱 |  | HTML Element 查询选择器。 插入玩家的容器 . |
| 故事编号 |  | **要求.** 弦乐 故事的关键. |
| 自动启动 | `false` | 布尔. 添加 `autoplay` 属性. |
| 自动启动声音 | `false` | 布尔. 添加 `autoplay` 属性到视频中,并且不要同时关闭视频. |
| 循环 | `false` | 布尔. 添加 `loop` 函数到视频. |
| 圆形 | `true` | 布尔. 启用或禁用玩家的圆角元素 . |
| 阴影 | `true` | 布尔. 启用或禁用玩家元素上的阴影 . |
| 宽度 | `undefined` | 号码。 设置玩家宽度 。 如果不定义高度,它将使用16:9的宽比自动计算. |
| 高度 | `undefined` | 号码。 设定玩家高度 。 如果不定义宽度,它将使用16:9的宽比自动计算. |
| 检查查看端口 | `true` | 布尔. 启用在屏幕视图区域外暂停播放器的功能 . |
| 播放按钮 | `true` | 布尔. 启用或禁用播放按钮 . |
| 语录按钮 | `false` | 布尔. 启用或禁用按钮下载记录。 仅在适用的情况下显示. |
| 保存选项 | `true` | 布尔. 启用或禁用保存上次观看的章节 。 它需要用户确认政策 |
| 使用媒体Proxy | `false` | 布尔. 允许对媒体内容使用由 Gobi 托管的倒置代理 . |
| **打开** | `[]` | 阵阵. 事件听众数据 |
| 视频播放 | `function` | 视频播放时打电话来的. |
| 视频暂停 | `function` | 视频暂停时呼叫. |
| 视频完成 | `function` | 视频完成后调用. |
| 上一个 | `function` | 改为上章时召入. |
| 单击下一个 | `function` | 改为下章时召入. |
| 在.clipChange 时 | `function` | 某章有变化时召出. |
| 启用。更新 | `function` | 当故事循环回起时调用( 需要循环为) `true`) (中文(简体) ). |
| 错误 | `function` | 发生错误时调用 . |
| 已装入 | `function` | 视频装入时调用. |

#### 活动

所有事件都以相关章节索引为第一个参数.

### 方法

您可以摧毁 Gobi 玩家以释放资源 :

```js
var player = new gobi.Player({
  container: '#player-container',
  storyId: 'story-key',
});

player.destroy();
```

## 在程序上打开 Gobi 故事

多个功能允许您在程序上打开故事弹出, 要么立即打开, 要么使用传递给一个控制器 回调 :

| 函数 | 说明 |
| --- | --- |
| `openPopup(id, options)` | 立即打开一个故事而不预装 |
| `renderPopups(options, callback)` | 预装故事供稍后打开 |
| `renderBubbles(options, callback)` | 显示以后可以打开的泡泡 |
| `discover(options, callback)` | 查找并嵌入了 gobi 故事 |

选项与 **泡泡选项**。 。 。 .

职能 `renderPopups()` 财务报告和审定财务报表 `renderBubbles()` 要求在 `options`。 。 。 . 这个 `discover()` 函数在与类相配合的圆顶中所需的元素 `gobi-stories` 以创建泡泡 或者说 `gobi-popups` 创建弹出.

职能 `openPopup()` 不需要提供要件.

召回的唯一论据是带有属性的控制器:

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `storyIds` | `string[]` | 一系列已装入的故事 ID |
| `openPopup(id)` | `function` | 为给定的故事 ID 打开弹出式故事播放器 |

说明: `on.loaded` 气泡选项也通过一个控制器,因为它是第一个参数.

您可以随时打开弹出式故事播放器 `openPopup()`数字 :

```js
gobi.openPopup('story-id');
```

> **重要**: 在许多浏览器播放带声音的视频时,至少需要一次启动视频的用户交互 有声音。 因此 `openPopup()` 必须通过用户交互事件(例如点击)进行调用,或在 以其他方式满足了这一要求,否则视频可能无法启动.

要在打开弹出前预装故事数据和海报图像, 请调用 `renderPopups()` 并使用传递给 打开故事的回话。 这可以提供更平稳的经验,特别是在较慢的互联网连接方面.

```js
gobi.renderPopups({ stories: [{ id: 'story-id' }] }, controller => {
  controller.openPopup('story-id');
});
```

如果您想要在页面上显示气泡, 并且想要在程序上打开气泡, 您可以使用渲染泡来创建 泡泡,并获得控制器的回调:

```js
gobi.renderBubbles({ container: '#gobi-container', stories: [{ id: 'story-id' }] }, controller => {
  controller.openPopup('story-id');
});
```

使用时 `gobi.discover()` 要创建出你的气泡,可以使用第二个参数获得控制器,以及 稍后使用:

```js
let gobiController;

gobi.discover({}, controller => {
  gobiController = controller;
});

// You can now use gobiController to open stories, for example with onClick handlers.
```

## 常见问题

### @gobistories/gobi-web-integration 是什么？

这个图书馆会让你把你的戈壁故事放到你的网站上\.

### 如何安装 @gobistories/gobi-web-integration？

在项目目录运行 npm install @gobistories/gobi-web-integration，或使用 pnpm add / yarn add / bun add。

### @gobistories/gobi-web-integration 支持 TypeScript 吗？

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

### @gobistories/gobi-web-integration 支持 ESM 还是 CommonJS？

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

### @gobistories/gobi-web-integration 可以商用吗？

@gobistories/gobi-web-integration 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @gobistories/gobi-web-integration 的下载量有多少？

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

### @gobistories/gobi-web-integration 还在维护吗？

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

