@govtechsg/decentralized-renderer-react-components

中文文档
3.16.4发布于 2025/05/09Apache-2.0TypeScriptESM + CJS近 30 天下载 5513

反应组件 用于抽象与 OpenAttestation 分散渲染器的通信。 详情见下文:

中文使用文档
文档目录19 节
  1. 特征
  2. 安装
  3. 如何运作
  4. 动作 API
  5. 从主机到框架动作
  6. 从框架到主机动作
  7. 使用量
  8. 框架连接器
  9. 框架文档渲染器
  10. 发展
  11. 彭帕尔
  12. 如何运作
  13. 使用量
  14. Svg 渲染器
  15. 制作方法财产
  16. 示例
  17. 步骤 1 - 准备您的模板 SVG
  18. 步骤 2 - 创建样本 Raw/ 未包装的 OpenAttestation doc
  19. 第3步 - Svg渲染器的基本用途

反应组件

反应组件 用于抽象与 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.md
  • LICENSE
  • 添加您的模板( 在 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
    • 有效载荷:具有两个特性的物体

    下面是一个代码示例:

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)的背景中

  • 请求提供文件模板清单。 动作直接返回模板列表

    下面是一个代码示例:

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页:1 Template,即生成文档的反应组件
  • attachmentToComponent:根据附件类型绘制组件附件的函数.

    目前,图书馆有两种功能:

    1. noAttachmentRenderer: 用途 UnsupportedRenderer

    2. 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 预览 :

demo template 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}
    />
}

在编译时,最终渲染出的形象应该看起来像:

demo compiled template svg

版本与发布记录

@govtechsg/decentralized-renderer-react-components 共发布 79 个版本,首次发布于 2019/10/18;过去 12 个月发布了 0 个版本。

版本发布日期距今
3.16.4latest2025/05/091.5 年前
3.17.0-beta.2beta2024/07/162 年前
3.16.32024/06/122 年前
3.17.0-beta.12024/05/312 年前
3.18.0-beta.12024/05/302 年前
3.17.02024/05/232 年前

其他发布通道:alpha → 3.13.0-alpha.1,beta → 3.17.0-beta.2。

关于 @govtechsg/decentralized-renderer-react-components 的常见问题

@govtechsg/decentralized-renderer-react-components 是什么?

反应组件 用于抽象与 OpenAttestation 分散渲染器的通信。 详情见下文:

如何安装 @govtechsg/decentralized-renderer-react-components?

在项目目录运行 npm install @govtechsg/decentralized-renderer-react-components,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@govtechsg/decentralized-renderer-react-components 支持 TypeScript 吗?

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

@govtechsg/decentralized-renderer-react-components 支持 ESM 还是 CommonJS?

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

@govtechsg/decentralized-renderer-react-components 可以商用吗?

@govtechsg/decentralized-renderer-react-components 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@govtechsg/decentralized-renderer-react-components 的下载量有多少?

根据 npm 官方下载统计,@govtechsg/decentralized-renderer-react-components 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,513 次,日均约 184 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@govtechsg/decentralized-renderer-react-components 还在维护吗?

最新版本 3.16.4 发布于 2025/05/09(1.5 年前);至今共发布 79 个版本,其中过去 12 个月发布了 0 个;首次发布于 2019/10/18。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。