英语 | русский
@diplodoc/html-扩展
用于YFM-aware应用程序的自定义 HTML 嵌入解决方案.
这是Diplodoc平台的扩展,它允许通过Markdown指令嵌入HTML.
此文件概览
此文件包含以下主题的信息 :
- 嵌入战略 由扩展支持
- 建议
isolated战略使用情况 确保您能够安全地嵌入潜在的不安全内容 - 浏览器运行时间的 Docs,此扩展部分负责在浏览器中正确显示嵌入内容.
- Markdown的文档 它变换插件,专门调整后用于
@diplodoc-platform/transform。它能确保嵌入式语法可以作为 HTML 提供. - 反应钩的文档
语法
此插件使用容器块指令语法 。 更多信息请参见: 平面平面/方向。 。 。 .
简单示例 :
::: html
<div>Your HTML code is here</div>
:::
一些样式的例子 :
::: 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>
:::
快速启动
将插件附加到变压器上 :
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运行. 因此,在使用这种模式时,强烈倾向于使用消毒(见下文) 插件文档) (中文(简体) ). 你可以用这个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 用于在您的页面中嵌入交互的脚本 .
您可以添加由 : 它变换插件。 。 。 .
<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>
或者你可以把运行时的源代码 包括在你的捆绑.
import '@diplodoc/html-extension/runtime';
要设置运行时间配置, 您可以使用函数 setupRuntimeConfig(config: HTMLRuntimeConfig)时
type HTMLRuntimeConfig = {
disabledModes: ('shadow' | 'srcdoc' | 'isolated')[];
};
数组中的模块 disabledModes 禁用此模式的运行时控制器, 因此页面上的元素带有 data-yfm-sandbox-mode={disabledMode} 运行时间不会改变.
它变换插件
插件用于 @ diplodoc/ 变形 软件包.
选项 :
-
runtimeJsPath- 运行时脚本上的名称,该脚本将显示结果script节.
默认 :_assets/html-extension.js -
bundle- 布尔旗以启用/无法复制捆绑的运行时间到目标目录.
目标导演在哪里<transformer output option>/<plugin runtime option>
默认 :true -
containerClasses- 在标签的容器节点上添加更多的类别。 它允许自定义html视图.
示例my-own-class and-other-class
默认 :undefined -
embeddingMode- 嵌入 战略 用于 全部 遇到嵌入物.接受数值:
srcdoc, (中文(简体) ),shadow, (中文(简体) ),isolated。 。 。 .默认 :
srcdoc。 。 。 . -
isolatedSandboxHost- 完全合格的URL IFrame 运行时间 具体用于isolated模式。 当使用其他模式时没有效果 。 这仍然可以被EmbedsConfig.isolatedSandboxHostURIOverride通过EmbeddedContentRootController.initialize财务报告和审定财务报表EmbeddedContentRootController.setConfig。 。 。 . -
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内容进行程序交互.
// TODO