英语 | русский
Diplodoc 页面构建器扩展
这是Diplodoc平台的延伸,允许使用 页面构造器 的组件。 Page Constructionor是一个基于YAML数据的用于渲染网页或其部分的库. 此扩展可以直接在您下标记文件中创建丰富的交互式页面布局.
扩展部分包括:
快速启动
将插件附加到变压器上 :
import pageConstructorExtension from '@diplodoc/page-constructor-extension';
import transform from '@diplodoc/transform';
const {result} = await transform(
`
::: page-constructor
blocks:
- type: 'header-block'
title: 'My Header'
description: 'This is a description'
:::
`,
{
plugins: [pageConstructorExtension.transform({bundle: false})],
},
);
不要忘记添加运行时间让页面构建器交互 :
// Import the runtime in your application
import '@diplodoc/page-constructor-extension/runtime';
import '@diplodoc/page-constructor-extension/runtime/styles';
// Or include it in your HTML
<script src='_assets/page-constructor.js'></script>
<link rel='stylesheet' href='_assets/page-constructor.css' />
// Or load it conditionally only when needed
import {PAGE_CONSTRUCTOR_RUNTIME} from '@diplodoc/page-constructor-extension/plugin';
// Check if page constructor is used in the content
if (result.meta?.script?.includes(PAGE_CONSTRUCTOR_RUNTIME)) {
// Load runtime asynchronously
Promise.all([
import('@diplodoc/page-constructor-extension/runtime'),
import('@diplodoc/page-constructor-extension/runtime/styles')
]);
}
语法
您可以使用您的下标记文件中的页面构建器 page-constructor 指令 :
::: page-constructor
blocks:
- type: 'header-block'
title: 'My Header'
description: 'This is a description'
:::
说明: 这个 blocks: 需要财产。 直接列表格式 blocks: 前缀不支持.
它变换插件
插件用于 @ diplodoc/ 变形 软件包.
选项 :
-
runtime- 显示结果的运行时脚本和样式名称script财务报告和审定财务报表style节.
可以是字符串(脚本和样式都使用同名),也可以是单独的对象script财务报告和审定财务报表style属性.
默认 :{ script: '_assets/page-constructor.js', style: '_assets/page-constructor.css' } -
bundle- 布尔旗以启用/无法复制捆绑的运行时间到目标目录.
目标目录所在<transformer output option>/<plugin runtime option>
默认 :true -
assetLinkResolver- 解决页面构建器内容中的资产链接(图像、视频等).
签署:(link: string) => string
默认 :undefined -
contentLinkResolver- 功能解决页面构建器内容中的内容链接(markdown文件,HTML文件等).
签署:(link: string) => string
默认 :undefined
准备运行时间
Page 构造器需要运行时脚本使内容在您的页面上交互. 增加这些脚本有两种主要方法:
1. 使用已生成资产
最佳服务:
- 静态 HTML 页面
- 服务器提交应用程序
- 当您想要将运行时间从主应用程序代码中分离时
<html>
<head>
<!-- Assets generated by the MarkdownIt transform plugin -->
<script src="_assets/page-constructor.js"></script>
<link rel="stylesheet" href="_assets/page-constructor.css" />
</head>
<body>
${result.html}
</body>
</html>
2. 包括在您的套装中
最佳服务:
- 单页应用程序
- 当使用模块捆绑器时(网包、卷起等)
- 如果您想要控制运行时间的版本
import '@diplodoc/page-constructor-extension/runtime';
import '@diplodoc/page-constructor-extension/runtime/styles';
渲染检测
运行时间自动检测是水合物还是根据内容的结构渲染出内容 :
- 服务器发送的内容 (带有预发HTML)将被水化
- 浏览器提交的内容 (空占位符)将全部完成
这使得您可以使用单个运行时间,明智地决定适当的渲染方法,在同时使用服务器和浏览器渲染的混合环境中简化了集成.
关于消毒的重要说明:
当使用服务器侧渲染(SSR)时,所有的HTML都会通过变换的默认消毒器. 然而,在客户端渲染时,Page Constructionor的内容不会被自动消毒. 如果您在客户端渲染情景中需要这个功能,您需要自己处理内容消毒,以防止潜在的安全问题.
初始化方法
初始化 Page 构造器运行时间有三种方法:
1. 反应部分
最佳服务:
- 反应应用程序
- 当您需要更多控制初始化时间时
- 当您想要与 React 的组件生命周期结合时
import {PageConstructorRuntime} from '@diplodoc/page-constructor-extension/react';
function App() {
return (
<>
{/* Your content */}
<PageConstructorRuntime />
</>
);
}
2. 直接运行时间导入
最佳服务:
- 静态 HTML 页面
- 非反应应用程序
- 简单的一体化设想
// Import the runtime - it will automatically detect the rendering type
import '@diplodoc/page-constructor-extension/runtime';
附加参数:
theme(可选) - 设置页面构造器组件的主题。 可用值 :'light' | 'dark'preMountHook(可选) - 在挂起组件前调用回调函数 。 接收作为参数的容器元素.
3. 有条件的运行时间加载
最佳服务:
- 业绩优化
- 当您想要加载运行时间时, 只有在需要时才会
- 每页可能不使用页面构建器的大应用程序
import {useState, useEffect} from 'react';
import {
transform as pageConstructorPlugin,
PAGE_CONSTRUCTOR_RUNTIME,
} from '@diplodoc/page-constructor-extension/plugin';
import {PageConstructorRuntime} from '@diplodoc/page-constructor-extension/react';
function App() {
const {result} = transform(content, {
plugins: [pageConstructorPlugin()],
});
const [runtimeLoaded, setRuntimeLoaded] = useState(false);
// Asynchronously load runtime only if needed
useEffect(() => {
if (result.meta?.script?.includes(PAGE_CONSTRUCTOR_RUNTIME)) {
// Load runtime asynchronously
Promise.all([
import('@diplodoc/page-constructor-extension/runtime'),
import('@diplodoc/page-constructor-extension/runtime/styles'),
]).then(() => {
setRuntimeLoaded(true);
});
}
}, [result.meta?.script]);
return (
<>
<div dangerouslySetInnerHTML={{__html: result.html}} />
{runtimeLoaded && <PageConstructorRuntime />}
</>
);
}
变形样式和运行时间
这个 @diplodoc/page-constructor-extension 软件包不捆绑 @diplodoc/transform CSS和JS在运行时需要手动导入:
@import '~@diplodoc/transform/dist/css/yfm.css';
import '@diplodoc/transform/dist/js/yfm';
反应钩
计外 PageConstructorRuntime 说明的构成部分 初始化方法 区域,扩展提供了反应钩子,用于对渲染过程进行更多的控制:
import {
usePageConstructorController,
usePageConstructor,
} from '@diplodoc/page-constructor-extension/react';
function MyComponent() {
// Get the controller
const controller = usePageConstructorController();
// Get the render function
const renderPageConstructors = usePageConstructor();
// Render page constructors when needed
useEffect(() => {
if (controller) {
renderPageConstructors();
}
}, [controller, renderPageConstructors]);
return <div>My Component</div>;
}
这些钩子在您需要时有用 :
- 提供页面构建器时的控制
- 与其他反应组件或库整合
- 执行自定义渲染逻辑
- 响应特定事件或状态变化
链接解析器
这个 assetLinkResolver 财务报告和审定财务报表 contentLinkResolver 选项允许您自定义如何在页面构建器内容中解决链接。 这些功能被调用到内容中的每个链接,并且应当返回已解决的链接.
assetLinkResolver: 要求连接资产(图像、视频等)contentLinkResolver: 调用内容的链接( 标记下的文件、 HTML 文件等)
示例
pageConstructorPlugin({
// Other options...
assetLinkResolver: (link) => {
// Add a prefix to asset links
return link.startsWith('http') ? link : `/assets/${link}`;
},
contentLinkResolver: (link) => {
// Convert .md links to .html
return link.endsWith('.md') ? link.replace('.md', '.html') : link;
},
});
示例
见 example 用于完整实例的目录 .