@alma-oss/spirit-web-反应

反应实施"精神设计"系统组件.

• 安装
• 使用量
• 翻译
• 其他属性
• 共享和继承的道具
• 测试
• 样式
• 从设计托肯斯生成的类型
• 公用事业
• 被控制 vs 未控制组件
• 折旧
• 实例
• Figma的执行
• 许可证

安装

期待着你 react 财务报告和审定财务报表 react-dom 安装在您的应用程序中, 运行 :

yarn add @alma-oss/spirit-web @alma-oss/spirit-web-react

或者说

npm install --save @alma-oss/spirit-web @alma-oss/spirit-web-react

使用量

链接精神CSS(参见 spirit-web 文档 更多选项:

<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/foundation.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/components.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/helpers.min.css" />
<link rel="stylesheet" href="node_modules/@alma-oss/spirit-web/css/utilities.min.css" />

QQ 确保将所有 CSS 文件按相同的顺序加载 .

在您的应用程序中导入反应组件 :

import { Button } from '@alma-oss/spirit-web-react';

前置 CSS 组件类

如果您想要用自己的命名空间前置组件类, 您可以使用 ClassNamePrefixProvider 上下文以提供应用程序中所有组件的前缀.

检查 spirit-web 文档 以学习如何前缀 CSS 类名称.

import { ClassNamePrefixProvider } from '@alma-oss/spirit-web-react/context/ClassNamePrefixContext';

export const Example = () => {
  return (
    <ClassNamePrefixProvider value="jobs">
      <Button>Button</Button>
    </ClassNamePrefixProvider>
  );
};

客户端运行

如果您想要使用带有路由器- 集成链接等组件的客户端路由( 例如) Link, (中文(简体) ), ButtonLink, (中文(简体) ), PaginationLink, (中文(简体) ), HeaderLink,或 TabLink),可以使用 RouterProvider 上下文以提供路由器导航功能。 当提供路由器时,内部链接会使用客户端-侧导航,而不是全页重载.

这个 RouterProvider 接受下列道具:

• children - 接收路由器集成的响应节点子树(需要)
• navigate - 接受路径字符串和可选路由器选项的函数

外部链接( 绝对) http:// 编号 : https:// URL, 协议相对的 URL 如 //example.com,或 URL 与其它方案如 mailto: 财务报告和审定财务报表 tel:),与非_self 目标,链接到 download,而被禁用的链接将总是使用标准锚行为.

路由器选项

所有链接组件接受 a routerOptions 道具,是传递给客户端侧路由器的对象 navigate 作为第二个参数。 这可以用来控制任何路由器特定的行为,如滚动,取而代之而不是推向历史等.

<Link href="/login" routerOptions={{ replace: true }}>
  Login
</Link>

Next.js App路由器

'use client';

import { Link, RouterProvider } from '@alma-oss/spirit-web-react';
import { useRouter } from 'next/navigation';

const MyComponent = () => {
  const router = useRouter();

  return (
    <RouterProvider navigate={router.push}>
      <Link href="/about">About</Link>
      <Link href="/contact">Contact</Link>
    </RouterProvider>
  );
};

如果你使用下一个.js 基盘 设置,直接包含在精神中 href 使锁定 URL 保持正确 :

'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 (
    <RouterProvider navigate={router.push}>
      <Link href={`${basePath}/about`}>About</Link>
    </RouterProvider>
  );
};

Next.js 页面路由器

在Pages路由器, router.push 实值 (url, as?, options?): 第二个参数是可选 as 路径和过渡选项(例如. shallow属于 第三届 参数。 灵魂传来 routerOptions 从链接组件作为第二个参数到 navigate,所以你应该 没有 通过 router.push 直接使用一个将选项转发到第三个参数的薄包装:

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 (
    <RouterProvider navigate={navigate}>
      <Link href="/about">About</Link>
      <Link href="/contact" routerOptions={{ shallow: true }}>
        Contact
      </Link>
    </RouterProvider>
  );
};

