# Yi UI · 文档与博客全文

# AI 助手面板

来源：https://yiui.dev/blocks/agent-chat-01/

<BlockViewer name="agent-chat-01" />

这个 AI 助手面板提炼自我的一个企业监控平台项目，保留「在工作区旁边排查问题」的交互，去掉认证、业务接口与监控数据依赖。默认使用离线模拟数据，不需要密钥或服务端。

- **两种布局**：右侧嵌入面板、右下角浮动窗口；聊天记录、输入草稿和滚动位置在切换时保留。
- **可检查的过程**：分析摘要、运行中的工具、成功与失败结果，以及可打开的参考来源，按顺序排成紧凑的 `Trace`（shadcn 的 `trace`），一行一步；每一步的输入与输出可折叠查看。
- **回答里的图表**：工具返回后，回答上方会出现一张紧凑的图表卡片：可用率走势（`MiniChart` 面积图加指标行）、GPU 占用（三个 `MiniRing` 进度环）、CI 各步骤耗时（`MiniChart` 柱图）。图表以 `data-chart` 数据块的形式在消息里流式出现，宽度跟随面板，高度只有 96px 左右，不会把消息撑长。
- **流式演示**：应用监控、vLLM 显存、CI 安装失败三个剧本，其他问题使用通用剧本。所有 reasoning 均为预写的演示摘要，不是真实模型的隐藏思维。
- **对话操作**：复制、点赞/点踩、重新生成、新建对话、停止生成。反馈仅保存在当前页面，不会上报。
- **窄屏适配**：小于 768px 时，两种模式都使用底部 Sheet，带焦点管理和 Escape 关闭；嵌入面板支持用鼠标或触摸拖动、用方向键调整宽度。

### 用到的本站组件

除输入框、按钮、气泡、Sheet 等 shadcn 原语外，区块里这几处直接用了本站自己的组件：

| 位置 | 组件 | 说明 |
| --- | --- | --- |
| 回答里的图表 | [`chart-card`](/components/chart-card)、[`mini-chart`](/components/mini-chart) | `ChartCard` 外壳 + `ChartMetrics` 指标行，图形用 `MiniChart`（面积、柱）与 `MiniRing`（进度环） |
| 空状态的背景与标题 | [`glyph-field`](/components/glyph-field)、[`text-animate`](/components/text-animate) | 四周淡淡的字符矩阵，欢迎语用 `TextReveal` 逐词显现 |
| 示例工作区的布局切换 | [`segmented-control`](/components/segmented-control) | 嵌入布局 / 浮动窗口，选中项就是当前布局 |

## 安装

<InstallCommand name="agent-chat-01" />

会安装 `app/agent/page.tsx` 页面，以及 `components/agent-chat/` 下的组件与数据文件。共享 hook 安装到 `hooks/use-controllable-state.ts`。shadcn 依赖来自官方 registry，本站组件 `chart-card`、`mini-chart`（图表及其 `recharts` 依赖）、`glyph-field`、`text-animate`、`segmented-control`（及它们依赖的 `flow-diagram` 色调）一并安装；npm 依赖为 `ai`、`@ai-sdk/react`、`motion`、`lucide-react`、`class-variance-authority`。实现基于 AI SDK 7 与 React SDK 4。

## 用法

```tsx title="app/workspace/page.tsx"
"use client"

import {
  AgentChatPanel,
  AgentChatProvider,
  AgentChatTrigger,
} from "@/components/agent-chat/agent-chat"

export default function Workspace() {
  return (
    <AgentChatProvider defaultMode="embedded" defaultOpen>
      <div className="flex h-dvh flex-col">
        <header className="p-4">
          <AgentChatTrigger variant="button" />
        </header>
        <div className="flex min-h-0 flex-1">
          <main className="min-w-0 flex-1 overflow-auto p-6">你的工作区</main>
          <AgentChatPanel />
        </div>
        <AgentChatTrigger />
      </div>
    </AgentChatProvider>
  )
}
```

Provider 内只创建一个 `useChat` 实例，也只挂载一个面板。将面板放在与 `main` 同级的 flex 容器中；嵌入时默认宽 400px，调整范围 320–640px，父容器需要有明确高度与 `min-h-0`。

## 示例

### 受控布局与自定义文案

```tsx title="components/workspace.tsx"
"use client"

import { useState } from "react"
import {
  AgentChatPanel,
  AgentChatProvider,
  AgentChatTrigger,
  type AgentChatMode,
} from "@/components/agent-chat/agent-chat"

export function Workspace() {
  const [mode, setMode] = useState<AgentChatMode>("embedded")
  const [open, setOpen] = useState(true)
  return (
    <AgentChatProvider
      mode={mode}
      onModeChange={setMode}
      open={open}
      onOpenChange={setOpen}
      labels={{ title: "工程助手", welcome: "今天要解决什么问题？" }}
    >
      <div className="flex h-dvh flex-col">
        <header>
          <AgentChatTrigger variant="button" />
        </header>
        <div className="flex min-h-0 flex-1">
          <main className="min-w-0 flex-1">你的工作区</main>
          <AgentChatPanel />
        </div>
        <AgentChatTrigger />
      </div>
    </AgentChatProvider>
  )
}
```

预览页包含嵌入、浮动、预填记录和从工作区发起问题的组合示例。

## API

### AgentChatProvider

<TypeTable
  type={{
    defaultMode: { type: '"embedded" | "floating"', description: "初始布局模式", default: '"floating"' },
    defaultOpen: { type: "boolean", description: "初始是否展开", default: "false" },
    transport: { type: "ChatTransport<UIMessage>", description: "聊天传输层；不传则使用内置 mock transport" },
    suggestions: { type: "string[]", description: "建议问题；不传时显示三个示例问题，传 `[]` 隐藏" },
    title: { type: "string", description: "面板标题", default: '"AI 助手"' },
    initialMessages: { type: "UIMessage[]", description: "可选的初始记录，演示页用它预填一轮对话" },
    children: { type: "ReactNode", description: "工作区内容", required: true },
  }}
/>

<Callout title="初始化与持久化">
  `default*` 与 `initialMessages` 只用于初始化。更换会话或 transport 配置时，可通过 Provider 的 React `key` 重新创建实例。会话状态仅在当前 Provider 生命周期内保存，刷新后重置；浮动窗口位置单独保存在 `localStorage`（`travinsy:agent-chat:position`），刷新或切换布局后仍会恢复。读取时以及窗口尺寸变化时，都会把位置约束在视口内。存储不可用时仍可在当前页面移动。
</Callout>

### labels

`labels` 接收 `Partial<AgentChatLabels>`，覆盖 `config.ts` 中 `DEFAULT_LABELS` 的任意几项（面板标题、输入框占位、按钮名称、状态文案等），例如 `labels={{ title: "工程助手", welcome: "今天要解决什么问题？" }}`。`thought` 支持 `{seconds}` 占位符；`moveWindow`（默认 `"移动助手窗口"`）用作浮动窗口拖动手柄的可访问名称；完整键列表见 `config.ts`。

### AgentChatPanel

<PropsTable name="agent-chat-01" component="AgentChatPanel" />

`draggable?: boolean` 默认 `true`，允许桌面浮动模式拖动；传 `false` 禁用指针和键盘移动。小于 768px 的 Sheet 自动禁用拖动。标题栏支持鼠标与触控拖动，操作按钮不会触发拖动；双击标题栏复位到默认右下角。`data-draggable` 表示可移动，拖动期间面板与标题栏设置 `data-dragging="true"`。

### 触发器、建议问题与 Hook

| 导出                  | API                                                                                                            |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| `AgentChatPanel`      | `{ className?: string; id?: string; draggable?: boolean }`；关闭时不渲染；桌面嵌入为 `aside`                   |
| `AgentChatTrigger`    | `{ variant?: "fab" \| "button"; className?: string }`；默认 `fab`，只在浮动模式关闭时显示                      |
| `useAgentChat()`      | `{ mode, setMode, toggleMode, open, setOpen }`；必须在 Provider 内调用                                         |
| `AgentChatSuggestion` | `{ question: string; children?: ReactNode; className?: string }`；从外部工作区打开面板并发送问题，生成期间禁用 |
| `AgentChatMode`       | `"embedded" \| "floating"`                                                                                     |

`Enter` 发送，`Shift + Enter` 换行，中文输入法选词时不会误发送。生成中点击「停止」调用 `stop()`；已收到的内容保留，未完成的工具标记为「已停止」。阅读旧消息时不会强制滚动到底部。

## 可访问性

- 标题栏与反馈按钮均有中文可访问名称，输入框有标签。
- 分析过程里每一步的状态写在标题文字里（运行中 / 已完成 / 失败 / 已停止），图标仅装饰；展开按钮暴露 `aria-expanded`。
- 图表卡片里的图是 `role="img"`，名称来自剧本里的 `label`；进度环是 `role="meter"`；关键数字同时写在指标行或环中央的文字里，不只靠图形。
- 聊天记录通过 `aria-live="polite"` 播报新增内容；按钮暴露 `aria-expanded`、`aria-pressed`，面板通过 `data-mode`、`data-state` 暴露状态。
- `Enter` 发送，`Shift + Enter` 换行；输入法组合期间不会误发。调整面板宽度可用左右方向键。
- 浮动模式下，Tab 聚焦「移动助手窗口」手柄，方向键每次移动 16px，Shift + 方向键移动 64px；Home、Enter 或空格复位到默认右下角。双击标题栏也可复位。移动始终限制在视口内；窄屏或 `draggable={false}` 时不显示手柄。
- 窄屏 Sheet 提供焦点管理、焦点回到触发区域和 Escape 关闭。
- 动效遵循 `prefers-reduced-motion`，来源链接标注新标签页。

## 注意事项

### 文件结构

```text
components/agent-chat/
├── agent-chat.tsx            # 对外入口、面板和触发器
├── agent-chat-context.tsx    # Provider 与会话状态
├── use-agent-chat-position.ts # 指针/键盘移动、视口约束与位置持久化
├── agent-chat-body.tsx       # 标题栏、滚动区、输入框
├── chat-message.tsx          # 消息气泡、分析过程 Trace、回复正文与反馈
├── chat-charts.tsx           # 回答里的图表卡片（迷你图、进度环）
├── chat-markdown.tsx         # 安全的简单 Markdown
├── config.ts                 # DEFAULT_LABELS 与建议问题
├── types.ts                  # 模式类型与图表块类型 ChatChart
├── mock-transport.ts         # 可取消的流
├── scripts.ts                # 预置剧本
└── demo-data.ts              # 页面默认记录与场景
hooks/use-controllable-state.ts
app/agent/page.tsx
```

### Mock transport 设计

`mock-transport.ts` 按最后一条用户消息匹配正则，构造标准 `UIMessageChunk` 队列。每次 `pull` 只输出一个片段：reasoning → 多个 dynamic tool → data-chart（图表）→ source-url → text → finish。延迟定时器受 `AbortSignal` 和流取消控制，不会执行真实命令或请求业务服务；`reconnectToStream` 返回 `null`。

`chat-message.tsx` 同时接受动态工具与 `tool-*` 静态工具消息。图表块的结构见 `types.ts` 的 `ChatChart`（`series` 走势 / 柱图、`rings` 进度环），必须可被 JSON 序列化，真实后端用 `type: "data-chart"` 的数据块下发即可。Markdown 仅支持段落、列表与行内代码，不执行 HTML；来源 URL 仅允许 HTTP(S)。

### 接入真实后端

客户端只需替换 transport；保持 `useChat` 在 Provider 中：

```tsx title="app/workspace/page.tsx"
"use client"

import { useState } from "react"
import { DefaultChatTransport } from "ai"
import {
  AgentChatPanel,
  AgentChatProvider,
  AgentChatTrigger,
} from "@/components/agent-chat/agent-chat"

export default function Workspace() {
  const [transport] = useState(
    () => new DefaultChatTransport({ api: "/api/chat" }),
  )
  return (
    <AgentChatProvider transport={transport} defaultOpen>
      <main>你的工作区</main>
      <AgentChatPanel />
      <AgentChatTrigger />
    </AgentChatProvider>
  )
}
```

下面的服务端示例应放在支持服务端运行的应用或独立 API 服务中。**本站是纯静态导出，不部署这个 POST Route Handler。** 跨域后端可以给 `api` 配置完整 URL，并在后端配置 CORS。真实应用还需实现认证、输入校验与工具权限控制。

```tsx title="app/api/chat/route.ts（服务端应用示例）"
import {
  convertToModelMessages,
  stepCountIs,
  streamText,
  tool,
  type UIMessage,
} from "ai"
import { z } from "zod"

export async function POST(request: Request) {
  const { messages }: { messages: UIMessage[] } = await request.json()
  const result = streamText({
    // 使用你配置的模型或 AI Gateway；密钥仅在服务端配置。
    model: "openai/gpt-5-mini",
    messages: await convertToModelMessages(messages),
    abortSignal: request.signal,
    stopWhen: stepCountIs(3),
    tools: {
      readMetrics: tool({
        description: "读取授权范围内的监控摘要",
        inputSchema: z.object({ service: z.string() }),
        execute: async ({ service }) => {
          // 替换为带权限检查的真实只读查询。
          return { service, availability: "99.95%", demo: true }
        },
      }),
    },
  })
  return result.toUIMessageStreamResponse({
    originalMessages: messages,
    sendReasoning: true,
    sendSources: true,
  })
}
```

`sendReasoning` 仅在模型提供可公开的 reasoning 内容时才有数据；不支持时可以省略该部分。工具 `input-streaming / input-available` 映射为运行中，`output-available` 映射为完成，`output-error / output-denied` 映射为失败；停止时未结束的调用显示为已停止。模型或检索工具提供的 `source-url` 映射为来源链接，不会自动生成引用。服务端应只发送适合向用户公开的分析摘要与工具输出。

参考：[AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot)。

---

# 分屏登录页

来源：https://yiui.dev/blocks/auth-01/

<BlockViewer name="auth-01" />

`Auth01` 提炼自我的一个企业监控平台项目的登录页，在原有「左侧品牌面板 + 右侧表单」结构上，补上了完整的账号流程：

- **登录**：密码登录 / 验证码登录用方条分段控件切换；账号（用户名或邮箱）、密码显示切换、记住登录状态开关、忘记密码、第三方登录（GitHub、Google）、跳转注册。
- **注册**：姓名、邮箱、密码（实时强度条）、确认密码、同意服务条款。
- **找回密码**：邮箱提交后切换为「邮件已发送」的成功状态，邮件图标向外扩散波纹。
- 三个视图在同一个组件内切换，带 180ms 的淡入位移过渡，系统开启「减少动态效果」时只保留淡入。
- 大屏左半屏是品牌面板，窄屏隐藏面板并在表单上方显示 Logo 与名称。
- 品牌面板的颜色都来自主题变量，切换颜色主题和亮暗模式后自动跟随：亮色下是 `primary` 底配 `primary-foreground` 文字；暗色下 `primary` 会变成浅色，面板改用 `card` 深底，只叠一层低透明度的 `primary` 渐变染上主题色，文字回到 `foreground`。光斑、波纹、字符矩阵共用一个 `--panel-glow` 变量。预览里可以直接试。
- 输入框、提交按钮、第三方登录按钮、「获取验证码」、「返回登录」统一为 36px（按钮用 `size="lg"`，输入框 `h-9`），与方条分段控件的 `lg` 档对齐。

### 用到的本站组件

这个区块本身就是自研组件的一组真实用例，除表单输入、按钮、复选框（注册页的条款勾选）仍用 shadcn 原语外，其余都换成了本站组件：

| 位置 | 组件 | 说明 |
| --- | --- | --- |
| 品牌面板背景 | [`ripple`](/components/ripple) | 以面板中心向外扩散的同心波纹，替代原来的静态圆环 |
| 品牌面板四周 | [`glyph-field`](/components/glyph-field) | 淡淡的 `0 / 1` 字符矩阵，`fade="center"` 让中间留白给文字 |
| 品牌面板标题 | [`text-animate`](/components/text-animate) 的 `TextReveal` | 挂载时按词逐个显现，读屏仍读完整标题 |
| 登录方式切换 | [`segmented-control`](/components/segmented-control) | 密码登录 / 验证码登录，替代原来的 Tabs |
| 记住登录状态 | [`toggle-switch`](/components/toggle-switch) | 即时生效的设置项，替代原来的复选框 |
| 「邮件已发送」 | [`ripple`](/components/ripple) | 邮件图标为圆心，表达「已发出」 |

## 安装

<InstallCommand name="auth-01" />

会安装 shadcn 的 `button`、`input`、`label`、`checkbox`，本站的 `ripple`、`glyph-field`、`text-animate`、`segmented-control`、`toggle-switch`（及它们依赖的 `flow-diagram` 色调与背景），以及 npm 包 `motion`、`zod`、`lucide-react`。如果项目里已有同名文件，CLI 会询问是否覆盖。

## 用法

最简单的用法是直接渲染，不传任何属性。此时所有回调都退回「控制台打印 + 模拟 0.8 秒请求」的示例实现，方便先看效果：

```tsx title="app/login/page.tsx"
import { Auth01 } from "@/components/auth-01/auth-01"

export default function LoginPage() {
  return <Auth01 />
}
```

### 接入你的认证服务

回调都返回 `Promise`。**组件负责按钮的 loading 状态；失败时 `throw new Error("中文原因")`，错误信息会显示在表单上方。** 下面以 better-auth 为例，NextAuth / Auth.js、Supabase 等同理：

```tsx title="app/login/page.tsx"
"use client"

import { useRouter } from "next/navigation"
import { Auth01 } from "@/components/auth-01/auth-01"
import { authClient } from "@/lib/auth-client"

export default function LoginPage() {
  const router = useRouter()
  return (
    <Auth01
      brand={{ name: "你的产品", title: "一句话说清价值" }}
      onSignIn={async (values) => {
        if (values.method === "code") {
          // 验证码登录：values.phone / values.code
          throw new Error("暂未开通验证码登录")
        }
        const isEmail = values.account.includes("@")
        const { error } = isEmail
          ? await authClient.signIn.email({
              email: values.account,
              password: values.password,
              rememberMe: values.remember,
            })
          : await authClient.signIn.username({
              username: values.account,
              password: values.password,
              rememberMe: values.remember,
            })
        if (error) throw new Error(error.message ?? "登录失败")
        router.push("/")
      }}
      onSignUp={async ({ name, email, password }) => {
        const { error } = await authClient.signUp.email({ name, email, password })
        if (error) throw new Error(error.message ?? "注册失败")
        router.push("/")
      }}
      onForgotPassword={async (email) => {
        const { error } = await authClient.requestPasswordReset({ email })
        if (error) throw new Error(error.message ?? "发送失败")
      }}
      onSendCode={async (phone) => {
        await fetch("/api/sms/send", { method: "POST", body: JSON.stringify({ phone }) })
      }}
      onSocialSignIn={async (provider) => {
        await authClient.signIn.social({ provider })
      }}
    />
  )
}
```

使用 NextAuth 时，把 `onSignIn` 换成 `signIn("credentials", { redirect: false, ... })` 并在返回 `error` 时抛出即可；第三方登录对应 `signIn(provider)`。

### 换成英文

`labels` 也能覆盖校验提示（`validation*` 键）。提示里的 `{min}`、`{length}` 由 `schemas.ts` 的规则常量填入，**保留占位符**就会显示成对应的数字：

```tsx title="app/login/page.tsx"
import { Auth01, type Auth01Labels } from "@/components/auth-01/auth-01"

// 只覆盖需要改的键，没写的键仍是默认中文
const english: Partial<Auth01Labels> = {
  signInTitle: "Welcome back",
  signInDescription: "Sign in to continue",
  accountLabel: "Username or email",
  accountPlaceholder: "you@example.com",
  passwordLabel: "Password",
  passwordPlaceholder: "Enter your password",
  signInSubmit: "Sign in",
  signUpTitle: "Create an account",
  nameLabel: "Name",
  emailLabel: "Email",
  newPasswordPlaceholder: "At least 8 characters, letters and numbers",
  confirmPasswordLabel: "Confirm password",
  signUpSubmit: "Sign up",
  // 校验提示：{min}、{length} 一定要保留，否则数字不会被填入
  validationAccountRequired: "Enter your username or email",
  validationPasswordRequired: "Enter your password",
  validationEmailRequired: "Enter your email",
  validationEmailInvalid: "Enter a valid email address",
  validationPhoneInvalid: "Enter a valid {length}-digit phone number",
  validationCodeInvalid: "Enter the {length}-digit code",
  validationPasswordMin: "Use at least {min} characters",
  validationPasswordLetter: "Include a letter",
  validationPasswordDigit: "Include a number",
  validationNameMin: "Name needs at least {min} characters",
  validationConfirmRequired: "Re-enter your password",
  validationPasswordMismatch: "Passwords do not match",
  validationTermsRequired: "Please accept the terms to continue",
}

export default function LoginPage() {
  return <Auth01 labels={english} />
}
```

完整键与默认值见下方 [labels](#labels)。

## API

### Auth01

<TypeTable
  type={{
    brand: { type: "Partial<BrandConfig>", description: "品牌信息，逐项覆盖默认示例品牌，见下方 BrandConfig" },
    defaultView: { type: '"sign-in" | "sign-up" | "forgot-password"', description: "初始视图", default: '"sign-in"' },
    socialProviders: { type: '("github" | "google")[]', description: "启用的第三方登录，传 `[]` 隐藏该区域；默认两个都开", default: '["github", "google"]' },
    allowSignUp: { type: "boolean", description: "设为 `false` 隐藏「注册」入口", default: "true" },
    termsHref: { type: "string", description: "注册页中「服务条款」的链接" },
    privacyHref: { type: "string", description: "注册页中「隐私政策」的链接" },
    labels: { type: "Partial<Auth01Labels>", description: "覆盖默认文案，键与默认值见下方 [labels](#labels)" },
    onSignIn: { type: "(values: SignInValues) => Promise<void>", description: '`values` 是联合类型：`{ method: "password", account, password, remember }` 或 `{ method: "code", phone, code }`' },
    onSignUp: { type: "(values: { name; email; password }) => Promise<void>", description: "校验通过后才会调用；确认密码与条款勾选已在组件内校验" },
    onForgotPassword: { type: "(email: string) => Promise<void>", description: "成功返回后显示「邮件已发送」" },
    onSendCode: { type: "(phone: string) => Promise<void>", description: "成功返回后「获取验证码」按钮进入 60 秒倒计时" },
    onSocialSignIn: { type: "(provider) => Promise<void>", description: "点击第三方登录按钮时调用" },
    className: { type: "string", description: "追加到最外层容器" },
  }}
/>

### BrandConfig

<TypeTable
  type={{
    name: { type: "string", description: "产品名", required: true },
    logo: { type: "ReactNode", description: "Logo。建议用 `currentColor` 的 SVG，在品牌面板（反色）和表单上方（正常色）都能看清；也可以传 `<img>`", required: true },
    title: { type: "string", description: "品牌面板的大标题", required: true },
    description: { type: "string", description: "品牌面板的说明", required: true },
    features: { type: "{ icon: ReactNode; title; description }[]", description: "特性列表，建议 2–3 条，图标用 `lucide-react`", required: true },
    copyright: { type: "string", description: "右下角版权文字", required: true },
  }}
/>

### labels

所有键都在 `config.ts` 的 `DEFAULT_LABELS` 里，传 `labels={{ signInTitle: "Sign in" }}` 这样覆盖其中任意几项。含 `{name}`、`{email}`、`{seconds}`、`{level}` 的文案会在渲染时填入实际值；表格末尾的 `validation*` 键是表单校验提示，其中的 `{min}`、`{length}` 由 `schemas.ts` 的规则常量填入（例如改小密码最小长度后，提示里的数字会自动变）。

| 键 | 默认值 | 说明 |
|---|---|---|
| `brandPanelLabel` | `{name} 品牌介绍` | 品牌面板的 `aria-label` |
| `signInTitle` | `欢迎回来` | 登录视图标题（`h1`） |
| `signInDescription` | `输入账号信息即可登录` | 登录视图说明 |
| `signInMethodLabel` | `登录方式` | 登录方式分段控件的 `aria-label` |
| `signInPasswordTab` | `密码登录` | 密码登录选项 |
| `signInCodeTab` | `验证码登录` | 验证码登录选项 |
| `accountLabel` | `用户名或邮箱` | 账号输入框的标签 |
| `accountPlaceholder` | `请输入用户名或邮箱` | 账号输入框的占位文字 |
| `passwordLabel` | `密码` | 密码输入框的标签 |
| `passwordPlaceholder` | `请输入密码` | 密码输入框的占位文字 |
| `forgotPassword` | `忘记密码？` | 密码框右侧的链接按钮 |
| `remember` | `记住登录状态` | 记住登录状态开关的标签 |
| `signInSubmit` | `登录` | 登录按钮与其加载文案 |
| `signInPending` | `登录中…` | 登录按钮与其加载文案 |
| `phoneLabel` | `手机号` | 验证码登录的手机号输入框的标签 |
| `phonePlaceholder` | `请输入 11 位手机号` | 验证码登录的手机号输入框的占位文字 |
| `codeLabel` | `验证码` | 验证码输入框的标签 |
| `codePlaceholder` | `6 位数字验证码` | 验证码输入框的占位文字 |
| `sendCode` | `获取验证码` | 「获取验证码」按钮的三种状态 |
| `sendCodePending` | `发送中…` | 「获取验证码」按钮的三种状态 |
| `resendCode` | `{seconds}s 后重发` | 「获取验证码」按钮的三种状态 |
| `socialDivider` | `或` | 第三方登录上方的分隔文字 |
| `noAccount` | `还没有账号？` | 跳转注册 |
| `signUpLink` | `注册` | 跳转注册 |
| `signUpTitle` | `创建账号` | 注册视图标题（`h1`） |
| `signUpDescription` | `填写以下信息即可完成注册` | 注册视图说明 |
| `nameLabel` | `姓名` | 姓名输入框的标签 |
| `namePlaceholder` | `请输入姓名` | 姓名输入框的占位文字 |
| `emailLabel` | `邮箱` | 邮箱输入框（注册与找回密码共用） |
| `emailPlaceholder` | `name@example.com` | 邮箱输入框（注册与找回密码共用） |
| `newPasswordPlaceholder` | `至少 8 位，包含字母和数字` | 注册密码框占位文字 |
| `confirmPasswordLabel` | `确认密码` | 确认密码输入框的标签 |
| `confirmPasswordPlaceholder` | `再次输入密码` | 确认密码输入框的占位文字 |
| `termsPrefix` | `我已阅读并同意` | 条款勾选行的四段文字 |
| `termsOfService` | `服务条款` | 条款勾选行的四段文字 |
| `termsConjunction` | `和` | 条款勾选行的四段文字 |
| `privacyPolicy` | `隐私政策` | 条款勾选行的四段文字 |
| `signUpSubmit` | `注册` | 注册按钮与其加载文案 |
| `signUpPending` | `注册中…` | 注册按钮与其加载文案 |
| `haveAccount` | `已有账号？` | 跳转登录 |
| `signInLink` | `登录` | 跳转登录 |
| `forgotPasswordTitle` | `找回密码` | 找回密码视图标题（`h1`） |
| `forgotPasswordDescription` | `输入注册时使用的邮箱，我们会发送重置链接` | 找回密码视图说明 |
| `sendResetLink` | `发送重置链接` | 提交按钮与其加载文案 |
| `sendResetLinkPending` | `发送中…` | 提交按钮与其加载文案 |
| `backToSignIn` | `返回登录` | 返回登录按钮 |
| `emailSentTitle` | `邮件已发送` | 发送成功视图标题（`h1`） |
| `emailSentDescription` | `我们已向 {email} 发送了重置密码的链接，请查收邮件。没收到？请检查垃圾邮件箱。` | 发送成功视图说明，`{email}` 会加粗显示 |
| `showPassword` | `显示密码` | 密码显示切换按钮的 `aria-label` |
| `hidePassword` | `隐藏密码` | 密码显示切换按钮的 `aria-label` |
| `passwordStrength` | `强度：{level}` | 强度条右侧文字 |
| `passwordStrengthEmpty` | `强度：—` | 强度条右侧文字 |
| `strengthWeak` | `弱` | 四个强度等级 |
| `strengthFair` | `一般` | 四个强度等级 |
| `strengthGood` | `较强` | 四个强度等级 |
| `strengthStrong` | `强` | 四个强度等级 |
| `validationAccountRequired` | `请输入用户名或邮箱` | 密码登录：账号为空 |
| `validationPasswordRequired` | `请输入密码` | 密码登录：密码为空 |
| `validationEmailRequired` | `请输入邮箱` | 邮箱为空（注册、找回密码） |
| `validationEmailInvalid` | `请输入有效的邮箱地址` | 邮箱格式错误 |
| `validationPhoneInvalid` | `请输入有效的 {length} 位手机号` | 验证码登录：手机号格式错误，`{length}` 默认 `11` |
| `validationCodeInvalid` | `请输入 {length} 位数字验证码` | 验证码格式错误，`{length}` 默认 `6` |
| `validationPasswordMin` | `密码至少 {min} 位` | 密码太短，`{min}` 默认 `8` |
| `validationPasswordLetter` | `密码需要包含字母` | 密码缺少字母 |
| `validationPasswordDigit` | `密码需要包含数字` | 密码缺少数字 |
| `validationNameMin` | `姓名至少 {min} 个字符` | 姓名太短，`{min}` 默认 `2` |
| `validationConfirmRequired` | `请再次输入密码` | 确认密码为空 |
| `validationPasswordMismatch` | `两次输入的密码不一致` | 两次输入的密码不同 |
| `validationTermsRequired` | `请先阅读并同意服务条款` | 未勾选条款 |
| `requestFailed` | `操作失败，请稍后重试` | 回调抛出的错误没有 `message` 时的兜底提示 |

## 可访问性

- 每个视图只有一个 `h1`（由 `ViewHeading` 渲染），品牌面板是带 `aria-label` 的 `aside`，光斑、波纹与字符矩阵等装饰全部 `aria-hidden`；品牌标题的逐词动画只作用在隐藏层，读屏读到的是完整原文。
- 输入框与 `Label` 通过 `htmlFor` / `id` 关联；字段错误用 `aria-describedby` 关联到同一个输入框，出错时设置 `aria-invalid`；表单级错误是 `role="alert"`，出现时立即朗读。
- 密码显示切换按钮带 `aria-pressed` 和随状态变化的中文名称（显示密码 / 隐藏密码）。
- 登录方式是带 `aria-label` 的单选组（`segmented-control`），方向键切换；「记住登录状态」是 `role="switch"` 的开关；「或」分隔线是 `role="separator"`。
- 密码强度条是装饰（`aria-hidden`），文字结果用 `aria-live="polite"` 播报；强度不只靠颜色区分，同时有文字。
- 「邮件已发送」视图是 `role="status"`，读屏会读出提交结果。
- 提交中按钮禁用并显示「登录中…」，避免重复提交；所有图标按钮都有中文 `aria-label`。
- 视图切换动画遵循 `prefers-reduced-motion`，开启后只保留淡入；波纹、字符矩阵与标题显现在开启「减少动态效果」时显示静态画面，标题直接显示全文。

## 注意事项

### 文件结构

```text
app/login/page.tsx                       # 页面入口：把回调接到你的认证服务
components/auth-01/
├── auth-01.tsx                          # 主组件：分屏布局 + 视图切换
├── config.ts                            # ★ 全部用户可见文案 DEFAULT_LABELS
├── brand.tsx                            # 品牌配置类型与默认示例品牌
├── brand-panel.tsx                      # 左侧品牌面板（波纹 + 字符矩阵 + 标题显现）、窄屏顶部品牌
├── sign-in-form.tsx                     # 登录（分段控件切换密码 / 验证码）+ 第三方登录
├── sign-up-form.tsx                     # 注册
├── forgot-password-form.tsx             # 找回密码（成功态用波纹）
├── password-strength.tsx                # 密码强度条与评分
├── social-buttons.tsx                   # GitHub / Google 按钮
├── form-parts.tsx                       # 输入框、密码框、错误提示等共用件
├── schemas.ts                           # zod 校验规则工厂与规则常量，提示语取自 labels
└── use-auth-form.ts                     # 受控表单状态 + 校验 + 提交状态
```

- **校验规则与校验提示分开**：规则常量（`PASSWORD_MIN_LENGTH`、`NAME_MIN_LENGTH`、`CODE_LENGTH`、`PHONE_PATTERN` / `PHONE_LENGTH`）在 `schemas.ts`，提示文案是 `labels` 的 `validation*` 键；提示里的 `{min}`、`{length}` 由常量填入，改规则后文案里的数字自动更新。schema 由 `createSignInSchema(labels)` 这类工厂函数生成，组件里用 `useMemo` 缓存，`labels` 引用不变就不会重建。
- **前端校验不是安全边界**：手机号、密码策略只是体验层，服务端必须再校验一次。
- **静态导出**：组件是纯客户端组件，不使用 Server Actions 或 `cookies()`，可用于 `output: "export"`。

### 如何自定义

- **校验规则**：规则常量都在 `schemas.ts`。手机号默认是中国大陆 11 位规则，面向其他地区时替换 `PHONE_PATTERN` 并同步 `PHONE_LENGTH`；密码策略是 `PASSWORD_MIN_LENGTH` 与两条正则（必须含字母、必须含数字）；姓名最短长度是 `NAME_MIN_LENGTH`，验证码位数是 `CODE_LENGTH`。提示文案不用改，数字会跟着常量走；`newPasswordPlaceholder`（「至少 8 位，包含字母和数字」）是静态示例文案，改了最小长度记得一并改。
- **强度条算法**：`password-strength.tsx` 的 `getPasswordStrength`，按长度（8、12）与大小写、数字、符号计分，颜色从 `destructive` 过渡到 `primary`。
- **只要登录**：传 `allowSignUp={false}`，再传 `socialProviders={[]}` 隐藏第三方登录（省略时默认会显示 GitHub 和 Google）。
- **增减第三方平台**：在 `social-buttons.tsx` 的 `providers` 里补一项，并扩展 `SocialProvider` 类型。
- **改文案**：优先用 `labels`，校验提示也一样，见上方[换成英文](#换成英文)；整站换语言时也可以直接改 `config.ts` 的 `DEFAULT_LABELS`。
- **表单状态**：刻意只用受控状态 + zod，没有引入 react-hook-form。字段首次失焦时校验该字段，提交失败后改为输入时实时校验。

---

# 区块

来源：https://yiui.dev/blocks/



---

# 设置页

来源：https://yiui.dev/blocks/settings-01/

<BlockViewer name="settings-01" />

`Settings01` 是「方条控件」系列的落地样板：数值滑块、分段选择、开关、色调选择和控制面板拼在一起，就是一个能直接安装使用的设置页。

- **五个分区**：外观、通知、声音与触感、编辑器、隐私。宽屏是左侧导航，导航项右侧的小圆标显示该分区已修改的项数；窄屏（< 768px）导航变成顶部的分段选择。
- **外观**：主题模式（浅色 / 深色 / 跟随系统，带图标）、强调色、界面字号（可直接输入）、圆角、信息密度、减少动态效果。右上角的预览卡片随这些设置实时变化。强调色还会染到整页控件的选中态上。
- **通知**：总开关关闭时其余开关和免打扰时段一起禁用；免打扰是一个区间滑块，读数写成「22:00 – 07:00」。
- **声音与触感**：主音量滑块拖动时有刻度音效；按键音效关闭时音色选择禁用。
- **编辑器**：缩进宽度、行高、制表符显示，右侧的代码预览同步变化。
- **隐私**：资料可见范围、数据收集开关、历史保留天数（刻度吸附 30 / 90 / 180 天）。
- **已修改**：每个控件的 `modified` 由「当前值 ≠ 默认值」得出，改过的项标签变亮；每个分区的面板头部显示本分区已修改项数，并带「复制设置」和「恢复本分区默认值」两个按钮。
- **底部保存栏**：显示总的已修改项数与保存状态，右侧是「恢复默认」和「保存」。保存时按钮进入 loading，成功显示「已保存」，失败显示回调抛出的 `Error.message`。

## 安装

<InstallCommand name="settings-01" />

会安装 `app/settings/page.tsx` 页面和 `components/settings-01/` 下的组件，并带上它依赖的本站控件：数值滑块、分段选择、开关、色调选择、控制面板（连同 `flow-diagram` 提供的色调变量）。shadcn 依赖为 `button`，npm 依赖为 `motion`、`lucide-react`。

## 用法

最简单的用法是直接渲染，不传任何属性。此时设置值在组件内部维护，「保存」退回「控制台打印 + 模拟 0.8 秒请求」的示例实现，方便先看效果：

```tsx title="app/settings/page.tsx"
import { Settings01 } from "@/components/settings-01/settings-01"

export default function SettingsPage() {
  return <Settings01 />
}
```

### 接入保存

`onSave` 返回 `Promise`。**组件负责按钮的 loading 状态；失败时 `throw new Error("中文原因")`，原因会显示在保存栏上。** 已有的设置用 `defaultValue`（或受控的 `value`）传入，没传的项取默认值：

```tsx title="app/settings/page.tsx"
"use client"

import {
  Settings01,
  type Settings01Values,
} from "@/components/settings-01/settings-01"

export default function SettingsPage({
  saved,
}: {
  saved: Partial<Settings01Values>
}) {
  return (
    <Settings01
      defaultValue={saved}
      onSave={async (values) => {
        const response = await fetch("/api/settings", {
          method: "PUT",
          headers: { "content-type": "application/json" },
          body: JSON.stringify(values),
        })
        if (!response.ok) throw new Error("保存失败，请稍后重试")
      }}
    />
  )
}
```

### 受控用法与实时生效

`value` / `onValueChange` 让你把设置放进自己的状态里，例如切换主题时立刻生效，不必等点「保存」：

```tsx title="app/settings/page.tsx"
"use client"

import { useState } from "react"
import { useTheme } from "next-themes"
import {
  Settings01,
  type Settings01Values,
} from "@/components/settings-01/settings-01"
import { DEFAULT_VALUES } from "@/components/settings-01/config"

export default function SettingsPage() {
  const { setTheme } = useTheme()
  const [values, setValues] = useState<Settings01Values>(DEFAULT_VALUES)
  return (
    <Settings01
      value={values}
      onValueChange={(next) => {
        if (next.theme !== values.theme) setTheme(next.theme)
        setValues(next)
      }}
      onSave={async (next) => {
        await saveToServer(next)
      }}
    />
  )
}
```

### 自定义默认值

`defaults` 逐项覆盖出厂默认值。「已修改」「恢复默认」都以它为准，没有传 `defaultValue` 时它也是初始值：

```tsx
<Settings01 defaults={{ accent: "blue", fontSize: 15, indent: "4" }} />
```

### 换成英文

`labels` 覆盖任意文案，含 `{count}`、`{value}` 的占位符要保留：

```tsx
import { Settings01, type Settings01Labels } from "@/components/settings-01/settings-01"

const english: Partial<Settings01Labels> = {
  title: "Settings",
  sectionAppearance: "Appearance",
  navAppearance: "Look",
  save: "Save",
  resetAll: "Reset to defaults",
  modifiedCount: "{count} changed",
  readoutPx: "{value} px",
}

export default function SettingsPage() {
  return <Settings01 labels={english} />
}
```

## API

### Settings01

<TypeTable
  type={{
    value: { type: "Settings01Values", description: "受控的全部设置值，见下方 Settings01Values" },
    defaultValue: { type: "Partial<Settings01Values>", description: "非受控时的初始值，没写的项取 `defaults`" },
    defaults: { type: "Partial<Settings01Values>", description: "出厂默认值，逐项覆盖 `config.ts` 的 `DEFAULT_VALUES`；决定「已修改」的判断和「恢复默认」的目标" },
    onValueChange: { type: "(value: Settings01Values) => void", description: "任何一项变化时回调，参数是变化后的全部设置（受控与非受控都会触发）" },
    section: { type: "Settings01SectionId", description: "受控的当前分区" },
    defaultSection: { type: '"appearance" | "notifications" | "sound" | "editor" | "privacy"', description: "非受控时的初始分区", default: '"appearance"' },
    onSectionChange: { type: "(section: Settings01SectionId) => void", description: "切换分区时回调" },
    onSave: { type: "(values: Settings01Values) => Promise<void>", description: "点击「保存」时调用；组件管理 loading，抛出的 `Error.message` 显示在保存栏。未传时只在控制台打印并等待 0.8 秒" },
    labels: { type: "Partial<Settings01Labels>", description: "覆盖默认文案，键与默认值见下方 [labels](#labels)" },
    className: { type: "string", description: "追加到最外层容器" },
  }}
/>

### Settings01Values

`config.ts` 的 `SECTION_KEYS` 记录了每个分区管哪些键。

<TypeTable
  type={{
    theme: { type: '"light" | "dark" | "system"', description: "主题模式", default: '"system"' },
    accent: { type: "string", description: "强调色，tone-picker 的色调名（`primary`、`blue`……）或任意 CSS 颜色", default: '"primary"' },
    fontSize: { type: "number", description: "界面字号（px），12–20", default: "14" },
    radius: { type: "number", description: "圆角（px），0–20", default: "10" },
    density: { type: '"compact" | "comfortable" | "spacious"', description: "信息密度", default: '"comfortable"' },
    reduceMotion: { type: "boolean", description: "减少动态效果", default: "false" },
    notifications: { type: "boolean", description: "通知总开关，关闭后其余通知项与免打扰禁用", default: "true" },
    notifyMentions: { type: "boolean", description: "提及我时通知", default: "true" },
    notifyReplies: { type: "boolean", description: "评论回复时通知", default: "true" },
    notifyEmail: { type: "boolean", description: "每日邮件摘要", default: "false" },
    notifyUpdates: { type: "boolean", description: "产品动态", default: "false" },
    quietHours: { type: "[number, number]", description: "免打扰时段 [起点, 终点]（小时），范围 12–36：36 即次日 12:00，读数按 24 小时取模，所以 `[22, 31]` 读作「22:00 – 07:00」", default: "[22, 31]" },
    volume: { type: "number", description: "主音量，0–100", default: "60" },
    keySound: { type: "boolean", description: "按键音效", default: "false" },
    soundTheme: { type: '"soft" | "crisp" | "mechanical"', description: "按键音色，按键音效关闭时禁用", default: '"soft"' },
    haptics: { type: "boolean", description: "触感反馈", default: "true" },
    indent: { type: '"2" | "4" | "tab"', description: "编辑器缩进宽度", default: '"2"' },
    lineHeight: { type: "number", description: "编辑器行高，1.2–2，步长 0.1", default: "1.6" },
    showTabs: { type: "boolean", description: "显示制表符与缩进标记", default: "false" },
    visibility: { type: '"public" | "team" | "private"', description: "资料可见范围", default: '"team"' },
    analytics: { type: "boolean", description: "匿名使用统计", default: "true" },
    crashReports: { type: "boolean", description: "崩溃报告", default: "true" },
    retention: { type: "number", description: "历史记录保留天数，7–365", default: "90" },
  }}
/>

### labels

所有键都在 `config.ts` 的 `DEFAULT_LABELS` 里，传 `labels={{ save: "Save" }}` 这样覆盖其中任意几项。含 `{count}`、`{value}` 的文案会在渲染时填入实际值。

| 键 | 默认值 | 说明 |
|---|---|---|
| `title` / `description` | `设置` / `调整外观、通知、声音与编辑器的偏好` | 页面标题（`h1`）与说明 |
| `navLabel` | `设置分区` | 导航与顶部分段选择的 `aria-label` |
| `navSectionModified` | `已修改 {count} 项` | 导航项圆标的提示与读屏文字 |
| `sectionAppearance` 等 5 个 | `外观` / `通知` / `声音与触感` / `编辑器` / `隐私` | 分区标题（`h2`） |
| `navAppearance` 等 5 个 | `外观` / `通知` / `声音` / `编辑器` / `隐私` | 窄屏顶部分段选择里的短名 |
| `descriptionAppearance` 等 5 个 | 见 `config.ts` | 分区说明 |
| `panelModified` / `panelDefault` | `已修改 {count} 项` / `全部为默认值` | 面板头部的状态 |
| `copySection` / `copiedSection` / `resetSection` | `复制本分区设置` / `已复制` / `恢复本分区默认值` | 面板头部两个图标按钮的名称 |
| `group*` | 见 `config.ts` | 各面板里的分组小标题 |
| `theme`、`themeLight`、`themeDark`、`themeSystem` | `主题模式`、`浅色`、`深色`、`跟随系统` | 主题模式 |
| `accent`、`fontSize`、`radius`、`density`、`densityCompact`、`densityComfortable`、`densitySpacious`、`reduceMotion`、`reduceMotionHint` | 见 `config.ts` | 外观其余控件 |
| `readoutPx` / `readoutDays` | `{value} px` / `{value} 天` | 字号、圆角、保留天数的读数 |
| `preview*` | 见 `config.ts` | 外观预览卡片里的文字 |
| `notifications`、`notify*`、`quietHours` 及对应 `*Hint` | 见 `config.ts` | 通知控件与它们的补充说明 |
| `volume`、`keySound`、`soundTheme`、`sound*`、`haptics` 及对应 `*Hint` | 见 `config.ts` | 声音与触感控件 |
| `indent`、`indentTwo`、`indentFour`、`indentTab`、`lineHeight`、`showTabs`、`showTabsHint`、`editorPreviewTitle` | 见 `config.ts` | 编辑器控件与预览标题 |
| `visibility`、`visibility*`、`analytics`、`crashReports`、`retention` 及对应 `*Hint` | 见 `config.ts` | 隐私控件 |
| `footerLabel` | `保存设置` | 底部保存栏的 `aria-label` |
| `modifiedCount` / `unmodified` | `已修改 {count} 项` / `全部为默认值` | 保存栏左侧的总计 |
| `unsaved` / `upToDate` / `saving` / `saved` | `有未保存的更改` / `没有未保存的更改` / `保存中…` / `已保存` | 保存栏左侧第二行的保存状态 |
| `save` / `resetAll` | `保存` / `恢复默认` | 保存栏的两个按钮 |
| `saveFailed` | `保存失败，请稍后重试` | 回调抛出的错误没有 `message` 时的兜底提示 |

## 可访问性

- 页面只有一个 `h1`，每个分区是带 `aria-labelledby` 的 `section`，标题是 `h2`；控制面板里的分组是带标题的 `role="group"`。
- 宽屏导航是 `nav`，当前分区带 `aria-current="page"`；圆标除了数字还有读屏文字「已修改 N 项」。窄屏顶部的分段选择是单选组，有 `aria-label`，方向键切换。
- 所有控件沿用各自的语义：滑块是原生滑块（方向键、Home / End、PageUp / PageDown），区间滑块的两个手柄分别叫「起点」「终点」，读数同时作为 `aria-valuetext`；开关是 `role="switch"`；色调选择与分段选择是单选组。
- 改过的项不只靠颜色区分：标签变亮之外，面板头部、导航圆标和保存栏都有文字计数。
- 保存状态是 `role="status"`，保存失败是 `role="alert"`，会立即朗读；保存中按钮禁用并显示「保存中…」，避免重复提交。
- 预览卡片是纯展示，对读屏隐藏；图标按钮都有中文名称，焦点环可见。
- 视图切换动画遵循 `prefers-reduced-motion`，开启后只保留淡入；预览里的脉冲点在「减少动态效果」打开时也会静止。

## 注意事项

### 文件结构

```text
app/settings/page.tsx                    # 页面入口：把 onSave 接到你的后端
components/settings-01/
├── settings-01.tsx                      # 入口：状态、已修改计数、分区切换、底部保存栏
├── config.ts                            # ★ DEFAULT_LABELS 文案、DEFAULT_VALUES 默认值、分区与键的对应
├── types.ts                             # Settings01Values 等类型
├── utils.ts                             # 值比较、小时格式化、错误文案
├── section-layout.tsx                   # 分区外壳：标题、控制面板头部（复制 / 恢复）、右侧预览位
├── section-nav.tsx                      # 宽屏左侧导航 + 窄屏顶部分段选择
├── appearance-section.tsx               # 外观
├── notifications-section.tsx            # 通知
├── sound-section.tsx                    # 声音与触感
├── editor-section.tsx                   # 编辑器
├── privacy-section.tsx                  # 隐私
├── previews.tsx                         # 外观预览卡片、编辑器代码预览
└── use-save-action.ts                   # 保存的 loading / 成功 / 错误状态
```

- **已修改的口径**：「已修改」比的是当前值与默认值（`defaults`），「有未保存的更改」比的是当前值与上次保存（或首次载入）的值；两者独立。恢复默认后，如果和上次保存的值不同，「保存」仍然可点，用来把重置存下来。
- **免打扰时段**：区间滑块的两个手柄不能交叉，而免打扰通常跨午夜，所以滑块范围取 12:00 到次日 12:00（值域 12–36），读数对 24 取模。需要全天范围时改 `notifications-section.tsx` 里的 `QUIET_MIN` / `QUIET_MAX`。
- **预览里的深色**：深色靠在卡片上套用 `.dark` 变量实现，站点本身已是深色时，选「浅色」无法在卡片里反向还原，所以预览标题栏另外写出了当前模式。
- **强调色**：`accent` 同时传给所有控件的 `tone`，并作为 `--flow-tone` 设在最外层，导航选中标记、预览卡片都跟着变；`primary` 跟随当前颜色主题。
- **增删设置项**：在 `types.ts` 加键、`config.ts` 的 `DEFAULT_VALUES` 和 `SECTION_KEYS` 登记，再到对应分区文件里加控件即可，计数、复制和恢复默认会自动包含它。
- **静态导出**：组件是纯客户端组件，不使用 Server Actions 或 `cookies()`，可用于 `output: "export"`。

---

# 角度刻度尺

来源：https://yiui.dev/components/angle-dial/

<ComponentPreview name="angle-dial-demo" />

## 安装

<InstallCommand name="angle-dial" />

## 用法

```tsx title="components/straighten-dial.tsx"
import { useState } from "react"
import { AngleDial } from "@/components/ui/angle-dial/angle-dial"

export function StraightenDial() {
  const [angle, setAngle] = useState(0)

  return (
    <AngleDial
      label="拉直"
      min={-45}
      max={45}
      value={angle}
      onValueChange={setAngle}
    />
  )
}
```

`value` / `defaultValue` / `onValueChange` 与站内其他方条控件同一套约定：给 `value` 就是受控，不给就由组件自己管，`defaultValue` 只决定起点与复位目标。外框、圆角与高度跟数值滑块完全一致，同一个面板里并排摆不会错位。

### 拖动刻度，读正中指针

刻度尺里躺着的是一段转盘，固定在正中的竖线是读数指针。按住刻度往左拖，刻度跟着手走，指针就读到更大的角度——每移动 `pixelsPerDegree` 像素走一度，默认是 `3`；调大更细，调小更灵敏。刻度每 5° 一根短线、每 15° 一根长线，两端渐隐，像从窗口里露出的一段转盘。

右侧是格式化后的读数，以及一个跟着转的小表盘，扫一眼就知道现在偏向哪边。

### 键盘与复位

刻度尺自己可以聚焦，键盘操作与数值滑块一致：

| 按键                  | 变化                      |
| --------------------- | ------------------------- |
| `←` `↓`               | 减一个 `step`             |
| `→` `↑`               | 加一个 `step`             |
| `Shift` + 方向键      | 按 `largeStep`（默认 15） |
| `PageUp` / `PageDown` | 按 `largeStep`            |
| `Home` / `End`        | 到两端                    |

双击刻度尺回到 `defaultValue`；不传 `defaultValue` 时回到 0，0 不在范围内时取 `min`。拖动松手、每次键盘变更、双击复位之后都会触发 `onValueCommitted`，需要「松手才算一次」时用它。

### 首尾相接

`max - min` 正好是 360 时自动首尾相接：范围是一整圈，越过 `max` 会从 `min` 接着走，360° 与 0° 是同一个角度，所以读数显示成 `min`。首尾相接时按 `End` 会停在 `max - step`（即离一圈终点最近的那一档），不会停在和起点重合的位置。

给别的范围也可以手动打开：传 `wrap` 即可，`wrap={false}` 则关掉自动判断。

```tsx
<AngleDial label="朝向" min={0} max={360} defaultValue={90} />
```

### 高度、色调与「已改动」

`variant` 与 `size` 的组合高度和数值滑块同一张表：

| `variant` | `sm` | `default` | `lg` |
| --------- | ---- | --------- | ---- |
| `bar`     | 28px | 32px      | 36px |
| `compact` | 18px | 22px      | 24px |

`tone` 只给指针与小表盘上色，取 `--flow-tone`；不传时用前景色。`modified` 把标签与读数从次要色提到前景色，并在根元素上留一个 `data-modified`，通常写成 `modified={value !== defaultValue}`，让控制面板里改过的项一眼可辨。

```tsx
<AngleDial
  label="旋转"
  variant="compact"
  tone="amber"
  modified={rotation !== 0}
  value={rotation}
  onValueChange={setRotation}
/>
```

## 示例

### 罗盘方位

范围 0–360 正好一圈，`wrap` 自动打开：拖过 360° 会从 0° 接着走。罗盘指针与刻度尺右侧的小表盘同步转动，读数旁标出八方位名。`largeStep={45}` 让 `Shift` + 方向键一次跳一个方位。

<ComponentPreview name="angle-dial-compass-demo" />

### 渐变角度

色块的 `linear-gradient` 角度直接来自刻度，下面一行是这段 CSS 的简写。渐变色只用主题提供的 `--flow-*` 变量，亮暗与颜色主题切换时一起变。

<ComponentPreview name="angle-dial-gradient-demo" />

## API

### AngleDial

<PropsTable name="angle-dial" component="AngleDial" />

默认 `min={-180}`、`max={180}`、`step={1}`、`largeStep={15}`、`pixelsPerDegree={3}`、`variant="bar"`、`size="default"`；`wrap` 不传时按「范围是否正好 360°」自动决定，`formatValue` 默认是 `数值°`，`modified`、`disabled` 默认关闭，`tone` 不传时用前景色。除上表外，其余属性直接落在根元素 `<div>` 上。

### angleDialVariants

`cva` 生成的根元素样式函数，有 `size` 与 `variant` 两个变体。高度通过根元素的 `--angle-dial-height` 变量传给内部，自己写包装层时可以复用它保持同一套高度。

```ts
const angleDialVariants: (props?: {
  size?: AngleDialSize
  variant?: AngleDialVariant
}) => string
```

### 类型

```ts
type AngleDialSize = "sm" | "default" | "lg"

type AngleDialVariant = "bar" | "compact"

type AngleDialProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "children"
> & {
  value?: number
  defaultValue?: number
  onValueChange?: (value: number) => void
  onValueCommitted?: (value: number) => void
  min?: number
  max?: number
  step?: number
  largeStep?: number
  wrap?: boolean
  pixelsPerDegree?: number
  label?: React.ReactNode
  formatValue?: (value: number) => string
  variant?: AngleDialVariant
  size?: AngleDialSize
  tone?: FlowTone
  modified?: boolean
  disabled?: boolean
}
```

## data-slot

| 元素       | `data-slot`         |
| ---------- | ------------------- |
| 根元素     | `angle-dial`        |
| 左侧标签   | `angle-dial-label`  |
| 刻度尺     | `angle-dial-ruler`  |
| 刻度       | `angle-dial-ticks`  |
| 指针       | `angle-dial-needle` |
| 读数与表盘 | `angle-dial-value`  |
| 小表盘     | `angle-dial-glyph`  |

根元素始终带 `data-variant`（`bar` / `compact`）；拖动中带 `data-dragging`，`modified` 为真时带 `data-modified`，禁用时带 `data-disabled`。

## 可访问性

- 刻度尺是 `role="slider"`，带 `aria-valuemin` / `aria-valuemax` / `aria-valuenow` 与 `aria-valuetext`。`aria-valuetext` 用的就是 `formatValue` 的结果，所以把读数换成「东北」「+12°」这类写法后，读屏念的也是它。
- 名称优先取 `label`（`aria-labelledby`），没有 `label` 时用 `aria-label`，两者都没有就退回「角度」——同一个表单里有多个刻度尺时务必给名称。
- 刻度、指针、读数与表盘都是 `aria-hidden` 的装饰，读屏只念上面那几个值。
- 焦点环只在键盘聚焦时出现（`focus-visible`）。鼠标按下刻度尺不会留下焦点框，但焦点会落到刻度尺上，可以用方向键接着微调。
- `disabled` 时去掉 Tab 可达性（`tabIndex={-1}`）、指针交互与键盘响应，并降到半透明。
- 系统开启「减少动态效果」时指针不再在拖动中轻微放大。

## 注意事项

- 组件在服务端就输出完整结构（刻度按当前值平移、表盘指针带着 `rotate()`），不需要预水合脚本，禁用 JS 时也能看到当前值。
- `formatValue`、`defaultValue` 建议定义在组件外，避免每次渲染都换一个新函数或新对象。
- 拖动期间的读数变化会正常触发 React 渲染；一次拖动里读数会连续刷新，这是有意的。
- 用作表单字段时外面自己套 `input type="hidden"`，组件只提交到 `onValueChange` / `onValueCommitted`。
- 受控模式下记得同时处理 `onValueChange`，否则拖动后值会弹回。
- `tone` 的颜色变量由 `flow-diagram` 条目提供，安装时会一并拉取；手动安装需要自己补上 `--flow-*` 变量。

## 源码

<ComponentSource name="angle-dial" />

---

# 卡片堆叠

来源：https://yiui.dev/components/card-stack/

<ComponentPreview name="card-stack-demo" />

## 安装

<InstallCommand name="card-stack" />

## 用法

`CardStackItem` 直接作为 `CardStack` 子级，内容自由组合。`CardStackControls` 放在同一级，提供上一张、下一张、指示点与暂停按钮。也可以通过 `items` 传入 React 节点数组，子级里只保留控制器。

```tsx title="components/card-stack-example.tsx"
"use client"

import {
  CardStack,
  CardStackItem,
  CardStackControls,
} from "@/components/ui/card-stack/card-stack"

export function CardStackExample() {
  return (
    <CardStack label="精选作品" className="max-w-sm">
      <CardStackItem>
        <h3>个人组件库</h3>
        <p>从重复的界面里提炼原语。</p>
      </CardStackItem>
      <CardStackItem>
        <h3>开发者笔记</h3>
        <p>记录解决问题的过程。</p>
      </CardStackItem>
      <CardStackControls />
    </CardStack>
  )
}
```

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整模式、轮换间隔、层叠深度、偏移与缩放，并开关暂停；未改动的项显示示例自己的取值。调整时预览画框大小不变。

### 引言堆叠

大引号、正文与署名组成卡片，内容高度由所有卡片的最大高度撑开，切换时页面不会跳动。示例文案为虚构内容。

<ComponentPreview name="card-stack-quotes-demo" />

### 拖拽预览

`mode="drag"` 关闭定时轮换。拖动距离超过 80px 时顶卡飞出，并进入循环序列底部；未超过阈值则回弹。触屏保留纵向页面滚动。

<ComponentPreview name="card-stack-drag-demo" />

### 指标卡

卡片内部可直接组合 `stat-card` 的标题、数值和趋势原语。堆叠本身不依赖统计卡；该 registry 依赖供此示例组合使用。

<ComponentPreview name="card-stack-stats-demo" />

## API

### CardStack

<PropsTable name="card-stack" component="CardStack" />

| 属性                   | 默认值     | 说明                                             |
| ---------------------- | ---------- | ------------------------------------------------ |
| `mode`                 | `auto`     | `auto` 定时轮换；`drag` 手动拖动                 |
| `interval`             | `4000`     | 轮换间隔，毫秒，最小 1000                        |
| `depth`                | `3`        | 可见层数，限制在卡片数量以内                     |
| `offset`               | `12`       | 每层向下偏移的像素，最小 0                       |
| `scale`                | `0.04`     | 每层缩小的比例；累计缩小最多 20%                 |
| `index / defaultIndex` | `— / 0`    | 受控索引或非受控初始索引，按卡片数量循环归一化   |
| `onIndexChange`        | `—`        | 接收新的零起始索引；受控时由调用方更新 `index`   |
| `items`                | `—`        | React 节点数组，与直接子级卡片择一使用           |
| `label`                | `卡片堆叠` | 轮播区域的可访问名称                             |
| `labels`               | 中文       | 覆盖前后切换、暂停、继续、卡片编号和轮播角色文案 |

自动模式在悬停、焦点位于组件内、离开视口或页面隐藏时暂停，恢复后重新计时。暂停按钮可持续暂停轮换。若不放控制器，调用方应提供等价的暂停入口。

### CardStackItem

细边框、无阴影的卡片容器；支持原生 `div` 属性。仅顶卡可交互，其他卡片使用 `inert` 与 `aria-hidden`。

<PropsTable name="card-stack" component="CardStackItem" />

### CardStackControls

按钮统一使用 `icon-sm`（28px）。指示点是带 `aria-pressed` 的按钮；自动模式附带暂停控制，零张或单张卡片时前后切换按钮禁用。

<PropsTable name="card-stack" component="CardStackControls" />

### 调整 Context

`CardStackTuningContext` 接收 `CardStackTuning` 覆盖项；`onReport(report: CardStackReport)` 回报覆盖前的实际属性。 `stableFrame` 固定调整期间的画框，不改变图形比例。

## 可访问性

- 根容器可聚焦；左右方向键切换，控制器按钮也支持原生键盘操作。
- 卡片内的输入框、滑块等保留自己的方向键操作，不拦截内部内容的键盘事件。
- 自动轮换不持续播报；手动操作或暂停时，当前卡片编号通过礼貌播报区更新。
- 减少动态效果时取消层叠位移、缩放和飞出，以淡入切换；拖拽仍可完成切换。
- 自动轮换时建议始终保留 `CardStackControls`，便于用户主动暂停。

## 注意事项

- 调整面板通过 `CardStackTuningContext` 覆盖子树里的 `mode`、`interval`、`depth`、`offset`、`scale`、`paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。

- 演示使用固定数据，首屏不依赖随机数或当前时间，适用于静态导出。
- 卡片与控制器需直接放在根容器下；`items` 支持任意节点。动态列表请使用稳定的 React key。
- 拖拽时会暂时超出卡片边缘，请按场景在外部预留空间或设置裁切区域。
- 指标示例的统计格式与涨跌约定沿用 `stat-card`。

## 源码

<ComponentSource name="card-stack" />

---

# 图表卡片

来源：https://yiui.dev/components/chart-card/

<ComponentPreview name="chart-card-target-demo" />

## 安装

<InstallCommand name="chart-card" />

条目依赖 shadcn 的 `chart`（`recharts` 的封装），安装时会一并添加。

## 用法

`ChartCard` 是外壳，分 `Header` / `Content` / `Footer` 三个区域，区域之间用细线隔开；图表放在 `Content` 里。

```tsx title="app/traffic.tsx"
import {
  ChartCard,
  ChartCardContent,
  ChartCardDescription,
  ChartCardHeader,
  ChartCardTitle,
  ChartSeries,
} from "@/components/ui/chart-card/chart-card"

const data = [
  { day: "2026-02-01", docs: 6200, blog: 4800 },
  { day: "2026-02-02", docs: 6900, blog: 5100 },
  // …
]

export function Traffic() {
  return (
    <ChartCard>
      <ChartCardHeader>
        <div>
          <ChartCardTitle>站点流量</ChartCardTitle>
          <ChartCardDescription>每日页面访问量</ChartCardDescription>
        </div>
      </ChartCardHeader>
      <ChartCardContent>
        <ChartSeries
          data={data}
          xKey="day"
          series={[
            { key: "docs", label: "文档" },
            { key: "blog", label: "博客" },
          ]}
        />
      </ChartCardContent>
    </ChartCard>
  )
}
```

| 组件 | 用途 |
| --- | --- |
| `ChartCard` + `Header` / `Title` / `Description` / `Action` / `Content` / `Footer` | 卡片布局 |
| `ChartMetrics` + `ChartMetric` | 竖线隔开的指标行 |
| `ChartTable` | 图表下方的明细表，首列带与序列同色的竖条 |
| `ChartGauge` | 刻度式环形仪表 |
| `ChartSeries` | 折线 / 柱 / 面积，支持堆叠与正负对比 |
| `ChartRanking` | 横向排名条 + 图例格 |
| `ChartLegendList` / `ChartLegendGrid` | 行内图例、图例格 |

页面顶部的预览把几个部件拼在了一张卡片里：左边 `ChartGauge` 显示目标进度，右边 `ChartSeries` 画两条面积序列，头部的 `ChartMetrics` 用同色圆点与序列对应。

## 示例

### 刻度式环形仪表

`ChartGauge` 由一圈细刻度组成，按值依次点亮：点亮的刻度由淡到浓，最后一格最亮最长，像指针停在当前值上。`ticks` 控制刻度数，`arc` 控制总角度（默认 270° 下方留口，360 为整圈），`fade={false}` 关掉渐变，`children` 替换中央内容。

<ComponentPreview name="chart-card-gauge-demo" />

### 多序列折线与明细表

`ChartSeries` 默认画折线；序列多于一条时在上方显示图例。图表下方的 `ChartTable` 用 `columns` 和 `rows` 描述明细，行里的 `tone` 对应图表里的序列。

<ComponentPreview name="chart-card-demo" />

### 堆叠柱与指标行

`type="bar"` 加 `stacked` 得到堆叠柱；头部的 `ChartMetrics` 把几个关键指标并排摆在一起。

<ComponentPreview name="chart-card-stacked-demo" />

### 正负对比

`stacked="diverging"` 让正值向上、负值向下堆叠，适合新增与流失、收入与支出这类方向相反的数据：把流失记为负数，两组数据就落在零线两侧，提示框里仍显示各自的数值。

<ComponentPreview name="chart-card-diverging-demo" />

### 排名条

`ChartRanking` 用名次作纵轴，条末标出数值，旁边（窄屏在下方）是带名称的图例格。百分比数据传 `max={100}`，其他数据默认取最大值作满值。

<ComponentPreview name="chart-card-ranking-demo" />

### 配色与坐标轴

序列没有指定 `tone` 时按顺序取默认色板：蓝、琥珀、绿、紫、玫红、青。默认色板里没有主题强调色——强调色会落在其中某一种附近，切到对应的颜色主题时会和那条序列撞色；单条序列想跟随主题时显式写 `tone="primary"`。颜色全部来自主题变量，14 个颜色主题和亮暗模式下都能正确显示。`tone` 也可以是 `chart-1` … `chart-5`、`up` / `down`（涨跌色，随 `convention` 变化）或任意 CSS 颜色。

坐标轴字号 11px，网格只有水平虚线，颜色是线条网格的 `--edge`。日期轴用 `formatDay` 变成「2月14日」或「02/14」，星期轴是单字「一…日」，纵轴整条轴共用一个单位：按数据最大值选「万 / 亿」（`en` 为 K / M / B），所有刻度都换算成它，不会出现 `9000` 与 `1.2万` 混在一起；数据的最大值不到 1 万时刻度都是普通整数。

## API

### ChartCard

<PropsTable name="chart-card" component="ChartCard" />

### ChartMetric

<PropsTable name="chart-card" component="ChartMetric" />

### ChartTable

<PropsTable name="chart-card" component="ChartTable" />

### ChartGauge

<PropsTable name="chart-card" component="ChartGauge" />

### ChartSeries

<PropsTable name="chart-card" component="ChartSeries" />

### ChartRanking

<PropsTable name="chart-card" component="ChartRanking" />

### ChartLegendList

<PropsTable name="chart-card" component="ChartLegendList" />

### ChartLegendGrid

<PropsTable name="chart-card" component="ChartLegendGrid" />

`ChartCardHeader`、`ChartCardTitle`、`ChartCardDescription`、`ChartCardAction`、`ChartCardContent`、`ChartCardFooter`、`ChartMetrics` 是带样式的容器，属性同对应的原生元素。

## 可访问性

- 图表容器是 `role="img"`，名称来自 `label`；悬停提示框读取精确数值。需要让读屏用户拿到数据时，配一张 `ChartTable` 或在文字里写出关键数字。
- `ChartGauge` 是 `role="meter"`，带 `aria-valuenow` 和 `aria-valuemax`；中央的数字是真实文本。
- `ChartTable` 用语义化的 `<table>`，表头 `scope="col"`，窄屏横向滚动而不是挤压。
- 序列靠图例的名称区分，不只靠颜色。
- 开启「减少动态效果」后，recharts 的入场动画关闭，仪表的刻度不再依次淡入；仪表的刻度由服务端直接输出，淡入是纯 CSS，没有脚本也完整显示。

## 注意事项

- 图表由 `ResponsiveContainer` 撑满容器，服务端渲染时先按 320×200 占位，水合后量出真实尺寸；`ChartSeries` 的高度用 `className`（默认 `h-64`）控制。
- 纵轴宽度用 `width="auto"` 按刻度文字自适应，需要和别的图表对齐时给相同的 `yDomain` 与 `yTicks`。
- 涨跌配色约定见 [统计卡片](/components/stat-card#涨跌配色约定)；`ChartCard` 与 `ChartSeries` 也接受 `convention`。

## 源码

<ComponentSource name="chart-card" />

---

# 手写清单

来源：https://yiui.dev/components/checklist/

<ComponentPreview name="checklist-demo" />

## 安装

<InstallCommand name="checklist" />

## 用法

`Checklist` 提供尺寸、色调与自动播放，`ChecklistList` 放条目，`ChecklistItem` 是一条带复选框的任务。勾选时文字变淡，并被一道略有起伏的手写划线划掉。划线宽度量自文字本身，中文、英文、数字都能完整覆盖。

```tsx title="components/checklist-example.tsx"
import {
  Checklist,
  ChecklistItem,
  ChecklistList,
  ChecklistProgress,
} from "@/components/ui/checklist/checklist"

export function ChecklistExample() {
  return (
    <Checklist tone="rose">
      <ChecklistProgress total={3} />
      <ChecklistList>
        <ChecklistItem defaultChecked>写完设计稿</ChecklistItem>
        <ChecklistItem>补上暗色截图</ChecklistItem>
        <ChecklistItem>发布</ChecklistItem>
      </ChecklistList>
    </Checklist>
  )
}
```

`ChecklistItem` 同时支持受控与非受控：传 `checked` 与 `onCheckedChange` 由你管理状态，只传 `defaultChecked` 则组件自己管。`ChecklistItem` 要作为 `ChecklistList` 的直接子级（用 `map` 生成也可以），自动播放按子级顺序编号。页面顶部的预览给 `Checklist` 加了 `autoplay`，进入视口后会自己逐条划掉；每条用 `tone` 指定不同的划线色，用 `meta` 在行尾放耗时之类的辅助信息。

## 示例

### 交互式

非受控条目配合进度条，点击任意一条划掉或恢复，计数实时更新。划线与勾选后的复选框填充用 `tone` 换成蓝色；进度条的色调单独用 `ChecklistProgress` 的 `tone` 指定。

<ComponentPreview name="checklist-interactive-demo" />

### 紧凑款

`size="sm"` 缩小复选框与字号，适合侧栏和小卡片。划线与复选框换成玫红，像红笔批改。

<ComponentPreview name="checklist-compact-demo" />

## API

### Checklist

`autoplay` 让清单按顺序自动划掉，全部完成后停 `resetDelay` 毫秒再清空重来。播放期间条目只读；进入视口才开始，离屏、`paused`、减少动态效果时停在静态快照（划掉约六成）。

<PropsTable name="checklist" component="Checklist" />

### ChecklistList

渲染 `<ul>` 并给每个子级编号，同时把条目数告诉 `Checklist`。接受 `ul` 的全部属性。

<PropsTable name="checklist" component="ChecklistList" />

### ChecklistItem

<PropsTable name="checklist" component="ChecklistItem" />

### ChecklistProgress

「已完成 / 总数」加进度条，手动勾选和自动播放都会实时更新。总数默认等条目挂载后统计，传 `total` 则服务端输出时也能直接显示准确计数。

<PropsTable name="checklist" component="ChecklistProgress" />

## 可访问性

- 复选框使用 Base UI 的 Checkbox，整行是 `<label>`，点击文字也能切换；焦点环可见，空格键切换。
- 划线只是视觉装饰，对读屏隐藏；是否完成由复选框的选中状态传达，文字同时变淡，不只靠划线。
- 进度条带 `role="progressbar"` 与 `aria-valuenow`，`label` 可以改读屏名称。
- 自动播放的条目为只读状态；系统开启「减少动态效果」时不播放，划线直接显示结果。

## 注意事项

- 划线用 SVG 路径加 `pathLength` 做描绘动画，纯 CSS 过渡，不依赖脚本驱动每一帧。路径的起伏来自条目序号，服务端与浏览器生成同一条线，水合不会出现差异。
- 条目文字不换行（`whitespace-nowrap`），过长的文字请自行截断或缩短。
- 色调变量依赖 `flow-diagram` 条目，受控 / 非受控逻辑依赖 `use-controllable-state`，安装时都会一并提供。

## 源码

<ComponentSource name="checklist" />

---

# 代码文件堆叠

来源：https://yiui.dev/components/code-stack/

<ComponentPreview name="code-stack-demo" />

## 安装

<InstallCommand name="code-stack" />

## 用法

`CodeStack` 负责排列，`CodeFile` 提供文件窗口、行号、语法骨架与语言角标。卡片可单独使用，不需要客户端 JavaScript。

```tsx title="components/source-files.tsx"
import { CodeStack, CodeFile } from "@/components/ui/code-stack/code-stack"

export function SourceFiles() {
  return (
    <CodeStack spread="fan">
      <CodeFile lang="ts" name="index.ts" seed={1} />
      <CodeFile lang="json" name="registry.json" seed={2} active />
      <CodeFile lang="css" name="theme.css" seed={3} />
    </CodeStack>
  )
}
```

文件按传入顺序排列，`active` 卡片显示强调色边框并置于上层。建议将激活卡放在序列中间，保留文件名的可见空间。每个直接子节点算作一张卡片，避免用 Fragment 包裹多个文件。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整排列与显示上限，并开关悬停散开与激活高亮；未改动的项显示示例自己的取值。调整时预览画框大小不变。

### 级联

以水平与垂直错位代替旋转，适合配置文件与构建流程的展示。

<ComponentPreview name="code-stack-cascade-demo" />

### 网格

所有文件平铺，窄屏两列、宽屏四列。文件名和语言角标均可直接读取；卡片高度放不下全部骨架行时，从第一行开始显示，底部裁切。

<ComponentPreview name="code-stack-grid-demo" />

## API

### CodeStack

<PropsTable name="code-stack" component="CodeStack" />

`spread` 支持 `fan / cascade / grid`；`hoverSpread` 默认开启，对扇形与级联生效，网格维持平铺。`max` 默认 8，超出部分不会渲染；0 输出空容器。扇形和级联默认高度 20rem，可通过 `className` 调整。

### CodeFile

<PropsTable name="code-stack" component="CodeFile" />

`lang` 支持 `ts / tsx / js / json / css / md / py / go / rs / yaml`；其他值仍显示大写角标，颜色回落到主题强调色。`name` 默认 `file.<lang>`。`seed` 决定自动生成的八行骨架，同一个种子在服务端与客户端生成相同结果。

自定义 `lines` 时，每行含 `indent`（百分比，0–60）和 `tokens` 数组；每个片段含 `width`（百分比，0–100）和可选的 `tone`。空数组显示没有代码行的文件窗口。

```tsx
<CodeFile
  lang="json"
  name="registry.json"
  lines={[
    { tokens: [{ width: 18, tone: "muted" }] },
    {
      indent: 10,
      tokens: [
        { width: 24, tone: "primary" },
        { width: 32, tone: "green" },
      ],
    },
    { tokens: [{ width: 12, tone: "muted" }] },
  ]}
/>
```

### 调整 Context

`CodeStackTuningContext` 接收 `CodeStackTuning` 覆盖项；`onReport(report: CodeStackReport)` 回报覆盖前的实际属性。 `stableFrame` 固定调整期间的画框，不改变图形比例。

## 可访问性

- 文件名和语言角标是可读取的文本；三点、行号与骨架仅作装饰，读屏不会逐行朗读。
- 悬停散开只改变装饰布局，不隐藏必要信息，也不添加无意义的 Tab 焦点；内部自带控件获得焦点时同样散开。
- 系统开启减少动态效果时保留初始排列并关闭过渡；触摸设备保留初始排列。
- 卡片用于文件示意，不展示实际源码。如需逐一读取完整文件名，使用网格模式。

## 注意事项

- 调整面板通过 `CodeStackTuningContext` 覆盖子树里的 `spread`、`max`、`hoverSpread`、`active`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。

- 扇形与级联的卡片宽度随容器变化，默认最多显示八张，适用于组件封面与空状态插图。
- 全部颜色来自主题 token 和 `--flow-*`，后者由安装时带入的 `flow-diagram` 条目提供。
- CSS 随组件输出，静态导出与无 JavaScript 环境均可显示并响应悬停。

## 源码

<ComponentSource name="code-stack" />

---

# 控制面板

来源：https://yiui.dev/components/control-panel/

<ComponentPreview name="control-panel-demo" />

## 安装

<InstallCommand name="control-panel" />

## 用法

面板只负责摆放，不持有任何状态：值由你管理，`onValueChange` 里改你自己的 state，面板跟着重渲染。

```tsx title="components/card-panel.tsx"
import { useState } from "react"
import {
  ControlPanel,
  ControlPanelActions,
  ControlPanelCopy,
  ControlPanelGroup,
  ControlPanelHeader,
  ControlPanelReset,
  ControlPanelTitle,
  formatJsx,
} from "@/components/ui/control-panel/control-panel"
import { ValueSlider } from "@/components/ui/value-slider/value-slider"

const DEFAULTS = { radius: 12 }

export function CardPanel() {
  const [radius, setRadius] = useState(DEFAULTS.radius)

  return (
    <ControlPanel className="max-w-sm">
      <ControlPanelHeader>
        <ControlPanelTitle>卡片</ControlPanelTitle>
        <ControlPanelActions>
          <ControlPanelCopy
            code={() =>
              formatJsx("Card", radius === DEFAULTS.radius ? {} : { radius })
            }
          />
          <ControlPanelReset onClick={() => setRadius(DEFAULTS.radius)} />
        </ControlPanelActions>
      </ControlPanelHeader>
      <ControlPanelGroup>
        <ValueSlider
          label="圆角"
          min={0}
          max={32}
          value={radius}
          onValueChange={setRadius}
        />
      </ControlPanelGroup>
    </ControlPanel>
  )
}
```

### 三个部分

`ControlPanel` 是带细边框的竖向容器（`rounded-lg border border-edge bg-background`）。里面通常放两样东西：

- `ControlPanelHeader`：高 40px 的标题栏，底部一条分隔线。左侧放 `ControlPanelTitle`，右侧用 `ControlPanelActions` 收拢按钮——它有 `ms-auto`，自动推到末端。
- `ControlPanelGroup`：一组控件。`title` 是小标题，`columns` 决定宽屏下的列数，相邻分组之间由组件自己画一条上边框，不用手写 `<hr>`。

`ControlPanelCopy` 与 `ControlPanelReset` 都是 `icon-sm`（28px）的幽灵按钮，直接塞进 `ControlPanelActions` 即可。前者把 `code` 写进剪贴板，成功后图标换成对勾、`aria-live` 播报「已复制」，1.5 秒后复原；后者只是一个按钮，恢复逻辑由你的 `onClick` 决定。

`ControlPanelActions` 就是普通容器，可以往里放自己的按钮（文字按钮用 `size="sm"`，与图标按钮同一档高度）。

### 复制为代码

`formatJsx` 把组件名与一组属性写成 JSX 字符串，专为「复制当前参数」这一步准备：

```tsx
import { formatJsx } from "@/components/ui/control-panel/control-panel"

formatJsx("Card", { radius: 12, shadow: "soft" })
// <Card radius={12} shadow="soft" />

formatJsx("Card", { radius: 12 }, { width: 16 })
// <Card
//   radius={12}
// />
```

规则：

- `undefined` 与 `null` 的属性直接省略，所以只传「与默认值不同的项」就得到一句干净的标签；
- `true` 写成裸属性名（`<Card bordered />`），`false` 写成 `{false}`；
- 字符串优先用双引号，含双引号或换行时改成 `{"..."}`；数字最多保留四位小数（去掉浮点尾差）；
- 数组与对象用 `JSON.stringify`；
- 一行放得下（默认不超过 72 个字符）就写一行，否则一个属性一行；能放下的空属性列表输出自闭合标签。

`code` 也可以传函数，点击那一刻才求值——面板上的值变化很频繁，传函数能保证复制到的是最新值，也省掉每次渲染重新拼字符串。

## 示例

### 分组

三个 `ControlPanelGroup`，各自带 `title`，中间的分隔线由组件画。`columns={2}` 让两个窄控件并排；只放一个控件时用 `sm:col-span-2` 跨满整行。文件里的 `SegmentedControl`、`ToggleSwitch`、`ValueSlider` 都是同一套方条的默认 `bar` 档（32px），排在一起高度一致，也足够好点。

<ComponentPreview name="control-panel-groups-demo" />

### 标题栏操作

`ControlPanelActions` 里除了复制与恢复，还能放自己的按钮：这里是一个「应用」文字按钮，面板改的是草稿，按下才写进左边的预览，没改动时禁用。面板下面把 `formatJsx` 的输出直接摊开，属性多的时候会按 `width` 自动换行。

<ComponentPreview name="control-panel-actions-demo" />

## API

### ControlPanel

<PropsTable name="control-panel" component="ControlPanel" />

### ControlPanelHeader

<PropsTable name="control-panel" component="ControlPanelHeader" />

### ControlPanelTitle

`<span>`，默认 `text-xs` 的次要色文字，过长时省略。需要标题语义时在外层自己加 `<h2>`，或给 `ControlPanel` 加 `aria-label`。

<PropsTable name="control-panel" component="ControlPanelTitle" />

### ControlPanelActions

<PropsTable name="control-panel" component="ControlPanelActions" />

### ControlPanelGroup

<PropsTable name="control-panel" component="ControlPanelGroup" />

`columns` 只在 640px 以上生效，窄屏一律单列；组内的子元素是网格项，用 `sm:col-span-2` / `sm:col-span-3` 跨列。子级容器需要 `min-w-0`，否则里面的 `truncate` 撑不开。

### ControlPanelCopy

<PropsTable name="control-panel" component="ControlPanelCopy" />

### ControlPanelReset

<PropsTable name="control-panel" component="ControlPanelReset" />

### formatJsx

```ts
function formatJsx(
  component: string,
  props: Record<string, unknown>,
  options?: { width?: number; children?: string },
): string
```

`width` 默认 `72`。传 `children` 时输出带子内容的完整标签（内容缩进两格），不传时是自闭合标签。

## 类型

```ts
type ControlPanelGroupProps = React.ComponentProps<"div"> & {
  title?: React.ReactNode
  /** 宽屏下的列数，窄屏一律单列
   *  @default 1 */
  columns?: 1 | 2 | 3
}

type ControlPanelCopyProps = Omit<
  React.ComponentProps<"button">,
  "onClick" | "children"
> & {
  /** 要复制的文本；传函数时在点击那一刻才求值 */
  code: string | (() => string)
  /** 按钮的可访问名称
   *  @default "复制代码" */
  label?: string
  /** 复制成功后的提示，读屏会朗读
   *  @default "已复制" */
  copiedLabel?: string
}

type ControlPanelResetProps = React.ComponentProps<"button"> & {
  /** 按钮的可访问名称
   *  @default "恢复默认" */
  label?: string
}

type FormatJsxOptions = {
  /** 单行的最大宽度
   *  @default 72 */
  width?: number
  /** 写在标签里的子内容；不传时输出自闭合标签 */
  children?: string
}
```

## data-slot

| 元素         | `data-slot`                 |
| ------------ | --------------------------- |
| 根元素       | `control-panel`             |
| 标题栏       | `control-panel-header`      |
| 标题         | `control-panel-title`       |
| 标题栏操作区 | `control-panel-actions`     |
| 分组         | `control-panel-group`       |
| 分组小标题   | `control-panel-group-title` |
| 分组网格     | `control-panel-grid`        |
| 复制按钮     | `control-panel-copy`        |
| 恢复按钮     | `control-panel-reset`       |

复制按钮在复制成功后的 1.5 秒里带 `data-copied`，可以据此加样式。

## 可访问性

- `ControlPanelTitle` 是 `<span>`：它只是视觉上的标题，不进文档大纲。需要让读屏知道这块面板是什么，给 `ControlPanel` 传 `aria-label` 或 `aria-labelledby`。
- `ControlPanelGroup` 渲染 `role="group"`，有小标题时用 `aria-labelledby` 关联到标题，读屏在组内切换时会念出组名。
- `ControlPanelCopy` 与 `ControlPanelReset` 是纯图标按钮，必须有名称：`label` 同时写进 `aria-label` 与 `title`（悬停提示）。
- 复制结果放在 `aria-live="polite"` 的 `sr-only` 元素里播报，视觉上只有图标变化。
- 两个按钮都是 `icon-sm`（28px），与 `ControlPanelActions` 里自己加的文字按钮保持同一档高度。

## 注意事项

- 面板不持有状态，也不提供 `onReset`。恢复默认由 `ControlPanelReset` 的 `onClick` 交回给你，因为默认值只有你知道。
- `navigator.clipboard` 只在安全上下文（https 或 localhost）可用，不可用时复制静默失败，不弹错、不改图标。需要兼容时自己判断 `navigator.clipboard` 再决定是否渲染复制按钮。
- 复制按钮不依赖 `Button` 组件，只用它的 `buttonVariants`；安装本条目时会一并拉取 `button`。
- 相邻分组之间的分隔线由 `[[data-slot=control-panel-group]+&]` 这条相邻选择器画出。自己往面板里插别的元素时，分隔线不会出现在那个元素与分组之间。
- 面板本身没有内边距，分组自己带 `p-3`。把面板嵌进别的卡片时，用 `className="rounded-none border-0"` 去掉自身的边框与圆角。

## 源码

<ComponentSource name="control-panel" />

---

# 流程动画图示

来源：https://yiui.dev/components/flow-diagram/

<ComponentPreview name="flow-diagram-showcase-demo" />

上图是一条 AI 应用的全链路：Web、App、CLI 三个入口错开发出请求，经网关进入 Agent；Agent 并行调度知识库、工具与大模型，三路耗时各异；结果汇总后沿原路送回每个入口。入口蓝、Agent 紫、三类能力各一种颜色、返回的结果绿，用到了图标节点、点亮、加载圈与状态点、常驻连线的流动纹理和方格底纹。

提炼自本站首页「我在做什么」里的三幅小插画。它不是一个“传数据就出图”的图表组件，而是一组 SVG 原语：你按设计坐标摆节点、连线、写标签，再给每一步指定出现的时刻，整张图就会按这条时间轴循环播放。

## 安装

<InstallCommand name="flow-diagram" />

## 用法

一张图由 `FlowDiagram` 外框和里面的原语组成。所有坐标都落在 `width × height` 的设计画布上，显示时整体等比缩小，所以 `FlowDiagram` 的宽度交给 `className` 控制即可。

```tsx title="app/pipeline.tsx"
import {
  FlowBeam,
  FlowDiagram,
  FlowNode,
  flowArrival,
  flowRoute,
} from "@/components/ui/flow-diagram/flow-diagram"

// 路径在组件外创建：长度要提前算出，光点的到达时刻靠它换算
const TO_PROCESS = flowRoute([[80, 50], [130, 50]])
const PROCESS_AT = flowArrival(0.5, TO_PROCESS)

export function Pipeline() {
  return (
    <FlowDiagram width={320} height={100} duration={4.4} exit={3.6} rest={3.4} className="w-full max-w-md">
      <FlowBeam route={TO_PROCESS} at={0.5} />
      <FlowNode x={50} y={50} width={60} litAt={0.2} label="输入" />
      <FlowNode x={160} y={50} width={60} litAt={PROCESS_AT} label="处理" />
    </FlowDiagram>
  )
}
```

最小的例子渲染出来是下面这样，三个节点依次点亮：

<ComponentPreview name="flow-diagram-demo" />

约定很少：

- **节点是容器。** `FlowNode` 画边框和点亮效果；简单的“图标 + 文字”直接用 `icon`、`label`、`description`，它们会整体居中。复杂内容（加载圈、状态点、进度条……）作为子元素按绝对坐标摆放，通常用 `FlowLabel` 或 lucide 图标（SVG 里直接给 `x`、`y`、`width`、`height` 即可）。
- **点亮时刻来自光点。** 光点出发的时刻 `at` 加上路径长度除以速度，就是它抵达的时刻，`flowArrival(at, route)` 帮你算好，直接传给目标节点的 `litAt`。
- **连线默认跟着光点一路长出来。** `FlowBeam` 的底线从起点生长到终点，光点走到哪线画到哪，到达时节点点亮；常驻的数据流还可以再加 `flow`，详见「连线动态」。
- **颜色来自主题变量。** 默认点亮用 `primary`，其他色调用 `tone` 指定，亮暗模式和颜色主题切换后自动跟随，详见「色调」。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整速度、默认色调与底纹，并开关底纹渐隐、循环与暂停；未改动的项显示示例自己的取值。色调只改默认色调，节点和光束自己指定的 `tone` 不受影响；关闭「循环」后只播一遍并停在静帧，再打开即从头重播。调整时外框与设计画布大小不变。

下面每个案例都是完整的源码，点「代码」标签可以看到写法。

### 全栈开发

需求分叉成前端和后端两条分支，汇合后敲出 `pnpm build`，再流向代码和上线。用到了分叉 / 汇合点 `FlowDiamond` 和逐字输入 `FlowTypedText`。前端蓝、后端紫、构建与代码琥珀、上线绿，光点和连线跟随各自分支的色调，节点带 lucide 图标。

<ComponentPreview name="flow-diagram-fullstack-demo" />

### AI Agent

文档与工具两路来源汇入输入框，逐字提问后进入“思考”，再依次给出答案条目。示例里的“星花变加载环”是用 `useFlowClock` 自己写的动画元素。文档蓝、工具琥珀、提问紫、结果绿，答案条目的图标和标签沿用各自来源的颜色。

<ComponentPreview name="flow-diagram-agent-demo" />

### 大模型部署

模型汇入推理引擎，再分发到 API、Chat、Agent 三个出口。同一条线上有两轮请求先后流过，第二轮用 `base={false}` 只画光点，避免底线叠粗。推理引擎到三个出口的线是常驻连接，画好后用 `flow` 让虚线持续向前流动。两个模型各用一种冷色，节点图标取自 `simple-icons` 的品牌图标（示例里包成 `FlowIcon`），推理引擎是琥珀色，就绪的出口变绿。

<ComponentPreview name="flow-diagram-deploy-demo" />

### RAG 检索增强

上排是入库：文档切片、嵌入、写入向量库；下排是问答：问题经检索拿到 top-3 片段，交给 LLM 生成，最后逐字打出回答。两条竖线分别负责“查询进入”和“结果取出”，不会重叠。

<ComponentPreview name="flow-diagram-rag-demo" />

### CI/CD 流水线

push 之后 lint 与 test 并行，耗时不同；先跑完的先打勾，汇合点要等最慢的那个。build 完成后部署上线，状态点带涟漪。琥珀色表示进行中、绿色表示通过：加载圈是琥珀色，对勾和通过之后的光点、部署节点是绿色。对勾是自己写的 lucide 图标，用 `flowToneStyle("green")` 给它设置色调。

<ComponentPreview name="flow-diagram-cicd-demo" />

### 登录鉴权

第一次密码错误，Auth 返回 401，红色光点沿一条环路绕回用户；重试通过后签发 JWT，带着 Bearer 访问受保护资源。`FlowBeam` 的 `tone="destructive"` 用来标出失败分支，这条环路的底线也会淡淡染成红色。

<ComponentPreview name="flow-diagram-auth-demo" />

### 微服务请求链路

网关扇出到三个服务并行处理，光点按路径长度反推出发时刻，所以同时到达；各服务按自己的耗时返回，耗时标签随返回的光点出现，汇合点等最慢的那个，最后得到总耗时。每个服务一种颜色（`tone`），扇出的光点、节点和返回的光点都用它，节点里的加载圈和状态点自动继承节点的颜色。

<ComponentPreview name="flow-diagram-microservice-demo" />

### 数据管道 ETL

竖向布局：三个数据源汇入清洗，进度条走完后写入数据仓库，再在看板上依次长出柱状图。每个数据源一种颜色，用 `icon` + `label` 一行写完节点；汇入清洗的三条线带 `flow`，表示数据源一直在接入。进度条和柱子是用 `useFlowClock` + `useTransform` 写的自定义元素，颜色用 `fill-(--flow-tone)` 取所在节点的色调。

<ComponentPreview name="flow-diagram-etl-demo" />

### MCP 工具调用

请求与结果走同一条线：先 `tools/list` 向三个服务器发现能力，再 `tools/call` 调用数据库，结果沿原路返回。返回路径只是把端点倒过来，用 `base={false}` 复用已经画好的线。

<ComponentPreview name="flow-diagram-mcp-demo" />

### 多模型路由

请求先经过路由器，再按任务分流到不同的模型：每个模型一种颜色，请求的光点、路由器到模型的连线和模型节点都用它。入口的线用一条 `FlowEdge` 画一次，三个请求的光点都用 `base={false}` 走这条线。模型节点用 `label` + `description` 写两行文字，加载圈和状态点放在节点里，颜色自动继承。

<ComponentPreview name="flow-diagram-router-demo" />

### 品牌色

在 `FlowDiagram` 上设一次 `tone`，里面没有单独指定色调的节点、光点、加载圈、状态点都继承它。`tone` 不限于内置名，任何 CSS 颜色都可以，这个例子用主题变量混出一个颜色；换成你自己的品牌色直接写 `tone="#ff6a00"` 或 `tone="oklch(0.7 0.2 40)"` 即可。

<ComponentPreview name="flow-diagram-brand-demo" />

## 时间轴

一张图只有一个时钟：从 `0` 走到 `duration` 秒，到头回到 `0` 重新开始。所有元素都是这个时间的函数，没有各自的定时器，所以不同元素之间不会错位。

<TypeTable
  type={{
    at: { type: "number", description: "元素出现 / 光点出发的时刻（秒），各原语的叫法略有不同：`FlowBeam` 的 `at`、`FlowNode` 的 `litAt`" },
    exit: { type: "number", description: "这一刻起所有元素一起淡出，到 `duration` 时完全消失，下一轮从空白重新开始", default: "duration - 0.8" },
    rest: { type: "number", description: "静帧时刻：首帧、服务端渲染和“减少动态效果”下显示的画面", default: "exit - 0.2" },
    duration: { type: "number", description: "一轮循环的总时长（秒）", default: "8" },
  }}
/>

三者的关系是 `最后一个元素出现 < rest < exit < duration`。

- **`rest` 要选在“画面完整”的一刻**：所有节点都已点亮、没有光点在飞。减少动态效果时图示会永远停在这一帧，所以它就是图示的“封面”。
- **`exit` 和 `duration` 之间留出淡出的时间**，默认 0.8 秒。
- **时刻不用手写死。** 光点到达时刻用 `flowArrival(at, route)` 推算，下一步从上一步的时刻加一点间隔算出来；示例里的 `REST`、`EXIT`、`DURATION` 都是这样级联得到的，改一个起点，后面自动顺延。

### 播放与暂停

- 进入视口（可见面积达到 40%）才开始走，离开视口立即暂停，不占 CPU。
- 初始时钟停在 `rest`，所以服务端渲染的静态 HTML、首帧水合结果、减少动态效果下的画面是同一帧，不会闪一下，也没有水合不一致。
- 切回标签页后时钟从原地继续，不会一下子跳过一大段。
- 开启系统的“减少动态效果”时不播放，也不显示光点，画面固定在 `rest`，连线都是完整的（带 `flow` 的线停在一帧虚线纹理上）。

循环、触发时机、暂停和速度都可以配置，见下面的「播放控制」。

### 自定义动画元素

`useFlowClock()` 返回 `{ time, duration, exit }`，`time` 是 motion 的 `MotionValue<number>`。用 `useTransform(time, 输入区间, 输出区间)` 就能把任何属性绑到时间轴上：

```tsx
function Progress() {
  const { time, exit, duration } = useFlowClock()
  const scaleX = useTransform(time, [2, 3.5], [0, 1])
  const opacity = useTransform(time, [exit, duration], [1, 0])
  return (
    <motion.g style={{ opacity }}>
      <motion.rect
        x={80} y={92} width={100} height={3}
        className="fill-primary"
        style={{ scaleX, transformBox: "fill-box", transformOrigin: "left" }}
      />
    </motion.g>
  )
}
```

别忘了在 `exit` 到 `duration` 之间把元素淡出，否则它会在下一轮开头突然消失。需要在渲染里读取时间做判断时，请像 `FlowTypedText` 那样用 `useMotionValueEvent`，不要在渲染期间调用 `Date.now()`，那会让服务端和客户端的结果对不上。

## 色调

`tone` 决定“亮起来是什么颜色”。`FlowNode`、`FlowDiamond` 点亮后的描边与淡底色、`FlowBeam` 的光点与流动纹理、`FlowEdge`、`FlowSpinner`、`FlowStatusDot`、`FlowTypedText` 的光标，以及可选的 `FlowLabel` 文字，都接受同一个 `tone`：

```tsx
<FlowBeam route={TO_API} at={1} tone="blue" />
<FlowNode x={160} y={50} width={72} tone="green" litAt={1.4} label="API" />
<FlowLabel x={160} y={80} tone="muted">200 OK</FlowLabel>
```

<ComponentPreview name="flow-diagram-tones-demo" />

### 内置色调

| 名称 | 取值 | 说明 |
| --- | --- | --- |
| `primary` | `var(--primary)` | 默认。随颜色主题变化 |
| `foreground` | `var(--foreground)` | 最醒目的中性色 |
| `muted` | `var(--muted-foreground)` | 弱化的中性色 |
| `destructive` | `var(--destructive)` | 失败、拒绝 |
| `blue` `green` `amber` `rose` `violet` `cyan` | `var(--flow-blue)` 等 | 多彩色调，不随颜色主题变化 |

多彩色调来自六个 CSS 变量，由 registry 条目的 `cssVars` 提供亮 / 暗两套 oklch 值，`shadcn add` 时会写进你的全局样式（本站已经在 `globals.css` 里同名定义）：

| 变量 | 亮色 | 暗色 |
| --- | --- | --- |
| `--flow-blue` | `oklch(0.56 0.2 258)` | `oklch(0.72 0.15 255)` |
| `--flow-green` | `oklch(0.62 0.16 150)` | `oklch(0.77 0.17 152)` |
| `--flow-amber` | `oklch(0.7 0.16 70)` | `oklch(0.82 0.15 82)` |
| `--flow-rose` | `oklch(0.62 0.21 5)` | `oklch(0.74 0.16 8)` |
| `--flow-violet` | `oklch(0.56 0.22 292)` | `oklch(0.74 0.15 295)` |
| `--flow-cyan` | `oklch(0.66 0.12 215)` | `oklch(0.82 0.11 208)` |

想换成品牌色，在全局样式里覆盖这些变量即可，所有用到它的图示一起变：

```css title="app/globals.css"
:root {
  --flow-blue: oklch(0.6 0.2 250);
}
.dark {
  --flow-blue: oklch(0.75 0.14 250);
}
```

### 任意颜色

`tone` 也接受任意 CSS 颜色，不在内置名里的字符串都按颜色处理（所以内置名拼错了也不会报错，只是颜色失效）：

```tsx
<FlowBeam route={TO_API} at={1} tone="#ff6a00" />
<FlowNode x={160} y={50} width={72} tone="oklch(0.7 0.2 150)" litAt={1.4} label="API" />
<FlowNode x={260} y={50} width={72} tone="var(--brand)" litAt={1.8} label="CDN" />
```

### 继承

所有原语只读一个 CSS 变量 `--flow-tone`，它沿 DOM 往下继承，所以不用在每个元素上重复写：

- `FlowDiagram` 的 `tone` 是整张图的默认色调（默认 `primary`）；
- `FlowNode` 指定了 `tone` 后，节点里没有单独指定色调的加载圈、状态点、光标都跟着变，图标也会染成这个颜色；
- 元素自己的 `tone` 优先。

自己写的 SVG 元素也可以用：`flowToneStyle("green")` 返回 `{ "--flow-tone": ... }`，放到 `style` 上，里面用 `fill-(--flow-tone)`、`stroke-(--flow-tone)/40`、`text-(--flow-tone)` 取色。

### 连线的颜色

连线默认是中性的前景色。给 `FlowBeam` 或 `FlowEdge` **明确指定** `tone` 后，生长的底线、虚线也会淡淡染上这个颜色（30% 不透明度）；继承自 `FlowDiagram` 的默认色调不会染线。

## 背景

`FlowDiagram` 的 `background` 选择外框的底纹，默认是向四周淡出的点阵：

<ComponentPreview name="flow-diagram-background-demo" />

```tsx
<FlowDiagram background="grid" />         {/* 方格 */}
<FlowDiagram background="none" />         {/* 不要底纹 */}
<FlowDiagram background="dots" fade={false} /> {/* 点阵铺满，不淡出 */}
<FlowDiagram background={<MyPattern />} />      {/* 自己的底纹元素 */}
<FlowDiagram background="none" backgroundClassName="bg-muted/40" />
```

- 内置底纹：`dots` 点阵、`grid` 方格、`lines` 横线、`hatch` 斜纹、`none` 无。点阵与斜纹用 `grid-layout` 提供的 `bg-dots`、`bg-hatch`，方格与横线直接用线条颜色 `--edge` 画渐变，所以都不需要额外的工具类，安装 `grid-layout` 就够了。
- `fade` 控制底纹是否向四周淡出（默认淡出），让图示像摆在图纸上；贴着边框铺满时设为 `false`。
- 传一个元素给 `background`，它会被放进铺满外框的绝对定位层（带 `pointer-events-none`），受 `fade` 影响；`backgroundClassName` 追加到这一层上，调透明度、换颜色，或者配合 `background="none"` 写一个纯 CSS 的底纹。
- 底纹颜色用的是线条颜色 `--edge`，随亮暗模式和颜色主题变化。

## 播放控制

<ComponentPreview name="flow-diagram-playback-demo" />

```tsx
<FlowDiagram loop={false} />                  {/* 只播一遍，停在 rest */}
<FlowDiagram trigger="always" />              {/* 不管是否在视口里都播 */}
<FlowDiagram paused={paused} speed={1.5} />   {/* 外部控制暂停与速度 */}
```

- `loop`（默认 `true`）：设为 `false` 时从头播一遍，走到 `rest` 就停在那一帧，不再淡出重来。因为首帧是 `rest` 静帧，所以单次播放开始时会从完整画面跳回起点再播；想重播，给 `FlowDiagram` 换一个 `key`。
- `trigger`（默认 `"in-view"`）：`in-view` 进入视口才播、离开暂停；`always` 只要没暂停就一直播。
- `paused`（默认 `false`）：暂停，画面停在当前这一刻；还没开始播时就是 `rest` 静帧。可以由外部状态控制，例如“悬停时暂停”。
- `speed`（默认 `1`）：整条时间轴的速度倍率，2 是两倍速，0.5 是半速。`duration`、`exit`、`rest` 等仍然按原速的秒数写。

不论怎么配置，三条保证不变：离开视口暂停、“减少动态效果”下固定在 `rest`、渲染期间不依赖随机数（水合稳定）。

## 布局

画布尺寸由 `width`、`height` 决定，子元素的坐标都以它为准；`fit` 决定显示时怎样适应外框：

- `scale-down`（默认）：只缩小不放大。外框比画布窄时等比缩小，宽时保持设计尺寸并居中，文字大小不会超过设计值；
- `contain`：等比缩放到刚好装进外框，外框更宽时会放大，适合让图示填满一个格子；
- `none`：始终保持设计尺寸，装不下的部分被外框裁掉。

外框的宽高交给 `className`：`w-full max-w-md`、`h-48`、`aspect-video` 等都可以，外框本身没有边框和固定高度。

## 连线动态

连线的两种动态都由同一个时间轴推导，没有独立的 CSS 动画或定时器，所以同样会在离开视口时暂停、在“减少动态效果”下停在 `rest` 这一帧（此时连线完整）。

### 生长

`FlowBeam` 默认 `line="draw"`：底线从起点沿路径画出来，长度正好跟随光点头部，光点走到哪线画到哪，所以目标节点的 `litAt` 一到，线也刚好抵达。线画完后保持完整，到 `exit` 才随循环淡出，下一轮从空白重新生长。

- 生长之前会留一条很淡的虚线（`foreground/10`）当引导，画面不会空着；不需要时传 `guide={false}`。
- 并行分支用同一个 `at` 出发，会同时开始生长，短的先到。
- 同一条线上的重复脉冲照旧用 `base={false}`，只有第一次负责生长，线不会重复画。
- 想保留旧的写法（整条线一开始就在、不随循环淡出），用 `line="static"`。

不带光点的 `FlowEdge` 传了 `at` 也是默认生长，用时 `drawDuration` 缺省按光点的飞行速度由路径长度换算，和光点线的节奏一致；`reveal="fade"` 可以改回整条淡入。虚线（`dashed`）没法分段生长，会自动改成淡入。

```tsx
<FlowEdge route={BACKUP} at={2.4} />                {/* 生长，2.4 秒开始 */}
<FlowEdge route={BACKUP} at={2.4} drawDuration={1} /> {/* 指定用时 */}
<FlowEdge route={BACKUP} at={2.4} reveal="fade" />   {/* 整条淡入 */}
```

### 流动

给连线加 `flow`，画好之后线上会出现持续向前的虚线纹理，像数据在管道里流动，用来表示“常驻连接 / 持续的数据流”，例如推理引擎到各个服务的出口、数据源到清洗。纹理的颜色跟随 `tone`，速度是 `FLOW_LINE_SPEED`（14 像素/秒），比光点慢得多，只是一点克制的呼吸感；方向沿路径从起点指向终点。它在连线画完后淡入，到 `exit` 随循环淡出。

```tsx
<FlowBeam route={TO_API} at={1.7} flow />
<FlowEdge route={TO_API} at={1.7} flow />
```

`flow` 按条开启：同一条线上重复脉冲的几个 `FlowBeam`，只在负责画线的那一个上设置，避免两层纹理叠在一起。

## API

### FlowDiagram

<PropsTable name="flow-diagram" component="FlowDiagram" />

其余属性透传到根 `div`。

### FlowNode

带细边框的节点；`x`、`y` 是中心点。`litAt` 到达时，边框和底色换成 `tone` 的颜色。`shape` 选择胶囊或方框，`icon`、`label`、`description` 是“图标 + 文字”的快捷写法，其余内容放进子元素。

<PropsTable name="flow-diagram" component="FlowNode" />

### FlowDiamond

分叉 / 汇合点，旋转 45° 的小方块。

<PropsTable name="flow-diagram" component="FlowDiamond" />

### FlowLabel

等宽小标签。颜色用 `tone`，或者用 `className` 覆盖（例如 `fill-muted-foreground text-[9px]`，注意 SVG 文字用的是 `fill-*` 而不是 `text-*`）。

<PropsTable name="flow-diagram" component="FlowLabel" />

### FlowBeam

连线加一枚沿线流动的光点，带一小段拖尾。底线默认跟随光点生长，`flow` 让画好的线持续流动。

<PropsTable name="flow-diagram" component="FlowBeam" />

### FlowEdge

不带光点的连线，用来画背景关系、备用路径，同样支持生长和流动。

<PropsTable name="flow-diagram" component="FlowEdge" />

### FlowReveal

在 `at` 时刻淡入的容器，淡出由时间轴统一负责。

<PropsTable name="flow-diagram" component="FlowReveal" />

### FlowTypedText

逐字打出的文字，后面跟一个会闪烁的光标。已打出的字数由时间推导。

<PropsTable name="flow-diagram" component="FlowTypedText" />

### FlowSpinner

旋转的加载圈，只在 `at` 到 `until` 之间显示。

<PropsTable name="flow-diagram" component="FlowSpinner" />

### FlowStatusDot

状态点，可选向外扩散涟漪表示服务在运行。

<PropsTable name="flow-diagram" component="FlowStatusDot" />

### 路径工具

```ts
function flowRoute(points: readonly FlowPoint[], radius?: number): FlowRoute
function flowArrival(at: number, route: FlowRoute): number
const FLOW_BEAM_SPEED: number // 110，光点飞行速度，单位：设计像素 / 秒
const FLOW_LINE_SPEED: number // 14，连线上流动纹理的速度，单位：设计像素 / 秒
function flowTextWidth(text: string, fontSize?: number): number // 估算文字宽度
function flowToneStyle(tone?: FlowTone): CSSProperties | undefined // 见「色调」
```

`flowRoute` 把折线变成圆角路径并算出长度，`radius` 是拐角半径（默认 6）。它是纯函数，请在组件外调用。`flowArrival` 返回光点抵达终点的时刻。它们和 `FLOW_BEAM_SPEED` 都定义在不依赖 React 的 `route.ts` 里。`flow-diagram.tsx` 是客户端模块，服务端组件不能直接调用它再导出的函数：要在服务端组件里算路径，请改从 `route.ts` 引入；在带 `"use client"` 的文件里（案例都是这样）从 `flow-diagram.tsx` 引入即可。`FLOW_BEAM_SPEED` 在需要“让几束光点同时到达”时有用：`出发时刻 = 到达时刻 - route.length / FLOW_BEAM_SPEED`，参见微服务和 MCP 案例。

```ts
type FlowPoint = readonly [x: number, y: number]
type FlowRoute = { d: string; length: number }
type FlowToneName =
  | "primary" | "foreground" | "muted" | "destructive"
  | "blue" | "green" | "amber" | "rose" | "violet" | "cyan"
type FlowTone = FlowToneName | (string & {}) // 内置名，或任意 CSS 颜色
type FlowBackgroundName = "dots" | "grid" | "lines" | "hatch" | "none"
type FlowFit = "scale-down" | "contain" | "none"
type FlowNodeShape = "pill" | "box"
```

`flowTextWidth` 按“拉丁字符 6px、中文 10px”（10px 字号）线性估算文字宽度，`FlowNode` 用它把图标和文字整体居中，`FlowTypedText` 用它摆光标；自己写需要对齐文字的元素时也可以用。

### data-slot

| 元素 | `data-slot` |
| --- | --- |
| 外框 | `flow-diagram` |
| 底纹层 | `flow-diagram-background` |
| 节点 | `flow-node` |
| 分叉点 | `flow-diamond` |
| 标签 | `flow-label` |
| 光点连线 | `flow-beam` |
| 生长的底线 | `flow-line` |
| 流动纹理 | `flow-line-flow` |
| 独立连线 | `flow-edge` |
| 淡入容器 | `flow-reveal` |
| 逐字文字 | `flow-typed-text` |
| 加载圈 | `flow-spinner` |
| 状态点 | `flow-status-dot` |

## 可访问性

- 默认整个图示 `aria-hidden`，读屏完全忽略，适合作为纯装饰。传入 `label` 后外框变成 `role="img"` 并带上 `aria-label`，内部的 SVG 内容不会再被逐个朗读，所以 `label` 应该概括整张图在讲什么，例如“请求从网关扇出到三个服务再汇合”。
- 图示不承载任何交互，没有可聚焦元素。
- 开启系统的“减少动态效果”时没有任何运动，画面固定在 `rest` 这一帧，信息完整。
- 状态不只靠颜色：失败分支除了红色还有 “401” 之类的文字，完成状态有对勾。

## 注意事项

- 调整面板通过 `FlowDiagramTuningContext` 覆盖子树里 `FlowDiagram` 的 `speed`、`tone`、`background`、`fade`、`loop` 与 `paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。
- 画布按设计尺寸绘制，窄屏时整体缩小，文字也会跟着缩小。设计时留意最窄的容器：10px 的文字缩到 0.7 倍就接近 7px，宽度小于 300px 的场景请把画布设计得更窄一些。
- 文字使用等宽字体，`FlowTypedText` 的光标位置按“拉丁字符 6px、中文 10px”估算，混排时请留一点余量。
- 底纹依赖 `grid-layout` 提供的 `bg-dots`、`bg-hatch` 和 `--edge` 变量，安装时会一并装上；不需要底纹时传 `background="none"`。
- 多彩色调依赖 `--flow-blue` 等六个变量。如果你的项目是手动安装、没有经过 `shadcn add`，需要自己把它们加进全局样式，否则这些色调的元素不会显示颜色。
- `tone` 里不是内置名的字符串都按 CSS 颜色处理，写错内置名（例如 `"bleu"`）不会报错，只是颜色失效。
- 路径只支持直线和圆角，拐角由 `flowRoute` 的 `radius` 控制；复杂曲线请自己写 `path` 并放进 `FlowReveal`。
- 生长依赖路径长度的估算，圆角处有一两像素的误差，不影响观感；同一路径的光点与线头始终同步，因为两者用的是同一个长度。
- 外框默认没有边框和固定高度，首页的用法是 `className="h-48 border-b border-edge"`。

## 源码

<ComponentSource name="flow-diagram" />

---

# 点阵地球

来源：https://yiui.dev/components/globe/

<ComponentPreview name="globe-demo" />

## 安装

<InstallCommand name="globe" />

## 用法

`Globe` 自身是一个正方形外框，球体占其中约 80%，外框的大小、位置完全由 `className` 决定：放大并推到卡片角落，就得到「半露出」的构图。`markers` 传入城市，`label` 是读屏时朗读的城市名，`labels` 在标记旁显示城市名胶囊。页首的预览把放大的地球推到卡片右下角，只露出亚洲一侧，左上放节点指标。

```tsx title="components/globe-example.tsx"
import { Globe, type GlobeMarker } from "@/components/ui/globe/globe"

const CITIES = [
  { label: "上海", location: [31.23, 121.47] },
  { label: "法兰克福", location: [50.11, 8.68] },
] satisfies GlobeMarker[]

export function GlobeExample() {
  return (
    <Globe
      label="分布在上海和法兰克福的节点"
      markers={CITIES}
      markerTone="amber"
      labels
      className="max-w-sm"
    />
  )
}
```

点阵、标记、弧线的颜色都从外框元素的 CSS 变量里取：点阵默认取 `--foreground`，标记默认取 `--primary`，也可以换成 `blue / green / amber / rose / violet / cyan` 或任意 CSS 颜色。切换亮暗模式或颜色主题时（`<html>` 的 `class`、`data-theme` 变化）会自动重新取色，不需要刷新。外框内部再套一层 `.dark`，该局部就按暗色渲染。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整自转速度（负值反向）、水平角、点阵密度、点阵与标记的色调，并开关城市标签与暂停；未改动的项显示示例自己的取值。调整时外框与球体大小不变。水平角是直接转到该角度，之后继续自转；标记挨得很近的示例打开标签会互相叠住。

### 图例

地球与 `GlobeLegend` 并排放置：图例是标记的文字版本，列出城市与经纬度，不依赖颜色与动画。

<ComponentPreview name="globe-legend-demo" />

### 深色发光

外层加 `dark` 强制暗色，`dotTone="cyan"` 让点阵取 `--flow-cyan`，球体边缘自动带一圈同色光晕。`arcs` 的两端与标记重合，每条弧线可以用自己的 `tone`。`phi`、`theta` 把视角转到大西洋一侧。

<ComponentPreview name="globe-dark-demo" />

### 拖拽旋转

`draggable` 打开后可以用鼠标或手指转动地球，松手带惯性，俯仰角缓缓回到初始值，然后恢复自转。`focus` 让地球缓动转向并停在某个地点，示例用一组 `aria-pressed` 按钮驱动它；再次点击传 `null` 就恢复自转。键盘聚焦后用左右方向键也能转。

<ComponentPreview name="globe-draggable-demo" />

## API

### Globe

<PropsTable name="globe" component="Globe" />

`GlobeMarker` 的字段：

| 字段 | 说明 |
| --- | --- |
| `location` | `[纬度, 经度]`，单位为度 |
| `label` | 城市名；读屏朗读，开启标签层时显示为胶囊 |
| `size` | 标记大小，默认 `0.045`，常用 0.03–0.08 |
| `tone` | 这个标记的色调，不传用 `markerTone` |
| `showLabel` | 单独控制标签显示，不传跟随 `labels` |

`GlobeArc` 有 `from`、`to`（都是 `[纬度, 经度]`）和可选的 `tone`。

`phi`、`theta` 是弧度。默认视角正对东亚；想对准某个地点，用导出的 `globeAngles([纬度, 经度])` 换算：

```tsx
import { Globe, globeAngles } from "@/components/ui/globe/globe"

const { phi, theta } = globeAngles([48.85, 2.35])

<Globe phi={phi} theta={theta} speed={0} />
```

### GlobeLegend

标记图例：名称配彩色圆点，`coordinates` 同时列出经纬度。放在地球旁边，给出不依赖颜色与动画的文字版本。

<PropsTable name="globe" component="GlobeLegend" />

## 可访问性

- 默认作为装饰隐藏；传入 `label` 后以图片语义朗读，说明末尾自动附上所有带 `label` 的城市名。
- `draggable` 时外框可聚焦，语义为「可旋转的地球」，左右方向键转动；没有传 `label` 会回落到默认说明。
- 标签层只是视觉辅助，对读屏隐藏；需要文字版本时配合 `GlobeLegend`。
- 系统开启「减少动态效果」时不自转，不播放惯性与俯仰回落；拖拽和键盘仍然可用，直接跟手。
- 地球离开视口或 `paused` 时停止渲染循环，回到视口后继续。

## 注意事项

- 调整面板通过 `GlobeTuningContext` 覆盖子树里 `Globe` 的 `speed`、`phi`、`theta`、`dotTone`、`markerTone`、`mapSamples`、`labels`、`draggable` 与 `paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。运行中改 `phi` 会让地球直接转到新角度。
- 地球由 [cobe](https://github.com/shuding/cobe) 在 WebGL 里绘制，约 5KB，没有其他运行时依赖。服务端输出一个同尺寸的圆形占位，画布就绪后淡出占位，不会造成布局跳动；浏览器不支持 WebGL 时占位一直保留，标记仍可通过读屏获取。
- `mapSamples` 越大点阵越密，也越吃显卡，默认 `16000`；小尺寸的缩略图可以降到 `8000`。设备像素比最高取 2。
- 每个 `Globe` 占用一个 WebGL 上下文，同一页建议不超过 8 个。
- 标签层的位置直接写进 DOM，每帧不触发 React 渲染；标签背面时随球体转过去自动淡出。
- 色调变量依赖 `flow-diagram` 条目，安装时会一并提供。

## 源码

<ComponentSource name="globe" />

---

# 字符矩阵

来源：https://yiui.dev/components/glyph-field/

<ComponentPreview name="glyph-field-demo" />

## 安装

<InstallCommand name="glyph-field" />

## 用法

`GlyphField` 负责背景，子内容使用普通 DOM，居中叠放在画布之上。高度由外框决定，可用 `className="h-screen"` 铺满屏幕，默认最小高度为 18rem。

```tsx title="components/security-field.tsx"
import { GlyphField } from "@/components/ui/glyph-field/glyph-field"

export function SecurityField() {
  return (
    <GlyphField glyphs="hex" tone={["muted", "primary"]} fade="center" paused>
      <h2>安全访问</h2>
      <p>端到端加密 · 零信任</p>
    </GlyphField>
  )
}
```

将 `paused` 设为 `false` 可播放随机闪烁。持续动画旁应提供暂停按钮，页首的演示展示了受控暂停的做法：按钮的状态直接绑定 `paused`。`glyphs` 可以是 `latin`、`binary`、`hex`、`katakana`、`cjk`，也可以直接传入任意字符串。字符按 Unicode 码点拆分，不会截断常见汉字。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整字符集、渐隐方式、字号、密度、速度与色调，并开关暂停；未改动的项显示示例自己的取值，自定义字符集和混合色调显示为「原样」。调整时容器大小不变，字号和密度只改变画布里的字符。

### 简洁中心

中心只放一个图标块与标题，适合做背景层上的轻量提示。

<ComponentPreview name="glyph-field-icon-demo" />

### 中文字符

外层加 `dark` 让这一块按暗色取色，常用汉字与绿色字符交错排列，`fade="center"` 给标题留出空位。此处使用静帧；移除 `paused` 即可闪烁，仍会尊重系统的减少动态效果设置。

<ComponentPreview name="glyph-field-cjk-demo" />

### 二进制横幅

更矮的容器也能自动铺满。`density` 控制格子占用率，`fontSize` 控制字符尺寸，`fade="none"` 保留完整矩阵，文字放在带底色的块里保证可读。

<ComponentPreview name="glyph-field-binary-demo" />

### 自定义字符集

`glyphs` 接受任意字符串，按 Unicode 码点拆分。`tone` 数组里重复某个值可以提高它出现的频率，示例让紫色占一半。

<ComponentPreview name="glyph-field-custom-demo" />

## API

### GlyphField

<PropsTable name="glyph-field" component="GlyphField" />

- `tone` 支持 `primary / foreground / muted / destructive / blue / green / amber / rose / violet / cyan`、CSS 变量表达式或数组；数组可重复某个色调以提高它的出现频率。
- `density` 是 0–1 的占用率；`fontSize` 最小 8px；`speed` 是每个逻辑帧的更新比例（0–1，默认 0.04），逻辑帧率为 20fps，0 表示静止。
- `fade="edges"` 四周淡出，`center` 让中心留白，`none` 保留完整矩阵。遮罩只作用于背景。
- 空字符集不绘制字符；空色调数组回落到 `muted`。

## 可访问性

- 字符背景默认从读屏隐藏，传 `label` 后仅背景获得图片语义；子内容始终可被读取，也可以放置链接或按钮。
- 装饰字符不进入实时播报区域，避免不断打断读屏。
- `paused`、离屏、浏览器标签页不可见或系统减少动态效果开启时停止动画。减少动态效果模式保留静态一帧。

## 注意事项

- 调整面板通过 `GlyphFieldTuningContext` 覆盖子树里 `GlyphField` 的 `glyphs`、`tone`、`density`、`fontSize`、`speed`、`fade` 与 `paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。
- 服务端和无 JavaScript 环境输出同尺寸的淡底色占位与完整子内容，画布就绪不会改变布局。
- 使用 ResizeObserver 跟随容器大小，设备像素比最高 2，单个画布最多 30000 个格子。
- 只重绘发生变化的格子；颜色在主题、亮暗模式或祖先局部主题改变时重新解析。修改外部样式表时可通过更新 `tone` 触发重新取色。
- 色调由 `flow-diagram` 的 `--flow-*` 变量提供，安装时一并带入。

## 源码

<ComponentSource name="glyph-field" />

---

# 时段问候

来源：https://yiui.dev/components/greeting/

<ComponentPreview name="greeting-card-demo" />

## 安装

<InstallCommand name="greeting" />

## 用法

组件分三层，按需取用：

| 组件              | 形态                                                        |
| ----------------- | ----------------------------------------------------------- |
| `Greeting`        | 行内文字，放进任何标题或段落                                |
| `GreetingPeriods` | 早 / 中 / 下午 / 晚四个时段的指示条，当前时段亮起并显示进度 |
| `GreetingCard`    | 问候卡片：图标、色调、大字问候、轮换的副标题，加上时段指示  |

`Greeting` 默认输出 `你好，很高兴在这里遇见你。`，挂载后换成与访客时段相符的问候语。

```tsx title="app/greeting.tsx"
import { Greeting } from "@/components/ui/greeting/greeting"

export function Intro() {
  return (
    <h2 className="text-xl font-medium">
      <Greeting />
    </h2>
  )
}
```

<ComponentPreview name="greeting-demo" />

## 示例

### 图标与称呼

`showIcon` 在问候语前加当前时段的图标（日出 / 太阳 / 日落 / 月亮），颜色随时段变化；`name` 拼上称呼，`nameSeparator` 控制两者之间的分隔。四个时段的问候语、`fallback` 与 `suffix` 都可以覆盖，`boundaries` 重新划分时段。

<ComponentPreview name="greeting-icon-demo" />

```tsx
<Greeting
  showIcon
  name="Travins"
  evening="夜深了"
  boundaries={{ morning: 6, noon: 12, afternoon: 15, evening: 20 }}
  suffix="，今天也辛苦了。"
/>
```

### 时段指示

`GreetingPeriods` 单独使用时就是一条时间轴：每格有图标、名称和区间，当前时段亮起主题之外的专属色调，格子底部的细线是这个时段已经过去的比例（每分钟更新）。区间文字跟着 `boundaries` 走。

<ComponentPreview name="greeting-periods-demo" />

### 问候卡片

`GreetingCard` 把前面的东西组合起来（也就是本页顶部的预览）：右上角的大图标与光晕随时段换色，副标题每 6 秒轮换一次（淡入淡出），底部是四时段指示。`showPeriods={false}` 去掉指示，`rotate={false}` 固定在第一条副标题。

### 固定在某个时刻

`hour` 接收 0–24 的小时数（可带小数，如 `12.5`）。传入后结果是确定的，服务端也会直接渲染，不再等待客户端挂载——设计预览、截图和测试都用得上。下面的按钮在真实时间和四个固定时刻之间切换：

<ComponentPreview name="greeting-preview-demo" />

### 时段划分

| 默认本地时间     | 问候语 | 对应 prop   | 色调 |
| ---------------- | ------ | ----------- | ---- |
| 05:00–10:59      | 早上好 | `morning`   | 琥珀 |
| 11:00–13:59      | 中午好 | `noon`      | 天蓝 |
| 14:00–17:59      | 下午好 | `afternoon` | 玫红 |
| 18:00–次日 04:59 | 晚上好 | `evening`   | 紫   |

`boundaries` 的四个值是各时段的起始小时，必须严格递增且落在 0–23；传错时回落到默认划分。`evening` 持续到次日 `morning` 开始。

色调来自 `--flow-amber` / `--flow-blue` / `--flow-rose` / `--flow-violet`，安装时随条目一起写入全局样式（与流程动画图示共用同一组变量），也可以在自己的样式里改写。没有这些变量时回落到主题强调色。

### 文案

`Greeting` 的文案用单独的 props；`GreetingPeriods` 与 `GreetingCard` 的文案集中在 `labels`，按字段整体覆盖：

| `labels` 字段         | 用于                                         |
| --------------------- | -------------------------------------------- |
| `eyebrow` / `pending` | 卡片顶部小标题，以及挂载前的占位             |
| `periods`             | 时段指示的读屏名称                           |
| `names`               | 四个时段的短名称（`{ morning: "早上", … }`） |
| `tags`                | 小标题后的英文标记（`MORNING` …）            |
| `messages`            | 各时段轮换的副标题，每个时段至少一条         |
| `fallbackMessage`     | 挂载前的副标题                               |

## API

### Greeting

<PropsTable name="greeting" component="Greeting" />

根元素是 `<span data-slot="greeting">`，`data-state` 在挂载前是 `pending`、拿到时段后变成 `ready`，同时带上 `data-period`（`morning` / `noon` / `afternoon` / `evening`）。

### GreetingPeriods

<PropsTable name="greeting" component="GreetingPeriods" />

根元素是 `<ol data-slot="greeting-periods">`，每格 `greeting-period`（`data-period`、`data-active`），进度条 `greeting-progress`。

### GreetingCard

<PropsTable name="greeting" component="GreetingCard" />

根元素是 `<div data-slot="greeting-card">`，带 `data-state` 与 `data-period`。

### useGreetingPeriod

```tsx
import { useGreetingPeriod } from "@/components/ui/greeting/greeting"

const { period, progress } = useGreetingPeriod() // period 在挂载前为 null
```

返回当前时段和已过去的比例（0–1），第一个参数是 `boundaries`，第二个是 `hour`。时间来自随条目安装的 `useNow` hook，全页面共用一个定时器。

## 可访问性

- 渲染的是内联 `<span>`，可以放进 `<p>`、`<h2>` 等任何文本容器，不改变标题层级。
- 挂载后的文案替换**没有**加 `aria-live`：它是页面的主文案而不是通知，逐字播报会打断读屏用户。确实需要播报时，在外层容器上自己加 `aria-live="polite"`。
- 时段图标与光晕都是装饰，`aria-hidden`；颜色之外，当前时段还有 `aria-current="true"` 和文字名称。
- `GreetingPeriods` 是带 `aria-label` 的有序列表，进度条只是视觉辅助，不进入无障碍树。
- 开启“减少动态效果”后副标题不再轮换，固定显示第一条；其余部分没有位移动画。
- 首屏文案与静态 HTML 一致，读屏和搜索引擎看到的是同一段文字，不会出现空内容。

## 注意事项

### 为什么必须在客户端渲染

问候语取决于访客设备上的本地时间，服务端渲染时无从得知。静态导出会把 HTML 在构建时生成一次，如果首屏直接用浏览器时间渲染，客户端水合时拿到的文本就会和 HTML 不一致。

组件因此把 `fallback` 作为初始文案，挂载后再替换，并每分钟校准一次。

<Callout variant="tip" title="把 fallback 写成中性问候">
  副作用是首屏会短暂显示
  `fallback`：把它设成一句中性、通用的问候（例如默认的“你好”）就不会显得突兀。传入
  `hour` 可以绕开这个问题。
</Callout>

### 其他

- 问候语和 `fallback`、`suffix` 都是纯字符串，不接受 JSX。需要强调某一段时，在外层用 `<span>` 包裹。
- 时区以访客设备为准，不做服务端时区推断，因此不需要 `timeZone` 参数。
- `Greeting` 返回内联 `<span>`，不是块级容器。

## 源码

<ComponentSource name="greeting" />

---

# 线条网格布局

来源：https://yiui.dev/components/grid-layout/

<ComponentPreview name="grid-layout-demo" />

## 安装

<InstallCommand name="grid-layout" />

## 用法

每个页面使用一个 `GridContainer`，在其中依次排列 `GridSection` 与 `GridSeparator`。相邻行只绘制底线，避免重复描边。

```tsx title="app/page.tsx"
import {
  GridContainer,
  GridSection,
  GridSeparator,
  GridColumns,
} from "@/components/ui/grid-layout/grid-layout"

export default function Page() {
  return (
    <GridContainer>
      <GridSection className="px-4 py-6">个人介绍</GridSection>
      <GridSeparator />
      <GridSection>
        <GridColumns>
          <div className="p-4">项目</div>
          <div className="p-4">文章</div>
        </GridColumns>
      </GridSection>
    </GridContainer>
  )
}
```

`GridSection` 默认只画底部横线；需要给第一行补一条顶部横线时传 `topLine`。

## 示例

### 分隔带纹路

`GridSeparator` 用 `pattern` 切换纹路。页面里的主分隔用默认的 `dots`（点阵）；`ruler`、`hatch`、`grid`、`plus`、`wave` 适合局部强调或区分不同类型的内容。

<ComponentPreview name="grid-separator-patterns-demo" />

### 编号标签

`label` 在分隔带左侧显示一段等宽小字，后接虚线，可以和任意纹路组合；`pattern="none"` 只保留编号和虚线。

<ComponentPreview name="grid-separator-label-demo" />

### 交点十字

`crosshair` 控制容器竖线与横线交点处的「+」：`GridSeparator` 默认关闭，传 `crosshair` 开启；`GridSection` 传 `crosshair` 会在底线两端绘制。也可以直接使用 `GridCrosshair` 原语，放在任何 `position: relative` 的容器的四个角。

<ComponentPreview name="grid-crosshair-demo" />

给带自己边框的卡片放十字时传 `anchor="border"`，十字会对齐卡片的边框而不是底线。

### 分栏

`GridColumns` 默认两栏，栏间是虚线，窄屏自动堆叠。要三栏就用 `className` 覆盖列数：`sm:grid-cols-3`。每栏的内边距自己写，一行一个 `GridSection`。

<ComponentPreview name="grid-columns-demo" />

### 侧边编号栏

章节类页面可以用「左侧窄编号栏 + 右侧内容」的两栏结构：宽屏用竖线隔开，窄屏编号移到标题上方。一章一个 `GridSection`，相邻章节只靠底线分开。

<ComponentPreview name="grid-section-sidebar-demo" />

## API

五个组件都支持对应 HTML 元素的原生属性，包括 `className`、`children`、`id` 和无障碍属性。

### GridContainer

<PropsTable name="grid-layout" component="GridContainer" />

### GridSection

<PropsTable name="grid-layout" component="GridSection" />

### GridSeparator

<PropsTable name="grid-layout" component="GridSeparator" />

`pattern` 可选值：`dots`（默认）、`ruler`、`hatch`、`grid`、`plus`、`wave`、`none`。同时导出 `gridSeparatorVariants`，类型 `GridSeparatorPattern`。

### GridColumns

<PropsTable name="grid-layout" component="GridColumns" />

### GridCrosshair

<PropsTable name="grid-layout" component="GridCrosshair" />

`position` 可选 `top-left`（默认）、`top-right`、`bottom-left`、`bottom-right`，同时导出 `gridCrosshairVariants`。

### data-slot 与状态

| 组件 | `data-slot` | 其他属性 |
| --- | --- | --- |
| `GridContainer` | `grid-container` | — |
| `GridSection` | `grid-section` | `data-top-line`（`true` / `false`） |
| `GridSeparator` | `grid-separator` | `data-pattern`；内部还有 `grid-separator-pattern`、`grid-separator-label` |
| `GridColumns` | `grid-columns` | — |
| `GridCrosshair` | `grid-crosshair` | `data-position` |

这些 `data-slot` 都可以作为父级选择器的锚点，例如 `[&>[data-slot=grid-section]]:px-4`。

## 可访问性

- 这些组件只提供容器，不添加 `role`，也不改变文档结构：`GridSection` 渲染真正的 `<section>`，`GridContainer`、`GridSeparator`、`GridColumns` 渲染 `<div>`。
- 行是页面骨架，语义需要自己补：给 `GridSection` 加 `aria-label` 或配合 `aria-labelledby` 指向行内标题，读屏才会把这一行念成区域。原生属性会原样透传。
- `GridSeparator` 与 `GridCrosshair` 是纯装饰，自带 `aria-hidden`，不会被读屏朗读，也不进入 Tab 顺序；纹路没有动画。`label` 同样会被一并隐藏，需要读屏识别的章节名请写在行内的标题里。
- 线条与文字的颜色都来自主题变量（`--edge`、`border-edge`），在亮暗模式和 14 个颜色主题下对比度一致，不依赖颜色传达信息。

## 注意事项

### 容器宽度

通过父元素上的 `--grid-width` 变量调整宽度，默认 `48rem`。文档页面使用 `80rem`。`GridColumns` 在窄屏下堆叠，`sm` 起显示两列。

视口比容器窄时，`GridContainer` 两侧各留出一段空白（gutter）：竖线向内缩，而全宽横线、分隔带仍延伸到屏幕边缘，内容像被框在线里。gutter 是两侧之和，窄屏默认 `2rem`、`sm` 起 `3rem`，容器达到最大宽度后自然居中，不再有空白。通过 `--grid-gutter` 变量覆盖，例如 `className="[--grid-gutter:0px]"` 让竖线贴到屏幕边缘；该变量同时作用于窄屏与 `sm` 以上。

### 主题与工具类

安装命令会注册 `--edge` 变量与 `border-edge` 主题映射，以及以下 Tailwind CSS v4 工具类：两个横线工具类 `screen-line-top`、`screen-line-bottom`；六个分隔带纹理工具类 `pattern-ruler`、`pattern-hatch`、`pattern-dots`、`pattern-grid`、`pattern-plus`、`pattern-wave`（供 GridSeparator 使用）；两个面积底纹 `bg-hatch`、`bg-dots`，可直接铺在任意元素上。线条与纹路的颜色都来自 `--edge` / `--foreground`，随颜色主题和亮暗模式变化。

全宽横线需要页面的 `html` 设置 `overflow-x: clip`；Registry 安装会一并写入该规则。

## 源码

<ComponentSource name="grid-layout" />

---

# 组件

来源：https://yiui.dev/components/



---

# 等轴测标志

来源：https://yiui.dev/components/isometric-mark/

<ComponentPreview name="isometric-mark-demo" />

## 安装

<InstallCommand name="isometric-mark" />

## 用法

传入平面形状即可，坐标就是平面 logo 自己的坐标（`y` 向下）。形状数组请定义在组件外面，避免每次渲染重新计算几何。

```tsx title="app/brand-mark.tsx"
import {
  IsometricMark,
  type IsometricShape,
} from "@/components/ui/isometric-mark/isometric-mark"

const SHAPES: readonly IsometricShape[] = [
  {
    outer: [
      [0, 0],
      [100, 0],
      [100, 100],
      [0, 100],
    ],
    holes: [
      [
        [35, 35],
        [65, 35],
        [65, 65],
        [35, 65],
      ],
    ],
  },
]

export function BrandMark() {
  return <IsometricMark shapes={SHAPES} label="我的标志" className="w-64" />
}
```

宽度由 `className` 控制，高度按 viewBox 自动适配。线宽、斜纹间距、虚线都跟着图形尺寸等比缩放，所以放大缩小时观感一致。

### 朝向与视角

`rotation` 在投影前把图形绕中心旋转，决定它平躺在地上的朝向；`elevation` 是视线的俯仰角，默认约 35.26°（标准等轴测），调大更接近俯视，调小更接近平视。

取 `0`、`90`、`180`、`-90` 时图形的横竖边沿等轴测的两条斜轴，像一块平放的板；斜向的图形可以取任意角度，让它的长边顺着某条斜轴更好看。页首的本站标志用的是 `rotation={-65}`：

```tsx
<IsometricMark shapes={SHAPES} rotation={-65} label="易" guides="edges" />
```

想直观比较不同朝向和俯仰，打开下方任一示例的「调整」面板拖动即可。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整朝向、俯仰、挤出高度、顶面材质、地面、辅助线与音色，并开关按下、高光与音效；未改动的项显示示例自己的取值。调整时画框固定，容器大小不变。

### 多个形状与色调

`shapes` 可以放多块互不相连的多边形，它们之间的遮挡自动计算；每块可以用 `tone` 单独着色。下面是 shadcn/ui 的标志：两道斜杠各是一块，分别取主题色的深浅，地面用条纹 `floor="lines"`。

<ComponentPreview name="isometric-mark-shadcn-demo" />

### 带孔的形状

`holes` 在外轮廓里挖孔，孔壁同样按朝向自动消隐。下面是 Pi 的像素标志：左边一块挖出方孔，右下的方块独立成一块并着主题色，顶面用网纹材质，地面用棋盘格 `floor="checker"`。

<ComponentPreview name="isometric-mark-pi-demo" />

### 静态图形

任何多边形都可以，最简单的一个三角形也行。下面是 Vercel 的三角标：素面材质（`material="plain"`）、包围盒辅助线（`guides`），关掉了 `highlight`；需要完全静态的插图时再关掉 `interactive`。地面用站点的点阵底纹 `floor="dots"`。

<ComponentPreview name="isometric-mark-vercel-demo" />

### 材质、地面与辅助线

- `material` 是顶面材质：`hatch` 斜纹「/」（默认）、`hatch-reverse` 斜纹「\」、`cross` 网纹、`dots` 点阵、`lines` 横纹、`plain` 素面。斜纹与图形长边接近平行时会有视差感，换一个方向或用横纹即可。
- `guides` 是背景虚线：`true` / `"box"` 画包围盒四边的延长线，适合横平竖直的图形；`"edges"` 沿图形自己最长的两个边方向画外侧切线，适合斜向的图形。
- `floor` 是地面，和辅助线同方向、同一平面，并对齐图形的每条边：`true` / `"grid"` 方格网、`"lines"` 条纹、`"checker"` 棋盘格，`"dots"` 则是站点的点阵底纹（8px 间距、1px 方点，铺在屏幕平面上）。

### 挤出高度与按下

`depth` 是挤出高度，单位与形状坐标相同，默认取图形平面尺寸的 12%。按住指针时图形被压到 `pressedDepth`（默认是 `depth` 的一半，设为 `0` 会被完全压平），松开或移出后弹回；线条高光跟随鼠标在窗口中的位置。触屏与“减少动态效果”下高光自动关闭，按下状态瞬间切换。这些都可以在示例的调整面板里直接试。

### 点击音效

`sound` 打开按下与松开时的合成音效（Web Audio 现场生成，不需要音频文件），默认关闭，本页所有示例都已打开。浏览器要求先有用户操作才能出声，所以音频在第一次按下时才初始化。静音偏好存在浏览器本地，页面上所有标志共用：`useIsometricMarkMuted()` 返回 `[muted, setMuted]`，可以用它做一个静音按钮，页首的示例右上角就是这样。这份偏好与站内其他带音效的组件共用（`localStorage` 的 `travinsy:sound:muted`）：同一页面里一处静音，其他组件的静音按钮与音效立刻跟上；换到另一个标签页也会同步。`soundTone` 调音色：`0` 偏闷，是低沉的「咚」；`1` 偏脆，是清脆的「咔」，默认 `0.6`。

```tsx
const [muted, setMuted] = useIsometricMarkMuted()

<IsometricMark shapes={SHAPES} sound soundTone={0.6} />
<button onClick={() => setMuted(!muted)}>{muted ? "打开音效" : "静音"}</button>
```

## 几何说明

组件不依赖手工描的路径，所有面都由平面多边形自动算出：

- **投影**：`X = (x - y)·cos30°`，`Y = (x + y)·k₁ - z·k₂`，其中 `k₁ = sin(e)·√2·cos30°`、`k₂ = cos(e)·√2·cos30°`，`e` 是 `elevation`；默认 35.26° 时 `k₁ = 0.5`、`k₂ = 1`，即标准等轴测。观察者位于 `(+x, +y, +z)` 一侧，viewBox 按投影后的包围盒自动计算并留少量边距。
- **面的组成**：顶面在 `z = depth`，外轮廓与孔一起用 `evenodd` 填充；每个环的每条边挤出一面侧墙，孔被挤成通孔。
- **背面剔除**：外轮廓取正面积、孔取负面积，所有环的“实体外侧”法线统一为 `(ey, -ex)`，只保留朝向观察者的墙。与观察方向垂直的墙在屏幕上面积为零，不绘制。
- **消隐**：画家算法。墙在屏幕上只占据 `x - y` 方向上的一段范围，范围重叠的两面墙比较重叠区间中点的 `x + y`，得到“谁挡住谁”，再做拓扑排序，凹多边形也能排对。顺序只取决于平面形状，按下动画时不用重排。顶面最后绘制。
- **按下动画**：一个弹簧驱动的高度值同时重算所有侧墙路径（只是 O(边数) 的字符串重建），顶面路径不变，整体用 `y` 偏移下移，材质纹理因此始终贴着轮廓。
- **地面**：辅助线与地面网格取同样的两个方向。每个方向上，若所有边到外侧切线的距离有足够大的公约数，就按它等距铺线；否则每条边各画一条线，外侧按平均间距延伸。

## API

### IsometricMark

<PropsTable name="isometric-mark" component="IsometricMark" />

其余属性透传到根 `svg`，`className` 与内置样式合并。

### useIsometricMarkMuted

```ts
function useIsometricMarkMuted(): readonly [
  muted: boolean,
  setMuted: (muted: boolean) => void,
]
```

读写点击音效的静音偏好。偏好存在 `localStorage` 的 `travinsy:sound:muted`，与站内其他带音效的组件共用，同一页面的所有标志共享（写入后广播 `travinsy:sound-muted-change` 事件）并在标签页之间同步；服务端与水合阶段按未静音渲染。

### 类型

```ts
type IsometricPoint = readonly [number, number]

type IsometricShape = {
  /** 外轮廓，顺时针或逆时针都可以 */
  outer: readonly IsometricPoint[]
  /** 孔，会被挤成通孔 */
  holes?: readonly (readonly IsometricPoint[])[]
  /** 这块形状的色调（任意 CSS 颜色，如 var(--primary)）：顶面与侧墙淡淡着色、线条取同色 */
  tone?: string
}

type IsometricMaterial =
  "hatch" | "hatch-reverse" | "cross" | "dots" | "lines" | "plain"

type IsometricFloor = "grid" | "lines" | "dots" | "checker"
```

页首的本站标志就用了 `tone`：上三道细斜杠用主题色由浅到深，下三道粗斜杠保持单色线稿。

### data-slot

| 元素       | `data-slot`                                       |
| ---------- | ------------------------------------------------- |
| 根元素     | `isometric-mark`                                  |
| 单面侧墙   | `isometric-mark-wall`                             |
| 顶面       | `isometric-mark-top`                              |
| 背景辅助线 | `isometric-mark-guides`                           |
| 地面       | `isometric-mark-floor`（`data-floor` 为具体材质） |

## 可访问性

- 不传 `label` 时根元素是 `aria-hidden`，读屏完全忽略，适合作为纯装饰；传入 `label` 后变成 `role="img"` 并带上 `aria-label`。
- 按下效果只响应指针，没有键盘等价操作，不承载任何功能。需要可点击时请把它包进 `a` 或 `button`，由外层提供语义与键盘支持。
- 高光在触屏设备（`(hover: none)`）与 `prefers-reduced-motion` 下自动关闭；减少动态效果时按下状态瞬间切换，不播放弹簧。
- 音效默认关闭；打开后请同时提供静音入口（`useIsometricMarkMuted`），音效只是点缀，不承载信息。
- 颜色由 `--foreground`、`--background` 与形状的 `tone` 混合得到；暗色模式下顶面、线条、纹理与着色比例单独加重，亮暗模式与颜色主题下都有足够的对比。

## 注意事项

- 高光位置取鼠标在**窗口**中的相对位置并映射到图形范围，因此鼠标不在图形上时高光也会随之移动；图形不在视口内（含 80px 缓冲）时不监听鼠标。
- 顶面与侧墙是实心填充（`--top`、`--wall`，亮色下等于背景色），用来遮挡后面的线，所以图形背后若有图案会被盖住；地面与背景辅助线画在最底层。
- `depth` 默认取图形平面尺寸的 12%；`pressedDepth` 默认是 `depth` 的一半，设为 `0` 则会被完全压平。
- 颜色变量 `--stroke`、`--pattern`、`--guide`、`--top`、`--wall` 以及着色比例 `--tone-top`、`--tone-wall`、`--tone-line` 定义在根元素的 class 里（亮暗各一套），可以用 `className` 覆盖，例如 `[--stroke:var(--primary)]`。
- `floor="dots"` 按图形的实际渲染尺寸换算 8px，尺寸变化时自动重算。
- 几何计算放在同目录的 `geometry.ts`，是不依赖 React 的纯函数；音效在 `sound.ts`。

## 源码

<ComponentSource name="isometric-mark" />

---

# 实时当地时间

来源：https://yiui.dev/components/local-time/

<ComponentPreview name="local-time-world-clock-demo" />

## 安装

<InstallCommand name="local-time" />

## 用法

组件分三种形态，都从同一个入口导入：

| 组件                            | 形态                           |
| ------------------------------- | ------------------------------ |
| `LocalTime`                     | 行内时间，可以放进任何一行文字 |
| `WorldClock` + `WorldClockItem` | 多个时区的世界时钟，列表或卡片 |
| `AnalogClock`                   | SVG 模拟表盘                   |

`timeZone` 接收 IANA 时区名，不是 `+08:00` 这类固定偏移。

```tsx title="app/header.tsx"
import { LocalTime } from "@/components/ui/local-time/local-time"

export function Header() {
  return (
    <p className="font-mono text-sm">
      <LocalTime timeZone="Asia/Shanghai" />
    </p>
  )
}
```

输出形如 `21:04:33 // 早 0.5 小时`：前半段是目标时区的当前时间，`//` 后是它与访客时区的差值。

<ComponentPreview name="local-time-demo" />

## 示例

### 行内时间的选项

`showDayNight` 在时间前加昼夜图标，`showZone` 附上 UTC 偏移，`animated` 让变化的数字轻微下落淡入，`hour12` 切换 12 小时制，`showSeconds={false}` 去掉秒（此时每分钟才刷新）。

<ComponentPreview name="local-time-inline-demo" />

### 世界时钟

`WorldClock` 接收 `zones` 数组（本页顶部的预览把它和 `AnalogClock`、`LocalTime` 拼成一块「协作时区」面板：左边是所在地的表盘，右边是四个协作城市），每一项一行：城市名、时区与 UTC 偏移、当前时间、昼夜图标，右下角是日期差（昨天 / 明天）和与访客的时差。`highlighted` 给某一项加上强调色竖条。

```tsx title="app/clocks.tsx"
import { WorldClock } from "@/components/ui/local-time/local-time"

const zones = [
  { label: "上海", timeZone: "Asia/Shanghai", highlighted: true },
  { label: "伦敦", timeZone: "Europe/London" },
  { label: "纽约", timeZone: "America/New_York" },
]

export function Clocks() {
  return <WorldClock zones={zones} className="max-w-sm" />
}
```

### 用组合方式写

需要给某一项加自己的属性时，直接把 `WorldClockItem` 作为 children 写出来；`hour12`、`showSeconds` 等设置由 `WorldClock` 统一下发。

<ComponentPreview name="local-time-compose-demo" />

### 卡片形态

`variant="cards"` 把每个城市排成带模拟表盘的卡片，两列布局，最后一张落单时自动撑满整行。

<ComponentPreview name="local-time-cards-demo" />

### 模拟表盘

`AnalogClock` 默认平滑转动：指针每帧由 `requestAnimationFrame` 直接写入，不触发 React 渲染，离开视口时暂停。`smooth={false}` 或系统开启“减少动态效果”时改为按秒跳格；表盘随昼夜轻微变色，秒针使用主题强调色。

<ComponentPreview name="local-time-analog-demo" />

### 文案与区域格式

可见文案集中在 `labels`，`locale` 决定 `Intl.DateTimeFormat` 与 `Intl.NumberFormat` 的结果。旧版单独的文案 props（`placeholderLabel`、`sameTimeLabel`、`aheadLabel`、`behindLabel`、`hourUnit`）继续可用，优先级高于 `labels` 里对应的字段。

```tsx
<LocalTime
  timeZone="Europe/London"
  locale="en-GB"
  labels={{
    pending: "local time",
    same: "same as you",
    ahead: "ahead",
    behind: "behind",
    hourUnit: "h",
  }}
/>
```

| `labels` 字段                      | 默认值                   | 用于                  |
| ---------------------------------- | ------------------------ | --------------------- |
| `pending`                          | `当地时间`               | 挂载前占位时间之后    |
| `same`                             | `与你同一时间`           | 与访客同一时间        |
| `ahead` / `behind`                 | `早` / `晚`              | 目标时区更靠前 / 靠后 |
| `hourUnit`                         | `小时`                   | 时差的单位            |
| `day` / `night`                    | `白天` / `夜间`          | 昼夜图标的读屏文字    |
| `yesterday` / `today` / `tomorrow` | `昨天` / `今天` / `明天` | 世界时钟的日期差      |
| `worldClock` / `live`              | `WORLD CLOCK` / `LIVE`   | 世界时钟标题栏        |
| `clock`                            | `当地时间`               | 模拟表盘的读屏名称    |

### 时差怎么算

组件把目标时区的 UTC 偏移和 `Date.prototype.getTimezoneOffset()` 相减得到小时数，夏令时（例如 `Europe/London`）自动跟随。差值为 0 时显示 `与你同一时间`。昼夜以目标时区的 6:00–17:59 为白天，只是视觉提示，不区分半球与季节。

## API

### LocalTime

<PropsTable name="local-time" component="LocalTime" />

| 元素              | `data-slot`       | 其他属性                                                                                       |
| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| 根元素            | `local-time`      | `data-state="pending"` / `"ready"`；开启 `showDayNight` 时有 `data-daylight="day"` / `"night"` |
| 当前时间 `<time>` | `local-time-time` | `dateTime`（ISO 字符串）                                                                       |
| UTC 偏移          | `local-time-zone` | —                                                                                              |
| `//` 后的说明     | `local-time-note` | —                                                                                              |
| 昼夜图标          | `day-night-mark`  | `data-daylight`                                                                                |

### WorldClock

<PropsTable name="local-time" component="WorldClock" />

根元素是 `role="group"` 的 `<div data-slot="world-clock">`，带 `data-variant`；标题栏 `world-clock-header`，列表 `world-clock-list`。

### WorldClockItem

<PropsTable name="local-time" component="WorldClockItem" />

根元素是 `<li data-slot="world-clock-item">`，带 `data-state`（`pending` / `ready`）、`data-highlighted` 与 `data-daylight`。必须放在 `WorldClock` 里。

### AnalogClock

<PropsTable name="local-time" component="AnalogClock" />

根元素是 `<svg data-slot="analog-clock">`，带 `data-state` 与 `data-daylight`；尺寸用 `className` 控制（默认 `size-28`）。

### useNow

时钟共用的 hook，随条目一起安装到 `hooks/use-now.ts`：

```tsx
import { useNow } from "@/hooks/use-now"

const now = useNow(1000) // 毫秒时间戳；服务端与水合期间为 null
```

全页面共用一个对齐整秒的定时器，多个时钟同时存在也只有一个 `setTimeout` 在跑，所有实例的秒数在同一帧跳动。

## 可访问性

- 时间用语义化的 `<time>` 加机器可读的 `dateTime`，读屏与复制粘贴拿到的都是标准格式。
- 每秒变化的内容**没有**加 `aria-live`：真正的实时时钟如果每秒播报会完全打断读屏用户。需要提醒时请在外层自行加 `aria-live="polite"`，并考虑把 `showSeconds` 关掉降低更新频率。
- 昼夜图标是装饰，同时输出 `白天` / `夜间` 的 `sr-only` 文字，颜色不是唯一信息。
- 世界时钟是 `role="group"`，用标题栏文字作名称；`AnalogClock` 是 `role="img"`，名称是 `label` 加上分钟精度的时间，指针每秒的变化不会被播报。
- 开启“减少动态效果”后：数字过渡关闭、模拟表盘按秒跳格、标题栏的“实时”圆点不再闪烁。
- 占位文案（`--:--:--`）与就位后的文本都使用 `tabular-nums` 且宽度一致，切换时不引起布局跳动。

## 注意事项

### 为什么必须在客户端渲染

时间依赖访客的浏览器时钟，服务端渲染出来的秒数一定会过期。`useNow` 在服务端和水合期间返回 `null`，组件输出 `--:--:--` 占位，水合完成后再换成真实时间。这样静态导出的 HTML 与客户端首屏完全一致，不会出现水合警告，也不会先闪出一个错误的时间。

### 其他

- `timeZone` 必须是合法的 IANA 名称，传错会在浏览器抛 `RangeError`。
- 所有实例共用一个定时器，同一页面放多个时钟的开销只来自各自的格式化；`Intl.DateTimeFormat` 实例按参数缓存。
- `AnalogClock` 的平滑模式用 `requestAnimationFrame`，每帧只做三次 `setAttribute`；整页放很多块表盘时可以给部分设置 `smooth={false}`。
- 12 小时制由 `hour12` 控制，24 小时制使用 `hourCycle: "h23"`，两者的上午 / 下午文字由 `locale` 决定。

## 源码

<ComponentSource name="local-time" />

---

# 跑马灯

来源：https://yiui.dev/components/marquee/

<ComponentPreview name="marquee-demo" />

## 安装

<InstallCommand name="marquee" />

## 用法

每组内容至少铺满容器，复制组首尾相接。动画由 CSS 驱动，`ResizeObserver` 仅测量一组内容的尺寸，按 `尺寸 / speed` 换算时长。

```tsx title="components/marquee-example.tsx"
import { Marquee, MarqueeItem } from "@/components/ui/marquee/marquee"

export function MarqueeExample() {
  return (
    <Marquee speed={48} gap={32} label="设计关键词">
      <MarqueeItem>线条网格</MarqueeItem>
      <MarqueeItem>LINE GRID</MarqueeItem>
      <MarqueeItem>组件库</MarqueeItem>
    </Marquee>
  )
}
```

页首的预览是两条反向滚动的丝带：`rotate` 把整条带子旋转 ±9°，交叉成 X 形。旋转带应放在带 `overflow-hidden` 的外层，并加宽到覆盖两端。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整速度、间距、旋转，并开关反向、两端渐隐、悬停暂停与暂停；未改动的项显示示例自己的取值。调整时预览画框大小不变。

### 实心与描边

同一条带里交替使用实心字与描边字，两行反向滚动。描边字用背景色填充，并先画描边（`paint-order: stroke fill`），字形重叠处的内部轮廓会被盖住。

<ComponentPreview name="marquee-type-demo" />

### 项目行情

用方向图标、正负号和数值表达变化。示例数据固定，仅展示布局，不连接实时服务。

<ComponentPreview name="marquee-ticker-demo" />

### 技术栈

两行文字胶囊以相同速度反向移动。使用通用工具图标，不依赖品牌图形资源。

<ComponentPreview name="marquee-stack-demo" />

### 纵向动态

纵向滚动需要给容器设置明确高度，例如 `className="h-56"`。持续滚动的正文旁应提供暂停入口，示例里的按钮直接绑定 `paused`。

<ComponentPreview name="marquee-vertical-demo" />

## API

### Marquee

<PropsTable name="marquee" component="Marquee" />

- `direction` 默认 `left`，支持 `left / right / up / down`；`reverse` 在当前方向上反转。
- `speed` 默认 `48`，单位为像素/秒，最小按 `1` 处理。间距与字体变化都会重新测量，因此长短内容的移动速度一致。
- `repeat` 默认 `3`，表示内容组总数，限制在 `2–20`。它不改变一组内容的移动速度。
- `gap` 默认 `32`，单位为像素；负值按 `0` 处理。组尾保留相同间距，接缝不会多一格或少一格。
- `fade` 默认开启，沿滚动方向对两端做渐隐。
- `rotate` 默认 `0`，单位为度。旋转带应放在带 `overflow-hidden` 的外层，并适当加宽以覆盖两端。
- `pauseOnHover` 默认开启；`paused` 可直接暂停。键盘焦点进入容器时始终暂停。
- `label` 默认“跑马灯”，可覆盖区域的朗读说明。

### MarqueeItem

<PropsTable name="marquee" component="MarqueeItem" />

项目默认不收缩、不换行，支持自定义布局和样式。纵向多行内容可用 `whitespace-normal`。

### 调整 Context

`MarqueeTuningContext` 接收 `MarqueeTuning` 覆盖项；`onReport(report: MarqueeReport)` 回报覆盖前的实际属性。

## 可访问性

- 只有第一组内容参与朗读；复制组使用 `aria-hidden` 与 `inert`，不进入焦点顺序。
- 区域可通过 Tab 聚焦，聚焦后暂停，便于阅读。
- 开启“减少动态效果”后取消动画、旋转与遮罩，只保留原始内容；可用键盘或触控滚动查看，纵向列表同样可滚动。
- 对会持续移动的正文，提供邻近的暂停控件并绑定 `paused`。装饰性丝带可在外层使用 `aria-hidden`，同时设置 `tabIndex={-1}`。

## 注意事项

- 调整面板通过 `MarqueeTuningContext` 覆盖子树里的 `speed`、`gap`、`rotate`、`reverse`、`fade`、`pauseOnHover`、`paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。

- 无 JS 时仍运行 CSS 动画，使用每组 `30s` 的回退时长。精确的 px/s 换算需要客户端测量，不能从服务端获知任意字体与内容的实际宽度。
- 请使用非交互展示内容，避免在复制组内放置表单、带固定 `id` 的元素或有副作用的组件。复制体虽然不可交互，仍会挂载。
- 组件自身不设置色彩或背景；通过主题 token 组合带子和胶囊。

## 源码

<ComponentSource name="marquee" />

---

# 迷你图

来源：https://yiui.dev/components/mini-chart/

<ComponentPreview name="mini-chart-demo" />

## 安装

<InstallCommand name="mini-chart" />

条目依赖 shadcn 的 `chart`（`recharts` 的封装），安装时会一并添加。示例里的卡片外壳用了 [统计卡片](/components/stat-card)，它不是必需的依赖。

## 用法

`MiniChart` 一个组件画四种图，用 `type` 切换；`data` 可以是纯数字，也可以是带标签的 `{ label, value }`。高度用 `className` 控制，默认 `h-16`，宽度撑满父级。

```tsx title="app/spark.tsx"
import { MiniChart } from "@/components/ui/mini-chart/mini-chart"

export function Spark() {
  return (
    <MiniChart
      type="area"
      data={[28, 27, 35, 29, 40, 57, 50]}
      seriesLabel="访客"
      label="近 7 天博客访客走势"
    />
  )
}
```

`label` 是读屏名称，说清楚这张图表示什么。进度环 `MiniRing` 和环形图 `MiniDonut` 从同一个入口导入。

## 示例

### 指标面板

六块指标拼成一条小仪表盘，每块用不同图形与色调，底部是数值与涨跌。

<ComponentPreview name="mini-chart-dashboard-demo" />

### 四种图形

`bar` 柱、`line` 折线、`area` 面积（带极淡的渐变）、`step` 阶梯线。折线和面积的纵轴范围贴着数据的最小到最大值，起伏更明显；柱图从 0 开始。

<ComponentPreview name="mini-chart-types-demo" />

### 横轴与强调

`showAxis` 打开极简横轴：11px 刻度，没有轴线和刻度线，只保留首尾和间隔均匀的标签。`tickFormatter` 把标签变成想要的样子，星期轴用单字「一…日」。柱图的 `highlight` 强调一根（下标、`"last"` 或 `"max"`），其余变淡；`track` 给每根柱加上底槽。

<ComponentPreview name="mini-chart-axis-demo" />

### 涨跌配色

`tone="trend"` 按首尾两点自动选涨色或跌色。颜色来自 `--stat-up` / `--stat-down`，由 `convention` 切换绿涨红跌与红涨绿跌，用法见 [统计卡片](/components/stat-card#涨跌配色约定)。

<ComponentPreview name="mini-chart-trend-demo" />

### 进度环

`MiniRing` 是纯 SVG，没有用图表库：`arc` 控制圆弧总角度（360 是整圆，270 是下方留口的仪表），`thickness` 控制粗细，`children` 替换中央的默认百分比。

<ComponentPreview name="mini-chart-ring-demo" />

### 环形图

`MiniDonut` 画几个分类的占比，分段之间留 2° 的缝，悬停有提示框，中央放合计。图例由你自己写，颜色按顺序对应默认色板。

<ComponentPreview name="mini-chart-donut-demo" />

## API

### MiniChart

<PropsTable name="mini-chart" component="MiniChart" />

根元素 `data-slot="mini-chart"`，带 `data-type`；图形颜色通过 shadcn `ChartContainer` 注入 `--color-value`。

### MiniRing

<PropsTable name="mini-chart" component="MiniRing" />

### MiniDonut

<PropsTable name="mini-chart" component="MiniDonut" />

## 可访问性

- 图表本身是 `role="img"`，名称来自 `label`；数据通过悬停提示框读取，需要精确数值请同时在文字里写出（如卡片里的大号数字）。
- `MiniRing` 是 `role="meter"`，带 `aria-valuenow` 和 `aria-valuemax`。
- 开启「减少动态效果」后，recharts 的入场动画关闭，进度环不播放入场动画；进度环由服务端直接输出最终弧长，没有脚本也完整显示。
- 涨跌趋势不只靠颜色：请在旁边配 [`StatTrend`](/components/stat-card) 这样带箭头和文字的元素。

## 注意事项

- 图表由 `ResponsiveContainer` 撑满父级，服务端渲染时先按 160×64 占位，水合后量出真实尺寸；父级必须有确定宽度。
- 同一页面放很多迷你图时，给不需要提示框的设置 `showTooltip={false}`，可以省掉事件监听。
- 提示框的数值用 `format`（`StatFormatOptions`）格式化，默认 `zh-CN` 压缩。

## 源码

<ComponentSource name="mini-chart" />

---

# 轨道环绕

来源：https://yiui.dev/components/orbit/

<ComponentPreview name="orbit-demo" />

## 安装

<InstallCommand name="orbit" />

## 用法

用 `OrbitRing` 定义轨道，用 `OrbitItem` 放入任意非交互节点。同一圈的节点通过 `angle` 分开，位置变化时内容始终保持正向。

```tsx title="components/orbit-example.tsx"
import {
  Orbit,
  OrbitRing,
  OrbitItem,
  OrbitCenter,
} from "@/components/ui/orbit/orbit"

export function OrbitExample() {
  return (
    <Orbit label="工具围绕核心环绕">
      <OrbitRing radius={100} duration={24}>
        <OrbitItem>01</OrbitItem>
        <OrbitItem angle={180}>02</OrbitItem>
      </OrbitRing>
      <OrbitCenter>核心</OrbitCenter>
    </Orbit>
  )
}
```

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整速度、轨道线样式、色调与底纹，并开关整体反向与暂停；这些都是对示例里所有轨道的整体覆盖，未改动的项显示示例自己的取值。调整时外框与画布大小不变。

### 半弧

`arc="half"` 保留上半圆，并在地平线处渐隐。节点继续沿整圆运动，在下半圆时隐藏。配合 `anchor="bottom"` 把轨道中心放到外框底边，高度只留给上半部分，适合放在区块底部。`OrbitCenter` 默认在轨道中心，示例用 `-translate-y-[calc(100%+0.5rem)]` 把标签抬到地平线上方。

<ComponentPreview name="orbit-half-demo" />

### 色调

`OrbitRing` 的 `tone` 给轨道线上色，`OrbitItem` 的 `tone` 给节点上色，两者互不影响；不传 `tone` 的轨道沿用主题线条色。底纹换成方格，中心用代码图标连接不同工具。

<ComponentPreview name="orbit-icons-demo" />

### 技术栈

节点可以放文字，追加 `w-auto px-3` 即可呈现胶囊式标签。宽标签需要给轨道两侧留出空间：示例的轨道半径取 96，窄屏下标签也不会被外框裁切。

<ComponentPreview name="orbit-stack-demo" />

## API

### Orbit

`size` 默认 `320`，表示正方形设计画布边长；容器更窄时画布缩小，轨道按比例缩放，节点文字保留原字号。外框默认高 `288px`，可以用 `className` 调整（画布 320 时建议 `h-80`，避免最外圈节点被裁切）。支持 `dots / grid / lines / hatch / none` 底纹。`anchor` 默认 `center`，`bottom` 让轨道中心落在外框底边。

<PropsTable name="orbit" component="Orbit" />

### OrbitRing

`radius` 默认 `100`，单位是设计像素；`duration` 默认 `24` 秒。`startAngle` 默认 `-90`，0 度在右侧，正值顺时针。`reverse` 改变运动方向。`tone` 只作用于轨道线，支持内置色调名或任意 CSS 颜色。父级或当前轨道 `paused` 时暂停，恢复后从当前角度继续。

<PropsTable name="orbit" component="OrbitRing" />

### OrbitItem

`angle` 是相对轨道起始角的偏移，默认 `0`。`tone` 默认 `foreground`，支持主题色及 `blue / green / amber / rose / violet / cyan`。必须置于 `OrbitRing` 内。

<PropsTable name="orbit" component="OrbitItem" />

### OrbitCenter

将内容放在画布正中央，自行组合标志、图标或文字。

<PropsTable name="orbit" component="OrbitCenter" />

## 可访问性

- 默认作为装饰隐藏；传入 `label` 后使用 `role="img"` 和文字说明，说明应概括整张图。
- 图示内不放按钮或链接，避免隐藏内容仍可获得键盘焦点。
- 尊重系统“减少动态效果”，以指定的起始角展示静帧；离开视口时自动暂停。
- 色调之外请用图标或文字区分节点；轨道线的颜色只是装饰。

## 注意事项

- 调整面板通过 `OrbitTuningContext` 覆盖子树里的 `paused`、`background` 和每条轨道的速度、方向、`dashed`、`tone`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。
- 动画由 `motion/react` 的 MotionValue 驱动，不逐帧触发 React 渲染。服务端首帧不依赖随机值或浏览器尺寸，可用于静态导出。
- 底纹、`--edge` 和多彩变量由 `flow-diagram` 的 registry 依赖一并提供，手动安装时也需要这些依赖。
- 所有同圈节点默认在同一位置，请显式设置不同 `angle`。最大半径加节点半宽应小于可用画布尺寸的一半；超出的部分由外框裁切。

## 源码

<ComponentSource name="orbit" />

---

# 波纹脉冲

来源：https://yiui.dev/components/ripple/

<ComponentPreview name="ripple-demo" />

## 安装

<InstallCommand name="ripple" />

## 用法

`pulse` 模式让波纹持续向外扩散，`reach` 模式保留固定圆环并轻轻改变透明度。内容通过 `RippleMarker` 按角度和半径定位，`radius={0}` 表示中心。`tone` 给波纹上色，同时写入 `--flow-tone`，标记里可以直接用 `bg-(--flow-tone)` 取同一个颜色。页首的预览是 `pulse` 模式加四个地区标记：波纹持续扩散，标记按延迟远近落在不同半径上。

```tsx title="components/ripple-example.tsx"
import { Ripple, RippleMarker } from "@/components/ui/ripple/ripple"

export function RippleExample() {
  return (
    <Ripple mode="reach" label="服务覆盖范围">
      <RippleMarker radius={0}>中心</RippleMarker>
      <RippleMarker angle={45} radius={0.8} node="华东" />
    </Ripple>
  )
}
```

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整模式、环数、环间距、周期与色调，并开关暂停；未改动的项显示示例自己的取值。调整时外框与设计画布大小不变，环数和间距只改变圆环本身。

### 在线状态

`tone="green"` 让脉冲呈绿色，头像上的状态点取同一个 `--flow-tone`；在线状态同时通过文字表达。

<ComponentPreview name="ripple-online-demo" />

### 只有中心

最小用法：一个中心标记加 `tone`，波纹与中心标记同色。

<ComponentPreview name="ripple-pulse-demo" />

### 固定圆环

`mode="reach"` 保留固定圆环，便于比较距离。中心展示信号状态，圆环旁用距离刻度说明覆盖范围，背景使用轻斜纹。圆环直径 100 / 200 / 300，`RippleMarker` 的 `radius` 取 1/3、2/3、1，刻度正好落在对应圆环上。

<ComponentPreview name="ripple-signal-demo" />

## API

### Ripple

<PropsTable name="ripple" component="Ripple" />

默认 `rings={4}`、`ringGap={48}`、`baseSize={48}`、`duration={4}`、`mode="pulse"`。不传 `tone` 时波纹沿用主题线条色。`ringGap` 表示相邻圆环的**直径差**，最外圈直径为 `baseSize + (rings - 1) × ringGap`；脉冲模式扩散到再外一圈后淡出。数量限制为 1–24，负间距按 0 处理，时长最小 0.1 秒。

`size` 默认 `320`，表示设计画布边长。容器更窄时圆环与标记位置等比缩小，内容字号保持不变。外框默认高 `288px`，可用 `className` 调整。底纹支持 `dots / grid / lines / hatch / none`。

### RippleMarker

<PropsTable name="ripple" component="RippleMarker" />

`angle` 默认 `0`，0 度在上方，正值顺时针。`radius` 默认 `1`，相对于最外圈半径：0 在中心，1 在最外圈，大于 1 在圆环外。`node` 和 `children` 均可承载内容，同时传入时使用 `node`。

## 可访问性

- 默认作为装饰隐藏；传入 `label` 后以图片语义朗读概括说明。
- 内容应是非交互元素，图示不产生键盘焦点。
- 系统开启“减少动态效果”时显示错开的完整静帧；离开视口或 `paused` 时停止计时，恢复后继续。
- 状态用文字配合颜色表达，数字有明确的单位说明。

## 注意事项

- 调整面板通过 `RippleTuningContext` 覆盖子树里 `Ripple` 的 `rings`、`ringGap`、`baseSize`、`mode`、`duration`、`paused`、`background` 与 `tone`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。
- 动画由共享 MotionValue 推导，每帧不触发 React 渲染。服务端输出确定性的同心环，不使用随机粒子，可用于静态导出。
- `RippleMarker` 应放在 `Ripple` 内。它按设计画布定位，不会跟随脉冲伸缩；覆盖关系明确的场景建议使用 `reach`。
- 大半径或长标签可能被容器边缘裁切，请预留标记尺寸。高度可以按使用场景调整，小格子中建议减少环数。
- 底纹和变量依赖 `flow-diagram` registry 条目，安装时会一并提供；手动安装时需自行引入对应工具类和变量。

## 源码

<ComponentSource name="ripple" />

---

# 分段选择

来源：https://yiui.dev/components/segmented-control/

<ComponentPreview name="segmented-control-demo" />

## 安装

<InstallCommand name="segmented-control" />

## 用法

```tsx title="components/view-switch.tsx"
import { LayoutGrid, List } from "lucide-react"
import { useState } from "react"
import { SegmentedControl } from "@/components/ui/segmented-control/segmented-control"

const OPTIONS = [
  { value: "list", label: "列表", icon: <List /> },
  { value: "grid", label: "网格", icon: <LayoutGrid /> },
]

export function ViewSwitch() {
  const [view, setView] = useState("list")

  return (
    <SegmentedControl
      aria-label="视图"
      options={OPTIONS}
      value={view}
      onValueChange={setView}
    />
  )
}
```

`options` 是必需项，值是字符串。传 `value` 与 `onValueChange` 走受控；只传 `defaultValue`（或都不传，此时落在第一项）由组件自己管。

### 结构与语义

外框是方条：细边框（`border-edge`）、小圆角、`bg-muted/60` 的淡底，和数值滑块同一副外观。每个选项是一个 `Radio.Root`，整块可点；选中时选项背后滑入一块 `segmented-control-indicator`，用 Motion 的共享布局动画在选项之间滑动，不会闪一下再出现。

`label` 是方条左侧的纯文字（与数值滑块、开关的标签同一种写法），选项则收进右侧一道微微下凹的槽里，选中项是槽里凸起的一块，字段名与可选项一眼分得开。`label` 同时作为整个单选组的可访问名称（`aria-labelledby`），写了它就不必再写 `aria-label`；不写 `label` 时整条都是选项，没有这道槽。

```tsx
<SegmentedControl label="对齐" options={ALIGN_OPTIONS} defaultValue="left" />
```

### 高度与色调

`variant` 与 `size` 共同决定高度，两档与数值滑块完全一致，放在同一个面板里能对齐：

| `variant` | `sm` | `default` | `lg` |
| --------- | ---- | --------- | ---- |
| `bar`     | 28px | 32px      | 36px |
| `compact` | 18px | 22px      | 24px |

`compact` 同时把字号收到 `text-xs`，适合挤在调整面板里的一排排参数。

`tone` 给选中块染上一档淡色。它会把 `--flow-tone` 写在根元素上，所以子树里其他读同一个变量的图形也会跟着变色。不传 `tone` 时选中块用背景色加一圈细描边，在浅色底上像一块浮起的白色贴片。

```tsx
<SegmentedControl
  aria-label="时间范围"
  tone="blue"
  size="sm"
  options={OPTIONS}
/>
```

### 选项里的小样

`icon` 是选项文字前的小样，放图标、色点、材质方块都行；它包在 `aria-hidden` 的容器里，读屏只念 `label`。图标尺寸默认收到 14px（`size-3.5`），自己给 `size-*` 可以覆盖。

```tsx
const OPTIONS = [
  { value: "cool", label: "冷色", icon: <Swatch tones={["blue", "cyan"]} /> },
  { value: "warm", label: "暖色", icon: <Swatch tones={["amber", "rose"]} /> },
]
```

## 示例

### 色调

访问量卡片上的时间范围切换。`tone="blue"` 只给选中块染上一档淡蓝；下面那条柱状图自己拿 `--flow-tone` 取色，和选中块用的是同一个变量。

<ComponentPreview name="segmented-control-tone-demo" />

### 左侧标签

`label` 是左侧的字段名，选项在右侧的槽里，读起来像「字段名 + 取值」。下面把对齐方式直接套在段落上，看得见这一行确实在起作用。

<ComponentPreview name="segmented-control-label-demo" />

### 小样

选项文字前的 `icon` 换成两个色点，「中性 / 冷色 / 暖色」一眼可辨。色点对读屏隐藏，信息仍由文字承担。

<ComponentPreview name="segmented-control-swatch-demo" />

## API

### SegmentedControl

<PropsTable name="segmented-control" component="SegmentedControl" />

除上表外，其余属性直接交给 Base UI 的 `RadioGroup.Root`：`disabled`（整组禁用，选中块与文字一起淡到 50%）、`aria-label`、`required` 等。

### segmentedControlVariants

`cva` 生成的根元素样式函数，有 `size` 与 `variant` 两个变体。写自己的包装层时可以复用它，高度通过根元素上的 `--segmented-control-height` 变量传给内部。

```ts
const segmentedControlVariants: (props?: {
  size?: SegmentedControlSize
  variant?: SegmentedControlVariant
}) => string
```

### 类型

```ts
type SegmentedControlSize = "sm" | "default" | "lg"

type SegmentedControlVariant = "bar" | "compact"

type SegmentedControlOption = {
  value: string
  label: React.ReactNode
  /** 文字前的小样：图标、色点、材质方块 */
  icon?: React.ReactNode
  disabled?: boolean
}

type SegmentedControlProps = Omit<
  React.ComponentProps<typeof RadioGroup>,
  "value" | "defaultValue" | "onValueChange" | "children"
> & {
  options: readonly SegmentedControlOption[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  label?: React.ReactNode
  variant?: SegmentedControlVariant
  size?: SegmentedControlSize
  tone?: FlowTone
  modified?: boolean
  className?: string
  style?: React.CSSProperties
}
```

## data-slot

| 元素                              | `data-slot`                   |
| --------------------------------- | ----------------------------- |
| 根元素                            | `segmented-control`           |
| 左侧标签                          | `segmented-control-label`     |
| 选项槽（有 `label` 时带凹槽底色） | `segmented-control-options`   |
| 选项                              | `segmented-control-item`      |
| 选中块                            | `segmented-control-indicator` |

根元素始终带 `data-variant`（`bar` / `compact`），`modified` 为真时带 `data-modified`，禁用时带 `data-disabled`；选项上是 Base UI 给的 `data-checked`、`data-disabled`。

## 可访问性

- 语义是单选组：根元素是 `role="radiogroup"`，每个选项是 `role="radio"`，选中状态由 `aria-checked` 表达。方向键在选项间移动并**直接选中**（不是「移过去再空格确认」）。
- 组的名称取自 `label`（`aria-labelledby`）；没写 `label` 时请务必给 `aria-label`，否则读屏只能念出一个没有名字的单选组。
- 选项的小样是装饰，`aria-hidden`；选项文字才是名称。
- 键盘焦点在选项上时有一圈 `focus-visible` 焦点环，并临时抬高 `z-index`，不会被旁边滑过来的选中块盖住。
- `modified` 只有配 `label` 时才有可见效果（标签从次要色变成前景色）；没有 `label` 时只留下 `data-modified`，供外界用选择器自己加样式。

## 注意事项

- 同一页里可能有多个分段选择，选中块的共享布局 id 用 `React.useId()` 各自生成，动画不会串到另一个组上。
- 系统开启「减少动态效果」时，选中块直接跳到位，不做滑动。
- 选项文字不换行（`whitespace-nowrap` + `truncate`），选项太多太窄时优先缩短文字，不要靠缩小字号。
- 值是字符串。需要数字或其他类型时在 `onValueChange` 里自己转，或者用 `String(value)` 存选项的 `value`。
- 受控 / 非受控共用一个 `useControllableState`；`options` 变化后如果当前值已不存在，组件不会自动改选，请在父级同步。
- `tone` 的颜色变量由 `flow-diagram` 条目提供，安装时会一并拉取。

## 源码

<ComponentSource name="segmented-control" />

---

# 动态格

来源：https://yiui.dev/components/shuffle-grid/

<ComponentPreview name="shuffle-grid-demo" />

## 安装

<InstallCommand name="shuffle-grid" />

## 用法

`items` 是条目池，每个条目有唯一的 `id`、可选的 `content`（图标、头像、任意节点）和 `tone`。`rows`、`cols` 决定盘面大小，`activeCount` 决定同时在场几个。组件每隔 `interval` 毫秒走一步：补一个、拿掉一个、换个格子或两个互换，每步只动一两个格子，画面始终是渐变的。

```tsx title="components/shuffle-grid-example.tsx"
import { Braces, Database, Globe } from "lucide-react"
import { ShuffleGrid } from "@/components/ui/shuffle-grid/shuffle-grid"

const ITEMS = [
  { id: "ts", tone: "blue", content: <Braces /> },
  { id: "db", tone: "green", content: <Database /> },
  { id: "web", tone: "violet", content: <Globe /> },
]

export function ShuffleGridExample() {
  return (
    <ShuffleGrid
      label="技术图标在方格里随机出现并点亮"
      rows={2}
      cols={3}
      items={ITEMS}
      activeCount={2}
    />
  )
}
```

随机数来自 `seed`，同一个种子在服务端与浏览器的初始画面一致，演示数据也就确定；换一个种子得到另一张初始画面。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整换位间隔、在场数、点亮数与盘面外观，并开关暂停；未改动的项显示示例自己的取值。调整时盘面的宽高比固定为打开时的样子，切换盘面外观（间距不同）后容器大小不变。有分类的示例由分类决定谁在场，「在场数」不起作用。

### 团队分配

给 `groups` 传分类，格子下方出现可横向滚动的胶囊，点击或自动轮播都会切换分类，格子里的条目随之换位。同一个人属于多个分类时是滑动换位，不是消失再出现。头像用 `ShuffleGridAvatar`，只显示首字，不使用真人照片。

<ComponentPreview name="shuffle-grid-team-demo" />

### 像素块

不传 `content`，条目就是一块纯色方块；`variant="pixels"` 把格子收紧成像素风，`interval` 调小让它快速出没。

<ComponentPreview name="shuffle-grid-pixel-demo" />

## API

### ShuffleGrid

`variant` 有三种外观：`lines` 共享 1px 分隔线的整块网格（默认），`tiles` 独立的圆角格，`pixels` 紧凑的纯色像素块。`litCount` 控制同时点亮几个，点亮的条目用自己的 `tone`，其余是中性色；传 `"all"` 全部点亮。

分类相关：`value` / `defaultValue` / `onValueChange` 以分类 `id` 同时支持受控与非受控；`groupInterval` 设为 `0` 关闭自动轮播，用户手动选过后会多等一轮再继续。

<PropsTable name="shuffle-grid" component="ShuffleGrid" />

`ShuffleGridItem` 的字段：`id`、`content`、`tone`；`ShuffleGridGroup` 的字段：`id`、`label`、`items`（条目 `id` 的数组，数量不能超过格子数）。

### ShuffleGridAvatar

首字母头像：圆底加一个字，亮起时换成条目的色调。放进 `content`，大小随格子自适应，也可以用 `className` 指定。

<PropsTable name="shuffle-grid" component="ShuffleGridAvatar" />

## 可访问性

- 盘面默认作为装饰隐藏；传 `label` 后以图片语义朗读概括说明。内容是随机变化的，不会逐个朗读。
- 分类胶囊是真正的按钮，用 `aria-pressed` 表达选中状态，Tab 可达，焦点环可见；读屏名称用 `groupsLabel` 改。
- 系统开启「减少动态效果」时不洗牌、不自动轮播，格子停在初始画面；手动点胶囊时直接切换，没有滑动。
- 离开视口或 `paused` 时停止所有定时器。

## 注意事项

- 调整面板通过 `ShuffleGridTuningContext` 覆盖子树里 `ShuffleGrid` 的 `interval`、`activeCount`、`litCount`、`variant` 与 `paused`，并用 `onReport` 回报示例自己的取值；`stableFrame` 让盘面按打开时的宽高比铺满，切换 `variant` 不改变容器大小。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。
- 同一条目在分类间换位用的是 `motion` 的共享布局动画，条目 `id` 在同一个盘面里必须唯一。
- 格子是正方形（`aspect-square`），盘面宽度由外层决定；`cols` 很大时单格会变小，图标大小可以通过 `content` 自行指定。
- 点亮的色调来自 `--flow-*` 变量，依赖 `flow-diagram` 条目，安装时会一并提供。

## 源码

<ComponentSource name="shuffle-grid" />

---

# 统计卡片

来源：https://yiui.dev/components/stat-card/

<ComponentPreview name="stat-card-demo" />

## 安装

<InstallCommand name="stat-card" />

## 用法

统计卡片不是一个大组件，而是一组小原语：`StatCard` 提供外壳，其余按需要拼进去。同一份数据在不同卡片里长什么样，由你选哪几块决定。

```tsx title="app/stats.tsx"
import {
  StatCard,
  StatHeader,
  StatLabel,
  StatTrend,
  StatValue,
} from "@/components/ui/stat-card/stat-card"

export function Stats() {
  return (
    <StatCard>
      <StatHeader>
        <StatLabel>API 调用量</StatLabel>
      </StatHeader>
      <StatValue value={12840000} unit="次" />
      <StatTrend value={12.4}>较上周</StatTrend>
    </StatCard>
  )
}
```

`StatValue` 收到数字时用 `formatStat` 格式化：默认按 `zh-CN` 压缩，`12840000` 显示为 `1284万`，单位 `unit` 跟在数字后面，字号更小、颜色更淡。数字一律 `tabular-nums`，涨跌时宽度不抖。

| 原语 | 用途 |
| --- | --- |
| `StatCard` / `StatGroup` | 卡片外壳 / 只设置涨跌配色约定的容器 |
| `StatHeader` / `StatLabel` / `StatIcon` | 标题行、指标名、图标方块 |
| `StatValue` / `StatTrend` / `StatMeta` | 大号数字、涨跌幅、两端对齐的说明行 |
| `StatStatus` / `StatBadge` | 状态行（图标 + 两行文字）、状态徽标 |
| `StatProgress` / `StatMeter` | 进度条、分格计量条 |
| `StatSegments` / `StatDistribution` | 横向分段条、分段条加图例格 |
| `StatZones` | 分区表（快 / 正常 / 慢 / 严重） |

## 示例

### 概览面板

四块统计共用细线拼成一块面板：KPI 与迷你走势、配额进度、分格健康度、流量来源分布。

<ComponentPreview name="stat-card-overview-demo" />

### 目标与状态

`StatStatus` 是卡片底部的一行：状态图标方块、说明文字和状态名。状态有四种——`ok` 达标、`watch` 关注、`risk` 风险、`review` 审核中，各自带固定的图标和色调；加 `render={<a href="…" />}` 与 `showChevron` 就成了一个入口。

<ComponentPreview name="stat-card-goal-demo" />

### 配额与进度

`StatProgress` 的 `tone="usage"` 按用量自动变色：65% 起关注、90% 起风险。`usageStatus` 和 `healthStatus` 把百分比换成状态名，可以拿去驱动 `StatBadge`。

<ComponentPreview name="stat-card-quota-demo" />

### 延迟分区

`StatZones` 展示「落在哪一档」的分布：每行一根彩色竖条、分区名、区间和占比。默认颜色按绿、蓝、琥珀、玫红排列，也可以逐行指定 `tone`。

<ComponentPreview name="stat-card-latency-demo" />

### 占比分布

`StatDistribution` 把合计、分段条和图例格放在一起，图例同时写出占比与数值。只想要那条分段条时用 `StatSegments`，或设置 `legend={false}`。

<ComponentPreview name="stat-card-distribution-demo" />

### 分格计量

`StatMeter` 是 N 个小格，按值从左向右依次点亮；颜色默认按健康度变化，低于 40% 风险、低于 75% 关注。

<ComponentPreview name="stat-card-health-demo" />

### 涨跌配色约定

涨跌色有两套习惯：国际通用绿涨红跌，国内行情软件红涨绿跌。组件不把颜色写死，只读 `--stat-up` / `--stat-down` 两个 CSS 变量，由 `convention` 改写：

- `intl`（默认）：绿涨红跌；
- `cn`：红涨绿跌。

变量沿 DOM 向下继承，所以在最外层的 `StatGroup`（或任意一张 `StatCard`）上设置一次，里面所有涨跌幅都会跟着变，包括 [迷你图](/components/mini-chart) 与 [图表卡片](/components/chart-card) 里的涨跌色。涨跌之外的状态色（达标 / 风险）不受它影响，达标永远是绿、风险永远是红。

<ComponentPreview name="stat-card-convention-demo" />

延迟、错误率这类「越低越好」的指标，给 `StatTrend` 加 `invert`：下降用「好」的颜色，箭头方向不变。上面第三张卡片就是这样用的：切到红涨绿跌后，延迟下降显示为红色，因为红色在这一套约定里是「好」的颜色。

### 数字格式

`formatStat` 是独立的工具函数，卡片内部用的就是它：

```tsx
import { formatStat } from "@/lib/data-display"

formatStat(12480) // "1.2万"
formatStat(345000000) // "3.5亿"
formatStat(12480, { locale: "en" }) // "12.5K"
formatStat(1250000, { style: "currency" }) // "¥125万"
formatStat(12.5, { style: "percent" }) // "12.5%"，传入的是百分点
formatStat(6.2, { style: "percent", sign: true }) // "+6.2%"
```

## API

### StatCard

<PropsTable name="stat-card" component="StatCard" />

根元素 `data-slot="stat-card"`，设置 `convention` 时带 `data-convention`。

### StatGroup

<PropsTable name="stat-card" component="StatGroup" />

### StatIcon

<PropsTable name="stat-card" component="StatIcon" />

### StatValue

<PropsTable name="stat-card" component="StatValue" />

### StatTrend

<PropsTable name="stat-card" component="StatTrend" />

根元素带 `data-trend="up" | "down" | "flat"`。

### StatStatus

<PropsTable name="stat-card" component="StatStatus" />

根元素带 `data-status`。

### StatBadge

<PropsTable name="stat-card" component="StatBadge" />

### StatProgress

<PropsTable name="stat-card" component="StatProgress" />

### StatMeter

<PropsTable name="stat-card" component="StatMeter" />

### StatSegments

<PropsTable name="stat-card" component="StatSegments" />

### StatDistribution

<PropsTable name="stat-card" component="StatDistribution" />

### StatZones

<PropsTable name="stat-card" component="StatZones" />

`StatHeader`、`StatLabel`、`StatMeta` 只是带样式的容器，属性同对应的原生元素。

### 工具函数

| 函数 | 说明 |
| --- | --- |
| `formatStat(value, options)` | 数字格式化，`options` 为 `style`、`locale`、`compact`、`currency`、`digits`、`sign` |
| `formatDay(date, style, locale)` | 日期轴文字：`long` → `2月14日`，`short` → `02/14`，`weekday` → `一` |
| `createAxisFormatter(max, options)` | 按整条轴统一单位的刻度格式化：最大值 ≥ 1 万时所有刻度都用「万」（`9000` 显示为 `0.9万`），≥ 1 亿用「亿」；`en` 换成 K / M / B |
| `usageStatus(percent)` / `healthStatus(percent)` | 百分比换成 `ok` / `watch` / `risk`，分别是「越高越危险」和「越高越好」两种口径 |

这些工具随条目一起安装到 `lib/data-display.ts`，[迷你图](/components/mini-chart) 和 [图表卡片](/components/chart-card) 共用同一份。

## 可访问性

- 进度条是 `role="progressbar"`，计量条与进度环是 `role="meter"`，都带 `aria-valuenow` 等取值，并用 `label` 提供读屏名称。
- 涨跌幅同时有箭头图标和 `sr-only` 的「上升 / 下降 / 持平」；状态行、徽标永远带文字，颜色不是唯一信息。
- 分段条是 `role="img"`，名称默认把每段的占比念出来；图例格写明占比与数值。
- 进度条、计量条、分段条的入场动画在系统开启「减少动态效果」时直接到位。

## 注意事项

- 小数位与压缩单位由 `Intl.NumberFormat` 决定：`zh-CN` 是「万 / 亿」，`en` 是 K / M / B。`Intl` 实例按参数缓存，反复格式化没有额外开销。
- 日期轴按 UTC 解析与输出，`"2026-02-14"` 这样的字符串在任何时区得到同样的文字，静态导出的 HTML 与客户端首屏一致。
- 进度条、计量条、分段条服务端直接输出最终宽度和点亮的格数，入场动画是纯 CSS（`@keyframes`，样式由组件以 `<style href precedence>` 提供，React 19 会去重并提升到 `<head>`），没有脚本也完整显示。

## 源码

<ComponentSource name="stat-card" />

---

# 文字动效

来源：https://yiui.dev/components/text-animate/

import Example0 from "@/registry/examples/text-animate-demo"
import Example1 from "@/registry/examples/text-animate-flip-demo"
import Example2 from "@/registry/examples/text-animate-reveal-demo"
import Example3 from "@/registry/examples/text-animate-scramble-demo"
import Example4 from "@/registry/examples/text-animate-highlight-demo"
import Example5 from "@/registry/examples/text-animate-mixed-demo"

<noscript>
  <style>{`[data-text-animate-script-preview] { display: none } [data-no-script-demo] button { display: none }`}</style>
</noscript>

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example0 />
  </div>
</noscript>

## 安装

<InstallCommand name="text-animate" />

## 用法

四个原语可以单独使用，也可组合成一个标题。服务端直接输出可读文字，动画在客户端增强。

```tsx title="components/text-animate-example.tsx"
import {
  TextFlip,
  TextReveal,
  TextScramble,
  TextHighlight,
} from "@/components/ui/text-animate/text-animate"

export function TextAnimateExample() {
  return (
    <div>
      <h2>
        把界面写成 <TextFlip words={["组件", "积木", "系统"]} />
      </h2>
      <p>
        <TextReveal>让每个想法都有形状。</TextReveal>
      </p>
      <p>
        <TextScramble trigger="hover">构建完成</TextScramble>
      </p>
      <p>
        从 <TextHighlight>细节</TextHighlight> 开始。
      </p>
    </div>
  )
}
```

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整轮换间隔、显现单位、错峰、解码时长、字符集与高亮色调，并开关轮换暂停；每项只作用于当前示例中相关的文字原语；未改动的项显示示例自己的取值。调整时预览画框大小不变。

### 关键词轮换

胶囊与下划线两种外观。隐藏测量层跟随字体和当前词条尺寸，用 250ms 过渡容器宽度。

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-flip-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example1 />
  </div>
</noscript>

### 分字与分词显现

`Intl.Segmenter` 按字素或词切分，保留空格、标点与组合字符。点击按钮重新挂载即可重播。

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-reveal-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example2 />
  </div>
</noscript>

### 乱码解码

字符从乱码逐步落定为目标文字，不模拟打字光标。支持中文目标文本；悬停与键盘聚焦都能重播。

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-scramble-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example3 />
  </div>
</noscript>

### 高亮扫过

文字保持可读，只让底部色块从左向右展开。色调使用主题变量，与页面亮暗模式一起变化。

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-highlight-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example4 />
  </div>
</noscript>

### 中英混排

中文、英文和日文词条可共用一组轮换。分词显现保留原始文本的空格。

<div data-text-animate-script-preview>
  <ComponentPreview name="text-animate-mixed-demo" />
</div>
<noscript>
  <div
    data-no-script-demo
    className="my-4 overflow-hidden rounded-lg border border-edge p-4"
  >
    <Example5 />
  </div>
</noscript>

## API

### TextFlip

<PropsTable name="text-animate" component="TextFlip" />

`words` 为词条数组，空数组渲染为空。`interval` 默认 `2600ms`，最小 `800ms`；`variant` 为 `pill`（默认）或 `underline`，`tone` 换胶囊与下划线的色调（默认 `primary`，其余同 `TextHighlight`）。`children` 可传入屏幕阅读器完整替代文案，否则朗读全部候选词。`paused` 可暂停轮换。离屏、页面隐藏或系统减少动态效果时停止轮换。

### TextReveal

<PropsTable name="text-animate" component="TextReveal" />

`children` 为纯文本。`by` 默认 `char`，支持 `word`；`locale` 默认 `zh-CN`，影响分词规则。中文逐字用 `char`，中英混排按词可用 `word`。`trigger` 默认 `in-view`，也可用 `mount`；每次挂载只播放一次。`stagger` 默认 `35ms`，每片段显现持续 `500ms`。

### TextScramble

<PropsTable name="text-animate" component="TextScramble" />

`children` 为最终纯文本。`trigger` 支持 `mount / hover / in-view`（默认）；`duration` 默认 `1000ms`，最小 `100ms`。`charset` 支持 `latin / digits / symbols / katakana / chinese`；`characters` 传入自定义字符集，空值回退为预设。字符按字素切分，空白不扰动，乱码不参与布局计算。

### TextHighlight

<PropsTable name="text-animate" component="TextHighlight" />

`variant` 为 `block`（默认）或 `underline`，`trigger` 为 `mount / in-view`（默认）。`tone` 默认 `primary`，也支持 `foreground / muted / destructive / blue / green / amber / rose / violet / cyan`；多彩色调来自 `--flow-*` 变量。可在句子里仅包裹关键词。

### 调整 Context

`TextAnimateTuningContext` 接收 `TextAnimateTuning` 覆盖项；`onReport(report: TextAnimateReport)` 回报覆盖前的实际属性。 多种原语共用同一覆盖层，回报按属性汇总；同一属性取第一个原语的值。当前示例没有的原语对应控件显示默认值。显现单位或错峰改变时自动重播显现；解码参数改变后，悬停示例需再次悬停或聚焦。

## 可访问性

- 轮换、分字和乱码组件将动画层设为 `aria-hidden`，单独提供完整文本，读屏不会逐帧朗读。
- 高亮不拆分原文，按正常文本顺序朗读。颜色不是传达内容的唯一方式。
- `hover` 解码也支持键盘聚焦，并提供可见的焦点环。
- 开启“减少动态效果”后显示完整文字，不轮换、不扰动、不模糊。无 JS 时同样保留原文和首个轮换词。
- 自动轮换适合短标题；关键信息应在固定正文中另有说明。

## 注意事项

- 调整面板通过 `TextAnimateTuningContext` 覆盖子树里的 `interval`、`by`、`stagger`、`duration`、`charset`、`tone`、`paused`，并用 `onReport` 回报示例自己的取值。不包这一层时组件行为不变；它面向调试与文档，正常使用不需要。

- 显现与高亮由带 `href` / `precedence` 的去重样式驱动；默认入场前文本也是可见的，避免脚本失败造成空白。
- `TextFlip` 在当前词上测量，不会为最长词预留固定宽度。请让所在句子可自然换行，避免容器过窄时放入超长且不换行的词条。
- `Intl.Segmenter` 需要现代浏览器。组件不创建实时播报区域，以免装饰性动画打断阅读。
- 色调复用 `flow-diagram`，安装时会一并提供相关变量。

## 源码

<ComponentSource name="text-animate" />

---

# 时间线

来源：https://yiui.dev/components/timeline/

<ComponentPreview name="timeline-demo" />

## 安装

<InstallCommand name="timeline" />

## 用法

`Timeline` 是有序列表；每项由标记、连接线和内容组成。把 `TimelineTime` 放进 `TimelineItem.time`，就能得到左侧的窄编号栏。把它放在标题旁，则是活动流的布局。

```tsx title="components/timeline-example.tsx"
import {
  Timeline,
  TimelineItem,
  TimelineMarker,
  TimelineConnector,
  TimelineContent,
  TimelineTitle,
  TimelineTime,
  TimelineDescription,
} from "@/components/ui/timeline/timeline"

export function TimelineExample() {
  return (
    <Timeline aria-label="项目里程碑">
      <TimelineItem time={<TimelineTime dateTime="2026">2026</TimelineTime>}>
        <TimelineMarker>01</TimelineMarker>
        <TimelineConnector />
        <TimelineContent>
          <TimelineTitle>发布第一个版本</TimelineTitle>
          <TimelineDescription>
            把反复使用的交互整理成组件。
          </TimelineDescription>
        </TimelineContent>
      </TimelineItem>
    </Timeline>
  )
}
```

## 示例

### 经历

给 `TimelineItem` 传 `time`，标记左边多出一列窄的时间栏，适合年份、日期这类用来定位的信息。标记不放内容时默认是一个小圆点。

<ComponentPreview name="timeline-experience-demo" />

### 活动流

标题与相对时间在同一行，窄屏可自然换行。附件槽可放文件胶囊、人物卡或首字母头像组。这里的相对时间是固定演示数据；真实应用需要由调用方更新。

<ComponentPreview name="timeline-activity-demo" />

### 项目进度

`done` 的后续线段为实线，`current / upcoming` 的后续线段为虚线。当前项具有 `aria-current="step"`；给标记也传入 `status="current"` 可开启轻微脉冲。

<ComponentPreview name="timeline-progress-demo" />

### 水平路线图

`orientation="horizontal"` 在 640px 及以上横排，窄屏退回纵向，避免压缩标题或产生横向滚动。

<ComponentPreview name="timeline-horizontal-demo" />

### 交替更新日志

`align="alternate"` 在宽屏把偶数项放在轴线左侧，窄屏全部回到右侧。读取顺序始终按 DOM 的时间顺序。

<ComponentPreview name="timeline-alternate-demo" />

## API

### Timeline

`orientation` 默认 `vertical`，`align` 默认 `start`。`alternate` 仅对竖向布局生效。支持原生 `ol` 属性，包括 `aria-label`。

<PropsTable name="timeline" component="Timeline" />

### TimelineItem

`status` 默认 `done`，同时控制连接线和标记的基础状态。`time` 是左侧编号栏的插槽；水平模式下放到标记上方。

<PropsTable name="timeline" component="TimelineItem" />

### TimelineMarker

默认显示圆点，也可放图标或数字。`tone` 支持 `primary / foreground / muted / destructive` 和六个 `--flow-*` 色调；`status` 可覆盖外层状态。装饰标记默认对读屏隐藏，有独立语义时使用 `label`。

<PropsTable name="timeline" component="TimelineMarker" />

### TimelineConnector

放在 `TimelineItem` 的直接子级，自动延伸至下一项；最后一项的连接线自动隐藏。

<PropsTable name="timeline" component="TimelineConnector" />

### TimelineContent

内容列，最后一项自动移除底部留白。

<PropsTable name="timeline" component="TimelineContent" />

### TimelineTitle

默认使用 `h3`，继承原生标题属性。

<PropsTable name="timeline" component="TimelineTitle" />

### TimelineTime

原生 `time` 元素，等宽数字。显示文本由调用方提供，`dateTime` 使用机器可读日期。

<PropsTable name="timeline" component="TimelineTime" />

### TimelineDescription

13px 正文，宽松行高，继承原生 `p` 属性。

<PropsTable name="timeline" component="TimelineDescription" />

### TimelineAttachment

可换行的内容槽；内部可以放链接或按钮，交互语义由调用方提供。

<PropsTable name="timeline" component="TimelineAttachment" />

## 可访问性

- 使用有序列表表达事件顺序；标题、日期与说明保留原生语义。
- 当前阶段通过 `aria-current` 表达；状态同时使用文字或图标说明。
- 系统启用“减少动态效果”时，入场位移与脉冲停止。
- 内容初始可见，CSS 入场动画只移动位置，无 JavaScript 时仍能阅读。

## 注意事项

- 标记、连接线、内容应是 `TimelineItem` 的直接子级，不额外包一层布局容器。
- 交替与水平布局使用视口断点；嵌入很窄的桌面容器时建议使用默认纵向布局。
- `timeline.css` 随源码安装，不要移除入口文件对它的导入。多彩变量由 `flow-diagram` 依赖提供。

## 源码

<ComponentSource name="timeline" />

---

# 方条开关

来源：https://yiui.dev/components/toggle-switch/

<ComponentPreview name="toggle-switch-demo" />

## 安装

<InstallCommand name="toggle-switch" />

## 用法

```tsx title="components/autosave-switch.tsx"
import { useState } from "react"
import { ToggleSwitch } from "@/components/ui/toggle-switch/toggle-switch"

export function AutosaveSwitch() {
  const [autosave, setAutosave] = useState(true)

  return (
    <ToggleSwitch
      label="自动保存"
      description={autosave ? "已开启" : "已关闭"}
      tone="blue"
      checked={autosave}
      onCheckedChange={setAutosave}
    />
  )
}
```

整条方条都是开关，不用对准右侧的小轨道。`checked` / `defaultChecked` / `onCheckedChange` 直接来自 Base UI 的 `Switch.Root`，受控与非受控都按这一套写。

### 外观

- 关：`bg-muted/60` 的淡底、细边框，文字是次要色；右侧是一个灰色胶囊轨道，圆形手柄停在左端。
- 开：整条从左往右铺上一层淡色（`toggle-switch-fill` 用 `scale-x` 展开，和数值滑块的已选填充同一种淡），轨道变成实色，手柄滑到右端，文字提到前景色。

`tone` 决定铺色（`--flow-tone` 的 15%，暗色下 25%）与打开时轨道的颜色；不传时用前景色，得到最中性的一档。手柄直径随尺寸档变化：`bar` 为 12 / 14 / 16px，`compact` 为 8 / 10 / 12px，整条高度与数值滑块对齐。

```tsx
<ToggleSwitch label="高亮当前行" defaultChecked tone="violet" />
```

### 高度

`variant` 与 `size` 的对照表和数值滑块一致，同一行放控件时不会参差：

| `variant` | `sm` | `default` | `lg` |
| --------- | ---- | --------- | ---- |
| `bar`     | 28px | 32px      | 36px |
| `compact` | 18px | 22px      | 24px |

`compact` 把字号收到 `text-xs`，几行叠起来也不占地方，适合调整面板与密排的设置页。

### 说明文字

`description` 渲染在标签右侧、字号字重都小一档，通常放**当前状态**或**生效范围**（「已开启」「邮件」「需开启同步」）。它是按钮内容的一部分，所以读屏会把标签与说明连起来念；只想念标签时传 `aria-label`。

```tsx
<ToggleSwitch label="每周摘要" description="邮件" />
```

## 示例

### 密排

`variant="compact"` 收成 22px 高，六条加上 `gap-1` 也只占半张卡。密排时不带 `description`，一行只有一个标签，视线不会被切断。

<ComponentPreview name="toggle-switch-compact-demo" />

### 禁用态

总开关关着时，下面三项 `disabled`：整条淡到 50%，不响应点击与键盘。打开总开关，三项立刻可以操作；`description` 在同一个位置换成状态文案，说明为什么点不动。

<ComponentPreview name="toggle-switch-disabled-demo" />

## API

### ToggleSwitch

<PropsTable name="toggle-switch" component="ToggleSwitch" />

除上表外，其余属性直接交给 Base UI 的 `Switch.Root`：`checked`、`defaultChecked`、`onCheckedChange(checked, eventDetails)`、`disabled`、`name`、`required`、`aria-label` 等。`render`、`nativeButton`、`children` 被移除了——组件固定渲染成原生 `<button type="button">`。

### toggleSwitchVariants

`cva` 生成的根元素样式函数，有 `size` 与 `variant` 两个变体，高度通过根元素上的 `--toggle-switch-height` 变量传给内部。

```ts
const toggleSwitchVariants: (props?: {
  size?: ToggleSwitchSize
  variant?: ToggleSwitchVariant
}) => string
```

### 类型

```ts
type ToggleSwitchSize = "sm" | "default" | "lg"

type ToggleSwitchVariant = "bar" | "compact"

type ToggleSwitchProps = Omit<
  Switch.Root.Props,
  "render" | "nativeButton" | "children"
> & {
  /** 标签，也是开关的可访问名称 */
  label: React.ReactNode
  /** 标签右侧的补充说明（如当前状态「已开启」） */
  description?: React.ReactNode
  variant?: ToggleSwitchVariant
  size?: ToggleSwitchSize
  tone?: FlowTone
  modified?: boolean
}
```

## data-slot

| 元素         | `data-slot`                 |
| ------------ | --------------------------- |
| 根元素       | `toggle-switch`             |
| 打开时的铺色 | `toggle-switch-fill`        |
| 标签         | `toggle-switch-label`       |
| 说明文字     | `toggle-switch-description` |
| 小轨道       | `toggle-switch-track`       |
| 手柄         | `toggle-switch-thumb`       |

根元素上还有：`data-checked`（Base UI 给的选中状态）、`data-disabled`、`data-modified`，以及始终存在的 `data-variant`（`bar` / `compact`）。

## 可访问性

- 根元素是原生 `<button role="switch">`，开关状态由 `aria-checked` 表达；空格键与回车键都能切换，`Tab` 进入。
- 整条都是可点区域，命中区就是那个 28 / 32 / 36px 高的方条，比常见的滑块式开关大得多。
- 关闭时文字是次要色、打开时是前景色，铺色与手柄位置也同时变化——状态不只靠颜色。
- 可访问名称来自按钮内的文字，`label` 与 `description` 会连起来念。想让读屏只念标签，传 `aria-label`。
- 禁用时整条淡到 50%、光标变 `not-allowed`，并且从 Tab 顺序里移除（原生 `disabled`）。

## 注意事项

- 手柄的位移是固定的（`translate-x-4.5`），跟着固定的轨道宽度走；RTL 下方向反转。
- 铺色用 `scale-x` 展开，铺的是整条而不是轨道，视觉上像「点亮」而不是「拨动」。系统开启「减少动态效果」时铺色与手柄都瞬时切换。
- 组件是全宽元素（`w-full`），放进窄容器时由容器决定宽度；标签与说明都是 `truncate`，过长时截断而不是换行。
- `tone` 的颜色变量由 `flow-diagram` 条目提供，安装时会一并拉取。

## 源码

<ComponentSource name="toggle-switch" />

---

# 色调选择

来源：https://yiui.dev/components/tone-picker/

<ComponentPreview name="tone-picker-demo" />

## 安装

<InstallCommand name="tone-picker" />

## 用法

```tsx title="components/accent-picker.tsx"
import { useState } from "react"
import { TonePicker } from "@/components/ui/tone-picker/tone-picker"

export function AccentPicker() {
  const [tone, setTone] = useState("primary")

  return <TonePicker label="强调色" value={tone} onValueChange={setTone} />
}
```

不传 `options` 时用内置的七个色调：主题色、蓝、绿、琥珀、玫红、紫、青，色点旁的名称也一并带上。`value` 存的是选项的 `value`（字符串），拿到之后自己去拼 `style={{ "--flow-tone": ... }}` 或套组件的 `tone` 属性。

### 选项与色点

每个选项有三个字段：

| 字段    | 说明                                                                 |
| ------- | -------------------------------------------------------------------- |
| `value` | 提交给 `onValueChange` 的值，字符串                                  |
| `label` | 可访问名称（`aria-label`）与悬停提示（`title`），**必填**            |
| `tone`  | 色点颜色：内置色调名（`primary`、`blue`…）、任意 CSS 颜色，或 `null` |

`tone: null` 画成虚线空心圆，通常表示「不上色」「跟随上级」这类不指定颜色的选项。任意 CSS 颜色都行，写 `var(--flow-cyan)`、`oklch(…)`、`#f97316` 都可以；想要跟随颜色主题，就写主题变量。

`toneOptions(tones)` 把一串色调名变成选项数组，名称取内置的中文名表（`primary` 主题色、`foreground` 前景色、`blue` 蓝、`green` 绿、`amber` 琥珀、`rose` 玫红、`violet` 紫、`cyan` 青），不在表里的名字原样用作名称。

```tsx
import { toneOptions } from "@/components/ui/tone-picker/tone-picker"

const TONES = toneOptions(["primary", "blue", "violet"])
// [{ value: "primary", label: "主题色", tone: "primary" }, …]
```

### 高度

`variant` 与 `size` 的对照表和数值滑块一致；色点大小跟着档位走，`sm` 12px、`default` 14px、`lg` 16px，`compact` 统一 10px：

| `variant` | `sm` | `default` | `lg` |
| --------- | ---- | --------- | ---- |
| `bar`     | 28px | 32px      | 36px |
| `compact` | 18px | 22px      | 24px |

标签省略时色点推到最右（`ms-auto`），此时务必给 `aria-label`——单选组本身也需要一个名字。

## 示例

### 自定义选项

标签的强调色。第一项 `tone: null` 画成虚线空心圆，表示「跟随上级」；最后一项用 `var(--flow-cyan)` 演示任意 CSS 颜色也能当色点。

<ComponentPreview name="tone-picker-custom-demo" />

### 多行

图表三组数据的配色。`variant="compact"` 让三条色点选择器排成一列也不占地方，每条只管自己那一组；上面的柱状图读同一份 `--flow-tone`，改完立刻换色。

<ComponentPreview name="tone-picker-series-demo" />

## API

### TonePicker

<PropsTable name="tone-picker" component="TonePicker" />

除上表外，其余属性直接交给 Base UI 的 `RadioGroup.Root`：`disabled`、`aria-label`、`required`、`orientation` 等。

### toneOptions

```ts
function toneOptions(tones?: readonly FlowTone[]): TonePickerOption[]
```

不传 `tones` 时返回默认的七项。名称取自内置的中文名表，表里没有的名字直接当名称用。

### tonePickerVariants

`cva` 生成的根元素样式函数，有 `size` 与 `variant` 两个变体。高度通过根元素的 `--tone-picker-height`、色点直径通过 `--tone-picker-swatch` 传给内部。

```ts
const tonePickerVariants: (props?: {
  size?: TonePickerSize
  variant?: TonePickerVariant
}) => string
```

### 类型

```ts
type TonePickerSize = "sm" | "default" | "lg"

type TonePickerVariant = "bar" | "compact"

type TonePickerOption = {
  value: string
  /** 可访问名称，悬停时也作为提示 */
  label: string
  /** 内置色调名或任意 CSS 颜色；`null` 画成空心圆 */
  tone: FlowTone | null
}

type TonePickerProps = Omit<
  React.ComponentProps<typeof RadioGroup>,
  "value" | "defaultValue" | "onValueChange" | "children"
> & {
  options?: readonly TonePickerOption[]
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  label?: React.ReactNode
  variant?: TonePickerVariant
  size?: TonePickerSize
  modified?: boolean
  className?: string
}
```

## data-slot

| 元素     | `data-slot`            |
| -------- | ---------------------- |
| 根元素   | `tone-picker`          |
| 左侧标签 | `tone-picker-label`    |
| 色点容器 | `tone-picker-swatches` |
| 色点     | `tone-picker-swatch`   |

根元素始终带 `data-variant`（`bar` / `compact`），`modified` 为真时带 `data-modified`；色点上是 Base UI 给的 `data-checked`，`data-disabled` 落在根元素上。

## 可访问性

- 语义是单选组：根元素 `role="radiogroup"`，每个色点 `role="radio"`。方向键在色点间移动并直接选中。
- 每个色点必须有名称，`label` 同时写进 `aria-label` 与 `title`。颜色不是唯一的信息载体——不要写只有色点、没有名称的选项。
- 选中状态除了名称还有两层视觉：色点外一圈前景色细环（`ring-2` 加 2px 偏移），色点本身在悬停时放大 10%。
- 组的名称取自 `label`（`aria-labelledby`）；省略 `label` 时用 `aria-label` 补上。
- 焦点环只在键盘聚焦时出现（`focus-visible`）。

## 注意事项

- 色点颜色来自主题变量，亮暗与颜色主题切换时会跟着变；要固定成品牌色就写任意 CSS 颜色。
- `modified` 只有配 `label` 时才有可见效果（标签从次要色变成前景色）；没有 `label` 时只留下 `data-modified`。
- 色点数量超过七、八个时一行会挤，考虑换成下拉或分成两行；色点直径不随容器缩放。
- 受控 / 非受控共用一个 `useControllableState`；`options` 变化后如果当前值已不存在，组件不会自动改选，请在父级同步。

## 源码

<ComponentSource name="tone-picker" />

---

# 数值滑块

来源：https://yiui.dev/components/value-slider/

<ComponentPreview name="value-slider-demo" />

## 安装

<InstallCommand name="value-slider" />

## 用法

```tsx title="components/volume-slider.tsx"
import { ValueSlider } from "@/components/ui/value-slider/value-slider"

export function VolumeSlider() {
  return <ValueSlider label="音量" defaultValue={40} />
}
```

不带状态时用 `defaultValue` 给初始值（不传就落在 `min`），组件自己管；需要读值就加 `value` 与 `onValueChange` 走受控。轨道本身即控件：点轨道跳转、按住手柄拖动，键盘也能操作。

### 标签与读数

`labelPlacement="inside"`（默认）时 `label` 渲染在轨道左端内部，右侧读数是格式化后的当前值，两者都是 `aria-hidden`，真正的语义挂在手柄上。手柄靠近文字时自动变淡，文字不会被挡住。`showValue={false}` 只留标签，`format` 或 `formatValue` 决定读数长什么样。

```tsx
<ValueSlider
  label="亮度"
  defaultValue={64}
  format={{ style: "unit", unit: "percent" }}
/>
```

`labelPlacement="outside"` 把标签与读数移到轨道上方一行：左侧标签、右侧读数，轨道里不放文字，手柄常驻可见也不再让位。区间这类要同时看清两个手柄的场景用它更合适。`variant="slim"` 的轨道放不下文字，固定按这一档处理，`labelPlacement` 在它下面不生效。

```tsx
<ValueSlider
  label="价格"
  labelPlacement="outside"
  min={0}
  max={2000}
  step={50}
  defaultValue={[200, 1200]}
/>
```

### 弹性过冲

往轨道外继续拖时，轨道按饱和的橡皮筋曲线被拉伸：越往外越难拉，最大位移是 `elasticity` 像素（默认 `12`），松手时用弹簧回到原位，两端的图标跟着轻轻一推。键盘在手柄已经位于端点时继续按同一个方向，也会拉一下再弹回来，让人知道已经到头。`elasticity={0}` 完全关掉。

拉伸只做在轨道内部的视觉层上，`Slider.Control` 自己不缩放，所以把指针拖出右端再拉回轨道中间，值仍然连续变化，不会跳。换边（从一端外面直接拖到另一端外面）时缩放原点固定在中心，只改平移量，同样不会跳。

```tsx
<ValueSlider label="音量" defaultValue={40} elasticity={24} />
```

### 刻度与磁吸

`ticks` 传数字表示把范围等分成几段，画 n - 1 条内部刻度线；传数组表示在指定值处画线。它同时是 `snapToTicks` 的目标：指针松手时（拖动或点击轨道）如果与最近刻度相差不到整个范围的 3%，值会吸过去；键盘逐步移动不吸附，所以方向键可以从刻度上走开，不会被反复拉回同一个点。刻度线用逻辑属性定位，RTL 下跟着手柄与填充一起从右边排布。

刻度建议落在 `step` 上。不在 `step` 上的刻度会被对齐到最近的 `step` 再提交，避免出现 3650 这种步长之外的数值；区间模式吸附后还要保证两个值顺序不变、且至少相隔 `minStepsBetweenValues` 个 `step`，不满足就放弃那次吸附。

```tsx
<ValueSlider
  label="色温"
  min={2700}
  max={6500}
  step={100}
  largeStep={500}
  defaultValue={4500}
  ticks={4}
  snapToTicks
  formatValue={(value) => `${value} K`}
/>
```

### 缓冲进度

`buffer` 是「已缓冲到的值」——比如视频已经加载到第 N 秒。它会在已选填充下面再画一段从 `min` 到 `buffer` 的次级填充，颜色比已选填充淡一档，用来区分「已加载」与「已播放」。只有单值模式生效，区间模式会忽略它。

```tsx
<ValueSlider
  aria-label="播放进度"
  min={0}
  max={214}
  defaultValue={62}
  buffer={102}
/>
```

### 格式化

`format` 是 `Intl.NumberFormat` 的选项，`locale` 默认 `zh-CN`，读数的小数位默认按 `step` 推导（`0.5` 显示一位）。`formatValue` 优先于 `format`，返回的字符串同时用于右侧读数与手柄的 `aria-valuetext`，适合加单位、正负号或把数字换成词语。

```tsx
<ValueSlider
  label="曝光"
  min={-100}
  max={100}
  defaultValue={0}
  formatValue={(value) => (value > 0 ? `+${value}` : String(value))}
/>
```

### 直接输入

读数平时是文字，`editable` 让它变成入口：点一下读数，或在手柄上按回车，原地换成一个输入框，读数变成可编辑的虚线。回车或失焦提交，`Esc` 放弃；输入里的千分位、单位之类会被忽略，只取数字部分，再夹到 `min`–`max` 之间并对齐到 `step`。回车提交后焦点还给手柄，键盘用户可以接着用方向键微调。

```tsx
<ValueSlider
  label="宽度"
  min={480}
  max={3840}
  step={40}
  editable
  defaultValue={1920}
  formatValue={(value) => `${value}px`}
/>
```

一次输入当作一次提交（触发 `onValueCommitted`），不放刻度音效，也不经过中间的过渡值。区间模式下不可输入（输入框只有一个，说不清改哪个手柄），`disabled` 时也不可输入。

`modified` 是给控制面板用的标记：传 `true` 时标签与读数从次要色提到前景色，根元素带上 `data-modified`。它不改变值，只是「这一项已改动」的视觉与钩子，通常写成 `modified={value !== defaultValue}`。

```tsx
<ValueSlider
  label="高度"
  editable
  modified={height !== 1080}
  value={height}
  onValueChange={setHeight}
/>
```

### 区间

值传数组即为区间：数组长度决定手柄数量，读数显示为「起点 – 终点」。数组在内部按升序处理，`label` 是字符串时手柄名称自动加上「起点」「终点」。两个手柄相遇时的行为由 Base UI 的 `thumbCollisionBehavior` 决定（默认 `push`），最小间隔由 `minStepsBetweenValues` 控制。

```tsx
<ValueSlider
  label="价格"
  min={0}
  max={2000}
  step={50}
  defaultValue={[200, 1200]}
  format={{ style: "currency", currency: "CNY", maximumFractionDigits: 0 }}
/>
```

### 音效

`sound` 打开音效：值变化时（拖动、点击轨道、键盘）播放刻度音，碰到两端播放碰边音。音效默认关闭，浏览器要求先有用户操作才能出声，所以音频在第一次交互时才初始化。

```tsx
import { useValueSliderMuted } from "@/components/ui/value-slider/value-slider"

const [muted, setMuted] = useValueSliderMuted()

<ValueSlider label="音量" defaultValue={40} sound />
<button type="button" onClick={() => setMuted(!muted)}>
  {muted ? "打开音效" : "静音"}
</button>
```

静音偏好与站内其他带音效的组件共用（`localStorage` 的 `travinsy:sound:muted`）：同一页面里一处静音，其他组件的静音按钮与音效立刻跟上；换到另一个标签页也会同步。

## 示例

每个示例的标题栏右侧都有「调整」开关：打开后可以实时调整过冲强度、尺寸、高度档、色调、刻度和磁吸，并开关读数与音效；未改动的项显示示例自己的取值。换尺寸档时，把滑块放进固定高度插槽的示例画框不会跳；换成 `slim` 时标签与读数会从轨道里移到上方、额外占一行，画框可能随之变高。

### 轨道高度

`variant` 是三档高度，外观都是同一种方条（细边框、淡色分层填充、竖线手柄）。默认的 `bar` 最高，标签与读数画在轨道里；`compact` 是中等高度，文字仍在轨道里、字号收到 xs，适合工具面板里一排排的参数；`slim` 是矮轨，标签与读数移到轨道上方，竖线手柄比轨道高出一截。下面这张画笔卡片里，笔刷大小与不透明度用 `variant="compact"`，平滑度用 `variant="slim"` 并带上刻度（`ticks={4}`）。

<ComponentPreview name="value-slider-variant-demo" />

### 音量与音效

`sound` 打开拖动时的刻度音效，`startIcon` 随值在三个喇叭图标之间切换，旁边的静音入口用 `useValueSliderMuted` 读写同一份偏好。

<ComponentPreview name="value-slider-volume-demo" />

### 价格区间

数组值给两个手柄，`labelPlacement="outside"` 让两个手柄常驻可见，`format` 用 `Intl` 的货币格式；上方的柱子落在区间内时取主题色，范围外的退成灰色。

<ComponentPreview name="value-slider-range-demo" />

### 图片调色

三条滑块实时改 CSS `filter` 的 `brightness`、`contrast`、`saturate`，曝光用 `ticks={[0]}` 加 `snapToTicks` 让 0 点磁吸，`formatValue` 补上正负号。

<ComponentPreview name="value-slider-photo-demo" />

### 播放进度

`variant="slim"` + `size="sm"` 收成播放器里的细进度条，没有可见 `label` 时用 `aria-label` 提供名称；读数写成「已播 / 总长」显示在轨道上方，`buffer` 画出比当前进度多 40 秒的已缓冲段。

<ComponentPreview name="value-slider-playback-demo" />

### 心情评分

`min={1}`、`max={5}`、`step={1}` 配 `ticks={4}` 得到五档，`formatValue` 把数字换成词语，读屏读到的也是词语。

<ComponentPreview name="value-slider-mood-demo" />

### 直接输入

导出尺寸卡片，三条滑块都开了 `editable`：点读数就能敲数字，回车确认、`Esc` 放弃。改过的项用 `modified` 把标签挑到前景色，一眼看出哪几项此时不是默认值。

<ComponentPreview name="value-slider-editable-demo" />

## API

### ValueSlider

<PropsTable name="value-slider" component="ValueSlider" />

默认 `min={0}`、`max={100}`、`step={1}`、`largeStep={10}`、`minStepsBetweenValues={0}`、`showValue`、`elasticity={12}`、`size="default"`、`variant="bar"`、`labelPlacement="inside"`、`locale="zh-CN"`；`snapToTicks`、`sound`、`editable`、`modified`、`disabled` 默认关闭，`tone` 不传时轨道用前景色，`buffer` 不传时不画缓冲段。

轨道高度由 `size` 与 `variant` 共同决定：`bar` 是 `sm` 28px、`default` 32px、`lg` 36px；`compact` 是 18px、22px、24px；`slim` 是 6px、8px、10px，竖线手柄依次高 14px、16px、18px，命中区至少 20px 高，矮轨也好按。读数小数位由 `step` 推导，`format` / `formatValue` 可以覆盖。

除上表外，其余属性直接交给 Base UI 的 `Slider.Root`：`form`（关联到页面上的某个表单）、`id`、`minStepsBetweenValues`（区间两个手柄之间至少隔几个 `step`）、`thumbCollisionBehavior`（`push` / `swap` / `none`，默认 `push`）。`orientation`、`thumbAlignment` 之类会影响横向布局的属性由组件接管，没有对外暴露——组件固定用 `thumbAlignment="edge"`，手柄落在两端时贴着轨道内侧对齐，不会探出边框半截。

### ValueSliderTuningContext

```ts
const ValueSliderTuningContext: React.Context<ValueSliderTuning>
```

可选的覆盖层：子树里所有 `ValueSlider` 的 `elasticity`、`size`、`variant`、`tone`、`ticks`、`snapToTicks`、`showValue`、`sound` 会被 Context 里的值替换，`onReport` 回报组件自己的实际取值。不发这个 Context 时组件行为不变，正常使用不需要它。

### useValueSliderMuted

```ts
function useValueSliderMuted(): readonly [
  muted: boolean,
  setMuted: (muted: boolean) => void,
]
```

读写音效的静音偏好，存在 `localStorage` 的 `travinsy:sound:muted` 里，与站内其他带音效的组件共用同一份偏好：同一页面的所有消费者共享（写入后广播 `travinsy:sound-muted-change` 事件，不依赖只有跨标签页才触发的 `storage`），也在标签页之间同步；服务端与水合阶段按未静音渲染。

### valueSliderVariants

`cva` 生成的根元素样式函数，有 `size` 与 `variant` 两个变体；写自己的触发器或包装层时可以复用它保持一致。轨道高度与手柄直径是通过根元素上的 CSS 变量（`--value-slider-track-height`、`--value-slider-thumb-size`）传给内部轨道与手柄的。

```ts
const valueSliderVariants: (props?: {
  size?: ValueSliderSize
  variant?: ValueSliderVariant
}) => string
```

### 类型

```ts
type ValueSliderValue = number | readonly number[]

type ValueSliderSize = "sm" | "default" | "lg"

type ValueSliderVariant = "bar" | "compact" | "slim"

type ValueSliderLabelPlacement = "inside" | "outside"

type ValueSliderProps<Value extends ValueSliderValue = number> = {
  value?: Value
  defaultValue?: Value
  min?: number
  max?: number
  step?: number
  largeStep?: number
  minStepsBetweenValues?: number
  disabled?: boolean
  name?: string
  onValueChange?: (value: Value) => void
  onValueCommitted?: (value: Value) => void
  format?: Intl.NumberFormatOptions
  locale?: Intl.LocalesArgument
  label?: React.ReactNode
  labelPlacement?: ValueSliderLabelPlacement
  "aria-label"?: string
  buffer?: number
  formatValue?: (value: number) => string
  showValue?: boolean
  startIcon?: React.ReactNode
  endIcon?: React.ReactNode
  ticks?: number | readonly number[]
  snapToTicks?: boolean
  elasticity?: number
  size?: ValueSliderSize
  variant?: ValueSliderVariant
  tone?: FlowTone
  editable?: boolean
  modified?: boolean
  sound?: boolean
  className?: string
  style?: React.CSSProperties
}

type ValueSliderTuning = Partial<
  Pick<
    ValueSliderProps,
    | "elasticity"
    | "size"
    | "variant"
    | "ticks"
    | "snapToTicks"
    | "showValue"
    | "sound"
  >
> & {
  /** `false` 表示去掉色调 */
  tone?: FlowTone | false
  onReport?: (report: ValueSliderReport) => void
}

type ValueSliderReport = {
  elasticity: number
  size: ValueSliderSize
  variant: ValueSliderVariant
  tone: FlowTone | undefined
  /** 示例用显式刻度数组时是 undefined，表示「没有段数可报」 */
  ticks: number | undefined
  snapToTicks: boolean
  showValue: boolean
  sound: boolean
}
```

示例用显式刻度数组时，调整面板的刻度滑块显示为默认的 0；一旦拖动刻度滑块，就换成等分刻度（刻度数组无法用段数表达）。

### data-slot

| 元素           | `data-slot`               |
| -------------- | ------------------------- |
| 根元素         | `value-slider`            |
| 轨道上方的文字 | `value-slider-labels`     |
| 交互区         | `value-slider-control`    |
| 轨道外框       | `value-slider-rail`       |
| 轨道           | `value-slider-track`      |
| 缓冲填充       | `value-slider-buffer`     |
| 已选填充       | `value-slider-indicator`  |
| 刻度线         | `value-slider-tick`       |
| 标签           | `value-slider-label`      |
| 读数           | `value-slider-value`      |
| 输入框         | `value-slider-input`      |
| 手柄           | `value-slider-thumb`      |
| 左端图标       | `value-slider-start-icon` |
| 右端图标       | `value-slider-end-icon`   |

`value-slider-labels` 只在 `labelPlacement="outside"`（以及 `variant="slim"`）时出现，`label` 与读数都放在它里面；`inside` 时这两个 `data-slot` 落在轨道内。`value-slider-input` 只在 `editable` 且正在输入时出现，临时替掉同一位置的读数。根元素在过冲时带 `data-overshoot`（`start` 往左、`end` 往右），禁用时带 `data-disabled`，拖动中带 `data-dragging`，手柄压住文字时带 `data-near="true"`，`modified` 为真时带 `data-modified`，并且始终带 `data-variant`（`bar` / `compact` / `slim`）。

## 可访问性

- 手柄是原生输入元素，键盘操作：`←` `→` `↓` `↑` 加减一个 `step`，`Shift` + 方向键与 `PageUp` / `PageDown` 按 `largeStep`，`Home` / `End` 到两端；区间时 `Home` / `End` 不会越过另一个手柄。RTL 布局下左右方向键的增减是反的（方向取自 Base UI 的 `DirectionProvider`，需要在应用里包一层 `<DirectionProvider direction="rtl">`，同时给页面设 `dir="rtl"`）。
- 读屏名称优先取 `aria-label`；没有时用字符串 `label`（区间自动补「起点」「终点」）；两者都没有时退回「数值」，所以同一个表单里有多个滑块时务必给 `label` 或 `aria-label`，否则几个手柄会重名。
- `aria-valuetext` 是格式化后的读数，所以 `format` / `formatValue` 的写法会直接决定读屏怎么念。
- 焦点环只在键盘聚焦时出现（`:focus-visible`），鼠标点击轨道不会留下焦点框。Control 上有一圈整体焦点环，聚焦的那个手柄还会自己出环，区间模式下能看出当前在调哪个手柄，并从 4px 加粗到 6px。
- 系统开启「减少动态效果」时不播放过冲与弹簧回弹，轨道不会被拉伸。
- `editable` 时读数是一个可点的文字入口：鼠标直接点，键盘在手柄上按 `Enter` 进入输入（回车被拦下，不会提交外层表单）。输入框自带名称（`输入` + 手柄名称），回车提交后焦点回到手柄，`Esc` 放弃并同样还回焦点；失焦提交时不抢焦点。
- 缓冲填充是 `aria-hidden` 的装饰，读屏只报当前值。
- 音效默认关闭。打开后请同时提供静音入口（`useValueSliderMuted`），音效只是点缀，不承载信息；静音偏好存在 `localStorage` 的 `travinsy:sound:muted`，与站内其他带音效的组件共用。

## 注意事项

- 组件在服务端就输出完整结构（手柄按 `left%` 定位、填充有宽度），不需要预水合脚本，禁用 JS 时也能看到当前值。
- 拖动期间的过冲动画由 MotionValue 直接改 `transform`，不触发 React 渲染；数值变化本身仍会渲染读数，所以一次拖动里读数会跟着刷新。
- 用作表单字段时传 `name`，值会随表单提交；受控模式下记得同时处理 `onValueChange`，否则拖动后值会弹回。需要挂到页面另一处的表单上时再传 `form`。
- `format` 对象、`formatValue` 函数与 `ticks` 数组建议定义在组件外，避免每次渲染都重建格式化器或刻度表。
- 组件用一次 `ResizeObserver` 观测轨道与文字宽度，服务端输出的是完整静态结构；首帧还没量到宽度时，落在两端 15% 以内的手柄先按「压在文字上」处理，量到之后按真实文字宽度判断。`slim` 的文字在轨道外，不做让位。
- `tone` 的颜色变量由 `flow-diagram` 条目提供，安装时会一并拉取；手动安装需要自己补上 `--flow-*` 变量。

## 源码

<ComponentSource name="value-slider" />

---

# 二维拖拽板

来源：https://yiui.dev/components/xy-pad/

<ComponentPreview name="xy-pad-demo" />

## 安装

<InstallCommand name="xy-pad" />

## 用法

```tsx title="components/light-pad.tsx"
import { useState } from "react"
import { XyPad } from "@/components/ui/xy-pad/xy-pad"

export function LightPad() {
  const [light, setLight] = useState({ x: 30, y: 70 })

  return (
    <XyPad
      label="光源"
      value={light}
      onValueChange={setLight}
      x={{ min: 0, max: 100, step: 1, label: "水平" }}
      y={{ min: 0, max: 100, step: 1, label: "高度" }}
    />
  )
}
```

值是一个 `{ x, y }` 对象。`value` / `defaultValue` / `onValueChange` 与其他方条控件同一套约定：给 `value` 就是受控，不给时由组件自己管，`defaultValue` 不传就落在两轴的中点。

### 拖动与十字线

按住任意位置或手柄拖动，两条轴一起变；十字线标出当前位置，一块淡色填充从左下角铺到手柄，与数值滑块的已选填充是同一种做法。松手时触发一次 `onValueCommitted`，拖动过程中只走 `onValueChange`。

指针按下时组件会把焦点交给横轴的隐藏滑块，所以拖完可以直接按方向键微调，不用再点一次。

### 两条轴

`x` 与 `y` 各是一个轴对象，字段都一样：

| 字段     | 默认    | 说明                                                  |
| -------- | ------- | ----------------------------------------------------- |
| `min`    | `0`     | 最小值                                                |
| `max`    | `100`   | 最大值                                                |
| `step`   | `1`     | 步长，落点按它对齐                                    |
| `label`  | `X`/`Y` | 轴名，读屏朗读与读数的名称                            |
| `format` | 无      | 读数格式，返回的字符串同时用于读数与 `aria-valuetext` |

横轴往右变大，纵轴**往上**变大——与屏幕坐标相反，符合「抬高」的直觉。角度这类有正负的轴直接写 `min={-60}`、`max={60}`，负数就在轴线左侧 / 下方。

```tsx
<XyPad
  label="视角"
  x={{ min: -60, max: 60, step: 1, label: "朝向", format: (v) => `${v}°` }}
  y={{ min: -45, max: 45, step: 1, label: "俯仰", format: (v) => `${v}°` }}
/>
```

`grid` 只改背景网格的疏密（默认每个方向 4 格），不影响取值与步长。

### 键盘

板子里有两个视觉隐藏的原生滑块，横轴一个、纵轴一个。聚焦其中任何一个时：

| 按键                  | 变化                         |
| --------------------- | ---------------------------- |
| `←` / `→`             | 横轴减 / 加一个 `step`       |
| `↑` / `↓`             | 纵轴加 / 减一个 `step`       |
| `Shift` + 方向键      | 步长放大十倍                 |
| `Home` / `End`        | 交给当前那条轴，跳到两端     |
| `PageUp` / `PageDown` | 交给当前那条轴，按原生序列走 |

上下键被接管成纵轴，所以两条轴都能用同一组方向键调，不必先在两个滑块之间 Tab 切换。

### 尺寸与色调

默认是正方形（`aspect-square`），用 `className` 改比例或高度：`className="aspect-[4/3]"`、`className="aspect-auto h-40"`。面板里需要跟着行高撑满时，用容器查询给不同断点分别设值。

`tone` 给十字线、手柄与填充上色，取 `--flow-tone`；不传时用前景色。`modified` 把标签与读数从次要色提到前景色，并在根元素上留一个 `data-modified`，写法通常是 `modified={value.x !== 50 || value.y !== 50}`。

```tsx
<XyPad
  className="aspect-[4/3]"
  label="白平衡"
  tone="cyan"
  x={{ label: "绿", min: -50, max: 50 }}
  y={{ label: "红", min: -50, max: 50 }}
/>
```

## 示例

### 情绪坐标

两条轴各带自己的中文轴名与取值范围，纵轴往上变大；板子外面标出「积极 / 消极」「平静 / 激动」，右上角的象限名随位置变化，`tone` 按积极 / 消极换成绿 / 玫红，颜色只是加强，名称本身已经把状态说清楚。

<ComponentPreview name="xy-pad-mood-demo" />

### 视角面板

二维拖拽板放进控制面板当「视角」：横轴转朝向、纵轴转俯仰，一次拖出任意机位；下面一条数值滑块单独控制透视距离。板子保持默认的正方形，两条轴的 `format` 补上度数，`modified` 标出改过的项，标题栏的复制按钮把当前视角写成 JSX。

<ComponentPreview name="xy-pad-view-demo" />

## API

### XyPad

<PropsTable name="xy-pad" component="XyPad" />

默认两条轴都是 `min={0}`、`max={100}`、`step={1}`，名称分别是 `X` 与 `Y`；`grid={4}`、`modified` 与 `disabled` 默认关闭，`tone` 不传时用前景色。除上表外，其余属性直接落在根元素 `<div>` 上（`role="group"` 与 `aria-label` 已经在组件里处理）。

### 类型

```ts
type XyPadValue = { x: number; y: number }

type XyPadAxis = {
  min?: number
  max?: number
  step?: number
  /** 轴名：读屏朗读与读数里用，如「朝向」；不传时是 X / Y */
  label?: string
  /** 读数格式；不传时直接显示数字 */
  format?: (value: number) => string
}

type XyPadProps = Omit<
  React.ComponentProps<"div">,
  "defaultValue" | "onChange" | "children"
> & {
  value?: XyPadValue
  defaultValue?: XyPadValue
  onValueChange?: (value: XyPadValue) => void
  onValueCommitted?: (value: XyPadValue) => void
  x?: XyPadAxis
  y?: XyPadAxis
  label?: React.ReactNode
  grid?: number
  tone?: FlowTone
  modified?: boolean
  disabled?: boolean
}
```

## data-slot

| 元素     | `data-slot`        |
| -------- | ------------------ |
| 根元素   | `xy-pad`           |
| 交互区   | `xy-pad-area`      |
| 背景网格 | `xy-pad-grid`      |
| 淡色填充 | `xy-pad-fill`      |
| 竖十字线 | `xy-pad-crosshair` |
| 手柄     | `xy-pad-thumb`     |
| 横轴滑块 | `xy-pad-input-x`   |
| 纵轴滑块 | `xy-pad-input-y`   |
| 标签     | `xy-pad-label`     |
| 读数     | `xy-pad-value`     |

根元素在拖动中带 `data-dragging`，`modified` 为真时带 `data-modified`，禁用时带 `data-disabled`。

## 可访问性

- 根元素是 `role="group"`，名称取 `label`（`aria-labelledby`），没有 `label` 时用 `aria-label`；两者都没有时这组滑块就没有名字，务必给一个。
- 语义落在两个视觉隐藏的原生 `input[type=range]` 上：各自带轴名与 `aria-valuetext`（`format` 的结果），读屏能分别念出「朝向 -32°」「俯仰 18°」这样的值。读数是 `aria-hidden` 的装饰，不重复朗读。
- 方向键的左右 / 上下分别对应横轴与纵轴，`Shift` 加大十倍；`Home` / `End` / `PageUp` / `PageDown` 交给原生滑块，只改当前聚焦的那条轴。
- 焦点环画在整块板子外面（`:has(:focus-visible)`），键盘进入时能看出是这一组在响应。
- `disabled` 时两个滑块一起禁用、去掉指针交互，并降到半透明。
- 十字线与填充只是加强，位置信息同时存在于手柄与两个滑块的数值里，颜色不是唯一载体。

## 注意事项

- 组件在服务端就输出完整结构（手柄按百分比定位、填充有宽高），禁用 JS 时也能看到当前值。
- 拖动用 `setPointerCapture`，指针移出板子也还能继续拖；鼠标按下时会阻止默认行为，不会选中旁边的文字。
- 落点会先夹进 `min`–`max`，再对齐到 `step`，所以读数不会出现步长之外的数值。
- 小数的位数按 `step` 的写法推导：`step={0.5}` 保留一位，`step={0.01}` 保留两位。
- 受控模式下记得同时处理 `onValueChange`，否则拖动后手柄会弹回。
- 用作表单字段时外面自己套两个 `input type="hidden"`，组件只提交到回调。
- `tone` 的颜色变量由 `flow-diagram` 条目提供，安装时会一并拉取；手动安装需要自己补上 `--flow-*` 变量。

## 源码

<ComponentSource name="xy-pad" />

---

# 介绍

来源：https://yiui.dev/docs/

Yi UI（易）是本站维护的开源组件库，名字取自站点标志「易」：既是「容易上手」，也是「随你改动」。它按 shadcn 方式分发：库本身不是 npm 包，每个条目都是一份源码，由 shadcn CLI 写进你的项目，之后完全属于你。视觉上围绕「线条网格」展开：内容区两侧的竖线、贯穿屏幕的横线、点阵与刻度尺分隔带。

## 与 shadcn 的关系

本站遵循 shadcn 的 [Registry 规范](https://ui.shadcn.com/docs/registry)，条目的 JSON 格式、安装命令与 CLI 行为都与官方一致。组件基于 shadcn/ui 的 `base-nova` 风格（Base UI 底座），使用 Tailwind CSS v4 与主题变量，所以能直接放进已初始化 shadcn 的项目，并跟随你的亮暗模式与颜色主题。

这里的内容是对官方组件的补充，不替代它们：按钮、对话框等通用原语继续使用 shadcn 官方组件。

## 内容分层

| 层级 | 说明 | registry 类型 |
| --- | --- | --- |
| [组件](/components/) | 单一职责的小部件，如线条网格布局、本地时间、时段问候 | `registry:ui` |
| [区块](/blocks/) | 可直接放进页面的整块界面，如登录、聊天、特性分栏 | `registry:block` |
| [模板](/templates/) | 整页风格模板，改一个配置文件就能换成自己的内容 | `registry:page` |
| [主题](/themes/) | 14 套颜色主题，亮暗模式独立切换 | `registry:theme` |

大层级可以依赖小层级：区块由组件组合而成，模板由区块与组件组成。安装时 CLI 会自动带上这些依赖。

## 如何使用

1. 在项目里初始化 shadcn，见[安装](/docs/installation/)。
2. 选一个条目，运行文档页顶部给出的安装命令。
3. 打开写入项目的源码，按需修改。

如果想少打几个字，或让 AI 编辑器直接检索这里的组件，可以继续阅读 [Registry 与命名空间](/docs/registry/) 与 [AI 与 llms.txt](/docs/llms/)。

---

# 安装

来源：https://yiui.dev/docs/installation/

## 前置条件

| 项 | 要求 |
| --- | --- |
| React | 19（源码把 `ref` 当普通属性传，并用到 React 19 的 `<style precedence>`） |
| Tailwind CSS | v4（条目用 `@utility` 与 `@theme inline` 写样式） |
| shadcn/ui | 已初始化，底座选 **Base UI**（`components.json` 里 `style` 以 `base-` 开头，如 `base-nova`） |
| Node.js | 20.18 以上（shadcn CLI 的要求） |
| 框架 | 组件本身不绑框架；区块和模板里的页面文件按 Next.js App Router 写，`app-shell-01` 还引入了 `next/link` 与 `next/navigation` |

为什么要 Base UI：条目里用到 shadcn 原语（`button`、`dropdown-menu`、`tooltip` 等）的地方，用的是 Base UI 的 `render` 属性，不是 Radix 的 `asChild`；`value-slider`、`toggle-switch`、`segmented-control` 等还直接引入 `@base-ui/react`。CLI 会按你项目的底座生成原语，所以在 Radix 项目里装 `app-shell-01` 会类型报错，详见下面的[常见问题](#常见问题)。

以上要求在 Next.js 16、React 19、Tailwind CSS v4 与 shadcn CLI 4.23 下实测通过。

## 准备项目

没有项目时，让 shadcn 直接建一个 Next.js 项目并选好 Base UI：

```bash title="终端"
pnpm dlx shadcn@latest init -t next -b base -p nova -n my-app
```

已有 Next.js 项目，在项目根目录初始化：

```bash title="终端"
pnpm dlx shadcn@latest init -b base -p nova
```

`-b base` 选择 Base UI 底座，`-p nova` 选择 Nova 预设，两者合起来就是 `base-nova`。不带参数运行 `init` 也可以，在提示里选 Base UI。完成后确认 `components.json` 的关键字段：

```json title="components.json"
{
  "style": "base-nova",
  "tailwind": { "css": "app/globals.css", "cssVariables": true },
  "aliases": { "components": "@/components", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" }
}
```

项目有 `src/` 目录时 `css` 是 `src/app/globals.css`。条目源码里的 `@/components/…`、`@/lib/utils`、`@/hooks/…` 会按这里的 `aliases` 改写，不需要手动改 import。

## 安装第一个组件

默认用完整 URL 安装，不需要额外配置。

<InstallCommand name="grid-layout" />

`pnpm dlx` 可以换成 `npx`、`yarn dlx` 或 `bunx`，命令框顶部的标签可以切换。想用更短的命令，见 [Registry 与命名空间](/docs/registry/)。

## 安装后发生了什么

CLI 做三件事：写入源码文件、安装 npm 依赖、把样式合并进全局 CSS。

### 文件落在哪里

路径按条目类型决定；项目有 `src/` 目录时都会加上 `src/` 前缀（实测 `src/components/ui/…`，不带 `src/` 的项目是 `components/ui/…`）。

| 类型 | 落点 | 例子 |
| --- | --- | --- |
| 组件 `registry:ui` | `components/ui/<name>/` | `components/ui/grid-layout/grid-layout.tsx` |
| 区块、模板的组件 | `components/<name>/` | `components/auth-01/auth-01.tsx` |
| 区块、模板的页面 | `app/…`，路径由条目指定 | `auth-01` 写入 `app/login/page.tsx`；`app-shell-01` 写入 `app/(app)/layout.tsx`、`app/(app)/dashboard/page.tsx` 与 `app/(app)/dashboard/[...slug]/page.tsx` |
| 共用 hook 与工具 | `hooks/`、`lib/` | `hooks/use-controllable-state.ts`、`lib/data-display.ts` |

文件装进项目后就是你的源码，可以直接改。每个条目页「手动」标签里的文件标题就是这里的落点。

### 依赖会连带安装

条目通过 `registryDependencies` 声明依赖，CLI 会把它们一起装上：

- **shadcn 官方组件**：例如 `control-panel` 会生成 `components/ui/button.tsx`。已经装过的不会重复写。
- **本站其他条目**：例如装 `value-slider` 会带上 `flow-diagram`（它再依赖 `grid-layout`）和 `hooks/use-controllable-state.ts`，一次写入十几个文件。
- **npm 包**：`motion`、`@base-ui/react`、`recharts` 等由 CLI 直接装进 `package.json`，用你项目的包管理器。

多个条目共用的文件（`grid-layout`、`flow-diagram`、`use-controllable-state` 等）只写一份，后装的条目会跳过已存在的同名文件。

### 样式与变量

线条网格依赖几个全局变量和工具类，它们由用到的条目写入你的全局样式（如 `app/globals.css`），不需要手抄：

| 内容 | 由谁写入 | 说明 |
| --- | --- | --- |
| `--edge`，以及 `@theme inline` 里的 `--color-edge` | `grid-layout`、`stat-card`、`chart-card`、`control-panel` 等用到线条的条目 | 线条颜色，由 `--foreground` 按比例混合，对应 `border-edge` 等工具类，亮暗各一份 |
| `--flow-blue` 等 6 个 `--flow-*` | `flow-diagram`、`stat-card`、`mini-chart`、`chart-card`、`greeting` | 流程图与图表的辅助色，亮暗各一份 |
| `screen-line-top`、`pattern-ruler`、`bg-grid` 等 `@utility` | `grid-layout` | 全宽横线、点阵与刻度尺分隔带 |
| `html, body { overflow-x: clip }`（`@layer base`） | `grid-layout` | 全宽横线比视口宽，用它避免出现横向滚动条 |

CLI 还会在 `@theme inline` 里多写一行 `--edge: var(--edge)`，这是 CLI 对自定义变量的固定写法，不影响显示。变量的值可以随时改，见[主题定制](/docs/theming/)。

### 已经有同名文件时

- 内容完全相同的文件自动跳过，输出里是 `Skipped ... files (files might be identical, use --overwrite to overwrite)`。
- 内容不同的文件会逐个询问：`The file button.tsx already exists. Would you like to overwrite? (y/N)`，默认是 N（保留你的文件）。
- `-y` 只跳过其他确认，**不会**替你回答覆盖提示。在 CI、脚本等非交互环境里遇到内容不同的同名文件时，CLI 停在这个提示后直接结束，一个文件都不写，退出码仍是 0；这类场景请先用 `--dry-run` 确认，或者显式加 `-o`。
- 加 `-o`（`--overwrite`）强制覆盖，会丢掉你对这些文件的修改。
- 想先看会改什么：`--dry-run` 只预览，`--diff` 看差异，`--view` 看文件内容。

```bash title="终端"
pnpm dlx shadcn@latest add https://yiui.dev/r/value-slider.json --dry-run
```

## 手动安装

不想用 CLI 时，条目页的「手动」标签把需要做的事列全了：先装依赖条目与 shadcn 组件、安装 npm 包、复制源码（标题是安装路径）、合并样式（给出要写进全局样式的完整 CSS）。npm 包与样式已经把依赖条目的部分汇总在内，依赖条目只需要复制它们的源码文件。

## 下一步

- 浏览[组件](/components/)、[区块](/blocks/)与[模板](/templates/)。
- 阅读[主题定制](/docs/theming/)，了解线条颜色、亮暗模式与颜色主题如何安装。
- 让 AI 编辑器直接检索和安装条目，见 [AI 与 llms.txt](/docs/llms/)。

## 常见问题

### CLI 报 `other side closed`

实测在同时设置了 `HTTP_PROXY`/`HTTPS_PROXY` 与 SOCKS 的 `ALL_PROXY`（`socks5h://…`）时，CLI 请求 `ui.shadcn.com` 会以 `other side closed` 失败；去掉 SOCKS 变量后同一条命令正常：

```bash title="终端"
env -u ALL_PROXY -u all_proxy pnpm dlx shadcn@latest add https://yiui.dev/r/grid-layout.json
```

### 项目是 Radix 底座，能用吗

不推荐，但大部分条目能用。CLI 会按项目底座生成 shadcn 原语，所以安装本身不会报错。实测在 `radix-nova` 项目里装全部 30 个条目：

- 只有 `app-shell-01` 的类型检查失败，共 5 处，都是 Base UI 与 Radix 的写法差异：`DialogTrigger`、`PopoverTrigger`、`TooltipTrigger`、`DropdownMenuTrigger` 没有 `render` 属性，`Tooltip` 没有 `disabled` 属性。
- 其余条目类型检查通过；`auth-01`、`settings-01`、`agent-chat-01` 的页面构建后能正常打开。

要在 Radix 项目里用 `app-shell-01`，需要自己改这 5 处；更省事的做法是换成 Base UI 底座。

### 找不到 `@/components/ui/...` 模块

检查 `tsconfig.json` 的 `paths` 与 `components.json` 的 `aliases` 是否一致。文件写到了 `components.json` 指定的别名目录，而不是固定的 `components/ui`。

### 样式没生效：线条不显示、`border-edge` 无效

打开全局样式，确认有 `--edge`（`:root` 与 `.dark`）和 `@theme inline` 里的 `--color-edge: var(--edge)`。改过全局 CSS 后 Turbopack 不更新时，删掉 `.next` 目录再启动。

### 服务端组件里调用 `flowRoute` 报错

报错形如 `Attempted to call flowRoute() from the server`。`flow-diagram.tsx` 是客户端模块，服务端组件不能直接调用它再导出的函数。在带 `"use client"` 的文件里使用，或在服务端组件里改从 `flow-diagram/route.ts` 引入 `flowRoute`、`flowArrival`。

### CLI 末尾提示给应用包上 `TooltipProvider`

这是 shadcn 安装 `tooltip` 时的通用提示。`app-shell-01` 已经自带 `TooltipProvider`，不用再包。

---

# AI 与 llms.txt

来源：https://yiui.dev/docs/llms/

## llms.txt

站点按 [llms.txt](https://llmstxt.org) 约定提供两个纯文本入口：

- [`/llms.txt`](https://yiui.dev/llms.txt)：站点简介、安装方式、组件清单与文档链接。适合当作索引喂给模型。
- [`/llms-full.txt`](https://yiui.dev/llms-full.txt)：全部文档与博客的 MDX 原文。适合一次性放进上下文。

两个文件都在构建时生成，内容与页面保持一致。

## 在 AI 编辑器中使用

最简单的方式：让 Agent 先读 `https://yiui.dev/llms.txt`，从中找到组件清单和每个条目的 JSON 地址，再按[安装](/docs/installation/)页里的命令运行。

向 Agent 提需求时，建议明确写出：

- 使用 Yi UI 的哪个条目，例如「用 `@yiui/grid-layout` 搭页面骨架」。
- 项目要先按[安装](/docs/installation/)初始化 shadcn，底座选 Base UI；让 Agent 先看 `components.json` 的 `style` 是否以 `base-` 开头。
- 安装前先加 `--dry-run` 看会写入哪些文件，已有同名文件默认不要覆盖。
- 颜色只用主题变量，不要硬编码。
- 安装后源码属于项目，可以按需修改。

如果 Agent 的运行环境设置了 SOCKS 代理（`ALL_PROXY`），shadcn CLI 可能以 `other side closed` 失败，让它用 `env -u ALL_PROXY -u all_proxy` 去掉该变量再运行，详见[安装](/docs/installation/#常见问题)。

## shadcn MCP

shadcn 官方提供 MCP 服务，可以让 AI 编辑器直接检索和安装 Registry 里的条目。先在 `components.json` 里配置好 `@yiui` 命名空间（见 [Registry 与命名空间](/docs/registry/)），然后初始化 MCP：

```bash title="终端"
pnpm dlx shadcn@latest mcp init --client claude
```

`--client` 可选 `claude`、`cursor`、`vscode`、`codex` 等。也可以手动写配置，例如 Claude Code 的 `.mcp.json`：

```json title=".mcp.json"
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}
```

配置完成后，可以直接这样对 Agent 说：

- 「列出 @yiui 里所有组件」
- 「把 @yiui/auth-01 加到项目里」

---

# Registry 与命名空间

来源：https://yiui.dev/docs/registry/

本站的所有条目都以 JSON 形式静态发布在 `/r/` 下，格式遵循 shadcn 的 registry-item 规范。开始之前请先按[安装](/docs/installation/)初始化 shadcn（Base UI 底座）。

## URL 安装

每个条目都有固定地址 `https://yiui.dev/r/<name>.json`，直接交给 CLI 即可，不需要配置：

```bash title="终端"
pnpm dlx shadcn@latest add https://yiui.dev/r/grid-layout.json
```

## 配置命名空间

在项目的 `components.json` 中合并以下配置。若已有其他 Registry，请保留原有条目。

```json title="components.json"
{
  "registries": {
    "@yiui": "https://yiui.dev/r/{name}.json"
  }
}
```

CLI 会把条目名代入 `{name}`，于是命令可以缩短为：

```bash title="终端"
pnpm dlx shadcn@latest add @yiui/grid-layout
```

两种方式装出来的文件和样式完全一样。

## 条目目录

完整的条目清单位于 [`/r/registry.json`](https://yiui.dev/r/registry.json)，包含每个条目的类型、依赖与文件列表。可以用它做检索，也可以交给脚本或 AI 工具读取。

也可以用 CLI 直接查看（需要先配置命名空间）：

```bash title="终端"
pnpm dlx shadcn@latest search @yiui
pnpm dlx shadcn@latest view @yiui/grid-layout
```

`search` 列出全部条目及说明，`view` 输出条目的完整 JSON，包含每个文件的源码。装之前想知道会写入哪些文件，可以给 `add` 加 `--dry-run`。

## 条目类型

| 类型 | 内容 | 示例 |
| --- | --- | --- |
| `registry:ui` | 单个组件，安装到 `components/ui/<name>/` | `grid-layout` |
| `registry:block` | 区块，由多个文件和组件组成，页面文件写入 `app/` | `auth-01` |
| `registry:page` | 整页模板，会写入 `app/` 下的页面与布局 | `app-shell-01` |
| `registry:theme` | 颜色主题，只写入 CSS 变量，会改写已有的同名变量 | `theme-blue` |

文件的具体落点、样式写入的内容见[安装](/docs/installation/)。

## 依赖关系

条目之间通过 `registryDependencies` 相互依赖，值有两种：

- shadcn 官方组件名，如 `button`、`input`，由 CLI 按你项目的底座生成。
- 本站其他条目的完整地址，如 `https://yiui.dev/r/flow-diagram.json`。

安装时依赖会递归解析、一起装上，所以即便你用 `@yiui/...` 命名空间，CLI 取依赖条目时访问的仍是 `https://yiui.dev/r/` 下的地址。已存在的文件默认会提示是否覆盖，处理方式见[安装](/docs/installation/#已经有同名文件时)。

大层级依赖小层级：区块和模板由组件拼成，组件之间也有依赖，例如 `value-slider` 依赖 `flow-diagram`，`flow-diagram` 再依赖 `grid-layout`。每个条目页的「命令」标签会列出会连带安装的内容，「手动」标签给出完整的依赖清单。

---

# 主题定制

来源：https://yiui.dev/docs/theming/

## 变量体系

所有组件只使用 shadcn 的语义变量：`background`、`foreground`、`muted-foreground`、`primary`、`border` 等，不写死任何颜色。换一套变量，整站颜色就随之改变。

线条网格额外引入一个变量 `--edge`，由前景色按比例混合得到，用于所有线条和分隔带。CLI 安装条目时写入你的 `globals.css` 的是这样的：

```css title="globals.css"
@theme inline {
  --color-edge: var(--edge);
}

:root {
  --edge: color-mix(in oklch, var(--foreground) 12%, transparent);
}

.dark {
  --edge: color-mix(in oklch, var(--foreground) 18%, transparent);
}
```

`@theme inline` 里的 `--color-edge` 让 `border-edge`、`bg-edge` 这些工具类可用。因为 `--edge` 跟随 `foreground` 计算，切换任何颜色主题后线条都会自动适配。`grid-layout` 以及 `stat-card`、`chart-card`、`control-panel` 等用到线条的条目都会写入它，已存在时不会重复添加。

流程图与图表的辅助色 `--flow-blue`、`--flow-green`、`--flow-amber`、`--flow-rose`、`--flow-violet`、`--flow-cyan` 同样以亮、暗各一份写入 `:root` 与 `.dark`，由 `flow-diagram`、`stat-card` 等条目带来，不随颜色主题变化，亮暗模式下都保证看得清。

## 亮暗模式

亮暗模式通过 `html` 上的 `.dark` class 切换，本站使用 `next-themes` 管理。它和颜色主题互不干扰：同一个颜色主题有亮、暗两组变量。

## 颜色主题

本站提供 14 套颜色主题，色值取自 Tailwind CSS v4 默认调色板（oklch），可以在[颜色主题](/themes/)页面实时预览，切换主题与亮暗模式，并复制 CSS。主题名统一按「中文 · English」显示，英文名就是 Tailwind 的色名，也是安装时用的 id。

本站自己用 `html` 上的 `data-theme` 属性切换颜色主题。你的项目里安装主题则是另一回事，见下面的「安装主题」。

### 中性基底 · Neutrals

三个灰族决定整套界面灰阶的色偏：背景、卡片、`muted`、边框、次要文字和 `primary` 都取自同一个灰族，选择器里用「浅 / 中 / 深」三段色带展示色偏。

| 主题 | id | 亮色 primary | 暗色 primary |
|---|---|---|---|
| 红色 · Red | `red` | red-600 | red-500 |
| 橙色 · Orange | `orange` | orange-600 | orange-600 |
| 琥珀 · Amber | `amber` | amber-600 | amber-600 |
| 青柠 · Lime | `lime` | lime-600 | lime-600 |
| 绿色 · Green | `green` | green-700 | green-600 |
| 青绿 · Teal | `teal` | teal-600 | teal-600 |
| 天蓝 · Sky | `sky` | sky-600 | sky-600 |
| 蓝色 · Blue | `blue` | blue-600 | blue-500 |
| 紫罗兰 · Violet | `violet` | violet-600 | violet-500 |
| 紫红 · Fuchsia | `fuchsia` | fuchsia-600 | fuchsia-500 |
| 粉红 · Pink | `pink` | pink-600（明度下调 0.012） | pink-500 |

- 彩色主题的按钮一律白字：深色字压在饱和色上发脏，统一白字更协调。为此每个主题取能让白字达到 3:1 的档位（按钮文字是 14px 中粗字，按 WCAG AA 大字 / 界面组件标准）；正文和次要文字仍保证 4.5:1，主色作为文字或图形时对背景至少 3:1。
- 红色主题的主色和危险色（`destructive`）本来是同一种红，所以把危险色拉开：亮色改用 red-800，暗色改用 red-300。
- 校验脚本：`pnpm tsx scripts/theme-contrast.ts` 会列出全部主题在亮、暗下的对比度，任何一项不达标就以非零状态退出。

> 之前的 `zinc`、`rose` 已移除。浏览器里保存了这两个 id 的访客会自动回落到默认的 `neutral`，不会报错。

## 安装主题

每套主题都是一个 `registry:theme` 条目，命名为 `theme-<id>`，只写入 CSS 变量，不写文件、不装依赖：

```bash title="终端"
pnpm dlx shadcn@latest add https://yiui.dev/r/theme-blue.json
```

配置了命名空间时（见 [Registry 与命名空间](/docs/registry/)）：

```bash title="终端"
pnpm dlx shadcn@latest add @yiui/theme-blue
```

实测（`theme-blue`）：CLI 会直接改写 `globals.css` 里 `:root` 与 `.dark` 中已有的同名变量，共 30 个（`--background`、`--primary`、`--chart-1`~`--chart-5`、`--sidebar-*` 等），**不会**生成 `data-theme` 选择器，所以一个项目同一时间只有一套主题，装另一套就是覆盖。改过这些变量的话，先提交或备份再安装。

主题不包含 `--radius`，圆角仍由你的 `globals.css` 决定；也不包含 `--edge` 与 `--flow-*`，线条随新主题的 `foreground` 自动变色。想像本站一样在运行时切换多套主题，需要自己把各套变量写成 `:root[data-theme="…"]` 选择器，可以参考[颜色主题](/themes/)页面复制的 CSS。

## 自定义

直接修改 `globals.css` 里的变量即可。建议只改变量值，不在组件里写具体颜色，这样所有条目都会跟着变化。

---

# 企业控制台布局

来源：https://yiui.dev/templates/app-shell-01/

<BlockViewer name="app-shell-01" />

`AppShell` 提炼自我的一个企业监控平台项目的整体布局，去掉了接口请求、权限过滤和登录逻辑，只留下布局与交互本身：

- **固定顶栏**：左侧品牌区宽度与导航对齐，右侧依次是 `headerActions`、亮暗模式切换、用户菜单；中间是自动生成的面包屑。
- **一级导航**：按分组排列，当前页高亮；可折叠为图标栏（名称出现在 Tooltip 里），折叠状态记在 `localStorage`，刷新后首帧就是上次的状态，不会闪烁。
- **二级工作区侧栏**：一级导航里的「模块」被选中时，右侧多出一栏，列出该模块下的页面。
- **独立滚动的主区域**：顶栏和侧栏固定，只有 `main` 滚动，切换页面自动回到顶部。
- **右侧 `aside` 插槽**：与 `main` 并排，高度占满顶栏以下的区域，用来放 AI 助手面板等。
- **窄屏适配**：宽度小于 768px 时，一级导航变成左侧 Sheet 抽屉，二级导航变成顶栏下方的横向标签条。
- 页面侧附带 `PageHeader`、`PageTabs`、`PageToolbar`、`PageFrame`，对应原项目的页面框架、范围切换和列表工具栏。
- 演示页直接用站内自研的数据展示组件拼成：
  - 概览页：指标是 [统计卡片](/components/stat-card) 加 [迷你图](/components/mini-chart) 走势；[图表卡片](/components/chart-card) 里依次是响应耗时趋势、错误预算（刻度仪表）、状态码分布（环形图）、最慢接口排行与最近事件表；范围切换用 [分段选择](/components/segmented-control)。
  - 拨测记录、接口探测、节点监控、事件与异常：各自带一组贴合主题的数据摘要（拨测量堆叠柱与异常原因环形图、耗时分布与 SLO 达标环、各区域 CPU / 内存进度环、事件趋势与处理进度），由 `ListPage` 的 `summary` 插槽放在列表上方。
  - 图表区用 Tailwind 的容器查询（`@container`）排版：主区域被右侧 `aside`（如 AI 助手面板）挤窄时自动改为单列，不只看浏览器视口宽度。
- 颜色全部来自主题变量，切换颜色主题和亮暗模式后自动跟随，预览里可以直接试。

预览里没有真实路由，所以演示用 `activeHref` + `onNavigate` 在本地模拟导航；接入 Next.js 时这两个属性都不用传，组件会用 `usePathname()` 高亮当前页。

## 安装

<InstallCommand name="app-shell-01" />

会安装 shadcn 的 `button`、`avatar`、`breadcrumb`、`dropdown-menu`、`input`、`popover`、`sheet`、`tooltip`，本站的 [统计卡片](/components/stat-card)、[迷你图](/components/mini-chart)、[图表卡片](/components/chart-card) 与 [分段选择](/components/segmented-control)（概览页与范围切换用到），npm 包 `lucide-react`、`next-themes`，以及 `hooks/use-controllable-state.ts`。如果项目里已有同名文件，CLI 会询问是否覆盖。

> 亮暗模式按钮依赖项目里已有的 `next-themes` `ThemeProvider`；不需要的话给 `AppShell` 传 `themeToggle={false}`。

## 文件结构

安装后文件落在这些位置（项目使用 `src/` 目录时会自动加上 `src/` 前缀）。入口是 `app-shell.tsx`：

```text
app/(app)/
├── layout.tsx                 # 控制台布局：把导航数据交给 AppShell
└── dashboard/
    ├── page.tsx               # 示例页面：概览仪表盘
    └── [...slug]/page.tsx     # 导航中其余页面的占位：通用列表页 + 该页数据摘要
hooks/use-controllable-state.ts  # 受控 / 非受控状态 hook
components/app-shell/
├── app-shell.tsx              # ★ 入口：组合顶栏、导航、主区域、aside 插槽
├── app-shell-script.tsx       # 首帧脚本：水合前恢复侧栏折叠状态
├── app-header.tsx             # 固定顶栏：品牌、折叠按钮、面包屑、右侧操作区
├── primary-nav.tsx            # 一级导航（支持折叠为图标栏）
├── workspace-sidebar.tsx      # 二级工作区侧栏 + 窄屏横向标签条
├── nav-config.ts              # ★ 导航数据，集中配置
├── nav-types.ts               # 导航类型与 resolveNav（根据地址找到当前位置）
├── config.ts                  # ★ 默认文案、文案上下文、一级导航宽度与过渡类名、存储键
├── nav-link.tsx               # 对 next/link 的封装，统一处理点击行为
├── page-header.tsx            # PageHeader / PageTabs / PageContent / PageFrame
├── page-toolbar.tsx           # 列表工具栏：总数、翻页、搜索、筛选插槽
├── header-status.tsx          # 顶栏服务状态弹层（数据由外部传入）
├── user-menu.tsx              # 头像 + 下拉菜单
├── theme-toggle.tsx           # 亮暗模式切换
├── use-stored-flag.ts         # 持久化到 localStorage 的布尔状态
├── dashboard-overview.tsx     # 演示：概览仪表盘（统计卡片 + 趋势图 + 图表区 + 事件表）
├── overview-charts.tsx        # 演示：概览的错误预算、状态码分布、最慢接口三张图表卡片
├── distribution-card.tsx      # 演示：环形图 + 图例格的占比卡片（概览与拨测记录共用）
├── page-summaries.tsx         # 演示：各导航页的数据摘要（按导航项 id 选择）
├── list-page.tsx              # 演示：列表页（工具栏 + summary 插槽 + 图表卡片里的明细表）
└── sample-data.ts             # 演示用假数据
```

演示相关的文件（`dashboard-overview.tsx`、`overview-charts.tsx`、`distribution-card.tsx`、`page-summaries.tsx`、`list-page.tsx`、`sample-data.ts`）只用来展示布局效果，接入真实数据后可以直接删除。

## 用法

`app/(app)/layout.tsx` 把导航数据和用户信息交给 `AppShell`，路由组 `(app)` 下的所有页面都会套上这层壳：

```tsx title="app/(app)/layout.tsx"
"use client"

import { AppShell } from "@/components/app-shell/app-shell"
import { navConfig } from "@/components/app-shell/nav-config"

export default function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <AppShell
      nav={navConfig}
      brand={{ name: "Acme 控制台", tagline: "企业级监控与运维" }}
      user={{ name: "管理员", email: "admin@example.com" }}
      onSignOut={() => {
        // 调用你的认证服务退出登录
      }}
    >
      {children}
    </AppShell>
  )
}
```

> 导航数据里的图标是 React 组件（函数），无法从服务端组件传给客户端组件，所以这个布局需要 `"use client"`。页面本身仍然可以是服务端组件。导航里的其余链接由 `dashboard/[...slug]/page.tsx` 兜底，显示通用列表页；在 `app/(app)/dashboard/` 下新建同名路由（例如下文的 `system/users/page.tsx`）就会替换掉对应的占位页。导航项改了地址或删掉后，兜底页会跟着导航数据走，不需要另外维护。

### 配置导航

导航数据都在 `nav-config.ts`，类型定义在 `nav-types.ts`：

```ts title="nav-config.ts"
import { LayoutDashboard, Settings, Users } from "lucide-react"
import type { NavConfig } from "./nav-types"

const navConfig: NavConfig = {
  sections: [
    {
      id: "workspace",
      label: "工作台",                       // 一级导航里的分组小标题
      entries: [
        // 叶子条目：点击直接跳转
        { id: "overview", label: "概览", href: "/dashboard", icon: LayoutDashboard },
        // 模块条目：有 items，选中后出现二级侧栏
        {
          id: "system",
          label: "系统管理",
          icon: Settings,
          description: "账号、权限与系统设置", // 二级侧栏顶部的副标题
          items: [
            {
              id: "users",
              label: "用户管理",
              href: "/dashboard/system/users",
              icon: Users,
              description: "账号与角色分配",    // 二级侧栏里的说明
              badge: 3,                          // 可选角标
            },
          ],
        },
      ],
    },
  ],
  // 固定在一级导航底部的分组，可选
  footer: { id: "resources", label: "资源与帮助", entries: [/* … */] },
}

export { navConfig }
```

| 类型 | 字段 | 说明 |
| --- | --- | --- |
| `NavLeaf` | `id` `label` `href` `icon` | 叶子条目；`description`、`badge` 可选 |
| `NavModule` | `id` `label` `icon` `items` | 模块；`items` 是 `NavLeaf[]`，`description` 可选。一级导航里点击模块会跳到第一个子项 |
| `NavSection` | `id` `label` `entries` | 一级导航的分组，`entries` 可以混排叶子和模块 |
| `NavConfig` | `sections` `footer?` | `footer` 固定在一级导航底部 |

约定：

- **高亮匹配**：`resolveNav(config, href)` 取 `href` 匹配最长的条目，`/dashboard/system/users/12` 会匹配到 `/dashboard/system/users`。比较时忽略查询串、哈希和末尾斜杠，开启 `trailingSlash` 的项目也能正常高亮。
- **面包屑**自动由「分组 → 模块 → 页面」生成，窄屏只显示最后一级。
- 没有匹配到任何条目时，不显示二级侧栏和面包屑，布局仍然正常。
- 需要按权限过滤导航时，在传给 `AppShell` 之前先过滤 `navConfig` 即可，组件本身不关心权限。

## 示例

### 在 aside 里放 AI 助手

`aside` 会渲染成 `main` 右侧的兄弟元素，和 `main` 一起在横向 flex 布局里分配宽度，高度占满顶栏以下的区域。放进来的面板应该：

1. 根元素是 `h-full` 的 `<aside>`，**自带宽度**（如 `w-96 shrink-0`），自己决定边框与背景；
2. 窄屏下是否隐藏由面板自己处理（例如加 `hidden lg:flex`）。

「AI 助手」按钮放进 `headerActions`，面板放进 `aside`，用一个状态位控制显隐：

```tsx title="app/(app)/layout.tsx"
"use client"

import { SparklesIcon } from "lucide-react"
import * as React from "react"

import { AppShell } from "@/components/app-shell/app-shell"
import { navConfig } from "@/components/app-shell/nav-config"
import { Button } from "@/components/ui/button"

export default function AppLayout({ children }: { children: React.ReactNode }) {
  const [assistantOpen, setAssistantOpen] = React.useState(false)
  return (
    <AppShell
      nav={navConfig}
      headerActions={
        <Button
          variant={assistantOpen ? "secondary" : "ghost"}
          aria-pressed={assistantOpen}
          onClick={() => setAssistantOpen((open) => !open)}
        >
          <SparklesIcon data-icon="inline-start" />
          AI 助手
        </Button>
      }
      aside={assistantOpen ? <YourAssistantPanel /> : null}
    >
      {children}
    </AppShell>
  )
}
```

站内的 [AI 助手面板](/blocks/agent-chat-01/) 区块在「嵌入」模式下就是这样一个自带宽度的 `<aside>`，可以直接放进 `aside` 插槽。

### 受控的侧栏折叠

`collapsed` / `defaultCollapsed` / `onCollapsedChange` 成对出现，同时支持受控与非受控。不传 `collapsed` 时组件自己维护，并把状态记在 `localStorage`（默认键 `travinsy:app-shell:collapsed`，可用 `storageKey` 修改）；传了就完全由你决定，不再读写本地存储，也不注入首帧脚本：

```tsx
const [collapsed, setCollapsed] = React.useState(false)

<AppShell nav={navConfig} collapsed={collapsed} onCollapsedChange={setCollapsed}>
  {children}
</AppShell>
```

受控模式下想避免首屏闪烁，要让**首次渲染传入的值就是最终状态**，例如在服务端从 cookie 读取后作为初始值传入；静态导出没有请求上下文，通常直接用默认的非受控模式即可。

### 首帧脚本：刷新不闪烁

静态导出的 HTML 在构建时生成，服务端不知道用户上次是否折叠过侧栏。如果等水合后再读 `localStorage`，已折叠的用户每次刷新都会先看到展开、再跳成折叠。`AppShell` 的做法与站点的颜色主题相同：

1. 非受控时，`AppShell` 在根元素里的第一个子节点渲染一段很短的内联脚本（`AppShellScript`）。浏览器解析 HTML 时同步执行它，在首次绘制与水合之前读取 `localStorage`，把结果写到根元素的 `data-collapsed`；没有本地记录时保持 `defaultCollapsed`。
2. 侧栏宽度、顶栏品牌区、图标 / 文字显示等**所有随折叠变化的样式都由 `data-collapsed` 通过 CSS 决定**（Tailwind 的 `group-data-[collapsed]/app-shell:` 变体），不依赖 React 状态，所以水合前就是正确的外观。
3. 水合后 React 状态读到同一个值，与 DOM 一致；根元素带 `suppressHydrationWarning`，所以脚本改写属性不会触发水合警告。点击折叠按钮时 React 同步更新 `data-collapsed` 与 `localStorage`。
4. 宽度过渡只在用户点击折叠按钮后才开启（根元素出现 `data-animate`），首次渲染与水合不会播放动画。
5. 通过路由跳转（客户端渲染）进入控制台时脚本不会执行，此时 React 直接按 `localStorage` 渲染，同样没有闪烁。

整个机制写在 `(app)` 布局的 `AppShell` 里，**不需要改根布局，也不需要在布局里手动放脚本**；`storageKey` 会自动传给脚本。如果你不用 `AppShell`、而是自己组合 `AppHeader` / `PrimaryNav`，可以单独使用 `AppShellScript`，把它放在带 `group/app-shell` 与 `data-collapsed` 的容器里作为第一个子节点，并给该容器加 `suppressHydrationWarning`。

> 内联脚本在严格的内容安全策略（CSP，不允许 `'unsafe-inline'`）下会被拦截，需要自行为脚本添加 nonce；脚本被拦截时退化为水合后再恢复折叠状态。

### 页面框架

主区域里的页面可以用 `page-header.tsx` 和 `page-toolbar.tsx` 里的组件快速搭起来：

```tsx title="app/(app)/dashboard/system/users/page.tsx"
import { PageFrame } from "@/components/app-shell/page-header"
import { PageToolbar } from "@/components/app-shell/page-toolbar"

<PageFrame
  section="系统管理"
  title="用户管理"
  description="账号与角色分配"
  actions={<Button>新建</Button>}
  toolbar={<PageToolbar total={128} page={1} pageSize={20} onPageChange={setPage} />}
>
  {/* 表格、卡片…… */}
</PageFrame>
```

### 自定义文案

用户可见文案集中在 `config.ts` 的 `DEFAULT_LABELS`，通过 `labels` 覆盖任意几项。`AppShell` 会把合并后的文案放进 context，所以主区域里的 `PageHeader`、`PageToolbar`、演示页面等组件会自动继承，不需要再逐个传 `labels`；单个组件也可以传自己的 `labels` 覆盖外层值。带占位符的文案会被填入实际名称：

```tsx
<AppShell
  nav={navConfig}
  labels={{ signOut: "Sign out", collapseSidebar: "Collapse", userMenu: "Account: {name}" }}
>
  {children}
</AppShell>
```

## API

### AppShell

<PropsTable name="app-shell-01" component="AppShell" />

### AppShellScript

<TypeTable
  type={{
    storageKey: { type: "string", description: "读取折叠状态的 `localStorage` 键，需与 `AppShell` 的 `storageKey` 一致", default: '"travinsy:app-shell:collapsed"' },
  }}
/>

通常不需要直接使用，`AppShell` 在非受控时会自动渲染它。

### 页面组件

| 组件 | 属性 | 说明 |
| --- | --- | --- |
| `PageHeader` | `title` `description?` `section?` `actions?` | 标题栏，滚动时吸附在主区域顶部 |
| `PageTabs` | `tabs` `value` `onValueChange` `trailing?` `labels?` | 范围切换条（应用、环境等），用分段选择实现，单选语义 |
| `PageToolbar` | `total` `page` `pageSize` `onPageChange` `search?` `onSearchChange?` `filters?` `labels?` | 总数、翻页、搜索；状态完全受控 |
| `PageContent` | — | 统一内边距与纵向间距 |
| `PageFrame` | 同 `PageHeader`，另有 `tabs?` `toolbar?` | 把标题栏、标签条、工具栏、内容区一次组合 |
| `HeaderStatus` | `services` `checkedAt?` `labels?` | 顶栏服务状态弹层，放进 `headerActions` |
| `UserMenu` / `ThemeToggle` | `labels?` | 头像菜单与亮暗模式切换 |
| `PrimaryNav` / `WorkspaceSidebar` / `WorkspaceMobileNav` | `config` 或 `module` `active`/`activeId` `labels?` | 一级导航与二级工作区导航，通常由 `AppShell` 组合 |

### labels

全部键在 `config.ts` 的 `DEFAULT_LABELS` 里。含 `{name}`、`{count}`、`{max}`、`{min}` 的文案会在渲染时填入实际值。

**外壳**

<TypeTable
  type={{
    skipToContent: { type: "string", description: "键盘跳转链接", default: '"跳转到主内容"' },
    mainContent: { type: "string", description: "`main` 的 `aria-label`", default: '"主内容"' },
    mainNavigation: { type: "string", description: "一级导航名称、窄屏抽屉说明", default: '"主导航"' },
    mainNavigationDescription: { type: "string", description: "一级导航名称、窄屏抽屉说明", default: '"选择要访问的页面"' },
    openNavigation: { type: "string", description: "窄屏打开抽屉按钮", default: '"打开导航"' },
    collapseSidebar: { type: "string", description: "折叠按钮名称，随状态切换", default: '"收起侧边栏"' },
    expandSidebar: { type: "string", description: "折叠按钮名称，随状态切换", default: '"展开侧边栏"' },
    breadcrumb: { type: "string", description: "面包屑的 `aria-label`", default: '"面包屑"' },
    brandHome: { type: "string", description: "品牌链接的 `aria-label`", default: '"{name}，回到首页"' },
    workspaceNavigation: { type: "string", description: "二级导航与二级侧栏的 `aria-label`", default: '"{name}导航"' },
    workspaceSidebar: { type: "string", description: "二级导航与二级侧栏的 `aria-label`", default: '"{name}侧栏"' },
    toggleTheme: { type: "string", description: "亮暗模式按钮", default: '"切换亮暗模式"' },
    userMenu: { type: "string", description: "用户菜单", default: '"用户菜单：{name}"' },
    signOut: { type: "string", description: "用户菜单", default: '"退出登录"' },
    pageToolbar: { type: "string", description: "工具栏名称与总数单位", default: '"列表控制"' },
    totalUnit: { type: "string", description: "工具栏名称与总数单位", default: '"条"' },
    previousPage: { type: "string", description: "翻页按钮", default: '"上一页"' },
    nextPage: { type: "string", description: "翻页按钮", default: '"下一页"' },
    search: { type: "string", description: "搜索框默认名称", default: '"搜索"' },
    serviceStatus: { type: "string", description: "顶栏服务状态", default: '"服务状态"' },
    serviceStatusAria: { type: "string", description: "顶栏服务状态", default: '"查看服务状态：{name}"' },
    checkedAt: { type: "string", description: "顶栏服务状态", default: '"检查于 {name}"' },
    stateHealthy: { type: "string", description: "服务状态文字", default: '"可用"' },
    stateWarning: { type: "string", description: "服务状态文字", default: '"需关注"' },
    stateUnavailable: { type: "string", description: "服务状态文字", default: '"不可用"' },
    stateUnknown: { type: "string", description: "服务状态文字", default: '"未知"' },
  }}
/>

**页面内容（演示页）**

<TypeTable
  type={{
    overviewSection: { type: "string", description: "概览页标题栏", default: '"工作台"' },
    overviewTitle: { type: "string", description: "概览页标题栏", default: '"概览"' },
    overviewDescription: { type: "string", description: "概览页说明", default: '"近 24 小时的拨测质量与告警情况"' },
    exportAction: { type: "string", description: "概览页操作按钮", default: '"导出"' },
    refreshAction: { type: "string", description: "概览页操作按钮", default: '"刷新"' },
    scopeSwitch: { type: "string", description: "范围切换条的 `aria-label`", default: '"数据范围"' },
    keyMetrics: { type: "string", description: "统计卡片区的 `aria-label`", default: '"关键指标"' },
    statTrendLabel: { type: "string", description: "统计卡片里迷你走势的读屏名称", default: '"{name}近 24 小时走势"' },
    latencyTrend: { type: "string", description: "响应耗时图表卡片", default: '"响应耗时趋势"' },
    latencyTrendUnit: { type: "string", description: "响应耗时图表卡片", default: '"每小时 P50，单位 ms"' },
    latencySeries: { type: "string", description: "图表序列名（提示框里显示）", default: '"P50 响应耗时"' },
    latencyPeak: { type: "string", description: "图表头部的指标名", default: '"峰值"' },
    latencyLow: { type: "string", description: "图表头部的指标名", default: '"谷值"' },
    latencyAverage: { type: "string", description: "图表头部的指标名", default: '"均值"' },
    latencyChartLabel: { type: "string", description: "响应耗时图表的 `aria-label`", default: '"过去 24 小时响应耗时，最高 {max} 毫秒，最低 {min} 毫秒"' },
    recentEvents: { type: "string", description: "事件表卡片与表格题注", default: '"最近事件"' },
    recentEventsCount: { type: "string", description: "事件表卡片与表格题注", default: '"按时间倒序，共 {count} 条"' },
    eventsCaption: { type: "string", description: "事件表卡片与表格题注", default: '"最近拨测事件"' },
    createAction: { type: "string", description: "列表页新建按钮", default: '"新建"' },
    searchEvents: { type: "string", description: "列表页搜索框", default: '"搜索应用或目标"' },
    listCaption: { type: "string", description: "列表页表格题注", default: '"{title}列表"' },
    emptyRows: { type: "string", description: "空结果提示", default: '"没有匹配的记录"' },
    columnApp: { type: "string", description: "表头", default: '"应用"' },
    columnTarget: { type: "string", description: "表头", default: '"目标"' },
    columnStatus: { type: "string", description: "表头", default: '"状态"' },
    columnLatency: { type: "string", description: "表头", default: '"耗时"' },
    columnTime: { type: "string", description: "表头", default: '"时间"' },
    eventOk: { type: "string", description: "事件状态徽标文字", default: '"正常"' },
    eventWarning: { type: "string", description: "事件状态徽标文字", default: '"需关注"' },
    eventError: { type: "string", description: "事件状态徽标文字", default: '"异常"' },
  }}
/>

### data-slot 与状态

根元素都带 `data-slot`，方便用选择器或 `has-data-[slot=…]` 定制：`app-shell`（`data-collapsed`、`data-animate`、`data-has-aside`、`data-has-workspace`）、`app-shell-header`、`app-shell-sidebar`、`app-shell-primary-nav`、`app-shell-nav-item`（`data-active`）、`app-shell-workspace-sidebar`、`app-shell-workspace-item`（`data-active`）、`app-shell-main`、`app-shell-page-header`、`app-shell-page-toolbar` 等。

## 可访问性

- 提供「跳转到主内容」链接，键盘 Tab 的第一个焦点；`main` 带 `aria-label`。
- 一级导航、二级导航、面包屑都是带名称的 `nav`；当前页用 `aria-current="page"`，当前模块用 `aria-current="true"`。
- 侧栏折叠按钮带 `aria-expanded` 与随状态变化的名称；折叠后导航项仍有 `aria-label`，并通过 Tooltip 显示名称。
- 窄屏抽屉是 Sheet（Base UI Dialog）：Esc 关闭、焦点被困在抽屉内、关闭后焦点回到触发按钮。
- 纯图标按钮都有 `aria-label`；状态徽标同时用图标与文字，不只靠颜色。
- 表格有 `caption` 与 `th scope="col"`；图表是 `role="img"`，带一段描述整体数据的 `aria-label`，状态徽标用色点加文字；范围切换条是单选组，方向键切换。
- 过渡动画在系统开启「减少动态效果」时关闭。

## 注意事项

- **静态导出**：布局完全在客户端运行，不使用 Server Actions 或 `cookies()`，可用于 `output: "export"`。
- **折叠状态与水合**：服务端输出使用 `defaultCollapsed`，首帧脚本在水合前按 `localStorage` 改写根元素的 `data-collapsed`，详见上面的「首帧脚本」。折叠样式只依赖 `data-collapsed`，自定义时请沿用 `group-data-[collapsed]/app-shell:` 变体，不要根据 React 状态切换结构，否则水合前外观会不一致。
- **布局高度**：外层使用 `h-svh`，应放在不带其他固定高度父级的路由组布局里；预览用 iframe 的高度。
- **一级导航宽度只定义一处**：展开 200px、折叠 60px 写在 `config.ts` 的 `NAV_WIDTH_CLASS`，`app-shell.tsx` 的侧栏与 `app-header.tsx` 的品牌区都从这里取，改宽度只需改一处；窄屏品牌区的 `max-md:w-[60px]` 也在这个常量里。过渡类名在同文件的 `NAV_WIDTH_TRANSITION`。
- **文案继承**：`AppShell` 的 `labels` 通过 context 传遍整个外壳和主区域，页面里自己传的 `labels` 优先级更高。
- **颜色**：来自项目的主题变量（`globals.css`），到 [主题](/themes/) 页挑一套复制进去，整个控制台自动换色。

### 主区域与助手的响应式布局

一级导航保留折叠偏好与首帧恢复，800px 以下使用抽屉导航。二级导航在 1280px 以下改为横向标签栏。扣除导航后，工作区达到 1240px 才并排展示 AI 助手（包含最大 640px 拖拽宽度，主内容至少 600px）；不足时助手覆盖在右侧，768px 以下沿用底部 Sheet。关闭助手后主内容使用全部剩余空间。手机主内容随屏幕宽度收缩。

页头按主区域容器宽度换行，范围切换可横向滚动。统计卡按内容容器的 480px / 960px 阈值显示两列 / 四列，其余为单列；图表沿用容器查询。

---

# 页面模板

来源：https://yiui.dev/templates/



---

# 一套高度表，拼出一个控制面板

来源：https://yiui.dev/blog/bar-controls/

本站首页首屏右边有一块“调一调”面板：一块二维板调视角，两组分段选择换材质和地面，一排色点换色调，一个开关管音效。组件文档里每个示例下面也能展开一块调整面板，改完可以直接复制成 JSX。

这几块面板里的控件是同一套，外观、高度和行为一致。这篇讲它们怎么从一个数值滑块长出来，中间哪些设计被我推翻了，以及面板怎么把“当前参数”变成一段代码。

## 从一个滑块开始

起点是 `value-slider`，一个基于 Base UI Slider 的数值滑块：标签和读数放在轨道里面，拖出两端时轨道有橡皮筋式的过冲，松手后弹簧回弹。

做它的时候定下了一套外观，后来整个系列都沿用：

- 细边框 `border-edge`，圆角 `rounded-md`，底色 `bg-muted/60`；
- 填充用色调变量 `--flow-tone` 铺一层淡色，不指定色调时用前景色的 10%；
- 手柄是一道竖线，不是圆点。

这个造型在视觉上更像仪表上的一格，而不是通用的圆形滑块。我给它起名“方条”。

## 一张高度表

方条做出来之后，下一步是让它们能放在同一个面板里。控件各自的高度不一样，一排下来参差不齐，所以先定一张高度表：

| 档位 | `sm` | `default` | `lg` |
| --- | --- | --- | --- |
| `bar` | 28px | 32px | 36px |
| `compact` | 18px | 22px | 24px |

`bar` 是默认高度，文字放在条里；`compact` 文字仍在条里，字号收到 `xs`。数值滑块另外有一档 `slim`（6 / 8 / 10px），轨道太矮放不下文字，标签挪到上方，竖线手柄比轨道高出一截。

实现上，每个控件用 `cva` 声明一组 `compoundVariants`，把“形态 × 尺寸”映射成一个 CSS 变量，样式只读这个变量：

```tsx title="toggle-switch.tsx"
compoundVariants: [
  {
    variant: "bar",
    size: "default",
    class: "[--toggle-switch-height:2rem] [--toggle-switch-knob:0.875rem]",
  },
  {
    variant: "compact",
    size: "default",
    class: "[--toggle-switch-height:1.375rem] [--toggle-switch-knob:0.625rem]",
  },
  // …其余档位同理
],
```

根元素写成 `h-(--toggle-switch-height)`，手柄大小跟着 `--toggle-switch-knob` 走。每个控件的变量名不同，数字是同一张表。`value-slider`、`segmented-control`、`toggle-switch`、`tone-picker`、`angle-dial` 用的都是这套值，所以并排放在一个面板里自然对齐。

下面这个示例把三档高度并排放在一起：

<ComponentPreview name="value-slider-variant-demo" />

## 被我否决的设计

### pill 和 line

高度表的第一版并不是现在这样。数值滑块的 `size` 三档只差 28 / 32 / 36px，看起来几乎一样高，我觉得不够有区分度，于是加了一个 `variant`：

- `pill`：8 / 10 / 12px 的圆角粗轨，实色填充，圆形手柄；
- `line`：2 / 4 / 4px 的细线，同样是圆形手柄。

做出来才发现，这两种和通用的滑块没有区别，方条的辨识度丢了，也和后面要补的开关、分段选择对不上。这两个变体在同一天里被我撤掉，换成了现在的 `bar / compact / slim`：三档都是方条，细边框、淡色分层填充、竖线手柄都不变，只是高度不同。

### 分段选择的标题

`segmented-control` 的第一版，标签是方条左边一个带竖线分隔的独立格子，后面才是选项。用起来发现标题容易被当成第一个选项。

现在的结构是：左侧是纯文字的字段名，和滑块、开关的标签同一个位置同一个样式；选项放在右侧一道下凹的槽里，选中的那一项是槽里凸起的一块。不写 `label` 时，整条都是选项。

后来我又把槽和选中块上的描边去掉了：外框、凹槽、选中块三层线叠在一起太杂。现在凹槽只用浅底色，选中块用背景色加一点轻阴影浮起来。

<ComponentPreview name="segmented-control-demo" />

### 开关的手柄

开关最初沿用了竖线手柄，和滑块同形。但开关表达的是“开 / 关”两个状态，竖线停在左边还是右边，没有圆形手柄那么直观。我把它改成了胶囊轨道加圆形手柄，打开时轨道变成实色，整条也从左往右铺上淡色。滑块表达的是连续的值，用竖线；开关表达的是两个状态，用圆点。

<ComponentPreview name="toggle-switch-demo" />

### 读数可以直接点

滑块拖得再顺，想设一个精确的数还是要输入。所以读数可以点：点读数或者在手柄上按回车，读数变成一个输入块，进入编辑时整段选中，直接打字替换，回车确认。

第一版的输入框是带边框的，聚焦时和滑块整体的焦点环叠在一起，一圈套一圈。后来我把滑块整条的焦点环限制成只在手柄被键盘聚焦时出现，输入框改成背景色小块加一圈色调细描边。

<ComponentPreview name="value-slider-editable-demo" />

## 控制面板和“复制为 JSX”

控件有了，需要一个放它们的容器。`control-panel` 由三部分组成：标题栏（标题加右侧的操作，比如复制和恢复），若干个分组，每个分组里是等宽网格。网格可以设成 1 到 3 列，窄屏（小于 640px）一律单列，相邻的分组之间自动画一条分隔线。

面板上最常用的是两个按钮：

- **恢复**：回到默认值；
- **复制**：把当前参数写成一段 JSX 放进剪贴板。

复制靠一个很小的函数 `formatJsx(组件名, 属性)`。它的规则很少：值为 `undefined` 的属性省略；`true` 写成裸属性名；字符串优先用双引号，含引号或换行时改成 `{"..."}`；数字去掉浮点尾差，最多保留 4 位小数；一行放得下（默认 72 个字符）就写一行，放不下每个属性一行。

“省略等于默认值的属性”这一步不在 `formatJsx` 里，而是在调用的地方。拿文档站的做法来说，是把面板当前的所有值先换成组件属性，再把默认值也换一遍，两者用 `JSON.stringify` 对比，一样的就丢掉：

```ts
const props = config.toTuning(all)          // 面板当前值 → 组件属性
const defaults = config.toTuning(config.defaults)
const kept: Record<string, unknown> = {}
for (const [key, value] of Object.entries(props)) {
  if (value === undefined) continue
  if (JSON.stringify(value) === JSON.stringify(defaults[key])) continue
  kept[key] = value
}
return formatJsx(config.component ?? "Component", kept)
```

所以复制出来的永远是你相对默认值改过的那几项，比如调了速度和倾斜，得到的是 `<Marquee speed={80} rotate={-6} />`（示意），而不是把二十个属性全贴一遍。一个都没改时，得到的是一句自闭合标签。

门面示例 `control-panel-demo` 就是这么做的：左边是一张实时的名片卡，右边是控制面板，圆角、内边距、阴影、色调、朝向、边框都由面板控制，面板里的控件跟着所选的色调变色，点复制得到这张名片的 JSX。

<ComponentPreview name="control-panel-demo" />

## 文档里的调整面板

组件文档的每个示例下面，有一个滑块图标的按钮，点开是一块调整面板。它也是用这套控件拼的，位于 `src/components/docs/tuner/`。

每个组件声明一份配置，说明有哪些控件、面板的值怎么变成组件的覆盖项、示例自己的取值怎么回报给面板。组件那边只需要导出一个覆盖用的 Context，面板打开时由框架把覆盖项挂进去，示例本身不用改。面板的控件类型也是这个系列：滑块、分段、开关、色调、角度（`angle-dial`）、二维板（`xy-pad`）。

最早所有示例共用同一份面板。后来发现这样不行：面板的覆盖作用于示例里的**所有**实例，而很多示例里的几个实例是刻意取了不同值的。比如走马灯的一个示例里有两条彩带，一条正倾斜、一条负倾斜，方向也相反；如果面板里有“旋转”和“反向”两个控件，一拖就把这个差异抹平了，示例的意思也就没了。

所以配置里加了按示例收窄的能力：

```ts title="tuner/marquee.tsx"
examples: {
  // 两条彩带一正一负倾斜、方向相反
  "marquee-demo": { omit: ["rotate", "reverse"] },
  // 竖向滚动不适合倾斜；示例自带暂停按钮
  "marquee-vertical-demo": { omit: ["rotate", "paused"] },
},
```

键是示例名，值是 `false`（这个示例不出面板）或者 `{ omit: [...] }`（去掉指定的控件）。复制代码时被去掉的项也同步排除。已经登记的有走马灯、数值滑块、文字动效、轨道、流程图、字符矩阵等。验收时要逐个示例检查面板有没有不合适的控件，这一条也写进了验收技能。

后来又补了两个控件。走马灯的旋转改用角度刻度尺 `angle-dial`：方条中间是一段可以左右拖动的刻度，正中的竖线指针读数。等轴测标志的朝向和俯仰合并成了一块二维板 `xy-pad`，拖一下同时调两个值。

## 首页的“调一调”

首页首屏的面板就是把这些拼起来：

- `XyPad`：视角，朝向和俯仰在一块板上；
- `SegmentedControl`：材质、地面，各一条；
- `TonePicker`：色调；
- `ToggleSwitch`：音效；
- 标题栏的 `ControlPanelReset`：恢复默认。

面板里的控件全是系列里的组件。窄屏放不下时，它收成一个“调一调”按钮。

同一套控件还拼出了一个设置页区块 `settings-01`：外观、通知、声音与触感、编辑器、隐私五个分区，滑块、分段选择、开关、色调选择和控制面板全部来自这个系列，分区还会显示“已修改”的计数。

---

# 一个人和几个 AI，做一套组件库

来源：https://yiui.dev/blog/ai-agents-component-library/

这个站的提交记录里，从 10 月 25 日到 28 日一共 197 个提交，覆盖组件、文档、区块、模板、主题、验收脚本和这几篇博客。写代码的不止一个模型：一个主控 Agent 负责拆任务和审查，几个子 Agent 分头干活，最后由主控统一提交。

这篇讲这套分工是怎么定的，任务说明怎么写才不会出岔子，以及几次验收抓出的真实问题。具体的调度规则是我本机的配置，这里讲它背后的原因。

## 分工：按出错代价分，不按“谁更强”分

我把角色定成四类：

| 角色 | 模型 | 负责 |
| --- | --- | --- |
| 主控 | Claude Opus 5.5（主线程） | 架构与目录规划、任务拆分、接口约定、代码审查、集成、最终验收 |
| 重要代码 A | Claude Sonnet 5.5，`effort: high` | 布局原语、主题系统、文档渲染管道、复杂交互组件 |
| 重要代码 B | Codex（`gpt-6.1-sol`，`reasoningEffort: medium`） | 同上，与 A 互为替补 |
| 简单、重复、等待 | Pi（DeepSeek-V4.1-Flash，`thinking: max`） | 批量写 MDX 和 demo、照着现成模式新增组件、修 lint 和类型错误、跑构建、截图验收 |

分工的依据是三条：

**成本。** 能力强的模型额度有限，不该拿去写大批结构相同的文档。能用 Pi 完成的任务一律交给 Pi，判断标准是三点：已有可照抄的模式、验收标准明确、出错代价低。批量写组件的 MDX 文档和 demo 就符合这三点：第一个写好之后模式已经定下来，后面的照着来。

**能力。** 布局原语、主题系统、复杂交互组件这类要跨文件做判断的代码，交给 A 或 B。它们互为替补：看哪边剩余额度多就先用哪边，一边受限或报错就换另一边。

**出错代价。** 同样是写代码，改错一个 demo 只影响一个示例页，改错布局原语会牵动整站。代价越高，派给越强的模型，审查也越严。

主控自己写代码的条件很窄：任务需要跨模块判断，或者子任务连续两次失败。其余时间它做的是拆任务、审查和集成。

## 任务说明怎么写：自包含

子 Agent 不会读到我和主控之前的对话。它只看到一段任务说明，所以说明必须自己把事情讲清楚。每份说明都要包含四项（这部分约定写在仓库的 `AGENTS.md` 里，对任何用 AI 协作的贡献者都适用）：

- **目标**：要做出什么，不是“改一下”；
- **要读的文件和技能**：先读哪些文件、哪些技能；
- **允许修改的文件范围**：写明哪些路径可以动；
- **验收标准**：比如 `pnpm build` 通过，或者某个脚本不报错。

再加上汇报要求：修改了哪些文件，做了哪些取舍，还有什么遗留问题。一个典型的说明大致长这样（示意）：

```text
目标：新增 tone-picker 的三个内页示例，每个示例讲一个场景。
先读：AGENTS.md，component-conventions 与 registry-item 技能，
     src/registry/examples/segmented-control-demo.tsx（照这个写）。
允许修改：src/registry/examples/tone-picker-*.tsx、content/docs/components/tone-picker.mdx。
不要改：registry.json 及其他任何文件。
验收：pnpm lint、pnpm build 通过。
不要 git commit。完成后汇报：改了哪些文件、做了哪些取舍、遗留问题。
```

这里面有两条规则不是凭空来的。

**文件范围不能重叠。** 同一个工作区里并行的子任务，如果改同一个文件，后写的会覆盖先写的。最典型的是 `registry.json`：每新增一个组件都要在里面登记，几个子任务同时登记就会冲突。我的办法是让子任务只汇报自己引入的依赖清单，由主控统一改这个文件。范围有重叠就串行，或者给子任务一个独立的 worktree。

**子 Agent 不提交。** 提交由主控在审查之后统一做，并且只暂存自己改过的路径，不用 `git add -A`。这条是吃过亏才定的：有一次我在同一个工作区里手改标志和文章，主控用 `git add -A` 把这些没改完的内容混进了两条无关的提交，后来才拆回来。

## 技能：把规范写下来，别每次口述

子 Agent 每次从零开始，不记得上一次的约定。所以约定得写在它能读到的地方。项目里 `.agents/skills/` 下放了一批技能文件，任务说明里只需要写“先读 xxx 技能”：

- `component-conventions`：组件书写规范，管分层、命名、`data-slot`、导出方式、Props、文案、样式 token、可访问性，以及上一篇讲的“加载与占位”。写或改 `src/registry` 下任何代码都要先读它。
- `registry-item`：新增 registry 条目的完整流程，从源码位置、`registry.json` 登记、写 demo 和文档，到构建与安装验证。
- `component-acceptance`：组件从开发到验收的流程与标准，附一份可以逐条勾选的清单。
- `grid-design`：线条网格设计规范，页面布局都按它来。
- `humanizer-zh`：中文润色，博客成稿前必须过一遍。

这样做还有一个好处：规范改了，只需要改一处。像“占位层必须绝对定位，淡出之后保留的节点也不能占尺寸”这样的条目，写进 `component-conventions` 之后，每个读它的子任务都会按它来。

## 验收为什么要独立

我的结论是：实现者说“完成了”，只能当作线索，不能当作证据。下面是三个实际发生过的例子。

**主题页预览区。** Codex 实现，Pi 验收，结论是“有条件通过”。它指出了两个具体问题：灰阶主题在暗色下，堆叠图里有一段几乎看不见，对比度只有 1.31:1；视口宽度在 640 到 715px 之间时，开关的文字被截断。主控据此修复：图表的取色改成亮色取 `chart-2` 到 `chart-5`、暗色取 `chart-1` 到 `chart-4`，灰阶主题里就不再有一段贴着底色消失；下排三列在 `md` 以下退成单列，开关文字不再被截。这两个问题都只在特定的主题或宽度下才出现，换一个状态就看不到了。

**全站加载方案。** 这一次 Pi 判了“不通过”，抓到三个阻塞问题，详见[上一篇](/blog/static-site-loading/)：骨架的 CSS 被构建配置当成全局样式，延迟没生效；图表占位把排名图撑高 433px；列表缩略图的骨架高度为 0。而此前自动化的 QA 脚本全是绿的。脚本检查的是我想到要检查的事，验收的人是在页面上实际看。这也是我后来给每类问题补一条断言的原因。

**子任务的自述不一定属实。** 数值滑块的一个子任务汇报说，缩放动画只加在 `Control` 内层。实际代码里，是 `motion.div` 把 `Control` 整个包住了，这会让 Base UI 换算数值用的矩形跟着缩放。这是一次 Codex 的独立审查发现的。从那之后，我形成了固定做法：涉及手感、坐标、可访问性的关键说法，主控抽查源码；Pi 产出之后固定再派 Codex 审查。审查时只给代码，不给实现者的结论，不然审查者容易被结论带着走。这样的审查通常要两轮。

每一轮的硬门槛是：

```bash
pnpm lint
pnpm registry:lint     # 构建前也会自动跑，不允许有警告
pnpm build
```

涉及视觉和交互的，再加两个脚本：`pnpm qa:shots` 按组件验收清单批量截图，并检查水合报错和横向溢出，最后生成一页对比报告；`pnpm qa:loading` 是上一篇里的加载检查。每次提交前还要用禁提词清单对整个仓库扫一遍，结果必须为空。

## 主控必须自己做的事

分工越细，越有几件事推不出去。

**跨模块的判断。** 子任务只看得见自己的目录。一个组件该放在 `ui` 还是 `blocks`，两个组件的接口怎么约定，哪个依赖该登记进 `registry.json`，这些要有全局视角。

**视觉取舍。** 区块改用自研组件的那一轮，AI 助手区块里的步骤流程被换成了 Timeline，结果整个流程变得很长。我否决了：它不如原来的 Trace 紧凑，太占地。于是定下一条规则：换成自研组件之后，尺寸不能比原来更大。后来这个区块的步骤流程换回了 Trace，同时加上了紧凑的图表。要不要换，换完好不好看，没有标准答案，只能由人来看、来判。

**集成与提交。** 并行的子任务各自在自己的范围里是对的，合在一起可能互相踩脚。主控把改动审查一遍，跑完门槛，再按路径暂存、一次提交。

## 这套办法的代价

- 写一份自包含的说明本身要花时间。小改动直接做比写说明更快，我不会为了“用上分工”去拆一个三行的改动。
- 独立验收不是免费的：每个重要任务要多一轮，有时两轮。但验收抓出的问题，到了线上就是别人的问题，我宁愿在这里多花一轮。
- 验收者也会漏。上面的例子里 Pi 抓到了自动化脚本漏的问题，但它能抓到什么，取决于它被要求看什么。所以验收说明里要写明“在哪些主题、哪些宽度、哪些状态下看”，不能只写“检查一下”。

开头说四天 197 个提交，写完这篇时已经过了 200。分工表以后多半还会改，模型会换，额度会变；但「验收要实测，不能只读汇报」这一条，我不打算再动。

---

# 静态站真的需要 loading 吗

来源：https://yiui.dev/blog/static-site-loading/

本站是 Next.js 16 的纯静态导出，所有页面在构建时就生成了 HTML，没有服务端等待，也没有接口请求。按理说不需要 loading。

但我在组件页上还是看到了「正在加载示例…」。这篇讲我怎么判断、怎么被实测推翻，最后加了哪些占位，以及验收时发现第一版有三处是坏的。

## 先下的判断：首屏是空的

起因是组件文档页的首屏。示例组件是客户端组件，按需加载，页面 HTML 里我看到的是 fallback 文字「正在加载示例…」。我据此判断：用户在 JS 下载完之前，首屏上没有示例，只有一行字。

对应的做法也很自然：把示例改成服务端渲染，让 HTML 里直接有内容。

## 原型实测推翻了它

动手之前我先做了个原型，用来确认这件事到底有多严重。方法是拦住所有 JS 请求，3 秒不放行，在 0.8 秒时截图。

截图里示例已经显示出来了。

原因在 React 的流式输出。服务端先输出 Suspense 的 fallback，示例的真实内容紧跟着放在一个隐藏的节点里：

```html
<div hidden id="S:0">…示例的真实内容…</div>
<script>$RC("B:0", "S:0")</script>
```

（示意，省略了属性。）HTML 解析到内联的 `$RC` 脚本时，用隐藏节点里的内容替换 fallback。这一步不依赖任何外部 JS，所以静态 HTML 里其实早就有示例，我之前看到的「正在加载示例…」只是它被替换之前的中间状态。

原型还顺带测了我原本打算做的方案：在服务端 `await import()` 示例。结果每个组件页的 JS 从约 1.27MB 涨到约 2.4MB，因为同一个路由下所有示例被打进了同一个包。为了解决一个不存在的问题，让所有页面多下一倍的代码，不值得，我放弃了这个方案。

## 真正的四个问题

首屏没问题，不代表没有别的问题。我换成「点链接跳转」「慢网」「水合之前」几个场景逐个看，找到四处：

1. **站内跳转时，示例代码块还在下载。** 页面已经切过去了，但示例区的 chunk 没到，这段时间示例区闪出纯文字。
2. **recharts 图表在水合前整块空白。** `ResponsiveContainer` 要在浏览器里测量容器尺寸，服务端输出的 HTML 里没有图。
3. **慢网下点了链接，页面没有任何反应。** 静态导出没有服务端等待，但预取没命中的跳转还是要等页面载荷，这段时间用户不知道点上了没有。
4. **预览 iframe 加载之前是空白。** 区块和模板的预览用 iframe，加载前那一块什么也没有。

这四处的共同点是：都发生在页面已经出现、内容还没到的那一小段时间里。

## 方案

### 统一的骨架

示例区、整页预览和组件缩略图原来各有各的 fallback。我换成了同一个 `PreviewSkeleton`：撑满调用方给的尺寸，淡色底，轻微脉冲。

有两条约束：

- **150ms 之后才显示。** 内容在 150ms 内到了就不需要骨架，否则快的网络上会看到骨架一闪而过。这个延迟是纯 CSS，不依赖 JS：

```css
.preview-skeleton {
  opacity: 0;
  animation:
    preview-skeleton-appear 1ms 150ms forwards,
    preview-skeleton-pulse 2s 151ms infinite;
}
@media (prefers-reduced-motion: reduce) {
  .preview-skeleton {
    animation: preview-skeleton-appear 1ms 150ms forwards;
  }
}
```

- **减少动态效果时不脉冲。** 系统设置了 `prefers-reduced-motion`，骨架只保留 150ms 后出现这一步。

### 图表：同尺寸占位，就绪后淡入

图表是四个问题里最难看的一个，因为它不是「晚一点出现」，而是在水合之前根本不存在，页面高度也会跟着变。

我给 `ChartSeries`、`ChartRanking`、`ChartGauge`、`MiniChart`、`MiniDonut` 都加了同一套处理：

- 服务端输出一个与最终图表同尺寸的占位，用主题变量上色（`bg-muted/30` 加几条虚线网格）；
- 容器上有 `data-ready`，用 `useSyncExternalStore` 判断是否已经水合；
- 真实图表在就绪前 `opacity-0`，就绪后 200ms 淡入，占位同时淡出。

占位和真实图表是叠在一起的，所以占位必须绝对定位，不参与布局。这条后来被验收抓出一个问题，下面讲。

### 跳转指示

站内跳转的指示，我在捕获阶段监听点击，判断是不是站内、同一路径之外的链接；点击后 200ms 页面还没切过去，才让指示出现；路径变了就熄灭，加一个 8 秒的兜底，防止链接被别的处理器拦下后一直亮着。

预取命中的跳转几乎是瞬间完成，用户根本不会看到它。只有慢网下预取没有命中的跳转才会触发。

这个指示最初是页头底边的一条 1px 线。做完发现它会和导航当前项下面的指示线叠在一起，看不出哪一条在表示什么。我把它挪到了页头标志的右侧，改成三道依次点亮的小斜杠：3×12px，倾斜 30°，每道延迟 160ms，一个周期 960ms，形状上呼应「易」标志的斜杠。减少动态效果时它保持静止。

### iframe 接近视口才加载

区块查看器里的 iframe 改成接近视口才挂载，加载中显示同一个骨架。首页的「区块与模板」一栏有四个缩小的实时预览，不用一开始就把四个页面全拉下来。

## 第一版自动检查全过了，验收却不通过

这套方案我配了一个脚本 `pnpm qa:loading`：在本地起一个静态服务，用 Playwright 驱动 Chrome，把所有 JS 请求挂起，检查图表是不是留了占位、占位尺寸对不对，再放行后对比前后的尺寸。第一版脚本全绿。

然后我让另一个子任务独立验收，不看实现者的汇报，自己去实测。它判了「不通过」，抓到三个阻塞问题：

1. **骨架根本没有延迟。** `PreviewSkeleton` 的样式最初写成了 CSS module，而项目的构建配置把这个文件当成了全局样式，类名被丢掉，动画根本没挂上。150ms 延迟没有生效，骨架一出现就是满的。
2. **图表占位把排名图撑高了 433px。** 占位里的 svg 带着 1:1 的 viewBox，是作为静态子元素放进去的，在排名图里按宽度撑出了一个正方形。更糟的是，就绪之后这个占位只是变透明，还留在文档流里，所以页面一直多出一大块空白。
3. **列表缩略图的骨架高度是 0。** 为了让骨架不受缩放影响，缩略图容器在加载态被改成了 `static`，骨架的 `absolute` 失去了定位参照，高度塌成 0；页面上 25 个看不见的骨架却还在向读屏播报「正在加载…」。

这三个问题，第一版的自动检查一个也没发现。第一个和第三个，脚本里没有对应的断言：没人检查骨架的动画是否生效，也没人检查缩略图里的骨架有没有撑满画框。第二个更隐蔽：CLS（累计布局偏移）测不出它，布局偏移只记录元素「跳了」，而这块空白从一开始就在，之后也没有动过。

## 补上的两条断言

修复很直接：骨架改成全局类，放进 `docs.css`；图表占位改成 `absolute inset-0` 脱离布局，里面的 svg 用 `preserveAspectRatio="none"` 铺满容器；缩略图去掉那组 `static`，骨架照常用 `absolute inset-0` 铺满画框。

更重要的是，每一类问题都要有一条会失败的断言，不然它还会再来。我加了两条。

**骨架动画确实生效，并且初始是透明的。** 在脚本里克隆一个骨架到固定尺寸的容器里，读 `getComputedStyle`：

```ts
const style = getComputedStyle(clone)
const result = { name: style.animationName, opacity: style.opacity }
// animationName 为 none，或初始 opacity 不是 "0"，都说明延迟没有生效
if (animation.name === "none" || animation.opacity !== "0")
  issues.push(`骨架动画或延迟失效：${JSON.stringify(animation)}`)
```

**摘掉占位前后，图表的高度差必须是 0。** 把占位节点临时摘下来，量一次容器高度，再放回去：

```ts
const placeholder = el.querySelector('[data-slot$="-placeholder"]')
const next = placeholder?.nextSibling
placeholder?.remove()
const without = el.getBoundingClientRect().height
if (placeholder) el.insertBefore(placeholder, next ?? null)
// item.height 是带着占位时的高度
if (Math.abs(item.height - without) > 0) issues.push(`移除占位造成高度变化`)
```

这条断言只在占位还在的时候量一次，就能抓到「占位在撑开布局」。同一个脚本还检查放行 JS 之后，占位的尺寸和正常图表的尺寸相差不超过 2px，所以占位和真实图表的尺寸一致也是被验证过的。

脚本覆盖所有组件页，再加上首页、主题页、区块列表、模板列表、组件列表和 `/view/app-shell-01/` 这 6 个页面。

## 现在的做法

整套加载方案写进了组件书写规范的「加载与占位」一节，写 registry 代码的人都要遵守：

- 依赖尺寸测量、canvas、WebGL 或当前时间的内容，必须有水合前占位；
- 占位与真实内容同尺寸，颜色用主题变量，不能让布局跳；
- 占位层绝对定位，不参与布局，淡出之后保留的节点也不能占尺寸；
- 文本类内容的服务端输出必须可见，不能为了等挂载把整块文字藏起来；
- 站内跳转的指示只覆盖页面载荷没到的慢跳转。

在这个站里，样板是点阵地球：球体出来之前，先放一个与球同大的径向渐变圆。下面这个排名图就是当时被占位撑高的那一类，现在占位在它上面是盖着的，摘掉也不会改变它的高度。

<ComponentPreview name="chart-card-ranking-demo" />

这件事最后改的代码并不多，时间都花在两次判断上：一次是动手之前的原型，一次是验收时的实测。两次都推翻了我原本以为对的东西，第一次省下了翻倍的 JS，第二次挡住了一块多出来 433px 的空白。

---

# 设计「易」：六根斜杠是怎么来的

来源：https://yiui.dev/blog/logo-design/

本站左上角的标志是一个「易」字：上面三道细斜杠是「日」，下面三道粗斜杠是「勿」，六根杠的右端切齐在同一条竖线上。下面三道杠的颜色跟着站点的颜色主题走，切到红色主题它就是红的。

这篇讲它从一个想法变成组件的过程：为什么用斜杠，在纸上怎么推出来，怎样把手稿收成可以检查的几何，以及放到页面上时遇到的问题。

## 意图：一个「易」字，两组三道杠

「易」上面是「日」，下面是「勿」。这个字有变易、简易、交易三层意思，对一个写代码的人来说，把复杂的东西变简单，本身就是「易」。

![把「易」拆成上「日」下「勿」，再落到六根斜杠上](/images/blog/logo-design/intent.jpg)

这个方向不是一开始就有的。上一版标志是一个带 `>_` 终端提示符的方块，下面接三道 45° 斜撇，用了几天总觉得复杂：外轮廓 18 个顶点，加两个孔，缩小以后细节全糊在一起。但整个标志里最有辨识度的，一直是下面那三道斜撇。

于是反过来想：既然三道杠最好认，能不能整个字都用杠来写？「勿」本来就是几道撇，三道粗杠可以留下；「日」是一个扁框，里面一横，正好也是三道横画，可以换成三道细杠。上下两组，各三道。

## 推演：在打印的辅助线上用铅笔涂

这种几何在屏幕上拖点很难找到感觉，我干脆打印出来手画。先做了一张 A4 辅助线稿，一页四格，每格里预先填好下面三道粗杠，斜线统一 1:2，杠厚 72，杠距 26，方格边长也是 26。然后用铅笔在上半部分试各种「日」的画法：

![打印辅助线后，用铅笔涂出来的四种「日」](/images/blog/logo-design/hand-sheet.jpg)

右下那格是最直白的写法：「日」是一个封闭的框，里面三道杠。其余几格在试杠的长短和起点。涂完能看出两件事：上面的杠要比下面细，否则两组粘成一团，分不出上下；杠与杠之间可以再靠近一点。

接下来就是做减法，每一步都比上一步少一样东西：

![从上一版标志到六根斜杠，一步一步减](/images/blog/logo-design/evolution.jpg)

1. 上一版标志里，被圈出来的是下面三道斜撇；
2. 把它们放到下面做「勿」，「日」先画成一个实心块加一个孔；
3. 「日」拆成三道细杠，左右两边各用一根竖条封住，还是一个框；
4. 去掉左边的竖条，「日」不再闭合；
5. 右边的竖条也去掉，每道杠缝都从右边穿出去。

到最后一步，六根杠彼此独立，只靠右端齐平连成一个整体，看上去像六道向右上扫过去的笔画。

## 收形：把手稿变成可以检查的几何

手稿只定方向，尺寸要在电脑上定。上组的杠厚和左端位置有好几种合理的组合，我把它们排成一张表，同一个尺寸、同一种配色并排看，也顺便看了双色的效果：

![上杠厚度与左端位置的组合，以及双色示意](/images/blog/logo-design/variants.png)

最后选的是上杠厚 36、上组左端和下组第三道杠对齐的那一版。然后把“看起来对齐”全部写成“必须落在这条线上”：

- 外框 416 × 584；
- 所有斜边都是 1:2，每根杠两端竖直切齐；
- 下组三道杠厚 72，左端依次是 0 / 78 / 156，每道比上一道往右缩 78；
- 上组三道杠厚 36，左端都在 156，和下组第三道杠对齐；
- 杠与杠之间、两组之间的缝都是 26；
- 六根杠的右端都切在 x=416。

![手工制图：1:2 的斜向辅助线、杠厚与杠缝](/images/blog/logo-design/construction-sketch.jpg)

几何由一个 Python 脚本生成，脚本里有三条自检：所有顶点必须是整数，斜边必须是精确的 1:2，总高必须是 584，不满足就直接报错。1:2 的好处是每横走 2 个单位正好升 1 个单位，只要左右端的 x 都是偶数，所有顶点就落在整数上，不会出现 `130.5` 这种坐标。脚本同时输出一张核对图，每条边的辅助线和每个尺寸都标在上面：

![核对图：红色虚线是每条边，右侧数字是斜线在右边界处的高度，蓝色是杠厚与杠缝](/images/blog/logo-design/construction.png)

最终的标志是六个平行四边形，上下两组各一条路径：

```xml title="logo.svg"
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 416 584">
  <path fill="var(--logo-upper, currentColor)" d="M156 130 416 0 416 36 156 166ZM156 192 416 62 416 98 156 228ZM156 254 416 124 416 160 156 290Z"/>
  <path fill="var(--logo-lower, currentColor)" d="M0 394 416 186 416 258 0 466ZM78 453 416 284 416 356 78 525ZM156 512 416 382 416 454 156 584Z"/>
</svg>
```

不设置 CSS 变量时两组都是 `currentColor`，就是单色版；设置以后可以分别上色。

![「易」从 256px 到 16px：亮色、暗色和双色](/images/blog/logo-design/sizes.png)

28px 以上两组都清楚。到 24px 和 16px，上组的细杠会糊成一片斜纹，剪影还认得出来，但已经看不清是六根杠了。

## 落地：组件与主题色

站点里的标志是一个 React 组件，直接内联 SVG。上组用 `currentColor`，跟着文字颜色走；下组加一个 `fill-primary`，跟着主题色走：

```tsx title="site-logo.tsx"
export function SiteLogo({ className, ...props }: React.ComponentProps<"svg">) {
  return (
    <svg
      viewBox="0 0 416 584"
      fill="currentColor"
      aria-hidden="true"
      className={cn("h-8 w-auto overflow-visible", className)}
      {...props}
    >
      <path data-part="upper" d="M156 130 416 0 …Z" />
      <path data-part="lower" className="fill-primary" d="M0 394 416 186 …Z" />
    </svg>
  )
}
```

站点的亮暗模式和颜色主题是两个独立的维度，颜色全部来自主题变量。这样写以后，标志不需要知道当前是哪个主题：暗色模式下上组变白，切到橙色主题下组变橙。默认的中性主题里，主题色本身就接近黑白，两组看起来是同一个颜色，切到彩色主题才看得出双色。

宽高从固定的正方形改成了 `h-8 w-auto`，高度对齐页头，宽度按 416:584 自己算。浏览器标签页的图标不能跟着页面主题变，用的是单色版；SVG 图标里写了 `prefers-color-scheme`，系统切到暗色时变白。

## 立体：挤出成等轴测 3D

我写过一个通用组件 `isometric-mark`：传入平面多边形，自动挤出成等轴测线条 3D。顶面填斜纹，侧面填背景色挡住后面的线，线条上有一圈跟着鼠标走的高光，按下时顶面带着斜纹一起弹簧下沉。

![铅笔速写：六根杠挤出成立体](/images/blog/logo-design/isometric-sketch.jpg)

新标志的六根杠是六个互不相连的平行四边形，正好可以直接传进去，每根杠各自挤出、各自遮挡。试着晃一晃鼠标、按住它：

<ComponentPreview name="isometric-mark-demo" />

组件里没有手画的路径，投影、背面剔除和遮挡排序都由代码从平面多边形算出来，换了标志只需要换一组顶点。

组件的用法和几何细节见 [等轴测标志](/components/isometric-mark/)。

现在这组坐标同时用在三个地方：页头的标志、分享卡片左上角，以及首页那个可以拖动视角的等轴测 3D，改一处就得三处一起改。下次再动它，我大概还是会先打印一张辅助线稿，拿铅笔涂几格再说。

---

# 在 H20 上部署 DeepSeek-V4.1-Flash

来源：https://yiui.dev/blog/deepseek-v41-flash-h20/

import { KeyStats } from "@/components/blog/dsv41/key-stats"
import { KvCapacity } from "@/components/blog/dsv41/kv-capacity"
import { LongInput } from "@/components/blog/dsv41/long-input"
import { EngineCompare } from "@/components/blog/dsv41/engine-compare"
import { ReleaseGain } from "@/components/blog/dsv41/release-gain"
import { H800Ratio } from "@/components/blog/dsv41/h800-ratio"

这篇记录 DeepSeek-V4.1-Flash 在一台 8 卡 H20 上的部署：上下文为什么开到 512K，为什么选 vLLM 不选 SGLang，调参得到哪些结论，压测怎么做，以及上线和回滚的思路。数字来自 2026 年 9 月到 10 月的测试记录，每个数字都写明口径。没测过的地方，我直接写没测。

<KeyStats />

## 目标与约束

这次部署的是 V4.1-Flash 的 1017 版权重（475.3 GiB，48 个 shard），替换同一台机器上已经在跑的 0909 版。目标有三条：对外服务名不变，调用方无感切换；上下文要能到 512K；相对已有基线，目标并发的输出吞吐下降不超过 10%，TTFT P50 劣化不超过 10%，P95 不超过 15%，成功率 100%。最后一条是评估方案里写死的门槛，后面所有“淘汰”都按它判。

机器是 8 张 H20（SM90），每卡约 97.9 GiB。有四条约束直接决定了后面的选择：

- 一个实例要占满 8 卡。试过两个 TP4 实例各占 4 卡，能启动，但单实例的 KV cache 只有 1,615,139 token，512K 下满长请求只能并发 3.08 路；TP8 加 EP8 是 17,594,168 token，33.56 路。
- FP4 的 indexer 缓存用不了。vLLM 把这条路径解析成 MXFP4，要求 Blackwell，H20 启动直接失败，只能用 FP8。
- 经典 MTP 用不了，V4.1 的权重里没有它需要的部分，投机解码只能用 DSpark。
- 评估新版本必须停掉线上容器，所以每次评估都要先让网关把流量切走。

## 上下文长度怎么取舍

我手上没有线上请求长度的分布统计，所以上限不是按分布定的，是按两个问题定的：显存能撑多少路，长请求要付多大代价。

先看容量。同一镜像、同一组参数，只改上下文上限和 Engram 表的位置，vLLM 启动时报告的 KV 容量折算成满长并发如下。Engram 表放 GPU 每卡多占 23.61 GiB（8 卡约 189 GiB），256K 下 KV 容量只剩主机内存方案的约 41%。多花的显存没换来速度：并发 1 到 16 的吞吐差别在 1% 以内，240K 输入的首 token 是 56.1 秒对 56.6 秒。所以 Engram 表一直放主机内存。

<KvCapacity />

1M 能跑：两种放置方式都完成了一个 1,000,000 token 输入、16 token 输出的请求，但首 token 要 460 秒左右，满长并发也只有 15.75 路，我没有把它当上线选项。

最终取 524288，对应 17,594,168 token 的 KV 容量，满长并发 33.56 路。这个长度上，1017 版换上 vLLM v0.32.0 镜像后，长输入预填充比 0909 版（`vllm/vllm-openai:deepseekv41-flash-0909`）快得多，TTFT 和 E2E 下降约 60%，测试中没有 OOM 和重启，每卡显存峰值约 93.3 GiB。

<LongInput />

这轮长上下文测试只完成了一部分：网关切回后出现了业务流量，我中止了测试，所以 240K 并发 4、262K 以上的边界和长短混合都没测。262K、393K 边界和 1 小时 C16 soak 是在 0909 版上通过的，1017 版没有重做。

还有两条运维上的结论。第一，524288 是提示词、聊天模板和输出的总预算：0909 版上输入 524272、输出 16 的请求返回了 HTTP 400，日志没保留错误内容，原因我没确认，所以业务请求要留余量。第二，长请求要隔离。一次混合测试里，一个 240K 请求叠加 300 个并发 16 的短请求，短请求的 TTFT 中位数只有 219 毫秒，P95 却到了 62.4 秒，代价全在尾部；17.4K 输入在并发 100 时 TTFT P99 约 380 秒。长请求应当单独路由并限并发，不能和短请求共用一个高并发池。

## 引擎选择：vLLM 对 SGLang

我用 SGLang 测了三个镜像，参数照它官方文档里 Hopper 的 TP8·EP8 推荐写法，再对齐 512K 和 Engram 主机内存。下图取最好的一个，`lmsysorg/sglang:nightly-dev-cu13-20261014-684fea8a`，对 vLLM v0.32.0。

<EngineCompare />

单并发时差距不大，并发一上去，SGLang 只有 vLLM 的约一半。另一个镜像 `nightly-dev-cu13-20260922-582389ce` 更低：1K/1K 并发 100 只有 180.8 tok/s，而且按默认显存比例起服务时，长上下文测试中 CUDA 分配器连 20 MiB 都映射不出来，OOM 了，调低显存比例才跑完。最早的 `lmsysorg/sglang:dev-dsv41` 在 Engram 表的布局上直接启动失败，换了布局才起来，我在它的评估中途停了下来。启动耗时也有差别：SGLang 首次启动要 16 到 30 分钟，vLLM 约 8 到 10 分钟。

要交代的是，SGLang 这边我按推荐写法跑，没有像对 vLLM 那样逐项调；差距大到调参很难补上，我才中止。这个结论只针对 V4.1 在这台机器上的表现，不是对两个引擎的一般性判断。

## 调参的结论

| 改动 | 数据 | 结论 |
|---|---|---|
| 开专家并行（EP8） | 每卡权重约 49.7 降到 38.1 GiB，KV 从约 776 万升到 1113 万 token；同时把并发序列上限从 16 提到 128，并发 32 的吞吐从 514 升到 737 tok/s | 采用。两个改动是一起做的，不能把 43% 全算给专家并行 |
| 投机解码草稿长度 5 改 3 | 并发 32 三轮均值 735.6 升到 814.5 tok/s（+10.7%）；草稿接受率从 24% 左右升到 34% 到 41% | 采用。草稿 2 的吞吐不低于 3，但 TTFT P95 最多恶化 94%；4 和 5 更差 |
| 每步调度的 token 预算翻倍 | 512K 下 KV 容量少 20.9%（17,594,168 到 13,916,531）；300 请求乘 3 轮对比，吞吐在噪声内，1K/1K 并发 50 的 E2E P95 从 59.8 秒变成 71.2 秒 | 不调。和并发序列上限一起翻倍，吞吐也只提升 0% 到 2.4% |
| 显存占用比例再提高 3 个百分点 | KV 容量多 7.6%，吞吐在噪声内；长上下文时每卡峰值已到约 93.3 GiB | 不调，余量比这点容量值钱 |
| 换 MoE 内核 | 并发 1 到 32 为 80、247、473、485 tok/s，默认实现为 87、273、496、514 | 不换。换前端实现等几个变体，也都没在整机吞吐上胜出 |

前缀缓存是开着的，但压测用的都是互不重复的随机输入，线上收益我没有测。新配置第一次启动要做 JIT 编译和 CUDA Graph 捕获，实测 13 到 29 分钟，之后同配置重启约 7.5 到 10 分钟，所以引擎的就绪等待时间要放宽，别让首次启动被超时判成失败。

## 压测方法

所有测试，不管打的是 vLLM 还是 SGLang，客户端都是同一个镜像里的 SGLang `bench_serving`，数据集用本地生成的随机 token，长度固定，最大输出和最小输出设成同一个值，关闭思考。覆盖的场景有：256 输入 128 输出、1K 对 1K、8K 对 8K、17.4K 输入 1K 输出，并发 1 到 100，外加 64K 到 240K 的长输入。几条规则是踩过坑之后加上的：

- 固定长度预检：开跑前先发一个请求，确认输入和输出的 token 数正好等于目标。SGLang 里把长度范围比例设成 0，表示长度在 1 到目标值之间随机，不能用来做固定长度对比。
- 每档校验成功数等于请求数、每个请求的输出长度等于目标、错误列表为空，任何一项不满足，这一档标为无效，不进结论。
- 吞吐按实际生成的 token 数算。冷缓存没有可移植的清除接口，我把“换种子、无前缀复用”定义为冷缓存。
- 首轮不计入。一次复测里，首轮并发 16 的 TTFT P95 是 5.13 秒，之后三轮是 0.40 到 0.48 秒，首轮的尾延迟不代表稳态。
- 先检查压测脚本本身。一次短请求矩阵，种子超过了 NumPy 接受的 32 位范围，客户端在发请求之前就抛了错，整个矩阵没有有效数据；同一次测试里 soak 脚本复用了过期的时间预算，循环计数被空转撑大，不能当成功次数。这两处我都只保留了有效的部分。

单机 8 卡，A/B 只能串行，所以分两层筛选：第一层是单轮、每档 100 请求的快速筛选，11 个配置前后跑了十几个小时，门槛是 100% 成功且 TTFT P95 相对基线劣化不超过 15%；入围的 1 到 2 个再做 300 请求乘 3 轮的正式对比，每轮种子不同，两个配置用同样的种子。原生产的基线是网关把它切走之后，在同一口径下补测的单轮数据，这是整套评估里最弱的一环。

## 结果

正式口径下，1017 版在 5 个场景都比原生产快，场景越偏高并发和长输入，提升越大。

<ReleaseGain />

提升有两条要打折。一是原生产只有单轮基线：筛选阶段同口径的单轮提升是并发 16 的 +13%、并发 32 的 +24%，正式口径只剩 +5% 和 +10%，差别来自 100 请求和 300 请求的口径不同。短请求我更相信正式数字，但基线本身没在 300 乘 3 的口径下重测，这两档的提升可能被低估。二是提升并不全是权重带来的：我把权重和镜像拆开测过，只换权重或只换镜像，并发 50 和 100 都没有稳定收益（0909 权重加 v0.32.0 的并发 50 反而低了 6%），两个一起换才拉开 20% 以上。短请求和长输入的提升主要来自新镜像，高并发则需要两者配合，更细的归因我没做。尾延迟同时下降：并发 32 的 TTFT P95 从 1.29 秒降到 0.83 秒，17.4K 并发 10 从 17.6 秒降到 7.2 秒。

TP4 方案也值得一提：单实例 TP4 在 1K/1K 并发 100 的吞吐其实比 TP8 还高（1840 对 1667 tok/s），但 TTFT P95 比基线差了 35.9%，KV 容量小一个数量级；两个 TP4 实例同时开起来，聚合吞吐在总并发 32 以上都不超过 TP8。TP8 是更合适的单实例形态。

再看 H20 本身。同一个模型分别部署在 H20 和 H800 上，用同一套压测场景对比（H20 一侧是 0909 版，每档 100 请求），H20 的单并发还不错，并发越高差得越多，输出吞吐占 H800 的比例如图：

<H800Ratio />

17.4K 场景从并发 10 到 100，输出吞吐几乎不再增长（215 到 245 tok/s）。100 个 17.4K 请求合计约 174 万输入 token，按整机约 4,400 tok/s 的总吞吐要排 6 分半钟，和实测约 380 秒的 P99 TTFT 对得上。我没做 profiling，“高并发时算力成为瓶颈”只是我对这条曲线的解读。

## 上线与回滚

线上是多个实例并行对外服务，所以升级不需要停服：晚上把这台机器的流量切到其他实例，腾空之后再动它，验证通过再切回来。一次模型升级一般控制在三个晚上的测试窗口内，白天只看数据、改方案，不碰线上。这次 1017 版也是这样：10 月 18 日晚开始评估，10 月 20 日晚完成切换。

上线脚本默认只演示不执行，动手前核对前置条件，包括服务上没有在途请求。顺序是：保存测试容器的完整配置快照，停掉测试容器（只停不删），确认端口释放，再起生产容器并存一份快照。10 月 20 日切换后的验收全部通过：

- 启动到健康检查通过 9 分 28 秒，重启计数 0。
- 思考开、关和工具调用都正常；固定长度请求 4 个，输入 261、输出 128 token，全部成功。
- KV 容量 17,594,168 token，空闲时运行中和排队中的请求都是 0，每卡已用 87,061 MiB、空闲 10,296 MiB，日志里没有 ERROR 和 OOM。
- 日志里有三条警告，都没拦住服务。其中一条是首批请求会遇到 Triton kernel 的 JIT 延迟尖峰，所以我建议切流之前先发几个代表性请求预热。

回滚靠旧容器：0909 版容器在切换后保持停止状态，没有删除，启动参数另存了一份脚本。回滚是先停新容器、再启旧容器，两者都要占满 8 张卡，顺序不能反。按同镜像候选的启动记录，到健康大约 8 到 10 分钟；旧容器本身的回滚耗时没有实测，也没有演练记录。

## 如果再部署一次

1. 先算 KV 预算再定上下文。同样的上限，Engram 表的位置能让 KV 容量差 2.4 倍，调度预算翻倍又吃掉 20.9%；要和“满长请求能并发几路”一起看。
2. 先固化压测口径，再比较配置。固定长度预检、有效性校验、种子范围检查，每一项都是被一次作废的数据逼出来的。
3. 筛选用单轮，结论用多轮。同一个配置，100 请求单轮显示并发 32 提升 24%，300 请求三轮只剩 10%；换权重和换镜像要分开测，也要一起测。
4. 保留旧容器，只停不删，在上线前就演练一次回滚。单机独占 8 卡，评估和回滚都要停掉线上，这是预案里最便宜的保险。
5. 在 H20 上，高并发和长输入不要指望线性扩展。长请求单独路由并限并发，比调任何一个启动参数都管用；还没补的是 1017 版 262K 以上的边界和 soak，以及线上真实请求长度的分布，后者直接决定 512K 这个上限合不合适。