PatternsSemantic
SettingsSectionCard
@mox-hub/patterns 模式 · Semantic · canonical
settings-section-card@mox-hub/patternsSemanticcanonicalsrc/components/settings-section-card.tsx变体演示settings-section-card
常规
基础偏好与默认行为
自动更新
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| id* | string | — | — |
| icon* | LucideIcon | — | — |
| tone* | "danger" | SettingsSectionTone | 'blue' | — |
| title* | ReactNode | — | — |
| description* | ReactNode | — | — |
| actions* | ReactNode | — | — |
| children* | ReactNode | — | — |
源码
/**
* SettingsSectionCard - 设置栏目卡(2026-10-01 设置页语义组件批)
*
* 设置子页栏目统一骨架:左侧 tone 彩底图标 + 标题 + 第二行描述 + 右侧操作槽
* (gap-2,§20.8),下方内容区(border-t 分隔)承载 DefinitionRow 列表 / 表单等
* 任意内容(§20.6:内容区不放嵌套卡)。tone='danger' 为 GitHub「Danger Zone」
* 惯例封闭档(红框红标题,置于页底,破坏性操作配确认弹窗)。
* id 即锚点(scroll-mt-24 避让 SettingsHeader 吸顶卡),供 SectionScrubber
* 跳转与 scrollspy。
* 与 semantic/section-card 的关系(裁决 2026-10-01):新件先行、设置域全量切换;
* 旧件维持现状待另批评估归并(存量 24 消费文件,小批原则不一次改写)。
* props 面封闭(G8):不接 className、不透传样式;tone 封闭词表留在组件内。
*/
import type { ReactNode } from 'react';
import type { LucideIcon } from 'lucide-react';
import { cn } from '@mox-hub/ui';
/** 图标底框装饰色档(accent 点缀,非状态语义;同 stats-card 口径词表留在组件内) */
export type SettingsSectionTone = 'blue' | 'green' | 'yellow' | 'red' | 'purple' | 'orange' | 'gray';
const TONE_CLASS: Record<SettingsSectionTone, string> = {
blue: 'bg-accent-blue-light text-accent-blue',
green: 'bg-accent-green-light text-accent-green',
yellow: 'bg-accent-yellow-light text-accent-yellow',
red: 'bg-accent-red-light text-accent-red',
purple: 'bg-accent-purple-light text-accent-purple',
orange: 'bg-accent-orange-light text-accent-orange',
gray: 'bg-muted text-muted-foreground',
};
export interface SettingsSectionCardProps {
/** 锚点 id(供 SectionScrubber 跳转/scrollspy;不传则无锚点) */
id?: string;
icon: LucideIcon;
/** 图标底框装饰色档;'danger' 为危险区特档(红框红标题,破坏性操作) */
tone?: SettingsSectionTone | 'danger';
title: ReactNode;
description?: ReactNode;
actions?: ReactNode;
children: ReactNode;
}
export function SettingsSectionCard({
id,
icon: Icon,
tone = 'blue',
title,
description,
actions,
children,
}: SettingsSectionCardProps) {
const danger = tone === 'danger';
return (
<section
id={id}
data-slot="settings-section-card"
data-tone={tone}
className={cn(
// 审计 P2-07:与 ui/Card 基线同构(rounded-xl + ring + shadow-xs),
// 设置页不再出现 8px 实边 + 无投影的另一套卡片壳。
'scroll-mt-24 overflow-hidden rounded-xl bg-card ring-1 shadow-xs',
danger ? 'ring-destructive/40' : 'ring-border/50',
)}
>
<header className="flex items-center gap-3 border-b border-border/60 px-4 py-3">
<span
className={cn(
'flex size-7 shrink-0 items-center justify-center rounded-md',
danger ? 'bg-destructive/10 text-destructive' : TONE_CLASS[tone],
)}
>
<Icon className="size-4" strokeWidth={1.75} />
</span>
<div className="min-w-0 flex-1">
<h2
className={cn(
'm-0 truncate text-sm font-medium',
danger ? 'text-destructive' : 'text-foreground',
)}
>
{title}
</h2>
{description ? (
<p className="mt-0.5 text-xs text-muted-foreground">{description}</p>
) : null}
</div>
{actions ? <div className="flex shrink-0 items-center gap-2">{actions}</div> : null}
</header>
<div className="p-4">{children}</div>
</section>
);
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
设置栏目卡:左图标+标题+描述+操作槽,内容区 border-t;id 即锚点,供 SectionScrubber 跳转。