Ordo UI
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*booleantrue—
saveBar*ReactNode——
children*ReactNode——
labels*Partial<SettingsPageFrameLabels>——
className*string——

源码

packages/patterns/src/components/settings-page-frame.tsx
/**
 * 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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

设置页整页骨架:SettingsHeader + SectionScrubber + SettingsSectionCard + StickySaveBar 组合;锚点与滚动行为内聚。