# @dodomain/connect 中文文档

规范地址：https://npmcn.com/package/%40dodomain/connect/

版本：0\.3\.2
npm 元数据更新时间：2026-08-19T19:56:05.193Z
中文译文更新时间：2026-11-12T14:32:37.077Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dodomain/connect
原文对照：https://npmcn.com/package/%40dodomain/connect/?lang=original
项目主页：https://dodomain.io/
源码仓库：https://github.com/DevinoSolutions/dodomain-sdk

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

- 包体积（解压后）：87.4 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-31T04:06:07.190Z
- 最新版本发布：2026-08-19T19:56:04.806Z
- 近 30 天下载量：14332（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Dodomain的官方浏览器部件——在模式iframe中打开主机域连接流量并转发其生命周期事件.

## 安装

```sh
npm install @dodomain/connect
```

也可以使用：`pnpm add @dodomain/connect`、`yarn add @dodomain/connect`、`bun add @dodomain/connect`

## README

# @ dodomain/ 连接

可嵌入的浏览器部件 [域名](https://dodomain.io/)打开主机连接流 在一个模式的 Iframe 中将其生命周期事件转发回您的应用程序。 与 [`@dodomain/node`](https://npmcn.com/package/%40dodomain/node),在服务器上会话符号的薄荷.

📖 **附有可操作示例的指南 : [dodomain.io/docs/widget (英语)](https://dodomain.io/docs/widget)** · 所有文件: [dodomain.io/docs (英语)](https://dodomain.io/docs)使用反应? [`@dodomain/react`](https://www.npmjs.com/package/@dodomain/react) 用钩子包裹此部件.

## 安装

```sh
npm install @dodomain/connect
# or: pnpm add @dodomain/connect · yarn add @dodomain/connect
```

零运行时间依赖, ~3KB 浏览器捆绑( 双端无害环境管理+ CJS + 自定义) `.d.ts`; 数据 捆绑留下 **无分区** 看到了吗 [`test/build.smoke.test.ts`](https://npmcn.com/package/%40dodomain/connect/test/build.smoke.test.ts)) (中文(简体) ).

## 使用量

```ts
import { showDoDomain } from "@dodomain/connect";

// token comes from your server: POST /api/v1/sessions via @dodomain/node
const { token } = await fetch("/my-api/domain-session").then((r) => r.json());

const handle = showDoDomain({
  token,
  onVerified: ({ domain }) => {
    console.log("connected:", domain);
    location.reload();
  },
  onClose: ({ state }) => {
    // "verified" | "pending" | "failed" | "unknown" — closing now tells you
    // something, so you don't have to re-poll your own backend to find out.
    if (state !== "verified") keepTheConnectDomainPromptVisible();
  },
  onError: (err) => {
    if (err.code === "MOUNT_BLOCKED") {
      // The iframe never mounted (host CSP, network, content blocker).
      // Same session, full page — see "Origins & CSP" below.
      location.assign(err.hostedUrl);
      return;
    }
    console.error("connect flow failed:", err.type, err.code);
  },
});

// handle.close() to dismiss it programmatically
```

## API 密码

### `showDoDomain(options) → { close }`

| 选项 | 类型 | 页:1 |
| --- | --- | --- |
| `token` | `string` | 要求。 会话符号( E)`dd_sess_…`从 `POST /api/v1/sessions`。 。 。 . |
| `baseUrl` | `string` | 域名来源. 默认为 `https://app.dodomain.io`。 。 。 . |
| `onVerified` | `(detail: { domain?: string }) => void` | 域能验出后起火. |
| `onClose` | `(detail: DoDomainCloseDetail) => void` | 当模式被解除时会起火(回放点击,内流关闭, `handle.close()`)),与会后已知的状态相通——见下文. 一个零弧 `() => …` 对照旧版本编写的处理器继续工作. |
| `onError` | `(detail: DoDomainWidgetError) => void` | 当流量不能加载或报告会话错误时起火——见下文。 默认缺席(前:沉默). |
| `loadTimeoutMs` | `number` | 等待主机流的负载握手需要多久才能将嵌入物视为失败. 默认 `15000`。 。 。 . |

返回一个控件 `close()`框中的信息为 **原产地检查** 反对 `baseUrl`,所以只有主机流才能触发回调. 必须在浏览器中运行 .

### `onError` —— 说 `DoDomainWidgetError`

一个跨原产地的 Iframe的HTTP 404/500不会开火 `onerror` 或暴露可读内容,所以 被打碎的嵌入器曾经是完全沉默的. 每个 `onError` 细节带一个 `code` (单位:千美元) `hostedUrl` (同一会话的整页流程),加a `type`数字 :

-   `{ type: "load-timeout", code: "MOUNT_BLOCKED" }` - 里面没有握手 `loadTimeoutMs` (a 404, DNS 失败, 离线网络, 内容屏蔽器, 或主机页面 CSP —— 任何从来就不够 运行主机流量自己的JS.
-   `{ type: "load-error", code: "MOUNT_BLOCKED" }` 一个更快的信号 用于同样的事实: iframe属于自己 `error` 事件开火, **或者说** 您的页面 CSP 报告封锁了帧 (单位:千美元)`securitypolicyviolation` 打开 `frame-src`编号 :`child-src`编号 :`default-src`)),着陆于 毫秒而不是等待出来 `loadTimeoutMs`。 。 。 .
-   `{ type: "session-error", code: string }` ——主机页面上载并报告故障. `code` 匹配主机页面本身的页内错误横幅所用的相同词汇 (单位:千美元)`expired`, (中文(简体) ), `not_found`, (中文(简体) ), `invalid_request`, (中文(简体) ), `internal`) (中文(简体) ). 两名制作人:a `verify()` 调用 自2026-08-18年以来,这一标志是: **当工作表显示时已死亡 打开** (单位:千美元)`expired` 编号 : `not_found`以迷惑的态度降临你 `load-timeout` 换句话说 将此一个当作终端: 关闭工作表并薄荷新会话 而不是重试同样的事物.

