# @cucumber-stories/cucumber-datatable 中文文档

规范地址：https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/

版本：3\.0\.1
npm 元数据更新时间：2023-04-11T15:18:41.812Z
中文译文更新时间：2026-11-11T04:25:56.972Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cucumber-stories/cucumber-datatable
原文对照：https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/?lang=original

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

- 包体积（解压后）：37.1 kB，51 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@cucumber/cucumber \>= 8\.x
- 首次发布：2022-11-16T16:35:39.947Z
- 最新版本发布：2023-04-11T15:18:41.680Z
- 近 30 天下载量：23579（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 0 个）

## 中文简介

Cucumber DataTable是一个用于简化并增强gherkins特征文件中的数据表格的库.

## 安装

```sh
npm install @cucumber-stories/cucumber-datatable
```

也可以使用：`pnpm add @cucumber-stories/cucumber-datatable`、`yarn add @cucumber-stories/cucumber-datatable`、`bun add @cucumber-stories/cucumber-datatable`

## README

# 木瓜数据表

[![Node.js CI](https://github.com/cucumber-stories/cucumber-datatable/actions/workflows/ci.yml/badge.svg)](https://github.com/cucumber-stories/cucumber-datatable/actions/workflows/ci.yml)

## 安装

`npm i @cucumber-stories/cucumber-datatable`

## 这是什么?

Cucumber DataTable是一个用于简化并增强gherkins特征文件中的数据表格的库. 通过为您的数据表提供计划,您可以很容易地从愚蠢的字符串传递到结构化和输入的数据.

### 样本比100个字好:

想象一下你想处理这样一个格金表:

```gherkin
Feature: Heroes sample

  Scenario: A simple heroes table
    Given the following heroes
      | Name         | Age |
      | Bruce Wayne  | 83  |
      | Tony Stark   | 52  |
      | Bruce Banner | 53  |
```

#### 感谢 `@cucumber-stories/cucumber-datatable` 写这个...

```typescript
import { DataTable } from "@cucumber/cucumber";
import { cucumberDataTable } from "@cucumber-stories/cucumber-datatable";

const getHeroes = cucumberDataTable({
  name: { columnName: "Name", converter: Converters.String },
  age: { columnName: "Age", converter: Converters.Number },
});

Given(/^The following heroes$/, function (dataTable: DataTable) {
  const heroes = getHeroes(dataTable);
  console.log(heroes); // [{ name: 'Bruce Wayne', age: 83 }, ...]
});
```

#### 不是那样的

```typescript
import { DataTable } from "@cucumber/cucumber";

Given(/^The following heroes$/, function (table: DataTable) {
  const lines = data.raw();
  // Here you have an hugly array of string arrays (string[][]) ☹️
});
```

## 如何用取来?

首先,你必须定义一个由两件事组成的词典. 它的密钥与输出对象相同,并附加以下元数据:

-   `columnName`: gherkin 文件中的列名 (`.feature`(中文(简体) )
-   `converter`: 用于从gherkin数据表中转换数据的转换器

你必须使用 `cucumberDataTable()` 函数创建用于您步骤中的可重用函数以转换您的 数据.

```typescript
import { cucumberDataTable } from "@cucumber-stories/cucumber-datatable";

const dictionary = {
  name: {
    columnName: "Name", // Column name in Gherkin file
    converter: Converters.String, // Converter to use (more samples below)
  },
  age: {
    columnName: "Age",
    converter: Converters.Number,
  },
};

const getStructuredData = cucumberDataTable(dictionary);

// ....
Given(/^The following table/, function (dataTable: DataTable) {
  const data = getStructuredData(dataTable);
});
```

### 转换器

转换器用于转换数据. 在框外,图书馆提供一些有用的转换器.

一些转换器可以配置,你可以有细节 [转换器配置](https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/#readme-converter-config) 节.

| 名称 | 在盖尔金 | 产出 | [默认配置](https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/#readme-converter-config) |
| --- | --- | --- | --- |
| `Converters.String` | `"Foo"` | `"Foo"` |  |
| `Converters.Number` | `"42"` | `42` |  |
| `Converters.YesNoToBoolean` | `"yes"` 或者说 `"no"` | `true` 或者说 `false` | `{ yes: "yes"; no: "no" }` |
| `Converters.StringArray` | `"Foo, Bar"` | `["Foo", "Bar"]` | `{ separator: "," }` |
| `Converters.ObjectArray` | `"Foo:42, Bar:32"` | [见下文](https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/#readme-object-array-converter) | `{ propertySeparator: ":", itemSeparator: "," }` |
| `Converters.Nullable` | `"<null>"` | [见下文](https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/#readme-nullable) | `{ nullValue: "<null>" }` |
| `Converters.Custom` | 您的特殊格式化逻辑 | [见下文](https://npmcn.com/package/%40cucumber-stories/cucumber-datatable/#readme-custom-converter) |  |

#### 转换器配置

如果转换器需要配置,可以拨打 `.withConfig` 带有指定配置的方法,例如:

```typescript
const dictionary = {
  tags: {
    columnName: "Tags",
    converter: Converters.StringArray.withConfig({
      separator: "-",
    }),
  },
};
```

#### 无效

如果您的一些值需要无效, 并想要用作 `null` 在代码中,您可以使用 `Nullable` 转换器.

```typescript
const dictionary = {
  name: {
    columnName: "Name",
    converter: Converters.Nullable(Converters.String),
  },
};

// name will be string | null
```

您也可以配置无效值, 默认为 `<null>`

```typescript
const dictionary = {
  name: {
    columnName: "Name",
    converter: Converters.Nullable(Converters.String, {
      nullValue: "vide",
    }),
  },
};

// name will be string | null, when the value is "vide"
```

#### 对象数组转换器

这个 `Converters.ObjectArray()` 有点棘手,所以它值得它自己 在我们的文件.

设想以下的 gherkin 文件 :

```gherkin
Feature: Heroes sample

  Scenario:
    Given the following attributes
      | Attributes     | Other |
      | 1:Color,2:Size | other |
      | 10:Name        | other |
```

如果您想要这样的输出 :

```typescript
[
  {
    attributes: [
      { code: 1, name: "Color" },
      { code: 2, name: "Size" },
    ],
    other: "other",
  },
  {
    attributes: [{ code: 10, name: "Name" }],
    other: "other",
  },
];
```

你也许需要 `Converters.ObjectArray()`。 。 。 .

要使用此转换器, 您必须定义 :

-   不同项目的分隔符
-   同一对象不同属性的分隔符

然后是筑巢物体的图谋:

```typescript
import {
  cucumberDataTable,
  Converters,
} from "@cucumber-stories/cucumber-datatable";

const dictionary = {
  attributes: {
    columnName: "Attributes",
    converter: Converters.ObjectArray({
      code: {
        position: 0,
        converter: Converters.Number,
      },
      name: {
        position: 1,
        converter: Converters.String,
      },
    }).withConfig({
      propertySeparator: ":",
      itemSeparator: ",",
    }),
  },
  // Other columns...
  other: {
    columnName: "Other",
    converter: Converters.String,
  },
};

const getStructuredData = cucumberDataTable(dictionary);
```

> 你不必说明 `.withConfig` 如果您想要保留默认配置 实值 `{ propertySeparator: ":", itemSeparator: "," }`

#### 自定义转换器

简而言之,转换器就是 `Converter` 课。 要创建自定义转换器以满足您的需要, 您需要 用于 `Converter.Custom(<Your converter function>)`。 。 。 .

转换器函数为:

1.  参数中的字符串(来自gherkin文件的数据),
2.  作为第二个参数的可选配置,
3.  并返回你想要的东西.

例如,如果想要从一列输出自定义结构,您可以这样做:

```typescript
import {
  cucumberDataTable,
  Converters,
} from "@cucumber-stories/cucumber-datatable";

const dictionary = {
  code: {
    columnName: "Code",
    converter: Converters.Custom((code: string) => ({ nested: code })),
  },
  configurableCode: {
    columnName: "Configurable code",
    converter: Converters.Custom(
      (code: string, config?: { append: string }) => code + config?.append
    ).withConfig({
      append: "-code",
    }),
  },
  // Other columns...
  other: {
    columnName: "Other",
    converter: Converters.String,
  },
};

const getStructuredData = cucumberDataTable(dictionary);
```

它将改变这个表格:

```gherkin
Feature: Heroes sample

  Scenario: A simple heroes table
    Given the following table
      | Code | Configurable code | Other |
      | 001  | 001               | other |
      | 002  | 001               | other |
```

输入 :

```typescript
[
  { code: { nested: "001" }, configurableCode: "001-code", other: "other" },
  { code: { nested: "002" }, configurableCode: "002-code", other: "other" },
];
```

## 发展

### 正在测试

运行 `npm test` 财务报告和审定财务报表 `npm run test-types`

### 发布新版本

1.  `npm version <major|minor|patch>`
2.  `git push --tags`
3.  在此标签上创建发布 .

## 常见问题

### @cucumber-stories/cucumber-datatable 是什么？

Cucumber DataTable是一个用于简化并增强gherkins特征文件中的数据表格的库\.

### 如何安装 @cucumber-stories/cucumber-datatable？

在项目目录运行 npm install @cucumber-stories/cucumber-datatable，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@cucumber/cucumber（\>= 8\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cucumber-stories/cucumber-datatable 支持 TypeScript 吗？

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

### @cucumber-stories/cucumber-datatable 支持 ESM 还是 CommonJS？

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

### @cucumber-stories/cucumber-datatable 可以商用吗？

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

### @cucumber-stories/cucumber-datatable 的下载量有多少？

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

### @cucumber-stories/cucumber-datatable 还在维护吗？

最新版本 3\.0\.1 发布于 2023/04/11（3 年前）；至今共发布 7 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/11/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。