UI 视觉设计 / 系统课时

用 Token 编写 Button 组件

用 Token 编写 Button 组件

把 Figma 设计稿中的颜色、尺寸与交互状态 Token 接入一个可复用的 React Button。完成后,页面可以验证默认、悬停、按下、键盘焦点、禁用及加载反馈;颜色和尺寸集中在 Token 层,后续换主题不需要修改组件逻辑。

学习目标

  • 建立基础色、语义色、组件 Token 到 Button 样式的映射。
  • 用 React 和 TypeScript 实现尺寸、禁用、加载及点击行为。
  • 通过鼠标、键盘和模拟异步请求验收状态与可访问性。

明确 Token 与状态的对应关系

以主按钮为例,采用两档尺寸:sm 高 36px,md 高 44px,圆角均为 8px。把 Figma 中的基础色 blue/600、blue/700、blue/800 分别映射为语义色,再转成 Button 专用 CSS 自定义属性,而不是把色值写进 JSX。

状态或属性 触发条件 使用的组件 Token
默认 可操作,未交互 --button-bg-default:#2563EB
悬停 :hover 且可操作 --button-bg-hover:#1D4ED8
按下 :active 且可操作 --button-bg-pressed:#1E40AF
键盘焦点 :focus-visible --button-focus-ring:#1E40AF
禁用与加载 disabled 或 aria-disabled --button-bg-disabled:#E2E8F0

焦点描边可以与悬停颜色同时存在;加载态则阻止再次点击。映射关系和状态覆盖顺序如下,图片中的 Token 路径与后面的 CSS 一一对应。

Button 颜色令牌依赖及状态覆盖关系

建立最小 React 工程

准备 Node.js 22.12+、npm 和浏览器。以下使用 Vite 的 react-ts 模板;已有 React TypeScript 工程可直接新建下节文件。Vite 的 Node.js 版本要求以官方指南为准。

bash
npm create vite@latest token-button-demo -- --template react-ts
cd token-button-demo
npm install

预期结果:三个命令正常完成,项目中存在 src/main.tsx、src/App.tsx 和 src/index.css。安装日志和耗时取决于环境,退出状态码应为 0。

编写 Button 与 Token 样式

新建 src/Button.tsx。真正不可使用时采用原生 disabled;加载中改用 aria-disabled 加事件拦截,避免正在操作的按钮从键盘焦点顺序中消失。type 默认设为 button,防止放进表单时意外提交。

tsx
import type { ComponentPropsWithoutRef, ReactNode } from "react";

type ButtonProps = Omit<ComponentPropsWithoutRef<"button">, "children"> & {
  children: ReactNode;
  size?: "sm" | "md";
  loading?: boolean;
};

export function Button({
  children,
  size = "md",
  loading = false,
  disabled = false,
  type = "button",
  className,
  onClick,
  ...rest
}: ButtonProps) {
  // 明确禁用优先:同时传入 disabled 和 loading 时以禁用为准
  const busy = loading && !disabled;

  return (
    <button
      {...rest}
      type={type}
      className={["ds-button", className].filter(Boolean).join(" ")}
      data-size={size}
      disabled={disabled}
      aria-disabled={busy || undefined}
      aria-busy={busy || undefined}
      onClick={(event) => {
        // aria-disabled 只声明语义,不会自动阻止点击或表单提交
        if (busy) {
          event.preventDefault();
          return;
        }
        onClick?.(event);
      }}
    >
      {busy && <span className="ds-button__spinner" aria-hidden="true" />}
      <span>{busy ? "处理中…" : children}</span>
    </button>
  );
}

用下列内容替换模板自带的 src/index.css。最上方三组变量分别是基础色、语义色和组件 Token;在正式项目中,这部分应由设计令牌构建流程生成,Button 选择器只读取 Token。

css
:root {
  --ref-blue-600: #2563eb;
  --ref-blue-700: #1d4ed8;
  --ref-blue-800: #1e40af;
  --sys-action-default: var(--ref-blue-600);
  --sys-action-hover: var(--ref-blue-700);
  --sys-action-pressed: var(--ref-blue-800);
  --button-bg-default: var(--sys-action-default);
  --button-bg-hover: var(--sys-action-hover);
  --button-bg-pressed: var(--sys-action-pressed);
  --button-bg-disabled: #e2e8f0;
  --button-fg-default: #ffffff;
  --button-fg-disabled: #475569;
  --button-focus-ring: var(--ref-blue-800);
  --button-height-sm: 36px;
  --button-height-md: 44px;
  --button-radius: 8px;
}

body {
  margin: 0;
  color: #0f172a;
  background: #ffffff;
  font-family: system-ui, sans-serif;
}

.ds-button {
  box-sizing: border-box;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  min-height: var(--button-height-md);
  padding: 0 16px;
  border: 1px solid transparent;
  border-radius: var(--button-radius);
  background: var(--button-bg-default);
  color: var(--button-fg-default);
  font: 600 14px/20px system-ui, sans-serif;
  cursor: pointer;
  transition: background-color 120ms ease;
}

