PatternsApp Patterns
ToolbarRow
@mox-hub/patterns 模式 · App Patterns · canonical
toolbar-row@mox-hub/patternsApp Patternscanonicalsrc/components/toolbar-row.tsx变体演示toolbar-row
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| aiId* | string | — | — |
| className* | string | — | — |
| views* | ToolbarViewEntry[] | — | — |
| activeViewId* | string | — | — |
| onSelectView* | (id: string) => void | — | — |
| onCreateView* | (name: string, icon?: string) => void | — | — |
| onUpdateView* | (id: string, patch: Partial<Pick<ToolbarViewEntry, "icon" | "name">>) => void | — | — |
| onDeleteView* | (id: string) => void | — | — |
| isDirty* | boolean | — | — |
| onSaveCurrentView* | () => void | — | — |
| viewStyle* | { value: string; onChange: (value: string) => void; options: ToolbarViewStyleOption[]; layout?: "auto" | "centered" | "dropdown"; } | — | — |
| filterMenu* | false | ToolbarMenuSlot | — | — |
| displayMenu* | false | ToolbarMenuSlot | — | — |
| downloadMenu* | false | ToolbarMenuSlot | — | — |
| extraActions* | ToolbarActionDescriptor[] | — | — |
| actions* | ReactNode | — | — |
| translate* | PatternTranslate | — | — |
源码
import {
useCallback,
useEffect,
useRef,
useState,
type ComponentProps,
type ReactNode,
} from "react";
import { type PatternTranslate } from "../lib/translate";
import { usePatternTranslate } from "../lib/i18n";
import {
Bot,
Bug,
CalendarRange,
Check,
CheckCircle2,
ChevronDown,
Clock,
Download,
Filter,
Flag,
FolderOpen,
Inbox,
Kanban,
LayoutGrid,
List,
Plus,
SlidersHorizontal,
Sparkles,
Star,
TableProperties,
Tag,
Target,
User,
Zap,
type LucideIcon,
} from "lucide-react";
import { cn } from "@mox-hub/ui";
import { RawButton } from "@mox-hub/ui/components/raw/raw-button";
import { HeaderActionButton } from "./header-action-button";
import { AnchoredMenu } from "@mox-hub/ui/components/anchored-menu";
import { Checkbox } from "@mox-hub/ui/components/checkbox";
import { SegmentedControl, type SegmentedTone } from "@mox-hub/ui/components/segmented-control";
import { Input } from "@mox-hub/ui/components/input";
import {
MENU_ITEM_CLASS,
MENU_LABEL_CLASS,
MENU_SEPARATOR_CLASS,
} from "@mox-hub/ui/components/menu-surface";
import { ContextMenu, type MenuItem } from "@mox-hub/ui/components/context-menu";
import {
ViewDisplayPopover,
type ViewDisplayPopoverProps,
} from "./view-display-popover";
/* ────────────────────────────── 类型 ────────────────────────────── */
/** 已保存视图:名称 + 图标 + 页面状态快照(筛选/样式/排序等,结构由页面自定义,天然可扩展) */
export interface ToolbarViewEntry {
id: string;
name: string;
/** 图标 key,经 TOOLBAR_VIEW_ICONS 解析 */
icon?: string;
/** 内置视图不可删除 */
builtIn?: boolean;
snapshot?: Record<string, unknown>;
}
export interface ToolbarViewStyleOption {
value: string;
label: string;
icon?: LucideIcon;
/** 激活滑块高亮色调(页面按需传入) */
tone?: SegmentedTone;
}
export interface ToolbarMenuItem {
type?: "item" | "label" | "separator" | "checkbox";
id?: string;
label?: ReactNode;
icon?: LucideIcon;
checked?: boolean;
disabled?: boolean;
onSelect?: () => void;
}
export interface ToolbarMenuSlot {
/** 自定义按钮文案(未传时按插槽类型采用默认国际化) */
label?: string;
/** 完全自定义按钮+弹层节点(如二级级联筛选菜单 FilterCascadeMenu),提供时优先于 content/items */
render?: () => ReactNode;
/** 高级显示弹窗配置(直接渲染 Linear 风格 ViewDisplayPopover) */
displayConfig?: ViewDisplayPopoverProps;
/** 结构化菜单项 */
items?: ToolbarMenuItem[];
/** 完全自定义下拉内容(优先于 items) */
content?: ReactNode;
/** 筛选菜单顶部搜索框(内置 300ms 防抖) */
search?: {
value: string;
onChange: (value: string) => void;
placeholder?: string;
};
/** 按钮右上角数字角标(>0 显示,如生效中的筛选数量) */
badge?: number;
}
/* ─────────────────── Filter 多选状态工具 ─────────────────── */
/**
* 快照里的筛选项归一为数组:兼容历史单值(string / 'all')与新多值(string[])。
* 空数组 = 该维度不做筛选(等价于旧 'all')。
*/
export function normalizeFilterSelection(value: unknown): string[] {
if (Array.isArray(value)) {
return value.filter((v): v is string => typeof v === "string" && v !== "all");
}
return typeof value === "string" && value !== "all" ? [value] : [];
}
/** 勾选/取消勾选一个筛选项(不可变更新) */
export function toggleFilterValue(values: string[], value: string): string[] {
return values.includes(value) ? values.filter((v) => v !== value) : [...values, value];
}
export interface ToolbarActionDescriptor {
id: string;
icon: LucideIcon;
label: string;
variant?: "primary" | "outline" | "secondary" | "ghost" | "danger";
/** 无下拉的直接动作按钮(圆形 hover 展开) */
onClick?: () => void;
/** 带下拉的按钮 */
menu?: ToolbarMenuSlot;
/** 自定义节点(如进度按钮等无法用 icon/label 描述的动作件),提供时优先于其余字段 */
render?: () => ReactNode;
}
/** 工具栏文案缺省:全部调用都带中文 fallback,翻译器回落到 fallback 即可。 */
export interface ToolbarRowProps {
aiId?: string;
className?: string;
/** 文案覆写(主仓 i18n 适配层集中传入 t() 包装)。 */
translate?: PatternTranslate;
/* 视图管理(左):整体不传(undefined)即隐藏视图胶囊与新增按钮——纯样式切换页(analytics / 类型详情)用 */
views?: ToolbarViewEntry[];
activeViewId?: string;
onSelectView?: (id: string) => void;
onCreateView?: (name: string, icon?: string) => void;
onUpdateView?: (id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => void;
onDeleteView?: (id: string) => void;
/** 当前视图是否有未保存变动(指示脏状态) */
isDirty?: boolean;
/** 保存当前改动到当前激活视图 */
onSaveCurrentView?: () => void;
/* 视图样式切换(居中 / 右侧下拉) */
viewStyle?: {
value: string;
onChange: (value: string) => void;
options: ToolbarViewStyleOption[];
/** auto:样式 >3 种时收进右侧按钮组下拉(默认),否则居中 */
layout?: "auto" | "centered" | "dropdown";
};
/* 右侧按钮组:默认 筛选 / 显示 / 下载,传 false 移除 */
filterMenu?: ToolbarMenuSlot | false;
displayMenu?: ToolbarMenuSlot | false;
downloadMenu?: ToolbarMenuSlot | false;
/** 页面注册的附加按钮(追加在默认按钮之后) */
extraActions?: ToolbarActionDescriptor[];
/** 自定义动作/状态节点(渲染在右侧按钮组前) */
actions?: ReactNode;
}
/** 视图可选图标(存储为字符串 key) */
export const TOOLBAR_VIEW_ICONS: Record<string, LucideIcon> = {
list: List,
board: Kanban,
gantt: CalendarRange,
table: TableProperties,
grid: LayoutGrid,
bot: Bot,
star: Star,
flag: Flag,
inbox: Inbox,
tag: Tag,
target: Target,
zap: Zap,
bug: Bug,
folder: FolderOpen,
clock: Clock,
user: User,
check: CheckCircle2,
sparkles: Sparkles,
};
/* ─────────────────────────── useToolbarViews ─────────────────────────── */
interface UseToolbarViewsOptions {
/** localStorage key 后缀:toolbar-views:<key> */
key: string;
/** 默认视图(至少一个),本地无存储时兜底 */
defaults: ToolbarViewEntry[];
/** 切换视图时恢复快照到页面状态 */
onApply?: (snapshot: Record<string, unknown> | undefined) => void;
}
const storageKeyOf = (key: string) => `toolbar-views:${key}`;
function loadViews(key: string, defaults: ToolbarViewEntry[]): ToolbarViewEntry[] {
try {
const raw = localStorage.getItem(storageKeyOf(key));
if (!raw) return defaults;
const parsed: unknown = JSON.parse(raw);
if (!Array.isArray(parsed) || parsed.length === 0) return defaults;
return parsed as ToolbarViewEntry[];
} catch {
return defaults;
}
}
/**
* 已保存视图状态管理:持久化到 localStorage(每页独立 key)。
*/
export function useToolbarViews({ key, defaults, onApply }: UseToolbarViewsOptions) {
const [initialState] = useState(() => {
const loaded = loadViews(key, defaults);
return { views: loaded, activeViewId: loaded[0]?.id ?? "" };
});
const [views, setViews] = useState<ToolbarViewEntry[]>(initialState.views);
const [activeViewId, setActiveViewId] = useState<string>(initialState.activeViewId);
const [isDirty, setIsDirty] = useState(false);
const onApplyRef = useRef(onApply);
const viewsRef = useRef(views);
const activeIdRef = useRef(activeViewId);
const snapshotRef = useRef<Record<string, unknown> | undefined>(initialState.views[0]?.snapshot);
const [loadedKey, setLoadedKey] = useState(key);
if (loadedKey !== key) {
setLoadedKey(key);
const reloaded = loadViews(key, defaults);
setViews(reloaded);
setActiveViewId(reloaded[0]?.id ?? "");
setIsDirty(false);
}
useEffect(() => {
onApplyRef.current = onApply;
viewsRef.current = views;
activeIdRef.current = activeViewId;
const activeSnapshot = views.find((v) => v.id === activeViewId)?.snapshot;
if (activeSnapshot !== undefined) snapshotRef.current = activeSnapshot;
});
useEffect(() => {
try {
localStorage.setItem(storageKeyOf(key), JSON.stringify(views));
} catch {
/* 存储不可用时静默降级为内存态 */
}
}, [key, views]);
const selectView = useCallback((id: string) => {
const target = viewsRef.current.find((v) => v.id === id);
if (!target || id === activeIdRef.current) return;
snapshotRef.current = target.snapshot;
setActiveViewId(id);
setIsDirty(false);
onApplyRef.current?.(target.snapshot);
}, []);
/** 页面状态变化时上报,写入当前激活视图的快照 */
const updateActiveSnapshot = useCallback((snapshot: Record<string, unknown>) => {
snapshotRef.current = snapshot;
setViews((prev) => {
let changed = false;
const next = prev.map((v) => {
if (v.id !== activeIdRef.current) return v;
if (JSON.stringify(v.snapshot) === JSON.stringify(snapshot)) return v;
changed = true;
return { ...v, snapshot };
});
return changed ? next : prev;
});
}, []);
/** 以当前页面状态为快照新建视图并激活 */
const createView = useCallback((name: string, icon?: string) => {
const id = `view-${Date.now().toString(36)}`;
const snapshot = snapshotRef.current ?? {};
setViews((prev) => [...prev, { id, name: name.trim() || "View", icon: icon ?? "star", snapshot }]);
setActiveViewId(id);
setIsDirty(false);
}, []);
const updateView = useCallback(
(id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => {
setViews((prev) => prev.map((v) => (v.id === id ? { ...v, ...patch } : v)));
},
[],
);
const deleteView = useCallback((id: string) => {
const current = viewsRef.current;
const target = current.find((v) => v.id === id);
if (!target || target.builtIn || current.length <= 1) return;
const next = current.filter((v) => v.id !== id);
setViews(next);
if (id === activeIdRef.current) {
const fallback = next[0];
snapshotRef.current = fallback.snapshot;
setActiveViewId(fallback.id);
setIsDirty(false);
onApplyRef.current?.(fallback.snapshot);
}
}, []);
const saveCurrentToActive = useCallback(() => {
if (snapshotRef.current) {
updateActiveSnapshot(snapshotRef.current);
setIsDirty(false);
}
}, [updateActiveSnapshot]);
return {
views,
activeViewId,
selectView,
updateActiveSnapshot,
createView,
updateView,
deleteView,
isDirty,
saveCurrentToActive,
};
}
/* ─────────────────────────── 内部子组件 ─────────────────────────── */
function ToolbarSearchBox({
value,
onChange,
placeholder,
}: NonNullable<ToolbarMenuSlot["search"]>) {
const [buffer, setBuffer] = useState(value);
const [prevValue, setPrevValue] = useState(value);
const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
if (prevValue !== value) {
setPrevValue(value);
setBuffer(value);
}
useEffect(() => {
clearTimeout(timer.current);
}, [value]);
useEffect(() => () => clearTimeout(timer.current), []);
const handleChange = (next: string) => {
setBuffer(next);
clearTimeout(timer.current);
timer.current = setTimeout(() => onChange(next), 300);
};
return (
<Input
value={buffer}
onChange={(event) => handleChange(event.target.value)}
onKeyDown={(event) => {
if (event.key === "Enter") {
clearTimeout(timer.current);
onChange(buffer);
}
}}
placeholder={placeholder}
className="h-control-sm text-xs"
/>
);
}
function ToolbarMenuItems({ items, close }: { items: ToolbarMenuItem[]; close: () => void }) {
return (
<div className="min-w-40">
{items.map((item, index) => {
const key = item.id ?? index;
if (item.type === "separator") {
return <div key={key} className={MENU_SEPARATOR_CLASS} />;
}
if (item.type === "label") {
return (
<div key={key} className={MENU_LABEL_CLASS}>
{item.label}
</div>
);
}
const Icon = item.icon;
const isCheckbox = item.type === "checkbox";
return (
<RawButton
key={key}
type="button"
disabled={item.disabled}
onClick={() => {
item.onSelect?.();
if (!isCheckbox) close();
}}
className={cn(
MENU_ITEM_CLASS,
"text-xs",
item.disabled && "pointer-events-none opacity-50",
)}
>
{isCheckbox ? (
<Checkbox
className="me-2"
checked={item.checked ?? false}
render={<span aria-hidden="true" />}
/>
) : Icon ? (
<Icon className="me-2 size-4 shrink-0" strokeWidth={1.75} />
) : null}
<span className="truncate">{item.label}</span>
</RawButton>
);
})}
</div>
);
}
function ToolbarMenuButton({
icon,
label,
variant = "outline",
menu,
...buttonProps
}: {
icon: LucideIcon;
label: string;
variant?: ToolbarActionDescriptor["variant"];
menu: ToolbarMenuSlot;
} & Omit<ComponentProps<typeof HeaderActionButton>, "icon" | "label" | "variant">) {
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);
const close = useCallback(() => setOpen(false), []);
return (
<span className="relative inline-flex shrink-0">
<HeaderActionButton
ref={anchorRef}
icon={icon}
label={label}
variant={variant}
pinned={open}
trailing={<ChevronDown className="ms-0.5 size-3 opacity-70" />}
aria-haspopup="menu"
aria-expanded={open}
onClick={() => setOpen((prev) => !prev)}
{...buttonProps}
/>
{menu.badge && menu.badge > 0 ? (
<span className="pointer-events-none absolute -top-1 end-0 flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-xs font-medium leading-none text-destructive-foreground">
{menu.badge > 99 ? "99+" : menu.badge}
</span>
) : null}
<AnchoredMenu open={open} onClose={close} anchor={anchorRef}>
{menu.displayConfig ? (
<ViewDisplayPopover {...menu.displayConfig} />
) : (
menu.content ?? (
<div className="flex max-h-80 flex-col">
{menu.search ? (
<div className="mb-1 shrink-0">
<ToolbarSearchBox {...menu.search} />
</div>
) : null}
<div className="min-h-0 overflow-y-auto">
<ToolbarMenuItems items={menu.items ?? []} close={close} />
</div>
</div>
)
)}
</AnchoredMenu>
</span>
);
}
function ExtraActionButton({ action }: { action: ToolbarActionDescriptor }) {
if (action.render) {
return <>{action.render()}</>;
}
if (action.menu) {
return (
<ToolbarMenuButton
icon={action.icon}
label={action.label}
variant={action.variant}
menu={action.menu}
data-ai-component={action.id}
/>
);
}
return (
<HeaderActionButton
icon={action.icon}
label={action.label}
variant={action.variant}
onClick={action.onClick}
data-ai-component={action.id}
/>
);
}
const PRESET_VIEW_NAMES = [
{ key: "all", label: "全部工单", icon: "list" },
{ key: "mine", label: "我的待办", icon: "star" },
{ key: "board", label: "按状态看板", icon: "board" },
{ key: "timeline", label: "时间线排期", icon: "gantt" },
{ key: "bugs", label: "高优缺陷", icon: "bug" },
{ key: "ai", label: "AI 自动化", icon: "bot" },
];
/** 视图新建/编辑面板(AnchoredMenu 内容) */
function ViewEditorPanel({
initialName = "",
initialIcon,
builtIn,
mode,
submitText,
onSubmit,
onDelete,
}: {
initialName?: string;
initialIcon?: string;
builtIn?: boolean;
mode: "create" | "edit";
submitText: string;
onSubmit: (name: string, icon: string) => void;
onDelete?: () => void;
}) {
const [name, setName] = useState(initialName);
const [icon, setIcon] = useState(initialIcon ?? "star");
const t = usePatternTranslate("toolbarRow", {});
return (
<form
className="flex w-72 flex-col gap-2.5 p-3"
onSubmit={(event) => {
event.preventDefault();
onSubmit(name.trim() || t("viewEditor.defaultName", "View"), icon);
}}
>
<div className="text-xs font-semibold text-foreground">
{mode === "create"
? t("viewEditor.create", "新建自定义视图")
: t("viewEditor.edit", "编辑视图")}
</div>
<Input
value={name}
onChange={(event) => setName(event.target.value)}
placeholder={t("viewEditor.namePlaceholder", "输入视图名称...")}
className="h-control-sm text-xs"
autoFocus
/>
{mode === "create" ? (
<div className="flex flex-wrap gap-1">
{PRESET_VIEW_NAMES.map((preset) => {
const presetLabel = t(
`viewEditor.presets.${preset.key}`,
preset.label,
);
return (
<RawButton
key={preset.key}
type="button"
onClick={() => {
setName(presetLabel);
setIcon(preset.icon);
}}
className="rounded-md border border-border bg-muted/30 px-1.5 py-0.5 text-2xs text-muted-foreground hover:bg-muted hover:text-foreground"
>
{presetLabel}
</RawButton>
);
})}
</div>
) : null}
<div className="text-2xs text-muted-foreground">{t("viewEditor.iconLabel", "选择代表图标")}</div>
<div className="grid grid-cols-6 gap-1.5 max-h-36 overflow-y-auto pe-1">
{Object.entries(TOOLBAR_VIEW_ICONS).map(([key, Icon]) => (
<RawButton
key={key}
type="button"
onClick={() => setIcon(key)}
aria-label={key}
className={cn(
"flex size-control-sm items-center justify-center rounded-md border transition-colors",
icon === key
? "border-primary bg-primary/10 text-primary shadow-xs"
: "border-transparent text-muted-foreground hover:bg-muted hover:text-foreground",
)}
>
<Icon className="size-4" strokeWidth={1.75} />
</RawButton>
))}
</div>
<div className="flex items-center gap-2 pt-1">
<RawButton
type="submit"
className="inline-flex h-control-sm flex-1 items-center justify-center rounded-md bg-primary px-3 text-xs font-medium text-primary-foreground shadow-xs transition-colors hover:bg-primary/90"
>
{submitText}
</RawButton>
{onDelete && !builtIn ? (
<RawButton
type="button"
onClick={onDelete}
className="inline-flex h-control-sm items-center justify-center rounded-md border border-border px-3 text-xs font-medium text-destructive transition-colors hover:bg-destructive/10"
>
{t("viewEditor.delete", "删除")}
</RawButton>
) : null}
</div>
</form>
);
}
/** 胶囊风格 ViewPill:rounded-full 胶囊、取消三个点、右键呼出系统 ContextMenu */
function ViewPill({
view,
active,
isDirty,
onSelect,
onUpdate,
onDelete,
onSaveCurrent,
translate,
}: {
view: ToolbarViewEntry;
active: boolean;
isDirty?: boolean;
onSelect: (id: string) => void;
onUpdate: (id: string, patch: Partial<Pick<ToolbarViewEntry, "name" | "icon">>) => void;
onDelete: (id: string) => void;
onSaveCurrent?: () => void;
translate?: PatternTranslate;
}) {
const [editing, setEditing] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);
const Icon = view.icon ? TOOLBAR_VIEW_ICONS[view.icon] : undefined;
const providerT = usePatternTranslate('toolbarRow', {});
const t = translate ?? providerT;
const contextMenuItems: MenuItem[] = [
...(active && isDirty && onSaveCurrent
? [
{
id: "save",
label: t("viewActions.save", "保存当前改动到视图"),
onClick: () => onSaveCurrent(),
},
]
: []),
{
id: "edit",
label: t("viewActions.edit", "编辑名称与图标"),
onClick: () => setEditing(true),
},
...(!view.builtIn
? [
{
id: "delete",
label: t("viewActions.delete", "删除视图"),
destructive: true,
onClick: () => onDelete(view.id),
},
]
: []),
];
const displayName =
view.builtIn && (view.id === 'all' || view.name === 'All')
? t('common.all', '全部')
: view.name;
return (
<div className="relative inline-flex shrink-0">
<ContextMenu items={contextMenuItems}>
<RawButton
ref={anchorRef}
type="button"
onClick={() => onSelect(view.id)}
title={`${displayName} (${t("viewActions.manageHint", "右键管理")})`}
aria-label={displayName}
className={cn(
"flex h-control-2xs shrink-0 items-center gap-1.5 rounded-full border px-3 text-xs font-medium transition-[background-color,color,box-shadow,transform] select-none [transition-duration:var(--motion-fast)]",
active
? "border-border bg-card text-foreground shadow-xs font-semibold"
: "border-border/40 bg-transparent text-muted-foreground hover:bg-muted hover:text-foreground",
)}
>
{Icon ? <Icon className="size-3.5 shrink-0 opacity-80" strokeWidth={1.75} /> : null}
<span className="max-w-32 truncate">{displayName}</span>
{active && isDirty ? (
<span
title={t("viewState.dirty", "包含未保存的筛选或显示改动")}
className="size-1.5 rounded-full bg-accent-yellow ring-1 ring-accent-yellow/40"
/>
) : null}
</RawButton>
</ContextMenu>
<AnchoredMenu
open={editing}
onClose={() => setEditing(false)}
anchor={anchorRef}
mode="dialog"
ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
>
<ViewEditorPanel
initialName={view.name}
initialIcon={view.icon}
builtIn={view.builtIn}
mode="edit"
submitText={t("viewEditor.save", "保存")}
onSubmit={(name, icon) => {
onUpdate(view.id, { name, icon });
setEditing(false);
}}
onDelete={() => {
onDelete(view.id);
setEditing(false);
}}
/>
</AnchoredMenu>
</div>
);
}
/** 胶囊风格新增视图按钮:rounded-full 微虚线 */
function AddViewButton({ onCreate }: { onCreate: (name: string, icon?: string) => void }) {
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);
const t = usePatternTranslate("toolbarRow", {});
return (
<>
<RawButton
ref={anchorRef}
type="button"
onClick={() => setOpen(true)}
aria-label={t("viewActions.add", "Add view")}
title={t("viewActions.add", "Add view")}
className="flex h-control-2xs shrink-0 items-center justify-center rounded-full border border-dashed border-border/70 px-2 text-xs text-muted-foreground transition-colors hover:border-primary/50 hover:bg-primary/5 hover:text-primary"
>
<Plus className="size-3.5" strokeWidth={2} aria-hidden />
</RawButton>
<AnchoredMenu
open={open}
onClose={() => setOpen(false)}
anchor={anchorRef}
mode="dialog"
ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
>
<ViewEditorPanel
mode="create"
submitText={t("viewEditor.createAction", "新建")}
onSubmit={(name, icon) => {
onCreate(name, icon);
setOpen(false);
}}
/>
</AnchoredMenu>
</>
);
}
function ViewStyleDropdown({
value,
onChange,
options,
translate,
}: {
value: string;
onChange: (value: string) => void;
options: ToolbarViewStyleOption[];
translate?: PatternTranslate;
}) {
const providerT = usePatternTranslate('toolbarRow', {});
const t = translate ?? providerT;
const [open, setOpen] = useState(false);
const anchorRef = useRef<HTMLButtonElement>(null);
const current = options.find((option) => option.value === value) ?? options[0];
if (!current) return null;
const currentLabel =
typeof current.label === "string"
? t(`viewDisplay.views.${current.value}`, current.label)
: current.label;
return (
<>
<HeaderActionButton
ref={anchorRef}
icon={current.icon ?? LayoutGrid}
label={currentLabel}
variant="outline"
pinned
trailing={<ChevronDown className="ms-0.5 size-3 opacity-70" />}
aria-haspopup="menu"
aria-expanded={open}
onClick={() => setOpen((prev) => !prev)}
/>
<AnchoredMenu
open={open}
onClose={() => setOpen(false)}
anchor={anchorRef}
mode="dialog"
ariaLabel={t("viewEditor.dialogLabel", "视图设置")}
>
<div className="min-w-36">
{options.map((option) => {
const Icon = option.icon;
const label =
typeof option.label === "string"
? t(`viewDisplay.views.${option.value}`, option.label)
: option.label;
return (
<RawButton
key={option.value}
type="button"
onClick={() => {
onChange(option.value);
setOpen(false);
}}
className={cn(MENU_ITEM_CLASS, "text-xs")}
>
{Icon ? <Icon className="me-2 size-4 shrink-0" strokeWidth={1.75} /> : null}
<span className="flex-1 truncate">{label}</span>
{option.value === current.value ? (
<Check className="ms-2 size-3.5 shrink-0 text-primary" strokeWidth={2.5} />
) : null}
</RawButton>
);
})}
</div>
</AnchoredMenu>
</>
);
}
/* ─────────────────────────── ToolbarRow ─────────────────────────── */
export function ToolbarRow({
aiId,
className,
views,
activeViewId,
onSelectView,
onCreateView,
onUpdateView,
onDeleteView,
isDirty,
onSaveCurrentView,
viewStyle,
filterMenu,
displayMenu,
downloadMenu,
extraActions,
actions,
translate,
}: ToolbarRowProps) {
const providerT = usePatternTranslate('toolbarRow', {});
const t = translate ?? providerT;
// 当 layout 为 centered 时优先居中;若未显式指定,当选项 > 3 种时自动下拉收纳(兼容历史规则)
const styleLayout =
viewStyle?.layout === "centered" || viewStyle?.layout === "dropdown"
? viewStyle.layout
: viewStyle && viewStyle.options.length > 3
? "dropdown"
: "centered";
return (
<header
className={cn(
"sticky top-10 z-sticky grid w-full shrink-0 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-3 border-b border-border bg-background px-page py-2",
className,
)}
data-ai-component={aiId ? `${aiId}.context-bar` : "ui.toolbar-row"}
data-ai-role="filter"
>
<div className="flex min-w-0 items-center gap-1.5 overflow-x-auto">
{views && onSelectView && onUpdateView && onDeleteView ? (
<>
{views.map((view) => (
<ViewPill
key={view.id}
view={view}
active={view.id === activeViewId}
isDirty={view.id === activeViewId ? isDirty : false}
onSelect={onSelectView}
onUpdate={onUpdateView}
onDelete={onDeleteView}
onSaveCurrent={onSaveCurrentView}
translate={translate}
/>
))}
{onCreateView ? <AddViewButton onCreate={onCreateView} /> : null}
</>
) : null}
</div>
{viewStyle && styleLayout === "centered" ? (
<div className="min-w-0 max-w-full justify-self-center overflow-x-auto">
<SegmentedControl
variant="rect"
value={viewStyle.value}
onChange={viewStyle.onChange}
options={viewStyle.options.map((option) => {
const Icon = option.icon;
const label =
typeof option.label === "string"
? t(`viewDisplay.views.${option.value}`, option.label)
: option.label;
return {
value: option.value,
label,
icon: Icon ? <Icon className="size-3.5" strokeWidth={1.75} /> : undefined,
tone: option.tone,
};
})}
/>
</div>
) : (
<div />
)}
<div className="flex min-w-0 items-center justify-end gap-2 overflow-x-auto">
{actions}
{viewStyle && styleLayout === "dropdown" ? (
<ViewStyleDropdown
value={viewStyle.value}
onChange={viewStyle.onChange}
options={viewStyle.options}
translate={translate}
/>
) : null}
{filterMenu ? (
filterMenu.render ? (
filterMenu.render()
) : (
<ToolbarMenuButton
icon={Filter}
label={filterMenu.label ?? t("common.filters", "Filter")}
menu={filterMenu}
/>
)
) : null}
{displayMenu ? (
displayMenu.render ? (
displayMenu.render()
) : (
<ToolbarMenuButton
icon={SlidersHorizontal}
label={displayMenu.label ?? t("viewDisplay.display", "Display")}
menu={displayMenu}
/>
)
) : null}
{downloadMenu ? (
<ToolbarMenuButton
icon={Download}
label={downloadMenu.label ?? t("common.download", "Download")}
menu={downloadMenu}
/>
) : null}
{extraActions?.map((action) => (
<ExtraActionButton key={action.id} action={action} />
))}
</div>
</header>
);
}
可访问性与 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。
用法说明
页面工具栏:视图胶囊 + 视图样式切换 + 筛选/显示/下载菜单 + 附加动作;useToolbarViews 持 localStorage 视图状态,文案经 translate 注入。