@element-hq/web-shared-组件
Element Web, Aurora, Element 共享反应组件库 模块... 这个软件包提供建在顶端的有意见的UI组件 复合设计系统 财务报告和审定财务报表 化合物 网页这不是设计系统 本身,而是一组更大的组件.
在新项目中安装
当将此库添加到新项目时, 以及安装
@element-hq/web-shared-components 作为常态,您还需要添加
复合网络 作为对等点
依赖性 :
pnpm add @element-hq/web-shared-components
pnpm add @vector-im/compound-web
(这避免了问题,我们最终会遇到不同版本的复合网络) 顶级项目和网络共享组件).
使用量
基本导入
JavaScript和CSS都可以导入如下:
import { RoomListHeaderView, useViewModel } from "@element-hq/web-shared-components";
import "@element-hq/web-shared-components/dist/element-web-shared-components.css";
或 CSS 文件内 :
@import url("@element-hq/web-shared-components");
子路径导入
正在浏览器 DOM 外运行的呼叫者( 例如 在内) AudioWorkletGlobalScope
或工人)可以拉入小独立 numbers 没有工具捆绑
装入包件的其余部分,由包件转运进口,
dnd-kit, 以及其他触及的代码 window 编号 : document数字 :
import { percentageOf, percentageWithin } from "@element-hq/web-shared-components/numbers";
子路径显示以下所列相同的函数: 格式化
和船舶作为自己的ES/CJS dist/numbers.{js,umd.cjs}更倾向于
其它一切的主包条目 .
使用组件
这个库有两种组件:
- 常设经常 反应组件不遵循特定模式.
- 视图 组件(MVVM模式).
[TIP] 项目故事书载有这些内容.
常规组件
这些组件可以通过路过道具直接使用. 示例
import { Flex } from "@element-hq/web-shared-components";
function MyApp() {
return <Flex align="center" />;
}
查看( MVVM) 组件
这些组成部分遵循 MVVM 模式视图模式 实例应作为道具提供.
这里有一个基本的例子:
import { ViewExample } from "@element-hq/web-shared-components";
function MyApp() {
const viewModel = new ViewModelExample();
return <ViewExample vm={viewModel} />;
}
公用事业
国际化
useI18n()- 钩去翻译I18nApi- 国际化的API公用事业
日期和时间
DateUtils- 日期格式化和操纵humanize- 人类可读时间格式化
格式化
FormattingUtils- 文本和数据格式化公用事业numbers- 公用事业的格式编号
发展
先决条件
- 节点.js >= 20.0.0
- pnpm 第10页
设置
# Install dependencies
pnpm install
# Build the library
pnpm prepack
运行故事本
pnpm storybook
写入组件
大部分组件应为: MVVM 模式 视图 组件。 实例见现有组件。 例外程度低 不需要视图模型的组件.
写故事书故事
所有组件都应附有故事书故事,供文献和视觉测试使用。 故事使用 TypeScript 写入 组件故事格式( CSF)。 。 。 .
使用浅浅、面向浏览的故事标题,例如 RoomList/RoomListSearchView 或者说 TimelineBody/DecryptionFailureBodyView。不要在故事书标题中镜像全部源路径.
故事文件结构
将故事文件放在组件旁边 .stories.tsx 扩展名 :
MyComponent/
├── MyComponent.tsx
├── MyComponent.module.css
└── MyComponent.stories.tsx
常规部分
对于正则回放组件(non-MVVM),通过定义元对象和故事变化来创建故事:
import type { Meta, StoryObj } from "@storybook/react-vite";
import { fn } from "storybook/test";
import { MyComponent } from "./MyComponent";
const meta = {
title: "Category/MyComponent",
component: MyComponent,
tags: ["autodocs"],
args: {
// Default args for all stories
label: "Default Label",
onClick: fn(), // Mock function for tracking interactions
},
} satisfies Meta<typeof MyComponent>;
export default meta;
type Story = StoryObj<typeof meta>;
// Default story uses the default args
export const Default: Story = {};
// Override specific args for variations
export const WithCustomLabel: Story = {
args: {
label: "Custom Label",
},
};
export const Disabled: Story = {
args: {
disabled: true,
},
};
MVVM 组件故事
对于 MVVM 组件, 创建一个使用 useMockedViewModel 财务报告和审定财务报表 withViewDocs数字 :
import React, { type JSX } from "react";
import { fn } from "storybook/test";
import type { Meta, StoryObj } from "@storybook/react-vite";
import { MyComponentView, type MyComponentViewSnapshot, type MyComponentViewActions } from "./MyComponentView";
import { useMockedViewModel } from "../../viewmodel";
import { withViewDocs } from "../../../.storybook/withViewDocs";
// Combine snapshot and actions for easier typing
type MyComponentProps = MyComponentViewSnapshot & MyComponentViewActions;
// Wrapper component that creates a mocked ViewModel.
// Must be a named variable (not inline) for docgen to extract its props.
const MyComponentViewWrapperImpl = ({ onAction, ...rest }: MyComponentProps): JSX.Element => {
const vm = useMockedViewModel(rest, {
onAction,
});
return <MyComponentView vm={vm} />;
};
// withViewDocs copies the View's JSDoc description onto the wrapper for Storybook autodocs
const MyComponentViewWrapper = withViewDocs(MyComponentViewWrapperImpl, MyComponentView);
// Must use `satisfies` (not `as` or `: Meta`) to preserve type info for docgen
const meta = {
title: "Category/MyComponentView",
component: MyComponentViewWrapper,
tags: ["autodocs"],
args: {
// Snapshot properties (state)
title: "Default Title",
isLoading: false,
// Action properties (callbacks)
onAction: fn(),
},
} satisfies Meta<typeof MyComponentViewWrapper>;
export default meta;
type Story = StoryObj<typeof MyComponentViewWrapper>;
export const Default: Story = {};
export const Loading: Story = {
args: {
isLoading: true,
},
};
由于这种方法,我们可以在故事论证中直接使用原始语来代替取景模型对象.
[大 要在Storybook的ArgTypes表格中显示快照字段文档,必须满足三项要求:
- 已命名的包装变量 - 包装必须指定给一个有名的
const(例如:.MyComponentViewWrapperImpl) 被传递至withViewDocs,这样react-docgen-typescript可以提取道具.withViewDocs调用 ——用原"取景"将包装组件包起来,复制"取景"的"JSDoc"描述.satisfies Meta——元对象必须使用satisfies Meta<...>(无)as Meta<...>或者说: Meta<...> =) (中文(简体) ). 类型断言和说明去除Docgen所依赖的所推断的成分类型.
链接图像设计
此软件包使用 @ storybook/addon-designs (英语) 将 Figma 设计直接嵌入到故事书中。 这有助于开发者将其执行与设计规格进行比较.
- 获取图像 URL:在Figma中打开您的设计,点击"Share" → "Copy link"
- 添加到故事参数: 包含
design元中的对象parameters - 支持的 URL 格式数字 :
- 文件链接 :
https://www.figma.com/file/... - 设计链接 :
https://www.figma.com/design/... - 特定节点 :
https://www.figma.com/design/...?node-id=123-456
- 文件链接 :
图片集成示例:
const meta = {
title: "RoomList/RoomListSearchView",
component: RoomListSearchViewWrapper,
tags: ["autodocs"],
args: {
// ... your args
},
parameters: {
design: {
type: "figma",
url: "https://www.figma.com/design/vlmt46QDdE4dgXDiyBJXqp/ER-33-Left-Panel?node-id=98-1979",
},
},
} satisfies Meta<typeof RoomListSearchViewWrapper>;
export default meta;
Figma设计将在"故事本""设计"分页中出现.
非UI 用户故事
对于公用功能,帮助者,以及其他非UI导出,使用TypeDoc生成的平分格式创建文档故事.
src/core/utils/humanize.stories.tsx
import React from "react";
import { Markdown } from "@storybook/addon-docs/blocks";
import type { Meta } from "@storybook/react-vite";
import humanizeTimeDoc from "../../typedoc/functions/humanizeTime.md?raw";
const meta = {
title: "Core/Humanize",
parameters: {
docs: {
page: () => (
<>
<h1>humanize</h1>
<Markdown>{humanizeTimeDoc}</Markdown>
</>
),
},
},
tags: ["autodocs", "skip-test"],
} satisfies Meta;
export default meta;
// Docs-only story - renders nothing but triggers autodocs
export const Docs = {
render: () => null,
};
[注] 一定要包括
skip-test标记在您的实用故事中,防止它们作为视觉测试运行.
工作流量 :
- 在工具函数中写入 TsDoc
- 导出函数从
src/index.ts - 运行
pnpm build:doc生成类型 Doc 标记 - 创建一个
.stories.tsx文件导入生成的标记下 - 文档在故事书中自动显示
测试
有两种测试:单位测试和视觉回归测试.
单位测试
这些测试涵盖了组件和公用事业的逻辑。 由维特建造 和反应测试库.
pnpm test:unit
视觉回归测试
这些测试确保了UI组件的正确渲染. 以"故事"为主线,利用剧作家在vitest下跑.
pnpm test:storybook:update
每一个故事都会被呈现出来, 并会拍摄一个截图, 并比照 现有基线。 如果出现视觉变化或AXE违规,测试会 失败.
屏幕截图位于 packages/shared-components/__vis__/。 。 。 .
[大 如果和Playwright有麻烦,请看 剧作家 EW 文档。 。 。 .
翻译
先看看我们的 翻译指南 财务报告和审定财务报表 翻译 dev 指南。 。 。 . 要生成此软件包的翻译字符串, 请运行 :
pnpm i18n
发布新版本
为了执行释放,见文件: ../RELEASING.md。 。 。 .