# @eeacms/volto-datablocks 中文文档

规范地址：https://npmcn.com/package/%40eeacms/volto-datablocks/

版本：9\.0\.6
npm 元数据更新时间：2026-10-30T12:20:33.187Z
中文译文更新时间：2026-11-13T07:54:23.345Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eeacms/volto-datablocks
原文对照：https://npmcn.com/package/%40eeacms/volto-datablocks/?lang=original
项目主页：https://github.com/eea/volto-datablocks
源码仓库：https://github.com/eea/volto-datablocks

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

- 包体积（解压后）：3.8 MB，392 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：10 个
- 首次发布：2021-05-28T14:23:46.026Z
- 最新版本发布：2026-10-30T12:20:33.021Z
- 近 30 天下载量：3881（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 13 个）

## 中文简介

(EEA) 提供原始数据连接到伏地图和其他块

## 安装

```sh
npm install @eeacms/volto-datablocks
```

也可以使用：`pnpm add @eeacms/volto-datablocks`、`yarn add @eeacms/volto-datablocks`、`bun add @eeacms/volto-datablocks`

## README

# 数据连接的 Volto 组件

[![Releases](https://img.shields.io/github/v/release/eea/volto-datablocks)](https://github.com/eea/volto-datablocks/releases)

[![Pipeline](https://ci.eionet.europa.eu/buildStatus/icon?job=volto-addons%2Fvolto-datablocks%2Fmaster&subject=master)](https://ci.eionet.europa.eu/view/Github/job/volto-addons/job/volto-datablocks/job/master/display/redirect) [![Lines of Code](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&metric=ncloc)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks) [![Coverage](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&metric=coverage)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks) [![Bugs](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&metric=bugs)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks) [![Duplicated Lines (%)](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&metric=duplicated_lines_density)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks)

[![Pipeline](https://ci.eionet.europa.eu/buildStatus/icon?job=volto-addons%2Fvolto-datablocks%2Fdevelop&subject=develop)](https://ci.eionet.europa.eu/view/Github/job/volto-addons/job/volto-datablocks/job/develop/display/redirect) [![Lines of Code](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&branch=develop&metric=ncloc)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks&branch=develop) [![Coverage](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&branch=develop&metric=coverage)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks&branch=develop) [![Bugs](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&branch=develop&metric=bugs)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks&branch=develop) [![Duplicated Lines (%)](https://sonarqube.eea.europa.eu/api/project_badges/measure?project=volto-datablocks&branch=develop&metric=duplicated_lines_density)](https://sonarqube.eea.europa.eu/dashboard?id=volto-datablocks&branch=develop)

[沃尔多](https://github.com/plone/volto) 加载

Volto-datablocks是一个有各种块和公用功能来提供"数据连接"组件于Volto网站的附加.

**此添加需要 `eea.docker.plonesaas@5.2.4-66`。 。 。 .**

## 开始

### 与 Docker 一起尝试 Volto 数据块

```
  git clone https://github.com/eea/volto-datablocks.git
  cd volto-datablocks
  make
  make start
```

转到 http://localhost:3:00

`make start` 现在默认为 Volto 18. 要运行同样的设置 对沃尔多17,使用:

```
  VOLTO_VERSION=17 make
  VOLTO_VERSION=17 make start
```

## 概念和术语

-   数据连接组件:是显示来自外部来源信息的组件或块; 例如,一个表格可以从一个 REST api 服务器( discodata.eea.europa.eu) 获取数据,并按要求显示数据
-   连接器 / 提供者: 是具有以下特征的自定义内容类型:
    -   标题: 担任连接器的名称, 它被plone 用来编译我们可查询连接器的短名或路径
    -   endpoint url: URL 到 REST api 服务器( ex. discodata.eea.europa.eu)
    -   sql query: 将在 REST api 服务器上执行的 sql
    -   参数(可选):一个参数列表(键),我们可以通过它来过滤连接器获取的数据
    -   需要的参数( 可选) : 需要的参数列表, 如不匹配连接符, 将返回空数据
    -   整理( 可选)
    -   读取( 可选)
-   从url; Ex.查询字符串参数或参数. `https://frontend/home?db_version=latest&p=1&nrOfHits=10`
-   数据查询是使用redux在内部构成的另一类参数
-   相连接的数据参数是存储数据查询的全局对象;我们稍后将获得更多相关内容

## 工作流程

一个数据连接的组件将使用一个连接器来获取其数据.

[eea.api.data连接器](https://github.com/eea/eea.api.dataconnector) 是一个 plone 添加, 显示一个 api, 连接器将运行一个查询并获取一些数据 .

### 如何使用 eea.api.data连接器

eea.api.data连接器曝光 `/@connector-data` 我们可以通过它 `POST` 请求获取连接器的数据。 我们可以向请求传递一些数据:

-   `form` - 来自url的参数
-   `data_query` - 相关数据参数的参数

您只能在连接器上使用此 API .

示例

假设连接器文件夹中添加了以下连接器:

```
title: Forests per capita
endpoint_url: https://discodata.eea.europa.eu/sql
sql_query: SELECT * FROM [FISE].[latest].[v_cnct_forest_per_capita]
parameters: ['NUTS_CODE']
```

连接器的路径是 `https://frontend/connectors/forests-per-capita`

通过以下请求:

```
> curl --location --request POST 'http://backend/Plone/++api++/connectors/forests-per-capita/@connector-data'
```

sql query将在指定的端点 url(discodata)上被执行,在获取数据后,响应会看起来像:

```JSON
{
   "@id": "https://backend/Plone/connectors/forests-per-capita",
   "data": {
      "metadata": {...},
      "results": {
         "COUNTRY": ["Albania", ...],
         "Forest per capita": [0.39, ...],
         "NUTS_CODE": ["AL", ...],
      }
   }
}
```

我们可以以两种方式过滤数据:

-   通过在 Discodata 上执行 sql 之前更新 sql 通过添加语句 - 这就需要在连接器上指定参数属性
-   通过从 Discodata 获取数据后过滤数据以获取循环

Obs:后端同时进行过滤. 回复中将始终包含被过滤出的数据.

在这种情况下,我们可以过滤 通过 `NUTS_CODE`2\. 请求将看起来是:

```
> curl --location --request POST 'http://backend/Plone/++api++/connectors/forests-per-capita/@connector-data' \
--header 'Content-Type: application/json' \
--data '{
    "form": {
        "NUTS_CODE": "FR"
    }
}'
```

因为 `NUTS_CODE` 将在连接器的参数列表中指定查询将被修改,并看起来像:

```sql
SELECT * FROM FISE.latest.v_cnct_forest_per_capita WHERE NUTS_CODE = 'FR'
```

因此,我们从迪斯科数据中获取的数据已经过滤过,并且反应会看起来像:

```JSON
{
   "@id": "https://backend/Plone/connectors/forests-per-capita",
   "data": {
      "metadata": {...},
      "results": {
         "COUNTRY": ["France"],
         "Forest per capita": [0.23],
         "NUTS_CODE": ["FR"],
      }
   }
}
```

如果我们没有 `NUTS_CODE` 在参数列表中指定 `NUTS_CODE` 在它从迪斯科数据中取出之后, 因此通过在参数列表中添加密钥,可以显著地减少数据使用.

如果我们想要设置相同的参数, 但通过数据 query, 请求会看起来像这样:

```
> curl --location --request POST 'http://backend/Plone/++api++/connectors/forests-per-capita/@connector-data' \
--header 'Content-Type: application/json' \
--data '{
   "data_query": [
      "i": "NUTS_CODE"
      "o": "plone.app.querystring.operation.selection.any"
      "v": ["FR"]
   ]
}'
```

Volto-datablocks提供4个钩子,一个数据连接的组件可以通过它向连接器提出请求:

```
connectToProviderData
connectToProviderDataUnfiltered
connectToMultipleProviders
connectToMultipleProvidersUnfiltered
```

Obs:一个数据连接的组件需要指定一个提供者 url(连接器的路径)到用来获取数据的钩子. 我们以后会有更多事情要做.

## 运算符

### 参数来自url - `form`

可用的运算符 :

```
eq          - equal
ne          - not equal
like
not like
in
nin         - not in
gt          - greater than
gte         - greater than equal
lt          - lower than
lte         - lower than equal
```

要从 URL 指定一个运算符到参数, 您需要使用此结构 :

```
some/path?parameter[operation]=value
```

例如,如果在主页上我们有一个数据连接的组件使用 `/connectors/forests-per-capita` 作为供应商,我们想通过多重过滤它 `NUTS_CODE` 我们可以使用“ in” 运算符设置 url 参数, 如:

```
https://frontend/?NUTS_CODE[in]=RO,FR
```

### 来自数据 query - `connected_data_parameters`

继续...

## 倾斜

继续...

## 特征

此添加中有一些数据相连接的块:

### 简单数据表

一个数据连接的表格,可以进行页码和过滤。 可通过实施模板进行定制.

`TODO: tutorial on how to customize and demo`

### 数据查询过滤器

由从块配置中选择的参数来创建过滤器.

`TODO: demo`

### 点数 表格图表

### 自定义连接块

## 用法( 开发者)

### 如何连接一个街区和一个提供者?

正如我们所说,我们有4个钩子,2个钩子使用过滤器,2个钩子不使用过滤器。 它们要求您通过返回对象的 GetConfig 函数 。 该对象需要一些具体的数据.

以下是需要传递到每个钩的配置 :

1.  `connectToProviderData`

```javascript
{
   provider_url: 'path/to/provider', // mandatory
   pagination: { // optional
      enabled: true,
      itemsPerPage: 5
   }
}
// Obs: provider_url is mandatory and pagination is optional. If pagination is not configured then connectToProviderData will run as if pagination is disabled.
```

2.  `connectToProviderDataUnfiltered`

```javascript
{
  provider_url: 'path/to/provider'; // mandatory
}
```

3.  `connectToMultipleProviders`

```javascript
{
   provider: [ // mandatory
      {
         provider_url: 'path/to/provider', // mandatory
         name: 'some name', // optional
         title: 'some title', // optional
         data_query: [...some_data_query] // optional
         has_data_query_by_context: true // optional
         has_data_query_by_provider: true // optional
      }
   ]
}
```

4.  `connectToMultipleProvidersUnfiltered`

```javascript
{
  provider: [
    // mandatory
    {
      provider_url: 'path/to/provider', // mandatory
      name: 'some name', // optional
      title: 'some title', // optional
    },
  ];
}
```

连接到多家提供者并不允许pagination.

以下是如何使用的实例 `connectToProviderData`数字 :

```javascript
import React from 'react';
import { compose } from 'redux';
import { connectToProviderData } from '@eeacms/volto-datablocks/hocs';

...

const View = props => {
   ...
   return <YourComponents />
}

export default compose(
  connectToProviderData((props) => {
    return {
      provider_url: props.data?.provider_url,
    };
  }),
)(View);

```

## 开始

### 与 Docker 一起尝试 Volto 数据块

```
  git clone https://github.com/eea/volto-datablocks.git
  cd volto-datablocks
  make
  make start
```

转到 http://localhost:3:00

### 在您的 Volto 工程中添加 volto 数据块

1.  确保你有 [Plone 后端](https://plone.org/download) 在http://localhost:8080/Plone上运行
    
    ```Bash
    docker compose up backend
    ```
    
2.  启动 Volto 前端
    

-   如果你已经有伏尔托项目,只需更新 `package.json`数字 :
    
    ```JSON
    "dependencies": {
        "@eeacms/volto-datablocks": "*"
    }
    ```
    

财务报告和审定财务报表 `volto.config.js`数字 :

```JavaScript
const addons = ['@eeacms/volto-datablocks'];
```

-   如果没有,请按照Plone官方文件对Volto 18+的建议,用 Cookieplone 创建一个:
    
    ```
    uvx cookieplone project
    cd project-title
    ```
    

1.  安装或更新依赖关系,然后启动项目 :
    
    ```
    make install
    ```
    
    对于 Cookieplone 项目, 在单独的终端中启动后端和前端 :
    
    ```
    make backend-start
    make frontend-start
    ```
    
    对于一个遗留下来的Volto 17项目,安装软件包 `yarn` 并像往常一样重新启动前端.
    
2.  转到 http://localhost:3:00
    
3.  剪辑愉快!
    

## 释放

见 [发 言](https://github.com/eea/volto-datablocks/blob/master/RELEASE.md)。 。 。 .

## 如何捐款

见 [发达国家d](https://github.com/eea/volto-datablocks/blob/master/DEVELOP.md)。 。 。 .

## 秘密扫描

此寄存器使用 Betterleaks GitHub 动作扫描当前 每个推拉请求的仓库内容。 扫描使用规则在 `.gitleaks.toml` 上传 a `betterleaks-report` 发现时的文物 检测到.

如果配置了可选的 SMTP 秘密, 失败的扫描也会发送电子邮件到 最后的犯规者。 工作流程期望这些寄存器或 组织机密:

-   `SMTP_URL`
-   `SMTP_PORT` (可选,默认为) `25`(中文(简体) )
-   `SMTP_EMAIL`
-   `SMTP_PASSWORD` (如果 SMTP 服务器不需要认证, 可选择)

端口 `465` 以直接 TLS 发送; 其他端口使用默认 SMTP 握手. 电子邮件中包含一个简短的发现摘要, 包括每个发现中经过编辑的匹配行.

有三个共同的结果:

1.  **一切都没事.** 这个 `Betterleaks / Scan for secrets` 检查为绿色 无需采取行动。 运行时间值的常规引用是确定的, 例如:
    
    ```js
    const tokenFromCookie = req.universalCookies.get('auth_token');
    ```
    
2.  **发现了一个真正的秘密.** 检查为红色,工作流程日志要求您 下载 `betterleaks-report` 艺术品 从 GitHub 打开文物 动作运行并检查报告的文件,行和规则 。 删除已承诺 值,将其移动到合适的密店,如果被曝光则旋转. 报告条目是这样的:
    
    ```json
    {
      "RuleID": "secret-literal-assignment",
      "File": "src/config.js",
      "StartLine": 12,
      "Secret": "[REDACTED]"
    }
    ```
    
3.  **调查结果是虚假的阳性.** 只有在显然没有时才保留该值 敏感,例如测试固定图、占位符或公共实例。 添加 `betterleaks:allow` 在同一行中,并在 拉请求.
    
    ```js
    const testPassword = 'admin'; //betterleaks:allow
    ```
    
    ```yaml
    password: "admin" #betterleaks:allow
    ```
    

不添加 `betterleaks:allow` 到真正的证书.

## 版权和许可证

原始守则的初始所有人是欧洲环境署. 所有权利保留.

见 [利比里亚](https://github.com/eea/volto-datablocks/blob/master/LICENSE.md) 详细情况.

## 供资

[欧洲环境署(欧盟)](http://eea.europa.eu/)

## 常见问题

### @eeacms/volto-datablocks 是什么？

\(EEA\) 提供原始数据连接到伏地图和其他块

### 如何安装 @eeacms/volto-datablocks？

在项目目录运行 npm install @eeacms/volto-datablocks，或使用 pnpm add / yarn add / bun add。

### @eeacms/volto-datablocks 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eeacms\_\_volto-datablocks 是否存在。

### @eeacms/volto-datablocks 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @eeacms/volto-datablocks 可以商用吗？

@eeacms/volto-datablocks 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eeacms/volto-datablocks 的下载量有多少？

根据 npm 官方下载统计，@eeacms/volto-datablocks 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,881 次，日均约 129 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eeacms/volto-datablocks 还在维护吗？

最新版本 9\.0\.6 发布于 2026/10/30（14 天前）；至今共发布 103 个版本，其中过去 12 个月发布了 13 个；首次发布于 2021/05/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。