回声元件

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

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一页.

在线故事书可在此找到

为什么用故事书?

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

在你写故事本之前

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

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

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

写入有效描述 :

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

超越基础:

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

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

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

• 标题: 按钮 - 一个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

如何开发并发布回声组件

检查 读取我 在 NX 库文件夹中.

可用的国家预防机制脚本

• lint-components
• build-components
• test-components

旧的回声组件库

以历史原因保存. 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中,包含默认道具,示例,和解释(在需要时).