@guardian/react-crossword

中文文档
20.1.0发布于 2026/10/08Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 1.6万

A standalone React component for rendering crosswords.

原始使用文档
文档目录9 节
  1. Features
  2. API
  3. Props
  4. Crossword data format
  5. Progress format
  6. Theming
  7. Architecture
  8. Layout
  9. Installation

@guardian/react-crossword

A standalone React component for rendering crosswords.

Example crossword grid

Features

  • Renders crossword grid and clues
  • Displays separators in grid for hyphenated and multiple-word answers
  • Layout is responsive (and can be customised)
  • Attempted clues are greyed out in the clue list
  • Clicking on a clue highlights the associated row or column
  • Groups clues together when they span multiple columns or rows
  • Progress is saved to local storage
  • Answers can be checked and revealed
  • Smart clearing when checking answers that strikes through incorrect letters
  • Anagram helper
  • Accessible: elements in the crossword are clearly labelled to communicate context and state to assistive technology
  • Keyboard navigable: you can tab between the grid, clues and controls, and these can be navigated with the arrow key
  • Includes print styles
  • Includes support for theming and custom colour schemes

API

Props

PropDetails
data(Required) Data to render the crossword, including clues, answers and metadata (See Crossword data format)
progress(Optional) Current state of the grid (See Progress format)
onProgressChange(Optional) Called each time the reader changes the grid, with { progress, filledCells, totalCells, isComplete }. isComplete is true when every cell holds its solution, and always false when solutions are not available. Not called when saved progress is restored on load.
Layout(Optional) Allows default layout to be customised (See Layout)

Any of the keys from the default theme can also be passed as a prop to customise the appearance of the crossword. These are detailed in the Theming section.

Crossword data format

This is an example set of data used to create the crossword shown above:

{
    id: 'crosswords/example/1',
    number: 1,
    name: 'Example crossword No 1',
    creator: {
        name: 'James',
        webUrl: 'https://www.theguardian.com/profile/maskarade',
    },
    date: 1740149419743,
    webPublicationDate: 1740149419743,
  entries: [
    {
      id: '1-across',
      number: 1,
      humanNumber: '1',
      clue: 'Toy on a string (2-2)',
      direction: 'across',
      length: 4,
      group: ['1-across'],
      position: { x: 0, y: 0 },
      separatorLocations: {
        '-': [2],
      },
      solution: 'YOYO',
    },
    {
      id: '2-across',
      number: 2,
      humanNumber: '2',
      clue: 'Have a rest (3,4)',
      direction: 'across',
      length: 7,
      group: ['2-across'],
      position: { x: 0, y: 2 },
      separatorLocations: {
        ',': [3],
      },
      solution: 'LIEDOWN',
    },
    {
      id: '1-down',
      number: 1,
      humanNumber: '1',
      clue: 'Colour (6)',
      direction: 'down',
      length: 6,
      group: ['1-down'],
      position: { x: 0, y: 0 },
      separatorLocations: {},
      solution: 'YELLOW',
    },
    {
      id: '3-down',
      number: 3,
      humanNumber: '3',
      clue: 'Bits and bobs (4,3,4)',
      direction: 'down',
      length: 7,
      group: ['3-down', '4-down'],
      position: { x: 3, y: 0 },
      separatorLocations: {
        ',': [4],
      },
      solution: 'ODDSAND',
    },
    {
      id: '4-down',
      number: 4,
      humanNumber: '4',
      clue: 'See 3 down',
      direction: 'down',
      length: 4,
      group: ['3-down', '4-down'],
      position: {
        x: 6,
        y: 1,
      },
      separatorLocations: {},
      solution: 'ENDS',
    },
  ],
  solutionAvailable: true,
  dateSolutionAvailable: 1542326400000,
  dimensions: {
    cols: 13,
    rows: 13,
  },
  crosswordType: 'quick',
    pdf: 'https://crosswords-static.guim.co.uk/gdn.quick.20250221.pdf',
}

Progress format

Grid progress is stored as a simple 2 dimensional array and is persisted in local storage. Each element in the array contains the value of the corresponding grid cell. Cells that are empty or not part of an answer are represented as an empty string.

