# @equinor/echo-components 中文文档

规范地址：https://npmcn.com/package/%40equinor/echo-components/

版本：7\.0\.0
npm 元数据更新时间：2026-10-30T09:44:59.759Z
中文译文更新时间：2026-11-14T00:29:37.529Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：964 kB，255 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>= 19\.2\.4，lodash \>= 4\.17\.21 \< 5，zustand \>= 4\.4\.7 \< 5，react-dom \>= 19\.2\.4，classnames 2\.5\.1，sortablejs \>= 1\.15\.1 \< 2，react-sortablejs 6\.1\.4，@equinor/eds-icons 0\.22\.0，@equinor/echo-utils \>= 7\.0\.0 \< 8\.0\.0，@equinor/eds-tokens 2\.1\.0，@equinor/eds-core-react 0\.49\.0
- 首次发布：2021-02-05T08:57:30.500Z
- 最新版本发布：2026-10-27T14:05:37.012Z
- 近 30 天下载量：2715（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：226（近 12 个月 37 个）

## 中文简介

这个可出版的图书馆是用 [无](https://nx.dev/)。 。 。 .

## 安装

```sh
npm install @equinor/echo-components
```

也可以使用：`pnpm add @equinor/echo-components`、`yarn add @equinor/echo-components`、`bun add @equinor/echo-components`

## README

# 回声元件

这个可出版的图书馆是用 [无](https://nx.dev/)。 。 。 .

Echo的构件,建于EDS(Equinor Design System)上.

## 扶养规则

**真相来源: `/eslint.config.js`** - 那个 `@nx/enforce-module-boundaries` 规则定义所有允许的依赖.

**回声组件只能从 :**

-   `echo-utils` ✅

**cANNO 无法从 :**

-   `echo-framework` ❌
-   `echo-search` ❌
-   `echo-core` ❌
-   `echo-base` ❌
-   `echopedia-web` (应用)

见 `libs/README.md` 用于完整依赖性流程图.

* * *

## 故事书指南

将"故事书"视为你应用的构件-UI组件的虚拟展示室. 它让开发者在孤立状态下进行组件实验,比如在建造更大型的东西之前同乐高斯一起修补. 故事书不仅仅是记录组件,而是创建互动游乐场供开发者探索其全部潜力.

### 在线故事书

出版静态故事书页面

-   a github 动作将静态故事书页面构建并部署到以下分支: `echo-components-storybook` - 我们不应该删除这个!
-   另外一个github动作会从这里取出,然后发布到github一页.

[在线故事书可在此找到](https://bookish-adventure-l5zz573.pages.github.io/?path=/docs/introduction--docs)

### 为什么用故事书?

-   快速开发:快速用组件进行实验,不需要整个应用程序运行.
-   提高一致性:确保所有组件在整个应用中都以同样的方式外观和行为.
-   更好的协作:设计者和开发者可以轻松地共享组件设计和功能.
-   易行维护:新开发者可以通过清晰的文档来理解现有组件.

### 在你写故事本之前

-   理解您的组件 : 需要一些时间来彻底了解你将要记录的组件. 他们的目的是什么? 他们接受什么道具? 他们能进入哪个州? 这些知识将指导你在故事书中展示的情景.
-   了解你的观众:想想谁会使用你的故事书。 他们主要是密码基地的新开发者 还是老兵? 这将影响你提供的细节水平以及你创造的故事的复杂性.

### 建立具有吸引力的故事区块

-   孤立与征服:故事书让组件自己发光. 这使得开发者可以进行道具和状态的实验,而不用担心与代码其他部分的相互作用.
-   多样性就是"生命的香料":不要只表现基本!. 以不同的道具组合(大小,样式),可视化主题(轻/暗模式)和功能状态(加载,出错,成功)显示组件的多功能性.
-   互动游戏地:使用故事书的交互功能. 允许开发者在故事本界面中直接更改道具并进行状态. 这促进了探索和实验.

### 写入有效描述 :

-   清晰而简明:写出清晰而简洁的描述来解释组件的目的和用途. 避免新开发者可能无法理解的技术术语 .
-   注重效益:突出利用该组成部分的好处。 如何使发展更容易或更有效?
-   代码实例:提供相关代码实例,以表明在实践中如何使用该组件. 包括基本用途和较先进的设想.

### 超越基础:

-   人人无障碍:在故事中考虑无障碍。 显示组件如何用于创建人人都能使用的界面 .
-   取得最佳效果的最佳做法:包括如何有效利用该组成部分的例子。 这有助于开发者避免常见的陷阱并写出更清洁,更可维护的代码.
-   视觉呼吁事项:对您的故事使用清晰而有条理的布局. 考虑使用截图或模型等视觉辅助工具来增强理解.

### 文本示例:让我们构建一个按钮故事!

想象一个按钮组件——应用程序的工作马. 这是如何编出一个令人信服的故事:

-   标题: 按钮 - 一个Versatile 动作触发器
-   说明:用于启动应用程序中的动作的多功能按钮组件。 支持各种风格(初级,二级),大小(大小),以及状态(辅助,残疾),以获得一致的用户体验.
-   Basic Usage: 显示带有默认标签和样式的简单按钮.
-   Properation Variariations:包含显示大小,变体等不同道具,以及残疾状态等不同道具的故事.
-   视觉主题(Visual Themes):如果适用,在不同的主题(光模式,暗模式)中显示按钮.
-   互动播放地:允许开发者修改按钮文本,选择一个变体,并直接从故事本中切换被禁用状态.
-   代码示例:提供代码片段,演示如何以不同的道具来导入和使用按钮组件.

### 在您的故事本中写好故事的食谱( 使用按钮组件示例)

**成份 :**

-   Fresh Code:您要显示的组件的代码( 如提供按钮. stories. tsx 文件) .
-   Storybook 公用事业: StoryFn和Meta功能出自 @storybook/react.
-   明晰而明晰:瞄准清晰而易懂的故事.
-   多样性:显示大小写不同的配置和使用方案.
-   视觉呼吁(可选):让故事视觉上呼吁更好的参与.

**第1步. 设置阶段:配置和标题(Meta):** 定义 Meta 对象 :

-   标题:一个说明性标题,表示组件等级(例如"组件/按钮/按钮").
-   组件:您正在显示的组件(例如按钮).
-   args:组件道具的默认值(例如:"按钮").
-   argTyps:定义用于交互道具选择的控制类型.
-   参数.docs.p:链接到组件文档(可选).

```
import { Meta, StoryFn } from '@storybook/react';
import { Button } from './Button'; // Replace with your Button component import path

const meta: Meta<typeof Button> = {
  title: 'Components/Button/Button', // Descriptive title for Storybook navigation
  component: Button,
  args: {
    as: 'button', // Default element type (can be overridden as 'span' or 'a')
  },
  argTypes: {
    as: {
      options: ['span', 'a', 'button'], // Available options for the 'as' prop
      control: {
        type: 'select', // Control type for selecting the 'as' prop in Storybook UI
      },
    },
  },
  parameters: {
    docs: {
      page: './Button.docs.mdx', // Path to your button documentation file (replace if needed)
    },
  },
};

export default meta;
```

**第2步. 创建模板:** 写入可重复使用的模板功能,使组件在容器元素(如div)内. 此模板将被用于大多数故事.

```
const Template: StoryFn<Button.Props> = (args) => (
  <div className="button-container"> {/* Add a container class for styling (optional) */}
    <Button {...args} />
  </div>
);
```

**第3步 讲出主要故事:介绍:**

-   定义一个使用模板功能的名为"介绍"(或类似)的故事.
-   用默认道具给一个基本按钮来显示其基本形式.

```
export const Introduction: StoryFn<Button.Props> = () => (
  <Template>You can control me</Template>
);
```

**步骤4. 香料 上:变化和状态:** 创建额外的故事来显示不同的按钮变异和状态 。 这些可以是:

-   不同风格(初级、二级、概述)
-   大小(大,小)
-   状态
-   装入状态( 如果适用)
-   图标变化( 有或没有图标)
-   交互式元素( 正在装入状态) 对于每个故事,提供反映变化的描述性标题(如"初级按钮-大").

```
export const PrimaryButtonLarge: StoryFn<Button.Props> = () => (
  <Template>
    <Button variant="primary" size="large">
      Large Primary Button
    </Button>
  </Template>
);

export const DisabledButton: StoryFn<Button.Props> = () => (
  <Template>
    <Button disabled>Click Me (Disabled)</Button>
  </Template>
);

export const LoadingButton: StoryFn<Button.Props> = () => (
  <Template>
    <Button isLoading>Loading...</Button>
  </Template>
);

export const IconButton: StoryFn<Button.Props> = () => (
  <Template>
    <Button variant="icon">
      <Icon name="search" /> {/* Assuming you have an Icon component */}
    </Button>
  </Template>
);
```

**第5步:视觉演示(可选):** 考虑使用背景颜色或布局来增强你的故事的视觉吸引力. 示例: 您可以自定义模板中的按钮- 容器类, 以添加背景颜色或样式, 用于更具视觉吸引力的演示文稿 .

**第六步,快来** 在文件末尾导出元对象(包含配置)...

```
export default meta;
```

### 图片示例:二级Marker

![image](https://github.com/equinor/EchopediaWeb/assets/54355967/25d9703e-5b43-4c8a-acc5-4a9f74fbbbf9)

## 如何开发并发布回声组件

检查 [读取我](https://npmcn.com/libs/README.md) 在 NX 库文件夹中.

## 可用的国家预防机制脚本

-   `lint-components`
-   `build-components`
-   `test-components`

## 旧的回声组件库

以历史原因保存. [https://github.com/equinor/EchoComponents (中文(简体) )](https://github.com/equinor/EchoComponents)

## 发展指南

**组成**

在决定如何写入您的新组件时, 考虑组成 。 使用较小的可互换组件,每个组件在较大组件的上下文中代表一个特定的函数或特征. 将包装组件与 `children` (b) 使最终产品能够更好地区分各种关切、较小的编码块和更高程度的定制.

### 示例:卡片组件

```
<Card.Container> {/* REQUIRED */}
    <Card.Image src="hello_world.jpg"> {/* INTERCHANGEABLE */}
        <Card.Caption>Descriptive text</Card.Caption> {/* INTERCHANGEABLE */}
        <Card.Heading>Heading</Card.Heading> {/* INTERCHANGEABLE */}
        <Card.Ingress>Subtitle/Ingress</Card.Ingress> {/* INTERCHANGEABLE */}
        <Card.Article>Main content</Card.Article> {/* INTERCHANGEABLE */}
    </Card.Image>
</Card.Container>
```

每个组件的构成可能因特征和正在解决的问题而异. 有些组件可能无法互换,有些组件可能需要额外的道具.

应该通过在项目中建立一个新的组成部分,作为回声元件构成的诱饵机制,来总结个人组成.

### 示例:靴子卡片组件

```
import React from 'react';

type Props = {
    heading: string;
    mainContent: string;
    imageSrc?: string;
    imageCaption?: string;
    ingress?: string;
};

export const ExampleCard: React.FC<Props> = ({ heading, mainContent, imageSrc, imageCaption, ingress }) => {
    return (
        <Card.Container>
            <Card.Image src={imageSrc}>
                {imageCaption && <Card.Caption>{imageCaption}</Card.Caption>}
                <Card.Heading>{heading}</Card.Heading>
                {ingress && <Card.Ingress>{ingress}</Card.Ingress>}
                <Card.Article>{mainContent}</Card.Article>
            </Card.Image>
        </Card.Container>
    );
};

export default ExampleCard;

```

### 开发者核对列表

1.  保持组件小, 聚焦于 **单一责任** 在可能的情况下.
2.  在可能的情况下,使用带有属性的包装组件 `children` 财务报告和审定财务报表 `className`。 。 。 .
3.  `className` 应 **总是包含**,以便在需要时允许定制样式。 (见要点) **6\. 国家.** 欲了解更多关于自定义样式的信息)
4.  部件的造型应始终采用 **CSS 模块**。 。 。 .
5.  确保组件准确反映所提供的UX素描,但如果UX素描没有说明具体用途,并/或提出异常困难的挑战,则不害怕挑战.
6.  允许单个组件的自定义造型并不意味着开发者可以随意任意操作. 自定义样式应始终得到UX的认可,并且只有在对用户体验有意义时才予以认可.
7.  当命名组件时,总是检查UX草图是否已经有一个名称,如果不使名称尽可能直观和描述.
8.  将每个组件添加到Storybook中,包含默认道具,示例,和解释(在需要时).

## 常见问题

### @equinor/echo-components 是什么？

这个可出版的图书馆是用 无。 。 。 \.

### 如何安装 @equinor/echo-components？

在项目目录运行 npm install @equinor/echo-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>= 19\.2\.4）、lodash（\>= 4\.17\.21 \< 5）、zustand（\>= 4\.4\.7 \< 5）、react-dom（\>= 19\.2\.4）、classnames（2\.5\.1）、sortablejs（\>= 1\.15\.1 \< 2）、react-sortablejs（6\.1\.4）、@equinor/eds-icons（0\.22\.0）、@equinor/echo-utils（\>= 7\.0\.0 \< 8\.0\.0）、@equinor/eds-tokens（2\.1\.0）、@equinor/eds-core-react（0\.49\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/echo-components 支持 TypeScript 吗？

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

### @equinor/echo-components 支持 ESM 还是 CommonJS？

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

### @equinor/echo-components 可以商用吗？

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

### @equinor/echo-components 的下载量有多少？

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

### @equinor/echo-components 还在维护吗？

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