**`code === "MOUNT_BLOCKED"` 这是您需要的“嵌入在这里是不可能的”检查:** 工作表从未出现,所以用户在工作表内所做的任何工作都无法成功——发送到 `err.hostedUrl` 换句话说 这是故意不叫的 `CSP_BLOCKED`: 从主页 a CSP块,一个DNS故障和一个广告屏蔽器是无法区分的,所有四个都想要相同的 倒计时.

### `onClose` —— 说 `DoDomainCloseDetail`

`onClose` 接收 `{ state, domain? }`,来源于流 自己的后米斯吉流量,所以 解雇并非含糊不清

| `state` | 含义 |
| --- | --- |
| `verified` | 流量报告已核实域(`domain` 已设定). 粘相——后期出错不能降级. |
| `pending` | 流量挂起, 但用户在任何结果前关闭 . |
| `failed` | 流量报告出错(例如a) `verify()` 并且从未被证实. |
| `unknown` | 部件完全没有从流中听到 —— 把这个配给 `MOUNT_BLOCKED` `onError`。 。 。 . |

签名 `connection.verified` webhook仍然是真相的来源; `state` 是一个UI提示,和 浏览器中的任何内容都可以被偷取.

## 来源和CSP

部件从 iframe 中装入主机流 **一个** 源代码,因此是一个内容-安全政策 您的页面必须允许它进入 `frame-src` (浏览器掉回 `child-src`,则 `default-src`故你们可以随意决定:

```
Content-Security-Policy: frame-src https://app.dodomain.io;
```

-   `https://app.dodomain.io` 生产来源—— 价值 `DODOMAIN_DEFAULT_ORIGIN` (单位:千美元)[`packages/core/src/origin.ts`](https://npmcn.com/package/%40dodomain/core/src/origin.ts)),这是什么 `baseUrl` 默认为 和这个repo定义的单一地点. `api.dodomain.io` 财务报告和审定财务报表 `connect.dodomain.io` 为: 同一用途的化妆品名称 **没有** 今天已经服役了——不要允许列入.
-   如果你通过自己的 `baseUrl` (自营或中转), 批准来源.
-   部件不向您的页面注入脚本、样式、字体或图像, 所以 `frame-src` 这是 只有它需要的指示。 它会听自己的页面 `securitypolicyviolation` 事件 早期检测到一个区块——一个只读的收听器,在任何地方都没有报告.

### 主机URL倒置

如果帧不能挂起,请倒回同一会话全页——没有第二次API呼叫 符号已经是您的 :

```ts
showDoDomain({
  token,
  onError: (err) => {
    if (err.code === "MOUNT_BLOCKED") location.assign(err.hostedUrl); // {baseUrl}/connect/{token}
  },
});
```

`hostedUrl` 故意省略 `embed`编号 :`origin`编号 :`theme` iframe 中包含的查询参数 : 将流量放入嵌入式模式,这对顶级导航是错误的. 过 `returnUrl` 当您将会话薄荷时, 用户会返回您的应用程序.

见 [`src/index.ts`](https://npmcn.com/package/%40dodomain/connect/src/index.ts) 执行.

## 常见问题

### @dodomain/connect 是什么？

Dodomain的官方浏览器部件——在模式iframe中打开主机域连接流量并转发其生命周期事件\.

### 如何安装 @dodomain/connect？

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

### @dodomain/connect 支持 TypeScript 吗？

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

### @dodomain/connect 支持 ESM 还是 CommonJS？

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

### @dodomain/connect 可以商用吗？

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

### @dodomain/connect 的下载量有多少？

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

### @dodomain/connect 还在维护吗？

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