# @bbc/psammead-grid 中文文档

规范地址：https://npmcn.com/package/%40bbc/psammead-grid/

版本：3\.1\.16
npm 元数据更新时间：2026-04-16T10:53:55.550Z
中文译文更新时间：2026-11-07T19:00:34.177Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bbc/psammead-grid
原文对照：https://npmcn.com/package/%40bbc/psammead-grid/?lang=original
源码仓库：https://github.com/bbc/psammead/tree/latest/packages/components/psammead-grid

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

- 包体积（解压后）：478 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@emotion/styled ^11\.0\.0
- 首次发布：2019-10-02T13:21:22.749Z
- 最新版本发布：2022-03-30T12:44:29.030Z
- 近 30 天下载量：3763（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 0 个）

## 中文简介

网格组件

## 安装

```sh
npm install @bbc/psammead-grid
```

也可以使用：`pnpm add @bbc/psammead-grid`、`yarn add @bbc/psammead-grid`、`bun add @bbc/psammead-grid`

## README

# (原始内容存档于2012-10-10) (英语). phammead-grid - [![Known Vulnerabilities](https://snyk.io/test/github/bbc/psammead/badge.svg?targetFile=packages%2Fcomponents%2Fpsammead-grid%2Fpackage.json)](https://snyk.io/test/github/bbc/psammead?targetFile=packages%2Fcomponents%2Fpsammead-grid%2Fpackage.json) [![Dependency Status](https://david-dm.org/bbc/psammead.svg?path=packages/components/psammead-grid)](https://david-dm.org/bbc/psammead?path=packages/components/psammead-grid) [![peerDependencies Status](https://david-dm.org/bbc/psammead/peer-status.svg?path=packages/components/psammead-grid)](https://david-dm.org/bbc/psammead?path=packages/components/psammead-grid&type=peer) [![Storybook](https://raw.githubusercontent.com/storybooks/brand/master/badge/badge-storybook.svg?sanitize=true)](https://bbc.github.io/psammead/?path=/story/grid--default) [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/bbc/psammead/blob/latest/LICENSE) [![npm version](https://img.shields.io/npm/v/@bbc/psammead-grid.svg)](https://www.npmjs.com/package/@bbc/psammead-grid) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/bbc/psammead/blob/latest/CONTRIBUTING.md)

## 说明

Psammead Grid是一个组件,可以使用CSS Grid来设置以列为基础的布局. 它的设立是为了遵循标准 [断点 GEL 组](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes) 您可以按照 GEL 网格准则, 在 GEL 边距、 沟道和固定宽度上切换, 如果您在页面布局中使用它 .

## 安装

`npm install @bbc/psammead-grid`

## 道具

| 参数 | 类型 | 需求 | 默认 | 示例 |
| --- | --- | --- | --- | --- |
| 栏 | 对象 | 对 | 不详 | `{ group0: 6, group1: 6, group2: 6, group3: 6, group4: 8, group5: 20 }` |
| 启动 Offset | 对象 | 没有 | 为所有定义的组设定所有值为 1 `columns` | `{ group0: 1, group1: 1, group2: 1, group3: 1, group4: 2, group5: 5 }` |
| 项目 | 布尔 | 没有 | 虚假 | 真实 |
| 启用 GelGutters | 布尔 | 没有 | 虚假 | `enableGelGutter` |
| 边距 | 对象 | 没有 | `{ group0: false, group1: false, group2: false, group3: false, group4: false, group5: false }` | `{ group0: true, group1: true, group2: true, group3: true }` |
| 父颜色 | 对象 | 没有 | 无效 | `columns: { group0: 6, group1: 6, group2: 3, group3: 3, group4: 4, group5: 4}` |
| 父目录 | 布尔 | 没有 | 虚假 | 真实 |
| 目录 | 字符串 | 没有 | `'ltr'` | `'rtl'` |

-   我应该什么时候用 `columns` 道具吗?
    -   这一点应始终加以界定.
    -   所有栏组 `group0` 结束 `group5` 应当提供.
    -   对a `<Grid>` 元素,它是网格的列数,以及它应该横跨的列数.
    -   对a `<Grid item>` 元素,是它应该跨行的列数.
