反应组件
反应组件 用于抽象与 OpenAttestation 分散渲染器的通信。 详情见下文:
特征
- 调试 - 在节点和浏览器中都起作用的JS调试工具
- ESLint 语录 - 用这个工具,你写质量代码.
- 欢乐 - Facebook使用的JavaScript测试框架
- 高级 - 它通过解析你的代码并重新打印它来强化一种一致的风格.
- 反应 - 用于构建用户界面的 JavaScript 库
- 反应测试库 - 鼓励良好测试做法的简单和完整的测试设施
- 类型脚本 - 一个提供可选静态打字的JavaScript超级集
- 语义释放 - 一个完全自动化的版本管理和软件包出版工具
- 故事书 - 与文件隔离开发UI组件的工具
- 网络软件包 - 组件捆绑器
安装
为分散的渲染器安装 React 组件,下载或 git clone 此寄存器数字 :
$ git clone https://github.com/Open-Attestation/decentralized-renderer-react-components.git my-components
$ cd my-components
$ rm -rf .git
$ npm install
请根据您的模块信息编辑以下文件 :
package.json(单元名称和版本)README.mdLICENSE- 添加您的模板( 在
src并配置模板登记册(在src/index.tsx存档).
如何运作
[TIP]
OpenAttestation现在支持SVG渲染. 点击 这里 需要更多信息.
首先,请务必阅读最初的导言和解释 分散渲染器。 。 。 .
为渲染文档,主机会装入相应的分散渲染器(如文档所指定)并使用iframe嵌入. 主机和iframe之间的通信是使用 后图像 API 并且是用动作设计的.
动作 API
所有动作都遵循相同的结构. 他们由下列人员组成: type 财务报告和审定财务报表 payload数字 :
type说明正在采取的行动,例如,RENDER_DOCUMENT表示渲染文档. 动作的类型是 强制。 。 。 .payload表示与类型有关的可选数据,例如要提供的文件的内容.
下面是一个代码示例:
const renderDocumentAction = {
type: "RENDER_DOCUMENT",
payload: {
document: documentToRender,
},
};
const printAction = {
type: "PRINT",
};
从主机到框架动作
以下列出为主机与iframe进行通信而采取的行动列表,因此必须由iframe所嵌入的应用程序处理: iframe
-
绘制文档 :
- 类型 :
RENDER_DOCUMENT - 有效载荷:具有两个特性的物体
- 文档 : (强制性)文档数据返回
getData方法从 @govtechsg/ 开放式测试 - 原始文档:(可选) OpenAttestation 文档
- 文档 : (强制性)文档数据返回
下面是一个代码示例:
- 类型 :
const action = {
type: "RENDER_DOCUMENT",
payload: {
document: getData(document),
rawDocument: document,
},
};
-
在分散渲染器提供的模板中选择一个模板(渲染器可能向许多不同的模板提供一个模板以显示文档):
- 类型 :
SELECT_TEMPLATE - 有效载荷:(强制性) 要显示的模板 ID
下面是一个代码示例:
- 类型 :
const action = {
type: "SELECT_TEMPLATE",
payload: "CUSTOM_TEMPLATE",
};
-
请求打印文件
- 类型 :
PRINT
下面是一个代码示例:
- 类型 :
const action = {
type: "PRINT",
};
第四个动作可以用于React Natural应用程序(引擎盖下不使用iframe)的背景中
-
请求提供文件模板清单。 动作直接返回模板列表
- 类型 :
GET_TEMPLATES - 有效载荷:(强制性)文件数据,由
getData方法从 @govtechsg/ 开放式测试
下面是一个代码示例:
- 类型 :
const action = {
type: "GET_TEMPLATES",
payload: getData(document),
};
从框架到主机动作
以下列出为iframe与主机通信而采取的行动清单(因此必须由嵌入iframe的应用程序处理):
-
提供iframe的全部内容高度,使主机可以自动适应嵌入式iframe大小.
- 类型 :
UPDATE_HEIGHT - 有效载荷:iframe的(强制性)全部含量高度
下面是一个代码示例:
- 类型 :
const action = {
type: "UPDATE_HEIGHT",
payload: 150,
};
-
提供文档上一个字段的名称来混淆。 值必须遵循所处理的路径属性 摇摆# 获得
- 类型 :
OBFUSCATE - 有效载荷:(强制性)去地道
下面是一个代码示例:
- 类型 :
const action = {
type: "OBFUSCATE",
payload: "a[0].b.c",
};
-
提供可用于渲染文档的模板列表
- 类型 :
UPDATE_TEMPLATES - 有效载荷:(强制性)每个元素为由字符串和标签组成的对象的阵列
下面是一个代码示例:
- 类型 :
const action = {
type: "UPDATE_TEMPLATES",
payload: [
{
id: "certificate",
label: "Certificate",
},
{
id: "transcript",
label: "Transcript",
},
],
};
使用量
图书馆提供两个主要组成部分,包括: FrameConnector 财务报告和审定财务报表 FramedDocumentRenderer。 。 。 .
框架连接器
这一构成部分将建立一个框架,并与所提供分散的制作器建立联系。 其属性包括:
source: url 到处理要显示的文档的分散渲染器dispatch: 函数监听分散渲染器触发的行动onConnected: 当连接到分散的渲染器时调用函数。 该函数将作为第一个参数提供,另一个参数可用于向iframe发送动作onConnectionFailure: 接受函数的可选属性。 如果出现连接失败/ 超时, 默认的渲染器将显示错误消息 。 如果此可选属性与文档一起定义,则将显示原始文档.
请检查密码 example/application 以查看如何使用此组件。 您也可以使用命令启动示例程序 npm run example:application
框架文档渲染器
此组件将和一个嵌入应用程序的主机建立连接。 其属性包括:
-
templateRegistry: 分散渲染器处理的模板的配置.templateRegistry是一个对象,每个密钥都有一组Template Configuration。 。 。 .一个
Template Configuration包括:id: 模板当前数组中唯一的标识符label: 表示模板内容的字符串(核查者显示标签时使用)template页:1Template,即生成文档的反应组件
-
attachmentToComponent:根据附件类型绘制组件附件的函数.目前,图书馆有两种功能:
-
noAttachmentRenderer: 用途UnsupportedRenderer -
fullAttachmentRenderer: 使用库所支持的所有附件类型(参见函数).此属性默认为
noAttachmentRenderer避免捆绑不必要地膨胀.
-
FramedDocumentRenderer 处理与主机应用程序和渲染器通信的所有逻辑:
- 它会自动呼叫
UPDATE_HEIGHT动作,当iframe被调整大小或当iframe内部有变化时(使用 变异观察员) (中文(简体) ). - 它会自动呼叫
Template根据主办方提供的信息,提供文件. - 当文件被请求渲染时,它将自动提供可用的模板(即它将调用
UPDATE_TEMPLATES一旦文件已经提供,即可采取行动). - 它会自动调用
OBFUSCATE请求时的行动Template。 。 。 .
你需要检查密码 example/decentralized-renderer 以查看如何使用此组件。 您也可以使用命令启动示例程序 npm run example:renderer
模板( 反应组件)
当一个文档被打开时, 每个文件都会被配置 Template 将提供以下属性:
document: (强制性) 文档数据由getData方法从 @govtechsg/ 开放式测试rawDocument: (可选) OpenAttestation 文档handleObfuscation: (强制性)一个调用功能,可以处理文档中的歧义. 提供的值必须遵循由 摇摆# 获得。 。 。 .
发展
为不同的开发任务运行下列命令:
-
npm run storybook: 开始一个故事本, 创建故事, 并可视化不同的组件 -
npm run test: 运行测试 -
npm run lint: 运行林特 -
npm run example:application: 运行在此库中构建的示例应用程序如果您更新了此库, 请确定要更新此示例 .
-
npm run example:renderer: 运行一个使用此库构建的分散化渲染器实例如果您更新了此库, 请确定要更新此示例 .
也可以以此为基础建造自己的分散式后台 反应模板。 。 。 .
彭帕尔
有兼容性 问题 在 Penpal 版本 ^ 5 和 ^ 4 之间. 如果您必须使用 Penpal 版本 ^ 4, 请获取版本 4.1.1 国家。 。 。 .
SVG 渲染
SVG渲染的执行基于 W3C草案。 。 。 .
如何运作
SVG渲染是现有的嵌入式渲染器方法的替代品,可以在不创建分散式渲染器的情况下实现.
相反,SVG图像需要通过直接嵌入到OA文档中来提供,或者通过提供可公开访问的链接来贬低SVG图像. 为了正确显示数据,所提供的SVG应包括: 手提箱表达式。 。 。 .
在显示点,要渲染的文档被传递到SvgRender组件,以便编译出最终的输出.
使用量
图书馆提供 SvgRenderer 组件.
Svg 渲染器
这个部分只有一个强制财产 document。 。 。 .
document: OA文档,形式为对象并有对应的字段来显示.style?: 要样式 iframe 元素.className?:为iframe设置类名.onResult?: SVG 装入后包含显示结果的回调函数.ref?: HTML Image Element 类型可以被取出,它会暴露已渲染元素的 DOM 节点.
制作方法财产
包含在 OA doc 中的对象数组,详情请参考 w3c 规格。 。 。 .
目前此库中的SvgRender只接受单一的SVG模板. 它将通过文档中提供的所有渲染对象进行排列,并显示第一个类型 SvgRenderingTemplate2023.
示例
SVG渲染图例. 简而言之,我们不会指定 digestMultibase。 。 。 .
步骤 1 - 准备您的模板 SVG
<svg width="340" height="110" xmlns="http://www.w3.org/2000/svg">
<rect x="5" y="5" width="330" height="100" fill="#d4d4d4" stroke="orange" stroke-width="8" rx="10" ry="10" />
<text x="170" y="45" font-family="Arial" font-size="15" fill="black" text-anchor="middle">Congratulations for achieving {{qualification}}!</text>
<text x="170" y="70" font-family="Arial" font-size="12" fill="black" text-anchor="middle">Awarded to: {{recipient.name}}</text>
</svg>
模板 SVG 预览 :
确保 SVG 引用的数据字段位于原始/未包装 OA 文档中, SVG 可以直接托管或嵌入.
步骤 2 - 创建样本 Raw/ 未包装的 OpenAttestation doc
样本 A - v2 doc 与主机 SVG :
[注]
使用 OA v2 的 SVG 渲染需要renderMethod属性代替$template。 。 。 .
{
<!-- Issuers field -->
"renderMethod": [{
"id": "http://example.com/static/svg_test.svg", // Put SVG data here to embed it directly
"type": "SvgRenderingTemplate2023",
"name": "SVG Demo",
}],
"qualification": "SVG rendering",
"recipient": {
"name": "Yourself"
}
}
带有嵌入式SVG的 B - v2 doc 样本 :
{
<!-- Issuers field -->
"renderMethod": [{
"id": `<svg width="340" height="110" xmlns="http://www.w3.org/2000/svg">
<rect x="5" y="5" width="330" height="100" fill="#d4d4d4" stroke="orange" stroke-width="8" rx="10" ry="10" />
<text x="170" y="45" font-family="Arial" font-size="15" fill="black" text-anchor="middle">Congratulations for achieving {{qualification}}!</text>
<text x="170" y="70" font-family="Arial" font-size="12" fill="black" text-anchor="middle">Awarded to: {{recipient.name}}</text>
</svg>`,
"type": "SvgRenderingTemplate2023",
"name": "SVG Demo",
}],
"qualification": "SVG rendering",
"recipient": {
"name": "Yourself"
}
}
第3步 - Svg渲染器的基本用途
对于非生产试验,提供适配器组件,允许使用SVG提供OA v2文件. 警告(Warning):这是一个实验性选项,用于OA v4之前想要尝试SVG渲染的用户. 这一构成部分将不予积极维持.
import React, { useRef } from "react";
import { __unsafe__not__for__production__v2__SvgRenderer } from "@govtechsg/decentralized-renderer-react-components";
// Your renderer component
const export DocumentRenderer: React.FC<RendererProps> = ({ rawDocument }) => {
const svgRef = useRef<HTMLImageElement>(null)
return
< __unsafe__not__for__production__v2__SvgRenderer
document={rawDocument}
svgRef={svgRef}
/>
}
在编译时,最终渲染出的形象应该看起来像: