PatternsLayout & Shells
SettingsPageFrame
@mox-hub/patterns 模式 · Layout & Shells · canonical
settings-page-frame@mox-hub/patternsLayout & Shellscanonicalsrc/components/settings-page-frame.tsx变体演示settings-page-frame
项目设置
管理项目成员、状态与自动化
通用
项目名称、可见性与默认分支。
成员
成员与角色管理。
有未保存更改
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| header* | ReactNode | — | — |
| sections* | SettingsSection[] | — | — |
| showScrubber* | boolean | true | — |
| saveBar* | ReactNode | — | — |
| children* | ReactNode | — | — |
| labels* | Partial<SettingsPageFrameLabels> | — | — |
| className* | string | — | — |
源码
/**
* SettingsPageFrame - L3 设置页整页装配件(W4 B6:设置页整页装配)
*
* 布局顺序:header(通常是 SettingsHeader)→ 可选 SectionScrubber(栏目跳转条)
* → 各 SettingsSectionCard(section.id 原样作为锚点 id)→ 可选 saveBar
* (通常是 StickySaveBar,由消费方按脏状态自行传入或传 null)。
*
* 分层:patterns 装配件,只组合设置域既有语义件(settings-header /
* section-scrubber / settings-section-card / sticky-save-bar);不取数、不发请求、
* 不持有表单/脏状态,不依赖 router/query/i18n 框架。scrollspy 与平滑滚动由
* SectionScrubber 自管,本件只负责声明 sections 与锚点一致性。
*
* icon 适配:SettingsSection.icon 收 ReactNode(常见 `<Bell />` 元素),而
* SettingsSectionCard 需要 LucideIcon 组件类型;本件把元素包成组件适配,
* 不复制卡片结构,也不采纳消费方自绘 section 骨架。
*
* children 是 sections 为空时的回退内容(例如整页引导/骨架),两者同时传入时
* 以 sections 为准。
*/
import { isValidElement, useMemo, type ComponentType, type ReactNode } from 'react';
import { Settings2, type LucideIcon } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { SectionScrubber } from './section-scrubber';
import { SettingsSectionCard } from './settings-section-card';
import { usePatternLabels } from '../lib/i18n';
/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface SettingsPageFrameLabels {
/** SectionScrubber 导航无障碍名 */
sectionNav: string;
/** 栏目容器 region 无障碍名 */
sectionsLabel: string;
}
export const SETTINGS_PAGE_FRAME_DEFAULT_LABELS: SettingsPageFrameLabels = {
sectionNav: '栏目导航',
sectionsLabel: '设置栏目',
};
export interface SettingsSection {
/** 锚点 id(透传 SettingsSectionCard,供 scrubber 跳转/scrollspy) */
id: string;
title: string;
description?: string;
/** 图标:可传 Lucide 组件或 `<Bell />` 元素;不传用中性设置图标兜底 */
icon?: ReactNode;
actions?: ReactNode;
content: ReactNode;
}
export interface SettingsPageFrameProps {
/** 页头槽(通常传 SettingsHeader) */
header?: ReactNode;
/** 栏目清单;声明顺序即展示顺序 */
sections: SettingsSection[];
/** 是否显示栏目跳转条(默认 true;sections 为空时不渲染) */
showScrubber?: boolean;
/** 页底保存栏槽(通常传 StickySaveBar;dirty=false 时该件自身返回 null) */
saveBar?: ReactNode;
/** sections 为空时的回退内容 */
children?: ReactNode;
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
labels?: Partial<SettingsPageFrameLabels>;
/** 页面外层附加类名 */
className?: string;
}
type SectionIcon = ComponentType<{ className?: string }>;
/**
* ReactNode 图标 → LucideIcon 组件:
* - React 元素(`<Bell />`):包一层 span 承接卡片下发的 className,并把内部
* svg 收进 16px 图标档(与 SettingsSectionCard 的 `<Icon className="size-4" />`
* 视觉一致);
* - 组件引用(Lucide 为 forwardRef 对象):直接透传;
* - 缺省:中性 Settings2 兜底,保持图标底板不空。
*/
function iconComponentOf(icon: ReactNode): SectionIcon {
if (icon == null) return Settings2 as unknown as SectionIcon;
// 组件引用:函数组件或 forwardRef/memo 对象(LucideIcon 即后者),直接透传
if (typeof icon === 'function') return icon as SectionIcon;
if (
typeof icon === 'object' &&
icon !== null &&
!isValidElement(icon) &&
'$$typeof' in icon
) {
return icon as unknown as SectionIcon;
}
const IconFromNode = ({ className }: { className?: string }) => (
<span className={cn('inline-flex items-center justify-center [&_svg]:size-4', className)}>
{icon}
</span>
);
return IconFromNode;
}
export function SettingsPageFrame({
header,
sections,
showScrubber = true,
saveBar,
children,
labels,
className,
}: SettingsPageFrameProps) {
const D = usePatternLabels('settingsPageFrame', SETTINGS_PAGE_FRAME_DEFAULT_LABELS);
const text: SettingsPageFrameLabels = {
sectionNav: labels?.sectionNav ?? D.sectionNav,
sectionsLabel: labels?.sectionsLabel ?? D.sectionsLabel,
};
const hasSections = sections.length > 0;
// SectionScrubber 的 observer effect 依赖 sections 引用:映射结果按源数组缓存,
// 避免本件每次渲染都重建 observer(跳转条建议模块级常量,见其组件注释)。
const scrubberSections = useMemo(
() => sections.map((section) => ({ id: section.id, label: section.title })),
[sections],
);
return (
<div
data-slot="settings-page-frame"
className={cn('flex min-w-0 flex-col gap-4', className)}
>
{header}
{showScrubber && hasSections ? (
<SectionScrubber
sections={scrubberSections}
labels={{ sectionNav: text.sectionNav }}
/>
) : null}
{hasSections ? (
<div
data-slot="settings-page-frame-sections"
role="region"
aria-label={text.sectionsLabel}
className="flex min-w-0 flex-col gap-4"
>
{sections.map((section) => (
<SettingsSectionCard
key={section.id}
id={section.id}
icon={iconComponentOf(section.icon) as unknown as LucideIcon}
title={section.title}
description={section.description}
actions={section.actions}
>
{section.content}
</SettingsSectionCard>
))}
</div>
) : (
children
)}
{saveBar}
</div>
);
}
可访问性与 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。
用法说明
设置页整页骨架:SettingsHeader + SectionScrubber + SettingsSectionCard + StickySaveBar 组合;锚点与滚动行为内聚。