# @alma-oss/spirit-web-react 中文文档 规范地址：https://npmcn.com/package/%40alma-oss/spirit-web-react/ 版本：5\.5\.0 npm 元数据更新时间：2026-10-19T10:39:04.972Z 中文译文更新时间：2026-11-06T11:35:55.399Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40alma-oss/spirit-web-react 原文对照：https://npmcn.com/package/%40alma-oss/spirit-web-react/?lang=original 项目主页：https://github.com/alma-oss/spirit-design-system#readme 源码仓库：https://github.com/alma-oss/spirit-design-system ## 关键信息（来自 npm 元数据） - 包体积（解压后）：12.9 MB，5713 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：5 个 - peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@alma-oss/spirit-web ^4\.0\.0，@alma-oss/spirit-icons ^3\.0\.0，@alma-oss/spirit-design-tokens ^4\.0\.0 - 首次发布：2025-12-15T11:36:17.903Z - 最新版本发布：2026-10-19T10:39:04.026Z - 近 30 天下载量：3369（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：21（近 12 个月 21 个） ## 中文简介 精神设计系统组件的响应实施 ## 安装 ```sh npm install @alma-oss/spirit-web-react ``` 也可以使用：`pnpm add @alma-oss/spirit-web-react`、`yarn add @alma-oss/spirit-web-react`、`bun add @alma-oss/spirit-web-react` ## README # @alma-oss/spirit-web-反应 [![minified](https://badgen.net/bundlephobia/min/@alma-oss/spirit-web-react)](https://bundlephobia.com/package/@alma-oss/spirit-web-react) [![minified + gzip](https://badgen.net/bundlephobia/minzip/@alma-oss/spirit-web-react)](https://bundlephobia.com/package/@alma-oss/spirit-web-react) [![dependency count](https://badgen.net/bundlephobia/dependency-count/@alma-oss/spirit-web-react)](https://bundlephobia.com/package/@alma-oss/spirit-web-react) [![tree shaking](https://badgen.net/bundlephobia/tree-shaking/@alma-oss/spirit-web-react)](https://bundlephobia.com/package/@alma-oss/spirit-web-react) [![client components](https://badgen.net/badge/client%20components/supported/green)](https://bundlephobia.com/package/@alma-oss/spirit-web-react) > 反应实施"精神设计"系统组件. - [安装](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-install) - [使用量](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-usage) - [翻译](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-translations) - [其他属性](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-additional-attributes) - [共享和继承的道具](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-shared-and-inherited-props) - [测试](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-testing) - [样式](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-styling) - [从设计托肯斯生成的类型](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-types-generated-from-design-tokens) - [公用事业](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-utilities) - [被控制 vs 未控制组件](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-controlled-vs-uncontrolled-components) - [折旧](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-deprecations) - [实例](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-examples) - [Figma的执行](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-implementing-from-figma) - [许可证](https://npmcn.com/package/%40alma-oss/spirit-web-react/#readme-license) ## 安装 期待着你 `react` 财务报告和审定财务报表 `react-dom` 安装在您的应用程序中, 运行 : ```shell yarn add @alma-oss/spirit-web @alma-oss/spirit-web-react ``` 或者说 ```shell npm install --save @alma-oss/spirit-web @alma-oss/spirit-web-react ``` ## 使用量 链接精神CSS(参见 [`spirit-web` 文档](https://github.com/alma-oss/spirit-design-system/tree/main/packages/web#readme) 更多选项: ```html ``` QQ 确保将所有 CSS 文件按相同的顺序加载 . 在您的应用程序中导入反应组件 : ```tsx import { Button } from '@alma-oss/spirit-web-react'; ``` ### 前置 CSS 组件类 如果您想要用自己的命名空间前置组件类, 您可以使用 `ClassNamePrefixProvider` 上下文以提供应用程序中所有组件的前缀. 检查 [`spirit-web` 文档](https://github.com/alma-oss/spirit-design-system/blob/main/packages/web/README.md#prefixing-css-class-names) 以学习如何前缀 CSS 类名称. ```tsx import { ClassNamePrefixProvider } from '@alma-oss/spirit-web-react/context/ClassNamePrefixContext'; export const Example = () => { return ( ); }; ``` ### 客户端运行 如果您想要使用带有路由器- 集成链接等组件的客户端路由( 例如) `Link`, (中文(简体) ), `ButtonLink`, (中文(简体) ), `PaginationLink`, (中文(简体) ), `HeaderLink`,或 `TabLink`),可以使用 `RouterProvider` 上下文以提供路由器导航功能。 当提供路由器时,内部链接会使用客户端-侧导航,而不是全页重载. 这个 `RouterProvider` 接受下列道具: - `children` - 接收路由器集成的响应节点子树(需要) - `navigate` - 接受路径字符串和可选路由器选项的函数 外部链接( 绝对) `http://` 编号 : `https://` URL, 协议相对的 URL 如 `//example.com`,或 URL 与其它方案如 `mailto:` 财务报告和审定财务报表 `tel:`),与非`_self` 目标,链接到 `download`,而被禁用的链接将总是使用标准锚行为. #### 路由器选项 所有链接组件接受 a `routerOptions` 道具,是传递给客户端侧路由器的对象 `navigate` 作为第二个参数。 这可以用来控制任何路由器特定的行为,如滚动,取而代之而不是推向历史等. ```jsx Login ``` #### Next.js App路由器 ```jsx 'use client'; import { Link, RouterProvider } from '@alma-oss/spirit-web-react'; import { useRouter } from 'next/navigation'; const MyComponent = () => { const router = useRouter(); return ( About Contact ); }; ``` 如果你使用下一个.js [基盘](https://nextjs.org/docs/app/api-reference/next-config-js/basePath) 设置,直接包含在精神中 `href` 使锁定 URL 保持正确 : ```jsx 'use client'; import { Link, RouterProvider } from '@alma-oss/spirit-web-react'; import { useRouter } from 'next/navigation'; // Same string as `basePath` in `next.config.js` (leading slash, no trailing slash) const basePath = '/docs'; const MyComponent = () => { const router = useRouter(); return ( About ); }; ``` #### Next.js 页面路由器 在Pages路由器, [`router.push`](https://nextjs.org/docs/pages/api-reference/functions/use-router#routerpush) 实值 `(url, as?, options?)`: 第二个参数是可选 `as` 路径和过渡选项(例如. `shallow`属于 **第三届** 参数。 灵魂传来 `routerOptions` 从链接组件作为第二个参数到 `navigate`,所以你应该 **没有** 通过 `router.push` 直接使用一个将选项转发到第三个参数的薄包装: ```jsx import { Link, RouterProvider } from '@alma-oss/spirit-web-react'; import { useRouter } from 'next/router'; const MyComponent = () => { const router = useRouter(); const navigate = (path, opts) => router.push(path, undefined, opts); return ( About Contact ); }; ``` #### 反应路由器 使用 `navigate` 从你的路由器。 保留 `href` 应用/路由配置所期望的格式中的值. ```jsx import { Link, RouterProvider } from '@alma-oss/spirit-web-react'; import { useNavigate } from 'react-router-dom'; const MyComponent = () => { const navigate = useNavigate(); return ( About ); }; ``` #### 重混合 Remix再导出相容的导航帮助器; 使用 `navigate` 以同样方式: ```jsx import { Link, RouterProvider } from '@alma-oss/spirit-web-react'; import { useNavigate } from '@remix-run/react'; const MyComponent = () => { const navigate = useNavigate(); return ( About ); }; ``` ## 翻译 具有内置英语默认的组件船. 要覆盖复制, 将您的应用程序或子树包入 **`I18nProvider`**。 。 。 . 你也可以通过: - 部分筑巢 **`translations`** (与库默认的嵌入形状相同),或 - 本地目录 **`locale`** + 本地密钥翻译(`translations[locale]`) (中文(简体) ). 缺少的密钥总是回到内置默认值. 没有活动对象条目的本地目录 `locale` 也使用这些默认——目录不作为翻译名空间合并. ```tsx import { I18nProvider } from '@alma-oss/spirit-web-react'; function App() { return ( ); } ``` ```tsx import { I18nProvider } from '@alma-oss/spirit-web-react'; const translations = { en: { common: { close: 'Close' } }, cs: { common: { close: 'Zavřít' } }, }; function App() { return ( ); } ``` 在客户端组件中,使用 **`useI18n`** 解决字符串。 无 `I18nProvider`, (中文(简体) ), `t` 只使用内置默认值. ```tsx import { useI18n } from '@alma-oss/spirit-web-react'; const { t } = useI18n(); t('common.close'); // 'Close' t('unknown.key'); // 'unknown.key' (returns the key when not found) ``` ### 占位符 这个 `t` 函数接受可选的第二个参数 **`params`**: 键匹配的对象 `{key}` 已解析字符串中的占位符. ```tsx t('textArea.counter.characters.enteredAria', { count: 42 }); ``` ### 组件字符串 所需的组件副本作为顶级道具被曝光,而带有内置默认的可选副本则归为 页:1 `strings` 道具 (英语). 两者都接受字面字符串或带有可选参数的翻译引用. ```tsx ``` 翻译参考文献可以使用任何应用程序或通过下列方式提供的词组密钥: `I18nProvider`;它们不受限制 到内置的命名空间。 决议优先是实例 `strings`,在v5迁移期间被贬损的别名, 提供者翻译,最后是内置的英语默认. 这个 `Aria` 后缀标记未显示且仅作为无障碍名称、描述或指令存在的文本. 显相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 相关字符串按目的分组. 每个组件 README 列出密钥, 字典 默认, 和英文副本在 a **翻译** 节。 词典路径匹配 `strings` 对象 (单位:千美元)`picker.tag.removeAria`) (中文(简体) ). 前几个路径,例如 `picker.removeItemLabel` 仍然有决心. ## 其他属性 所有组件都接受被传递到组件根元件上的额外属性. 用于添加自定义事件处理器、可访问属性或其他属性 由组件 API 不支持. i️ 需要将事件处理器传递到我们形式组件中的原生形式元素, 您可以使用 `inputProps` 道具 (英语). 支持的属性为: - `on*` 联合国. `onClick`(中文(简体) ) - `data-*` - `aria-*` - `id` 如果组件为其中任何一个属性设置了值,则所传递的值将被覆盖. 大多数组件还接受基于组件元素类型的本土HTML属性. ## 共享和继承的道具 一些组件从祖先组件中取出道具值,而不是(或除此之外)传递给 它们直接——例如,a `Label` 窝在一 `TextField` 当 `TextField` 已禁用,没有经过 `isDisabled` 页:1 `Label` 你自己来 本节解释两者 使这个办法发挥作用的机制——通过 `ContextPropsProvider`,以及群体背景——以及它们如何结合. ### 全球提案 一套固定道具—— `isDisabled`, (中文(简体) ), `isRequired`, (中文(简体) ), `validationState` 级联至 **每个** 后裔部分 自动,无论该组件的命名空间(见下文)。 将其设定为一次生产者组件(例如:. `TextFieldBase`和每个被窝 `Label`, (中文(简体) ), `HelperText`, (中文(简体) ), `ValidationText`等取出后再无接线. ### 命名空间道具 大部分其他共享道具为取名空间:生产部件提供 `ContextPropsProvider` 键入的值 其目标组件的命名空间,只有消费者读取该命名空间接收它. ```tsx {/* Only a component reading the "label" namespace picks up isLabelHidden */} ``` 每个消耗组件的默认命名空间是自有名称的骆驼Case形式——例如. `Label` 从 `label`, (中文(简体) ), `HelperText` 从 `helperText`, (中文(简体) ), `InputContainer` 从 `inputContainer`,以及 `StackItem` 从 `stackItem`。 。 。 . ### 覆盖命名空间 `propsContext` 消费者可以通过通过传递 `propsContext` 道具,允许 用于不同部件的道具: ```tsx {/* This Label reads the "button" namespace instead of its default "label" namespace */} ``` ### 优先发言 如果不止一个来源提供同样的道具,则优先(低至高): **全局道具 < 命名空间道具 < 直接道具** ```tsx {/* isLabelHidden is inherited, but the direct prop below still wins over isDisabled */} ``` ### 怎么样 `ContextPropsProvider` 合并值 `ContextPropsProvider` 级联进入其父母已经提供的一切——它不能取代继承的全部 数值。 顶级( 全局) 密钥替换该密钥的继承值; 命名空间密钥将一个级别深地合并到 所继承的命名空间对象,所以一个嵌入式提供者可以添加或覆盖单个命名空间道具,而无需 刺杀兄弟道具 由祖先设置 设置密钥到 `null`编号 :`undefined` 取出所传之相. ```tsx {/* Label here inherits both isLabelHidden and isStretched */} ``` ### 组上下文( 命名空间外的共享值) 少数相关组成部分具有单一价值,例如: `size` 或者说 `elementType` - 通过一个专门的 "组"上下文而不是通过 `ContextPropsProvider`。与关闭的全球道具组不同,加入一个组 上下文是选入并打开的:任何组件,包括您自己的应用程序中定义的一个组件,都可以简单地通过 读取上下文本身,并合并其中的值. ```tsx import { FormFieldsContext } from '@alma-oss/spirit-web-react'; import { useContext } from 'react'; const { size } = useContext(FormFieldsContext) ?? {}; ``` 制片人通过 `Provider` 帮助者 : ```tsx {/* descendants can read FormFieldsContext */} ``` 现有群体背景如下: | A. 背景情况 | 共同价值 | 消费者 | 生产商 | | --- | --- | --- | --- | | `FormFieldsContext` | `size` | `InputAddon`, (中文(简体) ), `InputContainer`, (中文(简体) ), `ControlButton`, (中文(简体) ), `Label` | `TextFieldBase`, (中文(简体) ), `UNSTABLE_Picker`, (中文(简体) ), `Select`, (中文(简体) ), `UNSTABLE_Combobox` | | `InlineElementsContext` | `elementType` | `Label`, (中文(简体) ), `HelperText`, (中文(简体) ), `ValidationText` | `Item`, (中文(简体) ), `Stack`, (中文(简体) ), `StackItem` | | `ListItemsContext` | `elementType` | `Item`, (中文(简体) ), `StackItem` | `Stack`, (中文(简体) ), `StackItem` | `InlineElementsContext` 财务报告和审定财务报表 `ListItemsContext` 都带着 `elementType`但他们回答了不同的问题 并按脱节部分阅读: `ListItemsContext` 告诉 `Item`编号 :`StackItem` 什么元素类型 _他们_ 本身应作为(例如). `li` 内置 a `ul` `Stack`),同时 `InlineElementsContext` 告诉他们的内线 内容( a)`Label`, (中文(简体) ), `HelperText`, (中文(简体) ), `ValidationText`)什么元素类型 _这个_ (如:. `span` 在一个 `Item`) (中文(简体) ). 他们被分开 所以一个组件 永远不会不小心读出一个价值 本来是为了自己的 后代—— `Item` 提供 `InlineElementsContext: { elementType: 'span' }` 为其儿童提供福利 看着这个价值适用于自己. ## 测试 ### 端到端测试 关于E2E测试的详细资料,包括视觉回归和无障碍测试,请参见: [`docs/contribution/e2e-testing.md`](https://github.com/alma-oss/spirit-design-system/tree/main/docs/contribution/e2e-testing.md) 财务报告和审定财务报表 [`docs/contribution/accessibility-testing.md`](https://github.com/alma-oss/spirit-design-system/tree/main/docs/contribution/accessibility-testing.md)。 。 。 . ## 样式 精神部分的设计使所有Alma职业应用程序保持一致。 它们包括内置型式的 仔细考虑,并经过广泛试验。 一般来说,自定义"精神"的设计被抑制,但大多数组件 确实提供了对布局和其他方面的控制。 此外,您还可以使用Spirit定义的设计符号,以确保您 应用符合设计要求,并适应各平台规模和颜色方案. ### 样式道具 所有"精神"组件都接受一套道具,可以用来控制其外间隔和显示. 道具为: #### 主题道具 - `theme` 这个 `theme` proc应用从设计符中生成的主题效用类. 使用 kebab- case 值来映射符号键( 如 . `theme-light-default`, (中文(简体) ), `theme-light-on-brand`) (中文(简体) ). 您可以应用 `theme` 任何巢层的道具,其中组件会消耗样式道具,而子组件会继承主题. #### 间距道具 - `margin` - `marginTop` - `marginRight` - `marginBottom` - `marginLeft` - `marginX` - `marginY` 这些道具接受一个间隔符(例如:. `space-100`, (中文(简体) ), `auto` 或带有断点键和间隔符的对象 数值或 `auto`。我们利用这些道具将全球CSS通用类设置在组件的根部元素上. #### 显示道具 - `hideOn` - 只在特定断点隐藏组件 - `hideFrom` - 从特定的断点上隐藏组件 这个 `hideOn` 道具接受单个 [断点符号](https://github.com/alma-oss/spirit-design-system/blob/main/docs/DICTIONARIES.md#breakpoint) (例如:. `mobile`, (中文(简体) ), `tablet`, (中文(简体) ), `desktop`),或一系列断点符号. 这个 `hideFrom` 道克接受单个断点符号. 该组件将使用 CSS 显示工具隐藏在指定的断点上. #### 实例 ```tsx // Spacing examples