-   我应该什么时候用 `item` 道具吗?
    -   这个 `item` 道具应被使用在一个 `<Grid>` 那是另一个孩子的直接孩子 `<Grid>`。使用 `columns` prop 的值, 您可以在每个断点选择要跨出多少列 .
    -   当您定义新网格项目时, 它可以而且应该被使用 - 您想要在断点上覆盖一组列数的东西 .

```jsx
<Grid
  columns={{ group0: 6, group1: 6, group2: 6, group3: 6, group4: 6, group5: 6 }}
>
  <Grid
    item
    columns={{
      group0: 1,
      group1: 1,
      group2: 1,
      group3: 1,
      group4: 1,
      group5: 1,
    }}
  >
    This spans 1 out of 6 columns for all widths
  </Grid>
  <Grid
    item
    columns={{
      group0: 5,
      group1: 5,
      group2: 5,
      group3: 5,
      group4: 5,
      group5: 5,
    }}
  >
    This spans 5 out of 6 columns for all widths
  </Grid>
</Grid>
```

-   我应该什么时候用 `startOffset` 道具吗?
    -   `startOffset` 一个对象的结构就像 `columns` 道具 (英语). 你可以把它放入窝里 `Grid` 或者说 `<Grid item>` 元素开始于第一个列以外的一列。 不应该加在外边 `Grid` 除非其直系父母有孩子 `display: grid`。 。 。 .
    -   如果不传入,相抵值默认为1,即开始网格.
-   网格上为什么没有垂直间隔?
    -   网格执行中只有柱子的沟槽/边框, [根据GEL规格](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes)这样做可以灵活地进行各种间隔。 要增加垂直间距,请在内容中添加粘贴/边距/上方/下方.
