# @diplodoc/html-extension 中文文档

规范地址：https://npmcn.com/package/%40diplodoc/html-extension/

版本：2\.9\.15
npm 元数据更新时间：2026-10-28T14:15:38.638Z
中文译文更新时间：2026-11-12T10:49:52.741Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40diplodoc/html-extension
原文对照：https://npmcn.com/package/%40diplodoc/html-extension/?lang=original
项目主页：https://diplodoc.com/
源码仓库：https://github.com/diplodoc-platform/html-extension

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

- 包体积（解压后）：204 kB，50 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，markdown-it ^13\.0\.1，@diplodoc/transform ^4\.78\.12
- 首次发布：2024-06-29T15:02:42.588Z
- 最新版本发布：2026-10-28T14:15:37.876Z
- 近 30 天下载量：7291（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 14 个）

## 中文简介

Diplodoc 变压器和构建器的 HTML 插件

## 安装

```sh
npm install @diplodoc/html-extension
```

也可以使用：`pnpm add @diplodoc/html-extension`、`yarn add @diplodoc/html-extension`、`bun add @diplodoc/html-extension`

## README

**英语** | [русский](https://github.com/diplodoc-platform/html-extension/blob/master/README.ru.md)

* * *

[![NPM version](https://img.shields.io/npm/v/@diplodoc/html-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/html-extension) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_html-extension&metric=alert_status)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_html-extension) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_html-extension&metric=coverage)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_html-extension) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_html-extension&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_html-extension) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_html-extension&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_html-extension) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_html-extension&metric=security_rating)](https://sonarcloud.io/summary/overall?id=diplodoc-platform_html-extension)

# @diplodoc/html-扩展

## 用于YFM-aware应用程序的自定义 HTML 嵌入解决方案.

这是Diplodoc平台的扩展,它允许通过Markdown指令嵌入HTML.

## 此文件概览

此文件包含以下主题的信息 :

-   [嵌入战略](https://npmcn.com/package/%40diplodoc/html-extension/#readme-embedding-strategies) 由扩展支持
-   [建议 `isolated` 战略使用情况](https://npmcn.com/package/%40diplodoc/html-extension/#readme-a-note-on-isolated-strategy-usage) 确保您能够安全地嵌入潜在的不安全内容
-   [浏览器运行时间的 Docs](https://npmcn.com/package/%40diplodoc/html-extension/#readme-prepared-runtime),此扩展部分负责在浏览器中正确显示嵌入内容.
-   [Markdown的文档 它变换插件](https://npmcn.com/package/%40diplodoc/html-extension/#readme-markdownit-transform-plugin),专门调整后用于 `@diplodoc-platform/transform`。它能确保嵌入式语法可以作为 HTML 提供.
-   [反应钩的文档](https://npmcn.com/package/%40diplodoc/html-extension/#readme-react-hook-for-smart-control)

## 语法

此插件使用容器块指令语法 。 更多信息请参见: [平面平面/方向](https://github.com/diplodoc-platform/directive/?tab=readme-ov-file#directive-syntax)。 。 。 .

简单示例 :

```md
::: html

<div>Your HTML code is here</div>

:::
```

一些样式的例子 :

```md
::: html

<style>
  :root {
    --dark-bg-color: #000;
    --dark-text-color: #FFF;
  }
  .dark {
    background-color: var(--primary-bg-color);
    color: : var(--primary-text-color);
  }
</style>
<div class="dark">Some info is here</div>
:::
```

## 快速启动

将插件附加到变压器上 :

```js
import htmlExtension from '@diplodoc/html-extension';
import transform from '@diplodoc/transform';
import * as sanitizeHtml from 'sanitize-html';

const {result} = await transform(
  `
::: html

<article class="forecast">
  <h1>Weather forecast for Seattle</h1>
  <article class="day-forecast">
    <h2>12 June 2024</h2>
    <p>Rain.</p>
  </article>
  <article class="day-forecast">
    <h2>13 June 2024</h2>
    <p>Periods of rain.</p>
  </article>
  <article class="day-forecast">
    <h2>14 June 2024</h2>
    <p>Heavy rain.</p>
  </article>
</article>

:::
`,
  {
    plugins: [
      htmlExtension.transform({
        sanitize: {
          head: (dirtyHtml) =>
            sanitizeHtml(dirtyHtml, {
              allowedTags: ['title', 'style', 'link', 'meta'],
              allowedAttributes: {
                meta: ['name', 'http-equiv', 'content', 'charset'],
                link: ['rel', 'href'],
              },
            }),
          body: (dirtyHtml) =>
            sanitizeHtml(dirtyHtml, {
              allowedTags: ['article', 'h1', 'h2', 'p', 'span'],
              allowedAttributes: {
                '*': ['class'],
              },
            }),
        },
        containerClasses: 'my-own-class',
      }),
    ],
  },
);
```

如果你使用 `head` 选项,不要忘记添加元标签 `<meta http-equiv="Content-Security-Policy" content="script-src 'none'">` 防止脚本被执行.

## 嵌入战略

扩展支持三种不同的嵌入战略:

-   `srcdoc` - 使用IFrame与 `srcdoc` 属性到嵌入指定的 HTML。 因此,IFrame继承了父母的血统 _财务报告和审定财务报表_ `Content-Security-Policy`然而,所有的 CSS 默认都是孤立的,永远不可能有任何风格渗出. 根据使用的CSP,这种模式引入了潜在的攻击矢量,因为任意的JS代码本来可以允许由宿主的CSP运行. 因此,在使用这种模式时,强烈倾向于使用消毒(见下文) [插件文档](https://npmcn.com/package/%40diplodoc/html-extension/#readme-markdownit-transform-plugin)) (中文(简体) ). 你可以用这个 `sandbox` 对IFrame设定额外限制的选项.
    
-   `shadow` ——目前是一种实验策略,使用"ShadowRoot"将内容嵌入主机页面. 应用和效果与 `srcdoc`,但是在浏览器中使用了较少的运行时间逻辑,提供了更平滑的经验(消除高度调整大小等). 内容消毒仍然是强烈建议。 根据ShadowDOM规则,在ShadowRoot内部声明的样式与页面的其余部分隔离,并具有潜力 _可继承_ 全球样式通过 `all: initial` 在阴影DOM边界.
    
-   `isolated` - 采用特殊IFrame的战略,其主机来源应不同,因此Same-Origin-Policy(SOP)不会申请这一IFrame。 通过选择退出SOP,任何正在IFrame内部运行的脚本都无法获得父执行上下文,以及它的存储,cookie等. 关键是,这种模式还提供了一种选择,对IFrame公司内部的内容使用限制性较小的CSP。 因此,这一战略对于嵌入部件(或其他类型的可能不安全的内容)是理想的。 你可以用这个 `sandbox` 对IFrame设定额外限制的选项.
    
    请注意,虽然人们可以通过提供 `srcdoc` 带有 `sandbox` 属性,将母体(宿主)的CSP凌驾于一套限制性较弱的政策之上的唯一途径是将IFrame实际存放在不同的来源上.
    
    由于高度隔离,不需要消毒. 此外,这种模式/战略是专门设计的,目的是在内容不卫生/不受限制的情况下开展工作,因此, `sanitize` 此扩展名的 Markdown 选项 它的插件在使用此模式时明显没有效果.
    

## 说明 `isolated` 战略使用情况

虽然 `srcdoc` 财务报告和审定财务报表 `shadow` 除了包含运行时间和使用插件外,模式不需要进一步的最小设置, `isolated` 模式需要您有细 `isolated`\- 相容的IFrame运行时间 在一个不同的来源.

IFrame 运行时间包含与主机运行时间进行通信所必需的代码,作为 : `@diplodoc-platform/html-extension/iframe` 输出。 该文件随后可以多种方式托管:

-   使用CDN,因为大多数CDN的出处并非设计为主机全网应用,因此这些出处不应该有与之相关的重要饼干,存储或其他关键数据,可以将嵌入中的一些恶意代码运行时可能发生的伤害降到最低并/或有效消除.
-   设置不同的逆向代理/ HTTP 服务器/ L7 上游响应不同的 `host` 页眉/`:authority` 伪头人.

确保不要使用应用程序的任何子域名,因为这样cookie仍然可能接触到恶意代码.

## 浏览器运行时间

有必要添加 `runtime` 用于在您的页面中嵌入交互的脚本 .  
您可以添加由 : [它变换插件](https://npmcn.com/package/%40diplodoc/html-extension/#readme-markdownit-transform-plugin)。 。 。 .

```html
<html>
  <head>
    <!-- Read more about '_assets/html-extension.js' and '_assets/html-extension.css' in 'Transform plugin' section -->
    <script src="_assets/html-extension.js" async></script>
  </head>
  <body>
    ${result.html}
  </body>
</html>
```

或者你可以把运行时的源代码 包括在你的捆绑.

```js
import '@diplodoc/html-extension/runtime';
```

要设置运行时间配置, 您可以使用函数 `setupRuntimeConfig(config: HTMLRuntimeConfig)`时

```ts
type HTMLRuntimeConfig = {
  disabledModes: ('shadow' | 'srcdoc' | 'isolated')[];
};
```

数组中的模块 `disabledModes` 禁用此模式的运行时控制器, 因此页面上的元素带有 `data-yfm-sandbox-mode={disabledMode}` 运行时间不会改变.

## 它变换插件

插件用于 [@ diplodoc/ 变形](https://github.com/diplodoc-platform/transform) 软件包.

选项 :

-   `runtimeJsPath` - 运行时脚本上的名称,该脚本将显示结果 `script` 节.  
    默认 : `_assets/html-extension.js`  
    
-   `bundle` - 布尔旗以启用/无法复制捆绑的运行时间到目标目录.  
    目标导演在哪里 `<transformer output option>/<plugin runtime option>`  
    默认 : `true`  
    
-   `containerClasses` - 在标签的容器节点上添加更多的类别。 它允许自定义html视图.  
    示例 `my-own-class and-other-class`  
    默认 : `undefined`  
    
-   `embeddingMode` - 嵌入 [战略](https://npmcn.com/package/%40diplodoc/html-extension/#readme-embedding-strategies) 用于 _全部_ 遇到嵌入物.
    
    接受数值: `srcdoc`, (中文(简体) ), `shadow`, (中文(简体) ), `isolated`。 。 。 .
    
    默认 : `srcdoc`。 。 。 .
    
-   `isolatedSandboxHost` - 完全合格的URL [IFrame 运行时间](https://npmcn.com/package/%40diplodoc/html-extension/#readme-a-note-on-isolated-strategy-usage) 具体用于 `isolated` 模式。 当使用其他模式时没有效果 。 这仍然可以被 [`EmbedsConfig.isolatedSandboxHostURIOverride`](https://npmcn.com/package/%40diplodoc/html-extension/src/types.ts#L8) 通过 [`EmbeddedContentRootController.initialize`](https://npmcn.com/package/%40diplodoc/html-extension/src/runtime/EmbeddedContentRootController.ts#L53) 财务报告和审定财务报表 [`EmbeddedContentRootController.setConfig`](https://npmcn.com/package/%40diplodoc/html-extension/src/runtime/EmbeddedContentRootController.ts#L94)。 。 。 .
    
-   `sanitize` - 用于消毒内容的可选函数 `srcdoc` 财务报告和审定财务报表 `shadow` 如果提供了模式。 它可以是一个有钥匙的物体 `head` 财务报告和审定财务报表 `body`,以单独指定用于 `<head>` (来自选项)和 `<body>` (已处理的HTML)内容. 如果对象中缺少一个密钥,相应的内容将不会被处理. 消毒剂 `head` 仅与 `srcdoc` 模式.
    
-   `sandbox` - 沙盒-模型,用于 `srcdoc` 财务报告和审定财务报表 `isolated` 嵌入策略(参见iframe sandbox属性). 默认禁用 。 需要说明 `allow-same-origin` 以允许主机运行时间(框架调整大小、碎片链接), `allow-popups allow-popups-to-escape-sandbox` 以允许在新标签中打开链接(链接到 `target="_blank"`),以及 `allow-top-navigation-by-user-activation` 以允许在当前标签中打开链接(链接与 `target="_parent"`) (中文(简体) ).
    

## 用于智能控制的反向钩

您可以使用回放钩与块内的HTML内容进行程序交互.

```TypeScript
// TODO
```

## 常见问题

### @diplodoc/html-extension 是什么？

Diplodoc 变压器和构建器的 HTML 插件

### 如何安装 @diplodoc/html-extension？

在项目目录运行 npm install @diplodoc/html-extension，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：markdown-it（^13\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @diplodoc/html-extension 支持 TypeScript 吗？

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

### @diplodoc/html-extension 支持 ESM 还是 CommonJS？

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

### @diplodoc/html-extension 可以商用吗？

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

### @diplodoc/html-extension 的下载量有多少？

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

### @diplodoc/html-extension 还在维护吗？

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