Ordo UI
PatternsApp Patterns

QuickCardsToggle

@mox-hub/patterns 模式 · App Patterns · canonical

quick-cards-toggle@mox-hub/patternsApp Patternscanonicalsrc/components/quick-cards-toggle.tsx
变体演示quick-cards-toggle

Props API

Prop类型默认值说明
visible*boolean——
onToggle*() => void——
label*string'Show cards'—
activeLabel*string'Hide cards'—
aiId*string——
className*string——

源码

packages/patterns/src/components/quick-cards-toggle.tsx
import { LayoutGrid } from 'lucide-react';
import { HeaderActionButton } from './header-action-button';
import { cn } from '@mox-hub/ui';

/**
 * QuickCardsToggle - 幽灵按钮:显示/隐藏页面「快捷看板卡片」栏目。
 * 放置在页面 header 最右侧按钮组的最左侧;激活(卡片显示)时呈明显高亮态。
 */
export function QuickCardsToggle({
  visible,
  onToggle,
  label = 'Show cards',
  activeLabel = 'Hide cards',
  aiId,
  className,
}: {
  /** 卡片栏目当前是否显示 */
  visible: boolean;
  onToggle: () => void;
  label?: string;
  activeLabel?: string;
  aiId?: string;
  className?: string;
}) {
  return (
    <HeaderActionButton
      icon={LayoutGrid}
      label={visible ? activeLabel : label}
      variant="ghost"
      onClick={onToggle}
      aria-pressed={visible}
      data-pressed={visible ? 'true' : undefined}
      className={cn(
        // 激活态明显区别:主色底 + 描边 + 主色图标
        visible && 'bg-primary/10 text-primary ring-1 ring-primary/25',
        className,
      )}
      data-ai-component={aiId}
      data-ai-action={aiId ? `${aiId}.click` : undefined}
      data-ai-role="toggle"
    />
  );
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

快捷看板显隐切换:HeaderActionButton 幽灵态,激活时高亮;状态由消费方受控。