The example crossword above is represented as:

[
    ['Y', 'E', 'L', 'L', 'O', 'W', ''],
    ['O', '', 'I', '', '', '', ''],
    ['Y', '', 'E', '', '', '', ''],
    ['O', 'D', 'D', 'S', 'A', 'N', 'D'],
    ['', '', 'O', '', '', '', ''],
    ['', '', 'W', '', '', '', ''],
    ['', 'E', 'N', 'D', 'S', '', ''],
];

The data is indexed by column (x) and then row (y) so the data in the array when printed is transposed when compared to the visual layout of the grid.

For example, the last letter of 2 across is in the 7th column and 3rd row of the grid so would be accessed as progress[6][2] giving us 'N'.

Theming

The following keys from the crossword theme can be passed to the Crossword component to customise its appearance:

KeyDescription
gridBackgroundColorbackground colour of 'black' squares/dividers etc on the grid
gridForegroundColorbackground colour of 'white' squares on the grid
gridTextColorcolour of text in the grid (clue numbers and entered letters)
gridPrintBackgroundColorbackground colour of 'black' squares on grid when printed
gridGutterSizesize of the gap between grid cells
gridCellSizelength of one side of a cell on on the grid
gridCellStrikeThroughcolour of the strike through on an incorrect cell
textColormain text colour (grid text, clues etc.)
focusColorcolour of the currently selected cell border
selectedTextColorcolour of currently selected clue
selectedBackgroundColorcolour of cells / clues that are currently selected
connectedBackgroundColorcolour of cells / clues that are connected to the currently selected clue
buttonBackgroundColorbackground colour of clue-helper buttons
buttonBackgroundHoverColorhover colour of clue-helper buttons
borderColorborder colour used to visually separate parts of the UI
clueListBorderColorborder colour applied to the top of the clue lists
clueMinWidthminimum width of a clue
clueMaxWidthmaximum width of a clue
anagramHelperBackgroundColorbackground colour of the anagram helper
anagramHelperCandidateTextColortext colour of shuffled letter that are not yet on the grid
focusedClueBackgroundColorbackground colour for the focused clue

Architecture

Layout

A custom layout component can passed to the Crossword component via the Layout prop. The individual components that the crossword is composed of are passed to the layout as props so that additional elements or styles can be applied as required. (This is used in DCR to customise the layout and allow the insertion of ad slots.)

This is a simplified example of a layout:

const Layout: CrosswordProps['Layout'] = ({
    Grid,
    Clues,
    Controls,
    SavedMessage,
    AnagramHelper,
    FocusedClue,
}) => {
    return (
        <div>
            <AnagramHelper />
            <div>
                <FocusedClue />
                <Grid />
                <FocusedClue />
                <Controls />
                <SavedMessage />
            </div>

            <div>
                <Clues direction="across" />
                <Clues direction="down" />
            </div>
        </div>
    );
};

Installation

$ pnpm add @guardian/react-crossword

or

$ npm i @guardian/react-crossword

版本与发布记录

@guardian/react-crossword 共发布 189 个版本,首次发布于 2019/09/03;过去 12 个月发布了 41 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
20.1.0latest2026/10/081 个月前
20.0.02026/10/081 个月前
0.0.0-canary-20261007091825canary2026/10/071 个月前
19.0.12026/06/234 个月前
19.0.02026/06/105 个月前
0.0.0-canary-202605181317572026/05/185 个月前

关于 @guardian/react-crossword 的常见问题

@guardian/react-crossword 是什么?

A standalone React component for rendering crosswords.

如何安装 @guardian/react-crossword?

在项目目录运行 npm install @guardian/react-crossword,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(^18.2.0)、@emotion/react(^11.11.4)、@guardian/libs(^33.0.0)、@guardian/source(^14.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@guardian/react-crossword 支持 TypeScript 吗?

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

@guardian/react-crossword 支持 ESM 还是 CommonJS?

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

@guardian/react-crossword 可以商用吗?

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

@guardian/react-crossword 的下载量有多少?

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

@guardian/react-crossword 还在维护吗?

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