PatternsApp Patterns
HeaderActionButton
@mox-hub/patterns 模式 · App Patterns · canonical
header-action-button@mox-hub/patternsApp Patternscanonicalsrc/components/header-action-button.tsx变体演示header-action-button
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| title | string | — | — |
| className | string | — | — |
| icon* | LucideIcon | — | — |
| form | string | — | — |
| label* | string | — | 展开时显示的文本,同时作为无障碍标签 |
| slot | string | — | — |
| style | CSSProperties | — | — |
| key | Key | — | — |
| disabled | boolean | — | — |
| formAction | string | ((formData: FormData) => void | Promise<void>) | — | — |
| formEncType | string | — | — |
| formMethod | string | — | — |
| formNoValidate | boolean | — | — |
| formTarget | string | — | — |
| name | string | — | — |
| type | "button" | "submit" | "reset" | — | — |
| value | string | number | readonly string[] | — | — |
| defaultChecked | boolean | — | — |
| defaultValue | string | number | readonly string[] | — | — |
| suppressContentEditableWarning | boolean | — | — |
| suppressHydrationWarning | boolean | — | — |
| accessKey | string | — | — |
| autoCapitalize | "off" | "none" | "on" | "sentences" | "words" | "characters" | (string & {}) | — | — |
| autoFocus | boolean | — | — |
| contentEditable | Booleanish | "inherit" | "plaintext-only" | — | — |
| contextMenu | string | — | — |
| dir | string | — | — |
| draggable | Booleanish | — | — |
| enterKeyHint | "search" | "enter" | "done" | "go" | "next" | "previous" | "send" | — | — |
| hidden | boolean | — | — |
| id | string | — | — |
| lang | string | — | — |
| nonce | string | — | — |
| spellCheck | Booleanish | — | — |
| tabIndex | number | — | — |
| translate | "yes" | "no" | — | — |
| radioGroup | string | — | — |
| role | AriaRole | — | — |
| about | string | — | — |
| content | string | — | — |
| datatype | string | — | — |
| inlist | any | — | — |
| prefix | string | — | — |
| property | string | — | — |
| rel | string | — | — |
| resource | string | — | — |
| rev | string | — | — |
| typeof | string | — | — |
| vocab | string | — | — |
| autoCorrect | string | — | — |
| autoSave | string | — | — |
| color | string | — | — |
| itemProp | string | — | — |
| itemScope | boolean | — | — |
| itemType | string | — | — |
| itemID | string | — | — |
| itemRef | string | — | — |
| results | number | — | — |
| security | string | — | — |
| unselectable | "off" | "on" | — | — |
| popover | "" | "auto" | "manual" | "hint" | — | — |
| popoverTargetAction | "toggle" | "show" | "hide" | — | — |
| popoverTarget | string | — | — |
| inert | boolean | — | — |
| inputMode | "search" | "text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | — | Hints at the type of data that might be entered by the user while editing the element or its contents |
| is | string | — | Specify that a standard HTML element should behave like a defined custom built-in element |
| exportparts | string | — | — |
| part | string | — | — |
| aria-activedescendant | string | — | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| aria-atomic | Booleanish | — | Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute. |
| aria-autocomplete | "none" | "list" | "inline" | "both" | — | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be |
| aria-braillelabel | string | — | Indicates an element is being modified and that assistive technologies MAY want to wait until the modifications are complete before exposing them to the user. |
| aria-brailleroledescription | string | — | Defines a human-readable, author-localized abbreviated description for the role of an element, which is intended to be converted into Braille. |
| aria-busy | Booleanish | — | — |
| aria-checked | boolean | "true" | "false" | "mixed" | — | Indicates the current "checked" state of checkboxes, radio buttons, and other widgets. |
| aria-colcount | number | — | Defines the total number of columns in a table, grid, or treegrid. |
| aria-colindex | number | — | Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. |
| aria-colindextext | string | — | Defines a human readable text alternative of aria-colindex. |
| aria-colspan | number | — | Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. |
| aria-controls | string | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. |
| aria-current | boolean | "time" | "true" | "false" | "page" | "step" | "location" | "date" | — | Indicates the element that represents the current item within a container or set of related elements. |
| aria-describedby | string | — | Identifies the element (or elements) that describes the object. |
| aria-description | string | — | Defines a string value that describes or annotates the current element. |
| aria-details | string | — | Identifies the element that provides a detailed, extended description for the object. |
| aria-disabled | Booleanish | — | Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable. |
| aria-dropeffect | "link" | "none" | "copy" | "execute" | "move" | "popup" | — | Indicates what functions can be performed when a dragged object is released on the drop target. |
| aria-errormessage | string | — | Identifies the element that provides an error message for the object. |
| aria-expanded | Booleanish | — | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. |
| aria-flowto | string | — | Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, |
| aria-grabbed | Booleanish | — | Indicates an element's "grabbed" state in a drag-and-drop operation. |
| aria-haspopup | boolean | "dialog" | "menu" | "true" | "false" | "grid" | "listbox" | "tree" | — | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. |
| aria-hidden | Booleanish | — | Indicates whether the element is exposed to an accessibility API. |
| aria-invalid | boolean | "true" | "false" | "grammar" | "spelling" | — | Indicates the entered value does not conform to the format expected by the application. |
| aria-keyshortcuts | string | — | Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. |
| aria-label | string | — | Defines a string value that labels the current element. |
| aria-labelledby | string | — | Identifies the element (or elements) that labels the current element. |
| aria-level | number | — | Defines the hierarchical level of an element within a structure. |
| aria-live | "off" | "assertive" | "polite" | — | Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region. |
| aria-modal | Booleanish | — | Indicates whether an element is modal when displayed. |
| aria-multiline | Booleanish | — | Indicates whether a text box accepts multiple lines of input or only a single line. |
| aria-multiselectable | Booleanish | — | Indicates that the user may select more than one item from the current selectable descendants. |
| aria-orientation | "horizontal" | "vertical" | — | Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. |
| aria-owns | string | — | Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship |
| aria-placeholder | string | — | Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. |
| aria-posinset | number | — | Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. |
| aria-pressed | boolean | "true" | "false" | "mixed" | — | Indicates the current "pressed" state of toggle buttons. |
| aria-readonly | Booleanish | — | Indicates that the element is not editable, but is otherwise operable. |
| aria-relevant | "text" | "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text additions" | "text removals" | — | Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified. |
| aria-required | Booleanish | — | Indicates that user input is required on the element before a form may be submitted. |
| aria-roledescription | string | — | Defines a human-readable, author-localized description for the role of an element. |
| aria-rowcount | number | — | Defines the total number of rows in a table, grid, or treegrid. |
| aria-rowindex | number | — | Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. |
| aria-rowindextext | string | — | Defines a human readable text alternative of aria-rowindex. |
| aria-rowspan | number | — | Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. |
| aria-selected | Booleanish | — | Indicates the current "selected" state of various widgets. |
| aria-setsize | number | — | Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM. |
| aria-sort | "none" | "ascending" | "descending" | "other" | — | Indicates if items in a table or grid are sorted in ascending or descending order. |
| aria-valuemax | number | — | Defines the maximum allowed value for a range widget. |
| aria-valuemin | number | — | Defines the minimum allowed value for a range widget. |
| aria-valuenow | number | — | Defines the current value for a range widget. |
| aria-valuetext | string | — | Defines the human readable text alternative of aria-valuenow for a range widget. |
| dangerouslySetInnerHTML | { __html: string | TrustedHTML; } | — | — |
| onCopy | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onCopyCapture | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onCut | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onCutCapture | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onPaste | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onPasteCapture | ClipboardEventHandler<HTMLButtonElement> | — | — |
| onCompositionEnd | CompositionEventHandler<HTMLButtonElement> | — | — |
| onCompositionEndCapture | CompositionEventHandler<HTMLButtonElement> | — | — |
| onCompositionStart | CompositionEventHandler<HTMLButtonElement> | — | — |
| onCompositionStartCapture | CompositionEventHandler<HTMLButtonElement> | — | — |
| onCompositionUpdate | CompositionEventHandler<HTMLButtonElement> | — | — |
| onCompositionUpdateCapture | CompositionEventHandler<HTMLButtonElement> | — | — |
| onFocus | FocusEventHandler<HTMLButtonElement> | — | — |
| onFocusCapture | FocusEventHandler<HTMLButtonElement> | — | — |
| onBlur | FocusEventHandler<HTMLButtonElement> | — | — |
| onBlurCapture | FocusEventHandler<HTMLButtonElement> | — | — |
| onChange | ChangeEventHandler<HTMLButtonElement, Element> | — | — |
| onChangeCapture | ChangeEventHandler<HTMLButtonElement, Element> | — | — |
| onBeforeInput | InputEventHandler<HTMLButtonElement> | — | — |
| onBeforeInputCapture | InputEventHandler<HTMLButtonElement> | — | — |
| onInput | InputEventHandler<HTMLButtonElement> | — | — |
| onInputCapture | InputEventHandler<HTMLButtonElement> | — | — |
| onReset | ReactEventHandler<HTMLButtonElement> | — | — |
| onResetCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onSubmit | SubmitEventHandler<HTMLButtonElement> | — | — |
| onSubmitCapture | SubmitEventHandler<HTMLButtonElement> | — | — |
| onInvalid | ReactEventHandler<HTMLButtonElement> | — | — |
| onInvalidCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoad | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onError | ReactEventHandler<HTMLButtonElement> | — | — |
| onErrorCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onKeyDown | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onKeyDownCapture | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onKeyPress | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onKeyPressCapture | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onKeyUp | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onKeyUpCapture | KeyboardEventHandler<HTMLButtonElement> | — | — |
| onAbort | ReactEventHandler<HTMLButtonElement> | — | — |
| onAbortCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onCanPlay | ReactEventHandler<HTMLButtonElement> | — | — |
| onCanPlayCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onCanPlayThrough | ReactEventHandler<HTMLButtonElement> | — | — |
| onCanPlayThroughCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onDurationChange | ReactEventHandler<HTMLButtonElement> | — | — |
| onDurationChangeCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onEmptied | ReactEventHandler<HTMLButtonElement> | — | — |
| onEmptiedCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onEncrypted | ReactEventHandler<HTMLButtonElement> | — | — |
| onEncryptedCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onEnded | ReactEventHandler<HTMLButtonElement> | — | — |
| onEndedCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadedData | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadedDataCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadedMetadata | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadedMetadataCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadStart | ReactEventHandler<HTMLButtonElement> | — | — |
| onLoadStartCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onPause | ReactEventHandler<HTMLButtonElement> | — | — |
| onPauseCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onPlay | ReactEventHandler<HTMLButtonElement> | — | — |
| onPlayCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onPlaying | ReactEventHandler<HTMLButtonElement> | — | — |
| onPlayingCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onProgress | ReactEventHandler<HTMLButtonElement> | — | — |
| onProgressCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onRateChange | ReactEventHandler<HTMLButtonElement> | — | — |
| onRateChangeCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onSeeked | ReactEventHandler<HTMLButtonElement> | — | — |
| onSeekedCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onSeeking | ReactEventHandler<HTMLButtonElement> | — | — |
| onSeekingCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onStalled | ReactEventHandler<HTMLButtonElement> | — | — |
| onStalledCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onSuspend | ReactEventHandler<HTMLButtonElement> | — | — |
| onSuspendCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onTimeUpdate | ReactEventHandler<HTMLButtonElement> | — | — |
| onTimeUpdateCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onVolumeChange | ReactEventHandler<HTMLButtonElement> | — | — |
| onVolumeChangeCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onWaiting | ReactEventHandler<HTMLButtonElement> | — | — |
| onWaitingCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onAuxClick | MouseEventHandler<HTMLButtonElement> | — | — |
| onAuxClickCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onClick | MouseEventHandler<HTMLButtonElement> | — | — |
| onClickCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onContextMenu | MouseEventHandler<HTMLButtonElement> | — | — |
| onContextMenuCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onDoubleClick | MouseEventHandler<HTMLButtonElement> | — | — |
| onDoubleClickCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onDrag | DragEventHandler<HTMLButtonElement> | — | — |
| onDragCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragEnd | DragEventHandler<HTMLButtonElement> | — | — |
| onDragEndCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragEnter | DragEventHandler<HTMLButtonElement> | — | — |
| onDragEnterCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragExit | DragEventHandler<HTMLButtonElement> | — | — |
| onDragExitCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragLeave | DragEventHandler<HTMLButtonElement> | — | — |
| onDragLeaveCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragOver | DragEventHandler<HTMLButtonElement> | — | — |
| onDragOverCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDragStart | DragEventHandler<HTMLButtonElement> | — | — |
| onDragStartCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onDrop | DragEventHandler<HTMLButtonElement> | — | — |
| onDropCapture | DragEventHandler<HTMLButtonElement> | — | — |
| onMouseDown | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseDownCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseEnter | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseLeave | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseMove | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseMoveCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseOut | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseOutCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseOver | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseOverCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseUp | MouseEventHandler<HTMLButtonElement> | — | — |
| onMouseUpCapture | MouseEventHandler<HTMLButtonElement> | — | — |
| onSelect | ReactEventHandler<HTMLButtonElement> | — | — |
| onSelectCapture | ReactEventHandler<HTMLButtonElement> | — | — |
| onTouchCancel | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchCancelCapture | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchEnd | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchEndCapture | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchMove | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchMoveCapture | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchStart | TouchEventHandler<HTMLButtonElement> | — | — |
| onTouchStartCapture | TouchEventHandler<HTMLButtonElement> | — | — |
| onPointerDown | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerDownCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerMove | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerMoveCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerUp | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerUpCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerCancel | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerCancelCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerEnter | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerLeave | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerOver | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerOverCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerOut | PointerEventHandler<HTMLButtonElement> | — | — |
| onPointerOutCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onGotPointerCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onGotPointerCaptureCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onLostPointerCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onLostPointerCaptureCapture | PointerEventHandler<HTMLButtonElement> | — | — |
| onScroll | UIEventHandler<HTMLButtonElement> | — | — |
| onScrollCapture | UIEventHandler<HTMLButtonElement> | — | — |
| onScrollEnd | UIEventHandler<HTMLButtonElement> | — | — |
| onScrollEndCapture | UIEventHandler<HTMLButtonElement> | — | — |
| onWheel | WheelEventHandler<HTMLButtonElement> | — | — |
| onWheelCapture | WheelEventHandler<HTMLButtonElement> | — | — |
| onAnimationStart | AnimationEventHandler<HTMLButtonElement> | — | — |
| onAnimationStartCapture | AnimationEventHandler<HTMLButtonElement> | — | — |
| onAnimationEnd | AnimationEventHandler<HTMLButtonElement> | — | — |
| onAnimationEndCapture | AnimationEventHandler<HTMLButtonElement> | — | — |
| onAnimationIteration | AnimationEventHandler<HTMLButtonElement> | — | — |
| onAnimationIterationCapture | AnimationEventHandler<HTMLButtonElement> | — | — |
| onToggle | ToggleEventHandler<HTMLButtonElement> | — | — |
| onBeforeToggle | ToggleEventHandler<HTMLButtonElement> | — | — |
| onTransitionCancel | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionCancelCapture | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionEnd | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionEndCapture | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionRun | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionRunCapture | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionStart | TransitionEventHandler<HTMLButtonElement> | — | — |
| onTransitionStartCapture | TransitionEventHandler<HTMLButtonElement> | — | — |
| variant | "primary" | "outline" | "secondary" | "ghost" | "danger" | — | — |
| pinned | boolean | — | 常显胶囊展开态(不收回圆形) |
| trailing | React.ReactNode | — | 展开态文本后追加的节点(如下拉箭头) |
| iconClassName | string | — | 追加到图标的类(如 animate-spin) |
| ref | Ref<HTMLButtonElement> | — | Allows getting a ref to the component instance. |
源码
import * as React from "react";
import type { LucideIcon } from "lucide-react";
import { cn } from "@mox-hub/ui";
import { RawButton } from "@mox-hub/ui/components/raw/raw-button";
/**
* PageHeader / ToolbarRow 操作按钮:默认正圆形仅图标,hover / focus-visible 展开为胶囊
* (左侧圆形图标区 + 右侧文本)。展开是真实宽度变化,同组兄弟按钮自然位移。
* `pinned` 常显展开态(下拉按钮在菜单打开时、视图样式切换的常驻形态);
* `trailing` 在文本后追加节点(如 ChevronDown)。
*/
const headerActionButtonVariants = {
primary:
"bg-primary text-primary-foreground hover:bg-primary/90",
outline:
"border border-border bg-background text-foreground hover:bg-muted hover:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
secondary:
"bg-secondary text-secondary-foreground hover:bg-secondary/85",
ghost:
"text-muted-foreground hover:bg-muted hover:text-foreground",
danger:
"bg-destructive text-destructive-foreground hover:bg-destructive/90",
} as const;
export interface HeaderActionButtonProps
extends Omit<React.ComponentProps<"button">, "children"> {
icon: LucideIcon;
/** 展开时显示的文本,同时作为无障碍标签 */
label: string;
variant?: keyof typeof headerActionButtonVariants;
/** 常显胶囊展开态(不收回圆形) */
pinned?: boolean;
/** 展开态文本后追加的节点(如下拉箭头) */
trailing?: React.ReactNode;
/** 追加到图标的类(如 animate-spin) */
iconClassName?: string;
}
const HeaderActionButton = React.forwardRef<HTMLButtonElement, HeaderActionButtonProps>(
({ icon: Icon, label, variant = "primary", pinned = false, trailing, iconClassName, className, type = "button", ...props }, ref) => {
return (
<RawButton
ref={ref}
type={type}
aria-label={label}
data-slot="header-action-button"
data-pinned={pinned ? "true" : undefined}
className={cn(
"group/hab flex h-control-sm shrink-0 items-center overflow-hidden rounded-full p-0 text-xs font-medium whitespace-nowrap transition-[background-color,border-color,color,transform] [transition-duration:var(--motion-fast)] [transition-timing-function:var(--motion-ease-standard)] select-none outline-hidden focus-visible:ring-2 focus-visible:ring-ring/50 active:translate-y-px disabled:pointer-events-none disabled:opacity-50",
headerActionButtonVariants[variant],
className,
)}
{...props}
>
<span className="flex size-control-sm shrink-0 items-center justify-center">
<Icon className={cn("size-4", iconClassName)} strokeWidth={1.75} aria-hidden />
</span>
<span
className={cn(
"flex max-w-0 items-center overflow-hidden text-xs font-medium opacity-0 whitespace-nowrap transition-[max-width,padding,opacity] [transition-duration:var(--motion-normal)] [transition-timing-function:var(--motion-ease-standard)] group-hover/hab:max-w-48 group-hover/hab:py-0 group-hover/hab:ps-1 group-hover/hab:pe-3 group-hover/hab:opacity-100 group-focus-visible/hab:max-w-48 group-focus-visible/hab:py-0 group-focus-visible/hab:ps-1 group-focus-visible/hab:pe-3 group-focus-visible/hab:opacity-100",
pinned && "max-w-48 py-0 ps-1 pe-3 opacity-100",
)}
>
{label}
{trailing}
</span>
</RawButton>
);
},
);
HeaderActionButton.displayName = "HeaderActionButton";
export { HeaderActionButton, headerActionButtonVariants };
可访问性与 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。
用法说明
页面/工具栏操作钮:圆形仅图标,hover/focus 展开为胶囊;pinned 常显;label 同时作为无障碍名。