-   我应该什么时候用 `parentColumns` 道具吗?
    -   `parentColumns` 一个对象的结构就像 `columns` 道具 (英语). 此道具明确将父网格的列配置传递为子 `<Grid>` 键. [参见实例.](https://github.com/bbc/psammead/tree/latest/packages/components/psammead-grid#parentcolumns-prop)
-   我应该什么时候用 `parentEnableGelGutters` 道具吗?
    -   `parentEnableGelGutters` 是一个布尔值,用于定义母网格上是否启用了沟槽. [参见实例.](https://github.com/bbc/psammead/tree/latest/packages/components/psammead-grid#parentcolumns-prop)
    -   这种道具只应被传递到不直接由母网内制取的儿童网格.

## 使用量

我们使用GEL网格作为断点, 以及我们的标准地沟和边缘. [GEL 网格文档中定义了这些值](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes)。 。 。 .

当我们提到 `group3` 我们指的是最小宽度的断点 `GEL_GROUP_3_SCREEN_WIDTH_MIN` 最大宽度( a) `GEL_GROUP_3_SCREEN_WIDTH_MAX`中定义这些值 [`@bbc/gel-foundations/breakpoints`](https://github.com/bbc/psammead/blob/latest/packages/utilities/gel-foundations/src/breakpoints.js)。 。 。 .

使用扩展网格组件时,如果您想要使用 `as` 道具,你需要使用 `forwardedAs`。这个道具使您能够将元素比一个级别更低.

#### 简单示例

举个例子 `<Grid>` 有8个栏 `group4` (从1008px到1279px). 它有四个孩子 `<Grid item>` 元素,一个跨出6/8列,其他三个跨出2/8列.

```jsx
import Grid from '@bbc/psammead-grid';

const MyComponent = () => (
  <Grid
    columns={{
      group0: 8,
      group1: 8,
      group2: 8,
      group3: 8,
      group4: 8,
      group5: 8,
    }}
  >
    <Grid
      item
      columns={{
        group0: 6,
        group1: 6,
        group2: 6,
        group3: 6,
        group4: 6,
        group5: 6,
      }}
    >
      <p>Item 1 - Paragraph that spans 6 out of 8 columns through group4</p>
    </Grid>
    <Grid
      item
      columns={{
        group0: 2,
        group1: 2,
        group2: 2,
        group3: 2,
        group4: 2,
        group5: 2,
      }}
    >
      <p>Item 2 - Paragraph that spans 2 out of 8 columns through group4</p>
    </Grid>
    <Grid
      item
      columns={{
        group0: 2,
        group1: 2,
        group2: 2,
        group3: 2,
        group4: 2,
        group5: 2,
      }}
    >
      <p>Item 3 - Paragraph that spans 2 out of 8 columns through group4</p>
    </Grid>
    <Grid
      item
      columns={{
        group0: 2,
        group1: 2,
        group2: 2,
        group3: 2,
        group4: 2,
        group5: 2,
      }}
    >
      <p>Item 4 - Paragraph that spans 2 out of 8 columns through group4</p>
    </Grid>
  </Grid>
);
```

在内部查看此示例时的图像 `group4` (从1008px到1279px). 当在任何其他断点上查看这个示例时,四个项目中的每一个都填满了行的全宽. ![8 column grid with items 6 2 2 2 with labels](https://npmcn.com/package/%40bbc/psammead-grid/documentation/8-column-grid-with-items-6-2-2-2-with-labels.png)

#### 设置标准的 GEL 沟槽和 GEL 边框

使用 `enableGelGutters` 编辑 `Grid` 键。 注:这应当 _没有_ 添加到一个 `<Grid item>` 元素! 使用时间 `margins` 也可以是两个 `<Grid>` 或者说 `<Grid item>`。 。 。 .

```jsx
import Grid from '@bbc/psammead-grid';

const MyComponent = () => (
  <Grid
    enableGelGutters
    columns={{
      group0: 2,
      group1: 4,
      group2: 4,
      group3: 6,
      group4: 8,
      group5: 12,
    }}
    margins={{
      group0: true,
      group1: true,
      group2: true,
      group3: true,
      group4: true,
      group5: true,
    }}
  >
    <Grid
      item
      columns={{
        group0: 2,
        group1: 4,
        group2: 4,
        group3: 6,
        group4: 6,
        group5: 12,
      }}
    >
      <p>
        Paragraph - for group 3 spans 6/6 columns, for group 4 spans 6/8 columns
      </p>
    </Grid>
    <Grid
      item
      columns={{
        group0: 2,
        group1: 4,
        group2: 4,
        group3: 6,
        group4: 2,
        group5: 12,
      }}
    >
      <p>
        Paragraph - for group 3 spans 6/6 columns, for group 4 spans 2/8 columns
      </p>
    </Grid>
  </Grid>
);
```

启用 GEL Gutters 和 GEL 边距的屏幕截图 ![Screenshot of this example with GEL Gutters and GEL Margins enabled](https://npmcn.com/package/%40bbc/psammead-grid/documentation/Screenshot-example-with-gelMargins-and-gelGutters.png)

在没有GEL Gutters 和 GEL 边框的情况下 ![Screenshot of this example without GEL Gutters and GEL Margins](https://npmcn.com/package/%40bbc/psammead-grid/documentation/Screenshot-example-without-gelMargins-and-gelGutters.png)

#### 网格网格示例

请注意,这里,任何时候你使用 `<Grid>` 生成新的网格。 每个断点的列总数通过 `columns` 道具 (英语). 然后定义孩子的行数 `<Grid item >` 应该跨度,你可以使用 `columns` 螺丝上 `<Grid item>`。 。 。 .

在图像周围的网格项目上,我们没有边距,但在段落项目上.

```jsx
import Grid from '@bbc/psammead-grid';

const MyComponent = () => (
  <Grid
    columns={{
      group0: 6,
      group1: 6,
      group2: 6,
      group3: 6,
      group4: 6,
      group5: 6,
    }}
  >
    <Grid
      columns={{
        group0: 6,
        group1: 6,
        group2: 6,
        group3: 6,
        group4: 6,
        group5: 6,
      }}
    >
      <Grid
        item
        columns={{
          group0: 6,
          group1: 6,
          group2: 6,
          group3: 3,
          group4: 3,
          group5: 3,
        }}
      >
        <ExampleImage />
      </Grid>
      <Grid
        item
        columns={{
          group0: 6,
          group1: 6,
          group2: 6,
          group3: 3,
          group4: 3,
          group5: 3,
        }}
      >
        <ExampleParagraph />
      </Grid>
    </Grid>
    <Grid
      item
      columns={{
        group0: 2,
        group1: 2,
        group2: 2,
        group3: 2,
        group4: 2,
        group5: 2,
      }}
    >
      <ExampleImage />
    </Grid>
    <Grid
      item
      columns={{
        group0: 4,
        group1: 4,
        group2: 4,
        group3: 4,
        group4: 4,
        group5: 4,
      }}
    >
      <ExampleParagraph />
    </Grid>
  </Grid>
);
```

#### 使用父目录和父目录的子网格 EnableGelGutters道具

请注意,无论何时你生孩子 `<Grid>` 父母网格之外,父母的柱子和沟槽配置不会自动传递给孩子. 这使得不支持cs网格的浏览器的布局被打破. 为了保证配置通过正确,你需要在这些道具中明确通过.

```jsx
import Grid from '@bbc/psammead-grid';

const parentProps = {
  enableGelGutters: true,
  columns: {
    group0: 6,
    group1: 6,
    group2: 6,
    group3: 6,
    group4: 6,
    group5: 6,
  },
};

const childProps = {
  columns: {
    group0: 6,
    group1: 6,
    group2: 6,
    group3: 6,
    group4: 6,
    group5: 6,
  },
};

const renderChildGrid = () => (
  <Grid
    parentEnableGelGutters={parentProps.enableGelGutters}
    parentColumns={parentProps.columns}
    {...childProps}
  >
    <ExampleParagraph />
  </Grid>
);

const MyComponent = () => (
  <Grid {...parentProps}>
    {renderChildGrid()}
  </Grid>
);
```

### 何时使用此组件

这个 `Grid` 组件可用于页面级别布局以及单个组件的布局. 可以将网格嵌入内部,以进行更复杂的布局. 请参看"故事书"中的例子.

### Frequenty 问的问题

-   我应该什么时候用 `item` 道具吗?
    -   这个 `item` 道具应被使用在儿童网格元素上,即: `<Grid>`。使用 `columns` prop 的值, 您可以在每个断点选择要跨出多少列 .
    -   当您定义新网格项目时, 它可以而且应该被使用 - 您想要在断点上覆盖一组列数的东西 .
-   我应该什么时候用 `columns` 道具吗?
    -   这一点应始终加以界定.
    -   对a `<Grid>` 元素,是网格的列数.
    -   对a `<Grid item>` 元素,是它应该跨行的列数.
-   我应该什么时候用 `startOffset` 道具吗?
    -   `startOffset` 对象与 `columns` 道具 (英语). 您可以将其设置在格子元素上,以便在第一列以外的一列开始.
    -   如果不传入,数值默认为1,即开始网格.
-   网格上为什么没有垂直间隔?
    -   网格执行中只有柱子的沟槽/边框, [根据GEL规格](https://www.bbc.co.uk/gel/guidelines/grid#grid-sizes)这样做可以灵活地进行各种间隔。 要增加垂直间距,请在内容中添加粘贴/边距/上方/下方.

### 无障碍说明

这个 `<Grid>` 组分为: `div` 键.

## 捐款

Psammead完全开源. 我们感谢任何贡献,无论是新的组件、错误修正还是总体改进。 请参看我们的主要贡献指南,可查阅: [psammead 仓库的根](https://github.com/bbc/psammead/blob/latest/CONTRIBUTING.md)。 。 。 .

### [行为守则](https://github.com/bbc/psammead/blob/latest/CODE_OF_CONDUCT.md)

我们欢迎对这项工作的反馈和帮助。 通过参与这个项目,你同意遵守 [行为守则](https://github.com/bbc/psammead/blob/latest/CODE_OF_CONDUCT.md)请稍候再读一下.

### 许可证

萨姆米德 [Apache 2.0 许可](https://github.com/bbc/psammead/blob/latest/LICENSE)。 。 。 .

## 常见问题

### @bbc/psammead-grid 是什么？

网格组件

### 如何安装 @bbc/psammead-grid？

在项目目录运行 npm install @bbc/psammead-grid，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@emotion/styled（^11\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bbc/psammead-grid 支持 TypeScript 吗？

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

### @bbc/psammead-grid 支持 ESM 还是 CommonJS？

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

### @bbc/psammead-grid 可以商用吗？

@bbc/psammead-grid 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bbc/psammead-grid 的下载量有多少？

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

### @bbc/psammead-grid 还在维护吗？

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