反应路由器

使用 navigate 从你的路由器。 保留 href 应用/路由配置所期望的格式中的值.

import { Link, RouterProvider } from '@alma-oss/spirit-web-react';
import { useNavigate } from 'react-router-dom';

const MyComponent = () => {
  const navigate = useNavigate();

  return (
    <RouterProvider navigate={navigate}>
      <Link href="/about">About</Link>
    </RouterProvider>
  );
};

重混合

Remix再导出相容的导航帮助器; 使用 navigate 以同样方式:

import { Link, RouterProvider } from '@alma-oss/spirit-web-react';
import { useNavigate } from '@remix-run/react';

const MyComponent = () => {
  const navigate = useNavigate();

  return (
    <RouterProvider navigate={navigate}>
      <Link href="/about">About</Link>
    </RouterProvider>
  );
};

翻译

具有内置英语默认的组件船. 要覆盖复制, 将您的应用程序或子树包入 I18nProvider。 。 。 . 你也可以通过:

• 部分筑巢 translations (与库默认的嵌入形状相同),或
• 本地目录 locale + 本地密钥翻译(translations[locale]) (中文(简体) ).

缺少的密钥总是回到内置默认值. 没有活动对象条目的本地目录 locale 也使用这些默认——目录不作为翻译名空间合并.

import { I18nProvider } from '@alma-oss/spirit-web-react';

function App() {
  return (
    <I18nProvider translations={{ common: { close: 'Zavřít' } }}>
      <YourApp />
    </I18nProvider>
  );
}

import { I18nProvider } from '@alma-oss/spirit-web-react';

const translations = {
  en: { common: { close: 'Close' } },
  cs: { common: { close: 'Zavřít' } },
};

function App() {
  return (
    <I18nProvider locale="cs" translations={translations}>
      <YourApp />
    </I18nProvider>
  );
}

在客户端组件中,使用 useI18n 解决字符串。 无 I18nProvider, (中文(简体) ), t 只使用内置默认值.

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} 已解析字符串中的占位符.

t('textArea.counter.characters.enteredAria', { count: 42 });

组件字符串

所需的组件副本作为顶级道具被曝光,而带有内置默认的可选副本则归为 页:1 strings 道具 (英语). 两者都接受字面字符串或带有可选参数的翻译引用.

<UncontrolledSplitButton labelButton="Save" />
<UncontrolledSplitButton labelButton={{ key: 'actions.save' }} />
<ModalHeader strings={{ closeAria: 'Dismiss dialog' }} />
<ModalHeader strings={{ closeAria: { key: 'common.close' } }} />
<ModalHeader strings={{ closeAria: { key: 'modal.close', params: { name: 'Settings' } } }} />

翻译参考文献可以使用任何应用程序或通过下列方式提供的词组密钥: 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 键入的值 其目标组件的命名空间,只有消费者读取该命名空间接收它.

<ContextPropsProvider value={{ label: { isLabelHidden: true } }}>
  {/* Only a component reading the "label" namespace picks up isLabelHidden */}
</ContextPropsProvider>

每个消耗组件的默认命名空间是自有名称的骆驼Case形式——例如. Label 从 label, (中文(简体) ), HelperText 从 helperText, (中文(简体) ), InputContainer 从 inputContainer,以及 StackItem 从 stackItem。 。 。 .

覆盖命名空间 propsContext

消费者可以通过通过传递 propsContext 道具,允许 用于不同部件的道具:

<ContextPropsProvider value={{ button: { color: 'danger' } }}>
  {/* This Label reads the "button" namespace instead of its default "label" namespace */}
  <Label propsContext="button">Delete</Label>
</ContextPropsProvider>

优先发言

如果不止一个来源提供同样的道具,则优先(低至高):

全局道具 < 命名空间道具 < 直接道具

<ContextPropsProvider value={{ isDisabled: true, label: { isLabelHidden: true } }}>
  {/* isLabelHidden is inherited, but the direct prop below still wins over isDisabled */}
  <Label isDisabled={false}>Name</Label>
