# @govtechsg/decentralized-renderer-react-components 中文文档

规范地址：https://npmcn.com/package/%40govtechsg/decentralized-renderer-react-components/

版本：3\.16\.4
npm 元数据更新时间：2026-07-03T07:14:45.690Z
中文译文更新时间：2026-11-17T06:46:42.725Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40govtechsg/decentralized-renderer-react-components
原文对照：https://npmcn.com/package/%40govtechsg/decentralized-renderer-react-components/?lang=original
项目主页：https://github.com/Open-Attestation/decentralized-renderer-react-components#readme
源码仓库：https://github.com/Open-Attestation/decentralized-renderer-react-components

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

- 包体积（解压后）：6.7 MB，201 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：18 个
- peer 依赖：react \>=16\.8\.0
- 首次发布：2019-10-18T07:36:47.572Z
- 最新版本发布：2025-05-09T05:55:57.271Z
- 近 30 天下载量：5513（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 0 个）

## 中文简介

[反应组件](https://github.com/Open-Attestation/decentralized-renderer-react-components) 用于抽象与 OpenAttestation 分散渲染器的通信。 详情见下文:

## 安装

```sh
npm install @govtechsg/decentralized-renderer-react-components
```

也可以使用：`pnpm add @govtechsg/decentralized-renderer-react-components`、`yarn add @govtechsg/decentralized-renderer-react-components`、`bun add @govtechsg/decentralized-renderer-react-components`

## README

# 反应组件

[反应组件](https://github.com/Open-Attestation/decentralized-renderer-react-components) 用于抽象与 OpenAttestation 分散渲染器的通信。 详情见下文:

-   [OpenCerts V2 公告](https://docs.opencerts.io/docs/migrations/v1_to_v2#announcements)
-   [开口站](https://openattestation.com/)

## 特征

-   [**调试**](https://github.com/visionmedia/debug) - 在节点和浏览器中都起作用的JS调试工具
-   [**ESLint 语录**](http://eslint.org/) - 用这个工具,你写质量代码.
-   [**欢乐**](https://jestjs.io/) - Facebook使用的JavaScript测试框架
-   [**高级**](https://prettier.io/) - 它通过解析你的代码并重新打印它来强化一种一致的风格.
-   [**反应**](http://reactjs.org/) - 用于构建用户界面的 JavaScript 库
-   [**反应测试库**](https://testing-library.com/) - 鼓励良好测试做法的简单和完整的测试设施
-   [**类型脚本**](https://www.typescriptlang.org/) - 一个提供可选静态打字的JavaScript超级集
-   [**语义释放**](https://semantic-release.gitbook.io/semantic-release/) - 一个完全自动化的版本管理和软件包出版工具
-   [**故事书**](https://storybook.js.org/) - 与文件隔离开发UI组件的工具
-   [**网络软件包**](https://webpack.js.org/) - 组件捆绑器

## 安装

为分散的渲染器安装 React 组件,下载或 `git clone` [此寄存器](https://github.com/Open-Attestation/decentralized-renderer-react-components)数字 :

```sh
$ 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渲染. 点击 [这里](https://npmcn.com/package/%40govtechsg/decentralized-renderer-react-components/#readme-svg-rendering) 需要更多信息.

首先,请务必阅读最初的导言和解释 [分散渲染器](https://docs.opencerts.io/docs/migrations/v1_to_v2)。 。 。 .

为渲染文档,主机会装入相应的分散渲染器(如文档所指定)并使用iframe嵌入. 主机和iframe之间的通信是使用 [后图像 API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) 并且是用动作设计的.

## 动作 API

所有动作都遵循相同的结构. 他们由下列人员组成: `type` 财务报告和审定财务报表 `payload`数字 :

-   `type` 说明正在采取的行动,例如, `RENDER_DOCUMENT` 表示渲染文档. 动作的类型是 _强制_。 。 。 .
-   `payload` 表示与类型有关的可选数据,例如要提供的文件的内容.

下面是一个代码示例:

```javascript
const renderDocumentAction = {
  type: "RENDER_DOCUMENT",
  payload: {
    document: documentToRender,
  },
};

const printAction = {
  type: "PRINT",
};
```

### 从主机到框架动作

以下列出为主机与iframe进行通信而采取的行动列表,因此必须由iframe所嵌入的应用程序处理: iframe

-   绘制文档 :
    
    -   类型 : `RENDER_DOCUMENT`
    -   有效载荷:具有两个特性的物体
        -   文档 : (强制性)文档数据返回 `getData` 方法从 [@govtechsg/ 开放式测试](https://github.com/Open-Attestation/open-attestation)
        -   原始文档:(可选) OpenAttestation 文档
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "RENDER_DOCUMENT",
  payload: {
    document: getData(document),
    rawDocument: document,
  },
};
```

-   在分散渲染器提供的模板中选择一个模板(渲染器可能向许多不同的模板提供一个模板以显示文档):
    
    -   类型 : `SELECT_TEMPLATE`
    -   有效载荷:(强制性) 要显示的模板 ID
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "SELECT_TEMPLATE",
  payload: "CUSTOM_TEMPLATE",
};
```

-   请求打印文件
    
    -   类型 : `PRINT`
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "PRINT",
};
```

第四个动作可以用于React Natural应用程序(引擎盖下不使用iframe)的背景中

-   请求提供文件模板清单。 动作直接返回模板列表
    
    -   类型 : `GET_TEMPLATES`
    -   有效载荷:(强制性)文件数据,由 `getData` 方法从 [@govtechsg/ 开放式测试](https://github.com/Open-Attestation/open-attestation)
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "GET_TEMPLATES",
  payload: getData(document),
};
```

### 从框架到主机动作

以下列出为iframe与主机通信而采取的行动清单(因此必须由嵌入iframe的应用程序处理):

-   提供iframe的全部内容高度,使主机可以自动适应嵌入式iframe大小.
    
    -   类型 : `UPDATE_HEIGHT`
    -   有效载荷:iframe的(强制性)全部含量高度
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "UPDATE_HEIGHT",
  payload: 150,
};
```

-   提供文档上一个字段的名称来混淆。 值必须遵循所处理的路径属性 [摇摆# 获得](https://lodash.com/docs/4.17.15#get)
    
    -   类型 : `OBFUSCATE`
    -   有效载荷:(强制性)去地道
    
    下面是一个代码示例:
    

```javascript
const action = {
  type: "OBFUSCATE",
  payload: "a[0].b.c",
};
```

-   提供可用于渲染文档的模板列表
    
    -   类型 : `UPDATE_TEMPLATES`
    -   有效载荷:(强制性)每个元素为由字符串和标签组成的对象的阵列
    
    下面是一个代码示例:
    

```javascript
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内部有变化时(使用 [变异观察员](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)) (中文(简体) ).
-   它会自动呼叫 `Template` 根据主办方提供的信息,提供文件.
-   当文件被请求渲染时,它将自动提供可用的模板(即它将调用 `UPDATE_TEMPLATES` 一旦文件已经提供,即可采取行动).
-   它会自动调用 `OBFUSCATE` 请求时的行动 `Template`。 。 。 .

你需要检查密码 `example/decentralized-renderer` 以查看如何使用此组件。 您也可以使用命令启动示例程序 `npm run example:renderer`

#### 模板( 反应组件)

当一个文档被打开时, 每个文件都会被配置 `Template` 将提供以下属性:

-   `document`: (强制性) 文档数据由 `getData` 方法从 [@govtechsg/ 开放式测试](https://github.com/Open-Attestation/open-attestation)
-   `rawDocument`: (可选) OpenAttestation 文档
-   `handleObfuscation`: (强制性)一个调用功能,可以处理文档中的歧义. 提供的值必须遵循由 [摇摆# 获得](https://lodash.com/docs/4.17.15#get)。 。 。 .

## 发展

为不同的开发任务运行下列命令:

-   `npm run storybook`: 开始一个故事本, 创建故事, 并可视化不同的组件
    
-   `npm run test`: 运行测试
    
-   `npm run lint`: 运行林特
    
-   `npm run example:application`: 运行在此库中构建的示例应用程序
    
    如果您更新了此库, 请确定要更新此示例 .
    
-   `npm run example:renderer`: 运行一个使用此库构建的分散化渲染器实例
    
    如果您更新了此库, 请确定要更新此示例 .
    

也可以以此为基础建造自己的分散式后台 [反应模板](https://github.com/Open-Attestation/decentralized-renderer-react-template)。 。 。 .

## 彭帕尔

有兼容性 [问题](https://github.com/Aaronius/penpal/issues/52) 在 Penpal 版本 ^ 5 和 ^ 4 之间. 如果您必须使用 Penpal 版本 ^ 4, 请获取版本 [4.1.1 国家](https://github.com/Aaronius/penpal/releases/tag/v4.1.1)。 。 。 .

# SVG 渲染

SVG渲染的执行基于 [W3C草案](https://w3c-ccg.github.io/vc-render-method/#render-svgrenderingtemplate2023)。 。 。 .

## 如何运作

SVG渲染是现有的嵌入式渲染器方法的替代品,可以在不创建分散式渲染器的情况下实现.

相反,SVG图像需要通过直接嵌入到OA文档中来提供,或者通过提供可公开访问的链接来贬低SVG图像. 为了正确显示数据,所提供的SVG应包括: [手提箱表达式](https://handlebarsjs.com/guide/expressions.html)。 。 。 .

在显示点,要渲染的文档被传递到SvgRender组件,以便编译出最终的输出.

## 使用量

图书馆提供 `SvgRenderer` 组件.

### Svg 渲染器

这个部分只有一个强制财产 `document`。 。 。 .

-   `document`: OA文档,形式为对象并有对应的字段来显示.
-   `style?`: 要样式 iframe 元素.
-   `className?`:为iframe设置类名.
-   `onResult?`: SVG 装入后包含显示结果的回调函数.
-   `ref?`: HTML Image Element 类型可以被取出,它会暴露已渲染元素的 DOM 节点.

### 制作方法财产

包含在 OA doc 中的对象数组,详情请参考 [w3c 规格](https://w3c-ccg.github.io/vc-render-method/#svgrenderingtemplate2023)。 。 。 .

目前此库中的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](https://github.com/Open-Attestation/decentralized-renderer-react-components/blob/master/example/application/fixtures/images/demo-cert.svg?raw=true)

确保 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](https://github.com/Open-Attestation/decentralized-renderer-react-components/blob/master/example/application/fixtures/images/demo-cert-compiled.png?raw=true)

## 常见问题

### @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 和提交记录判断。

