# @guardian/interactive-component-library 中文文档

规范地址：https://npmcn.com/package/%40guardian/interactive-component-library/

版本：0\.9\.17
npm 元数据更新时间：2026-11-03T10:11:07.818Z
中文译文更新时间：2026-11-17T02:47:25.329Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40guardian/interactive-component-library
原文对照：https://npmcn.com/package/%40guardian/interactive-component-library/?lang=original
项目主页：https://github.com/guardian/interactive-component-library#readme
源码仓库：https://github.com/guardian/interactive-component-library

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

- 包体积（解压后）：421 kB，297 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：10 个
- peer 依赖：d3-geo ^3\.1\.1，preact 10\.21\.0，d3-zoom ^3\.0\.0，d3-scale ^4\.0\.2，d3-polygon ^3\.0\.1，d3-selection ^3\.0\.0
- 首次发布：2024-04-08T15:07:06.601Z
- 最新版本发布：2026-11-03T10:11:07.292Z
- 近 30 天下载量：26948（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：118（近 12 个月 22 个）

## 中文简介

一组用于交互式页面的可重用组件, 使用 Preact 写入 [原子设计](https://bradfrost.com/blog/post/atomic-web-design/) 原则.

## 安装

```sh
npm install @guardian/interactive-component-library
```

也可以使用：`pnpm add @guardian/interactive-component-library`、`yarn add @guardian/interactive-component-library`、`bun add @guardian/interactive-component-library`

## README

# `@guardian/interactive-component-library`

一组用于交互式页面的可重用组件, 使用 Preact 写入 [原子设计](https://bradfrost.com/blog/post/atomic-web-design/) 原则.

## 在新客户端项目中安装组件库

```
npm install @guardian/interactive-component-library
```

## 为这个寄存器贡献力量

> 建设项目需要节点v16.18.1或更高.

1.  克隆此寄存器
2.  运行 `corepack enable` 以启用 pnpm
3.  安装依赖关系 `pnpm i`
4.  运行 `pnpm dev` 以启动本地的故事书服务器

### 原子设计

组成部分库的结构按照 [原子设计](https://bradfrost.com/blog/post/atomic-web-design/) 原则,使用下三级.

1.  文章(从 `atoms` (由于明显的原因)
2.  分子
3.  有机体

粒子是构成其他所有事物的构件(如按钮)的最低等元件. 分子代表更复杂的组分(如一表),并往往依赖于粒子组分. 有机体将前两个关卡合并为一个交互页面的不同部分,例如KeySeats.

文件夹使用相同的命名结构,其中 `particles`, (中文(简体) ), `molecules` 财务报告和审定财务报表 `organisms` 文件夹在 `src/lib/components`,以区分三个不同的级别.

### 添加新组件

在相应的目录中创建您新组件的文件夹 。 文件夹的名称应为您在 [凯巴布案](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case),也就是说. `src/lib/components/particles/my-new-component`。 。 。 .

文件夹应包含以下内容:

-   `index.jsx` 包含实际组件的代码
-   `[component-name].stories.jsx` 包含如何使用组件的实例,写入为 [故事书故事](https://storybook.js.org/docs/writing-stories)
-   `docs.mdx` 故事书中组件的额外文档( 可选)

### 当地开发和测试

在开发期间,你往往会想看到一个组件在您正在研究的互动页面中的样子,而不重建并发布新版本的组件库. 为了方便工作流程,我们使用 [npm-链接](https://docs.npmjs.com/cli/v10/commands/npm-link)。 。 。 .

这是如何设置:

```
cd ~/projects/interactive-component-library       # go into the package directory
npm link                                          # creates global link
cd ~/projects/interactive-project                 # go into your project directory
npm link @guardian/interactive-component-library  # link-install the package
```

你干完后,快跑开 `pnpm build:lib:watch` 来包装库并重建文件更改.

返回您的项目指定的版本 `package.json`数字 :

```
npm uninstall --no-save @guardian/interactive-component-library && npm install
```

### 出版新版本

要出版新版组件库,请遵循这些步骤:

1.  [创建新发行](https://github.com/guardian/interactive-component-library/releases/new) 在 GitHub (不要忘记写一些发行笔记)
2.  出版发行 [触发工作流程](https://github.com/guardian/interactive-component-library/actions) 将图书馆包装并公布在国家预防机制登记册上。 如果发布动作失败, 您也可以手动触发
3.  发布动作还创建出一个拉出请求来突起版本号. 合并拉动请求以完成释放

## 脚本

总是预用 `pnpm`数字 :

-   `dev`: 启动故事书,促进地方发展
-   `build`: 构建静态故事书项目
-   `build:lib`: 将组件库建入 **数字** 文件夹
-   `build:lib:watch`: 与先前的命令相同, 但是它看 `/src` 文件夹和更改后的重建

## 测试童话书中的暗模式

在工具栏中使用日/月按钮在光和暗模式之间切换. ![Screenshot 2024-03-27 at 08 24 43](https://github.com/guardian/interactive-component-library/assets/1107150/3a93adfc-56da-4c1d-b5b8-dc7ff5aedfbf) ![Screenshot 2024-03-27 at 08 24 32](https://github.com/guardian/interactive-component-library/assets/1107150/bad208aa-7967-446f-b658-e937aa2d114b)

启用暗模式 `.ios` 财务报告和审定财务报表 `.dark-mode` 分类到 `<body>` 元素,它反过来使故事预览呈现出深色模式颜色(此行为可以自定义于 `.storybook/preview.scss`) (中文(简体) ).

> 注意使用此按钮启用暗模式不影响 [`prefers-color-scheme` CSS 媒体专题节目](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)。如果组件使用 `prefers-color-scheme` 直接, 您还需要更改您的系统或浏览器设置, 才能看到样式生效 .

## 许可证

[Apache 2.0 (英语)](https://npmcn.com/package/%40guardian/interactive-component-library/LICENSE)

## 常见问题

### @guardian/interactive-component-library 是什么？

一组用于交互式页面的可重用组件, 使用 Preact 写入 原子设计 原则\.

### 如何安装 @guardian/interactive-component-library？

在项目目录运行 npm install @guardian/interactive-component-library，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：d3-geo（^3\.1\.1）、preact（10\.21\.0）、d3-zoom（^3\.0\.0）、d3-scale（^4\.0\.2）、d3-polygon（^3\.0\.1）、d3-selection（^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @guardian/interactive-component-library 支持 TypeScript 吗？

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

### @guardian/interactive-component-library 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @guardian/interactive-component-library 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @guardian/interactive-component-library 可以商用吗？

@guardian/interactive-component-library 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @guardian/interactive-component-library 的下载量有多少？

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

### @guardian/interactive-component-library 还在维护吗？

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