</ContextPropsProvider>

怎么样 ContextPropsProvider 合并值

ContextPropsProvider 级联进入其父母已经提供的一切——它不能取代继承的全部 数值。 顶级( 全局) 密钥替换该密钥的继承值; 命名空间密钥将一个级别深地合并到 所继承的命名空间对象,所以一个嵌入式提供者可以添加或覆盖单个命名空间道具,而无需 刺杀兄弟道具 由祖先设置 设置密钥到 null编号 :undefined 取出所传之相.

<ContextPropsProvider value={{ label: { isLabelHidden: true } }}>
  <ContextPropsProvider value={{ label: { isStretched: true } }}>
    {/* Label here inherits both isLabelHidden and isStretched */}
  </ContextPropsProvider>
</ContextPropsProvider>

组上下文( 命名空间外的共享值)

少数相关组成部分具有单一价值,例如: size 或者说 elementType - 通过一个专门的 "组"上下文而不是通过 ContextPropsProvider。与关闭的全球道具组不同,加入一个组 上下文是选入并打开的:任何组件,包括您自己的应用程序中定义的一个组件,都可以简单地通过 读取上下文本身,并合并其中的值.

import { FormFieldsContext } from '@alma-oss/spirit-web-react';
import { useContext } from 'react';

const { size } = useContext(FormFieldsContext) ?? {};

制片人通过 Provider 帮助者 :

<Provider values={[[FormFieldsContext, { size: 'small' }]]}>{/* descendants can read FormFieldsContext */}</Provider>

现有群体背景如下:

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 财务报告和审定财务报表 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 道具接受单个 断点符号 (例如:. mobile, (中文(简体) ), tablet, (中文(简体) ), desktop),或一系列断点符号. 这个 hideFrom 道克接受单个断点符号. 该组件将使用 CSS 显示工具隐藏在指定的断点上.

实例

// Spacing examples
<Alert marginBottom="space-100" />
<Button marginX={{ mobile: 'space-100', tablet: 'space-200' }} />

// Hide examples
<Alert hideOn="mobile" />  // Hidden only on mobile
<Button hideOn={['mobile', 'tablet']} />  // Hidden only on mobile and tablet
<Alert hideFrom="tablet" />  // Hidden from tablet breakpoint and up

// Theme examples
<Header theme="theme-light-default" />
<Header theme="theme-light-on-brand" />

如果您需要更多对组件样式的控制, 请使用 逃生舱。 。 。 .

从设计托肯斯生成的类型

一些道具(如:相色相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 它们将数值限制在设计系统中定义的值,并随时更新每个符号变化.

如果您需要额外的值, 您需要与设计师协调, 以便添加到 Figma 中, 并通过符号获取 .

逃脱帽子

虽然我们鼓励团队利用精神设计,但我们确实意识到,有时产品特定的定制 也许需要。 在这种情况下,我们鼓励你和你的设计师 跟我们谈谈我们也许可以建议 或者你的设计可以帮助提出未来的精神补充.

虽然传统的类名和样式道具在"精神回放"组件中不支持,但有两个出逃 窗口,您可以 风险使用。这些是 UNSAFE className 和 UNSAFE style 。 这些道具的使用应该是 考虑 最后办法。它们可以用来围绕“精神网络反应”中的bugs或限制工作,但应当 不用于长期.

其背后的理由是,未来对Spirit设计的更新可能会导致出乎意料地打破产品的变化. 如果一个 Spirit Web 的内部 DOM 结构或 CSS 属性发生变化, 可能导致冲突 产品中CSS的被覆盖。 因此,阶级名称和风格不安全,如果你使用他们知道你 你冒着风险这么做.

请参考其他格式 网页软件包文档。 。 。 .

公用事业

pxToRem()

pxToRem 将像素值转换为 a rem 绳子。 它使用 Spirit 字体大小( 16 px by) 默认值)和小数后小数零.

import { pxToRem } from '@alma-oss/spirit-web-react/utils';