/* 尺寸只由组件 Token 控制,不随内容变化 */
.ds-button[data-size="sm"] {
  min-height: var(--button-height-sm);
  padding-inline: 12px;
}

.ds-button:hover:not(:disabled):not([aria-disabled="true"]) {
  background: var(--button-bg-hover);
}

.ds-button:active:not(:disabled):not([aria-disabled="true"]) {
  background: var(--button-bg-pressed);
}

.ds-button:focus-visible {
  outline: 3px solid var(--button-focus-ring);
  outline-offset: 2px;
}

.ds-button:disabled,
.ds-button[aria-disabled="true"] {
  background: var(--button-bg-disabled);
  color: var(--button-fg-disabled);
  cursor: not-allowed;
}

.ds-button[aria-disabled="true"] {
  cursor: progress;
}

.ds-button__spinner {
  width: 14px;
  height: 14px;
  border: 2px solid currentColor;
  border-right-color: transparent;
  border-radius: 50%;
  animation: ds-spin 700ms linear infinite;
}

@keyframes ds-spin {
  to { transform: rotate(360deg); }
}

/* 尊重系统减少动态效果的偏好 */
@media (prefers-reduced-motion: reduce) {
  .ds-button { transition: none; }
  .ds-button__spinner { animation: none; }
}

.demo-row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 12px;
}

disabled 由浏览器原生阻止交互并退出 Tab 顺序;aria-disabled 不会自动阻止事件,所以加载时既要添加语义属性,也要在点击回调中拦截。只用降低透明度来模拟禁用,不具备这些行为。

运行示例并逐项验收

替换 src/App.tsx。第一个按钮模拟耗时 800ms 的保存操作,第二个验证尺寸与点击,第三个验证原生禁用;role="status" 把异步反馈提供给辅助技术。

tsx
import { useState } from "react";
import { Button } from "./Button";

export default function App() {
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState("尚未提交");

  async function handleSave() {
    setLoading(true);
    setMessage("正在处理…");

    try {
      // 仅用于演示;生产环境替换为真实的异步请求
      await new Promise<void>((resolve) => window.setTimeout(resolve, 800));
      setMessage("提交成功(演示)");
    } finally {
      setLoading(false);
    }
  }

  return (
    <main style={{ padding: 24 }}>
      <h1>Button 状态验收</h1>
      <div className="demo-row">
        <Button loading={loading} onClick={handleSave}>提交</Button>
        <Button size="sm" onClick={() => setMessage("小号已点击")}>
          小号按钮
        </Button>
        <Button disabled onClick={() => setMessage("错误:禁用仍可点击")}>
          不可操作
        </Button>
      </div>
      <p role="status">{message}</p>
    </main>
  );
}

执行开发服务器命令:

bash
npm run dev

预期输出会包含本地访问地址(以下只摘录关键字段):

text
Local: http://localhost:<PORT>/

<PORT> 是实际端口占位符,可能因本机占用情况变化。打开终端显示的真实地址,按下表验证:

操作 预期结果
鼠标悬停、按住主按钮 背景依次使用 #1D4ED8、#1E40AF
按 Tab 定位主按钮,再按 Enter 或 Space 出现 3px 焦点描边,并可触发提交
点击“提交”后立即重复点击 约 800ms 内显示“处理中…”和旋转指示,不会重复触发提交
点击或尝试 Tab 定位“不可操作” 不触发回调,也不进入正常 Tab 焦点顺序
检查“小号按钮”与主按钮 最小高度分别为 36px 和 44px
打开系统“减少动态效果”偏好 转场与旋转动画停用,状态文字仍可读

需要核对内部属性时,使用浏览器开发者工具检查加载按钮是否同时出现 aria-disabled="true" 与 aria-busy="true"。完成后执行 npm run build,构建应成功生成 dist 产物;若仍沿用 Vite 模板的 src/main.tsx,它已负责加载 src/index.css,不需要重复导入。

避免三个常见实现错误

  • 把加载态等同于原生禁用。 请求期间直接设置 disabled 容易使当前焦点丢失。本实现保留加载态焦点,但必须配合事件拦截;若业务规定加载时也不可聚焦,可以改成原生禁用并重新测试焦点体验。
  • 只给 aria-disabled 不拦截事件。 辅助技术会读出“不可用”,但鼠标或键盘仍可能触发处理函数。组件中的 preventDefault() 与提前返回缺一不可,尤其是在 type="submit" 的表单里。
  • 把状态色写死在组件。 不要在 onMouseEnter 中直接修改 style.backgroundColor;主题变更应替换 --sys-action-* 的值,悬停、按下和禁用的优先级交给 CSS 选择器管理。

验收时保留一份默认、焦点、禁用与加载态的对照记录,并检查 role="status" 在加载结束后能播报完成消息。这样组件既能对齐设计 Token,也能在鼠标、键盘和异步交互中保持一致行为。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Token 编写 Button 组件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通