pxToRem(24); // → '1.5rem'
pxToRem('16px'); // → '1rem'
pxToRem(14, { baseFontSize: 16, decimals: 2 }); // → '0.88rem'

见 单位指南 详细情况,包括常设委员会 等同字体大小与设计符号的关系.

被控制 vs 未控制组件

• A 类 控制部分 是取其当前 通过道具表示值,并通过Change这样的回调来通知变化. 一个母组件通过处理回调和管理自己的“控制” 状态,并将新值作为道具传递到受控组件. 也可以称之为"垃圾组件".

• 一个 未控制组件 是自己储存的 内置状态,您可以使用一个参考文献查询 DOM 以查找其当前值 当你需要的时候。 这有点像传统的HTML.

所有组件默认为 控制 组件,所以您必须提供您自己的控制或切换功能,以使它们随心所欲地发挥作用.

为了更好的开发者经验,还有 无控制 提供的构成部分的变式. 你可以用这个 Uncontrolled 用于更快开发的变体.

折旧

此套件对在下个主放出时会被去掉或被替换的道具,功能和组件使用去化警告. 检查您的浏览器控制台, 以查看您是否正在使用任何已贬值的功能 .

👉 参见 DEPRECATES 文件 用于所有折旧清单.

环境警告

生产

这个 warning 用于校正警告检查的工具 process.env.NODE_ENV 变量以决定是否显示警告. 如果环境变量设定为 production 不显示警告.

测试

在进行测试时,你可能会看到贬值警告. 您可以通过嘲笑执行 warning 函数或 console.warn 函数. 但我们强烈地劝阻你们不要这么做,因为堕落警告是用来帮助你们准备下一次重大释放的.

beforeEach(() => {
  jest.spyOn(console, 'warn').mockImplementation(() => {});
});

afterEach(() => {
  console.warn.mockRestore();
});

实例

见 实例 现场演示.

从图像执行

如果你执行来自Figma设计的 " 精神 " 组成部分——无论是否得到大赦国际的援助——我们提供并建议 以下工具可以帮助你.

Figma 代码连接

Figma 代码连接 将 Figma 组件链接到代码片段。 用它来查看每个设计组件 以代码写成,并使用哪些道具(例如. size, (中文(简体) ), iconName, (中文(简体) ), textColor执行时。 带有图解模式 您可以在“代码”分页中直接用 Figma 读取片段.

AI-辅助执行

如果您使用 AI 驱动工具从 Figma 执行 UI,以下帮助代理生成准确的 Spirit 代码.

图片MCP —— 说 图片MCP (模式上下文协议)让AI读取您 Figma 文件:设计上下文, 截图和选定节点的元数据。 Figma 桌面应用程序打开后, 配置了 Figma MCP 服务器 在工具中,代理可以使用工具如: get_design_context 财务报告和审定财务报表 get_screenshot。 。 。 . 见 Figma MCP 文档 更多信息.

Figma 到代码技能 —— 说 代码图 (单位:千美元)/spirit:figma-to-code教人工智能 工具如何使用当前Spirit Web React APIs从 Figma 设计中执行生产React. 当请求的输出是React代码时使用. 为了对Figma框架进行前手动设计系统审查, 使用情况 /spirit:review-figma-design 换句话说 安装执行技能:

npx skills add https://github.com/alma-oss/spirit-design-system --skill figma-to-code

要多学习技能,看 技能文件。 。 。 .

内容提要

• 如果你使用人工智能 审查 a 移交前图框,运行 /spirit:review-figma-design 先说. 这一审查是以后执行的质量闸门: 框架将进入 /spirit:figma-to-code 输出.
• 如果你使用人工智能 执行 来自Figma的UI,安装了Figma MCP和 /spirit:figma-to-code,然后用 Figma 节点或 URL 来提示代理.
• 在 Figma 中,使用 Figma 代码连接来查看和复制您执行的组件的代码 .

许可证

见 自由主义 文档供参考.