Ordo UI
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类型默认值说明
titlestring——
classNamestring——
icon*LucideIcon——
formstring——
label*string—展开时显示的文本,同时作为无障碍标签
slotstring——
styleCSSProperties——
keyKey——
disabledboolean——
formActionstring | ((formData: FormData) => void | Promise<void>)——
formEncTypestring——
formMethodstring——
formNoValidateboolean——
formTargetstring——
namestring——
type"button" | "submit" | "reset"——
valuestring | number | readonly string[]——
defaultCheckedboolean——
defaultValuestring | number | readonly string[]——
suppressContentEditableWarningboolean——
suppressHydrationWarningboolean——
accessKeystring——
autoCapitalize"off" | "none" | "on" | "sentences" | "words" | "characters" | (string & {})——
autoFocusboolean——
contentEditableBooleanish | "inherit" | "plaintext-only"——
contextMenustring——
dirstring——
draggableBooleanish——
enterKeyHint"search" | "enter" | "done" | "go" | "next" | "previous" | "send"——
hiddenboolean——
idstring——
langstring——
noncestring——
spellCheckBooleanish——
tabIndexnumber——
translate"yes" | "no"——
radioGroupstring——
roleAriaRole——
aboutstring——
contentstring——
datatypestring——
inlistany——
prefixstring——
propertystring——
relstring——
resourcestring——
revstring——
typeofstring——
vocabstring——
autoCorrectstring——
autoSavestring——
colorstring——
itemPropstring——
itemScopeboolean——
itemTypestring——
itemIDstring——
itemRefstring——
resultsnumber——
securitystring——
unselectable"off" | "on"——
popover"" | "auto" | "manual" | "hint"——
popoverTargetAction"toggle" | "show" | "hide"——
popoverTargetstring——
inertboolean——
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
isstring—Specify that a standard HTML element should behave like a defined custom built-in element
exportpartsstring——
partstring——
aria-activedescendantstring—Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
aria-atomicBooleanish—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-braillelabelstring—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-brailleroledescriptionstring—Defines a human-readable, author-localized abbreviated description for the role of an element, which is intended to be converted into Braille.
aria-busyBooleanish——
aria-checkedboolean | "true" | "false" | "mixed"—Indicates the current "checked" state of checkboxes, radio buttons, and other widgets.
aria-colcountnumber—Defines the total number of columns in a table, grid, or treegrid.
aria-colindexnumber—Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid.
aria-colindextextstring—Defines a human readable text alternative of aria-colindex.
aria-colspannumber—Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
aria-controlsstring—Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-currentboolean | "time" | "true" | "false" | "page" | "step" | "location" | "date"—Indicates the element that represents the current item within a container or set of related elements.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-descriptionstring—Defines a string value that describes or annotates the current element.
aria-detailsstring—Identifies the element that provides a detailed, extended description for the object.
aria-disabledBooleanish—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-errormessagestring—Identifies the element that provides an error message for the object.
aria-expandedBooleanish—Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-flowtostring—Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion,
aria-grabbedBooleanish—Indicates an element's "grabbed" state in a drag-and-drop operation.
aria-haspopupboolean | "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-hiddenBooleanish—Indicates whether the element is exposed to an accessibility API.
aria-invalidboolean | "true" | "false" | "grammar" | "spelling"—Indicates the entered value does not conform to the format expected by the application.
aria-keyshortcutsstring—Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-levelnumber—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-modalBooleanish—Indicates whether an element is modal when displayed.
aria-multilineBooleanish—Indicates whether a text box accepts multiple lines of input or only a single line.
aria-multiselectableBooleanish—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-ownsstring—Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship
aria-placeholderstring—Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value.
aria-posinsetnumber—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-pressedboolean | "true" | "false" | "mixed"—Indicates the current "pressed" state of toggle buttons.
aria-readonlyBooleanish—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-requiredBooleanish—Indicates that user input is required on the element before a form may be submitted.
aria-roledescriptionstring—Defines a human-readable, author-localized description for the role of an element.
aria-rowcountnumber—Defines the total number of rows in a table, grid, or treegrid.
aria-rowindexnumber—Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid.
aria-rowindextextstring—Defines a human readable text alternative of aria-rowindex.
aria-rowspannumber—Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
aria-selectedBooleanish—Indicates the current "selected" state of various widgets.
aria-setsizenumber—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-valuemaxnumber—Defines the maximum allowed value for a range widget.
aria-valueminnumber—Defines the minimum allowed value for a range widget.
aria-valuenownumber—Defines the current value for a range widget.
aria-valuetextstring—Defines the human readable text alternative of aria-valuenow for a range widget.
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }——
onCopyClipboardEventHandler<HTMLButtonElement>——
onCopyCaptureClipboardEventHandler<HTMLButtonElement>——
onCutClipboardEventHandler<HTMLButtonElement>——
onCutCaptureClipboardEventHandler<HTMLButtonElement>——
onPasteClipboardEventHandler<HTMLButtonElement>——
onPasteCaptureClipboardEventHandler<HTMLButtonElement>——
onCompositionEndCompositionEventHandler<HTMLButtonElement>——
onCompositionEndCaptureCompositionEventHandler<HTMLButtonElement>——
onCompositionStartCompositionEventHandler<HTMLButtonElement>——
onCompositionStartCaptureCompositionEventHandler<HTMLButtonElement>——
onCompositionUpdateCompositionEventHandler<HTMLButtonElement>——
onCompositionUpdateCaptureCompositionEventHandler<HTMLButtonElement>——
onFocusFocusEventHandler<HTMLButtonElement>——
onFocusCaptureFocusEventHandler<HTMLButtonElement>——
onBlurFocusEventHandler<HTMLButtonElement>——
onBlurCaptureFocusEventHandler<HTMLButtonElement>——
onChangeChangeEventHandler<HTMLButtonElement, Element>——
onChangeCaptureChangeEventHandler<HTMLButtonElement, Element>——
onBeforeInputInputEventHandler<HTMLButtonElement>——
onBeforeInputCaptureInputEventHandler<HTMLButtonElement>——
onInputInputEventHandler<HTMLButtonElement>——
onInputCaptureInputEventHandler<HTMLButtonElement>——
onResetReactEventHandler<HTMLButtonElement>——
onResetCaptureReactEventHandler<HTMLButtonElement>——
onSubmitSubmitEventHandler<HTMLButtonElement>——
onSubmitCaptureSubmitEventHandler<HTMLButtonElement>——
onInvalidReactEventHandler<HTMLButtonElement>——
onInvalidCaptureReactEventHandler<HTMLButtonElement>——
onLoadReactEventHandler<HTMLButtonElement>——
onLoadCaptureReactEventHandler<HTMLButtonElement>——
onErrorReactEventHandler<HTMLButtonElement>——
onErrorCaptureReactEventHandler<HTMLButtonElement>——
onKeyDownKeyboardEventHandler<HTMLButtonElement>——
onKeyDownCaptureKeyboardEventHandler<HTMLButtonElement>——
onKeyPressKeyboardEventHandler<HTMLButtonElement>——
onKeyPressCaptureKeyboardEventHandler<HTMLButtonElement>——
onKeyUpKeyboardEventHandler<HTMLButtonElement>——
onKeyUpCaptureKeyboardEventHandler<HTMLButtonElement>——
onAbortReactEventHandler<HTMLButtonElement>——
onAbortCaptureReactEventHandler<HTMLButtonElement>——
onCanPlayReactEventHandler<HTMLButtonElement>——
onCanPlayCaptureReactEventHandler<HTMLButtonElement>——
onCanPlayThroughReactEventHandler<HTMLButtonElement>——
onCanPlayThroughCaptureReactEventHandler<HTMLButtonElement>——
onDurationChangeReactEventHandler<HTMLButtonElement>——
onDurationChangeCaptureReactEventHandler<HTMLButtonElement>——
onEmptiedReactEventHandler<HTMLButtonElement>——
onEmptiedCaptureReactEventHandler<HTMLButtonElement>——
onEncryptedReactEventHandler<HTMLButtonElement>——
onEncryptedCaptureReactEventHandler<HTMLButtonElement>——
onEndedReactEventHandler<HTMLButtonElement>——
onEndedCaptureReactEventHandler<HTMLButtonElement>——
onLoadedDataReactEventHandler<HTMLButtonElement>——
onLoadedDataCaptureReactEventHandler<HTMLButtonElement>——
onLoadedMetadataReactEventHandler<HTMLButtonElement>——
onLoadedMetadataCaptureReactEventHandler<HTMLButtonElement>——
onLoadStartReactEventHandler<HTMLButtonElement>——
onLoadStartCaptureReactEventHandler<HTMLButtonElement>——
onPauseReactEventHandler<HTMLButtonElement>——
onPauseCaptureReactEventHandler<HTMLButtonElement>——
onPlayReactEventHandler<HTMLButtonElement>——
onPlayCaptureReactEventHandler<HTMLButtonElement>——
onPlayingReactEventHandler<HTMLButtonElement>——
onPlayingCaptureReactEventHandler<HTMLButtonElement>——
onProgressReactEventHandler<HTMLButtonElement>——
onProgressCaptureReactEventHandler<HTMLButtonElement>——
onRateChangeReactEventHandler<HTMLButtonElement>——
onRateChangeCaptureReactEventHandler<HTMLButtonElement>——
onSeekedReactEventHandler<HTMLButtonElement>——
onSeekedCaptureReactEventHandler<HTMLButtonElement>——
onSeekingReactEventHandler<HTMLButtonElement>——
onSeekingCaptureReactEventHandler<HTMLButtonElement>——
onStalledReactEventHandler<HTMLButtonElement>——
onStalledCaptureReactEventHandler<HTMLButtonElement>——
onSuspendReactEventHandler<HTMLButtonElement>——
onSuspendCaptureReactEventHandler<HTMLButtonElement>——
onTimeUpdateReactEventHandler<HTMLButtonElement>——
onTimeUpdateCaptureReactEventHandler<HTMLButtonElement>——
onVolumeChangeReactEventHandler<HTMLButtonElement>——
onVolumeChangeCaptureReactEventHandler<HTMLButtonElement>——
onWaitingReactEventHandler<HTMLButtonElement>——
onWaitingCaptureReactEventHandler<HTMLButtonElement>——
onAuxClickMouseEventHandler<HTMLButtonElement>——
onAuxClickCaptureMouseEventHandler<HTMLButtonElement>——
onClickMouseEventHandler<HTMLButtonElement>——
onClickCaptureMouseEventHandler<HTMLButtonElement>——
onContextMenuMouseEventHandler<HTMLButtonElement>——
onContextMenuCaptureMouseEventHandler<HTMLButtonElement>——
onDoubleClickMouseEventHandler<HTMLButtonElement>——
onDoubleClickCaptureMouseEventHandler<HTMLButtonElement>——
onDragDragEventHandler<HTMLButtonElement>——
onDragCaptureDragEventHandler<HTMLButtonElement>——
onDragEndDragEventHandler<HTMLButtonElement>——
onDragEndCaptureDragEventHandler<HTMLButtonElement>——
onDragEnterDragEventHandler<HTMLButtonElement>——
onDragEnterCaptureDragEventHandler<HTMLButtonElement>——
onDragExitDragEventHandler<HTMLButtonElement>——
onDragExitCaptureDragEventHandler<HTMLButtonElement>——
onDragLeaveDragEventHandler<HTMLButtonElement>——
onDragLeaveCaptureDragEventHandler<HTMLButtonElement>——
onDragOverDragEventHandler<HTMLButtonElement>——
onDragOverCaptureDragEventHandler<HTMLButtonElement>——
onDragStartDragEventHandler<HTMLButtonElement>——
onDragStartCaptureDragEventHandler<HTMLButtonElement>——
onDropDragEventHandler<HTMLButtonElement>——
onDropCaptureDragEventHandler<HTMLButtonElement>——
onMouseDownMouseEventHandler<HTMLButtonElement>——
onMouseDownCaptureMouseEventHandler<HTMLButtonElement>——
onMouseEnterMouseEventHandler<HTMLButtonElement>——
onMouseLeaveMouseEventHandler<HTMLButtonElement>——
onMouseMoveMouseEventHandler<HTMLButtonElement>——
onMouseMoveCaptureMouseEventHandler<HTMLButtonElement>——
onMouseOutMouseEventHandler<HTMLButtonElement>——
onMouseOutCaptureMouseEventHandler<HTMLButtonElement>——
onMouseOverMouseEventHandler<HTMLButtonElement>——
onMouseOverCaptureMouseEventHandler<HTMLButtonElement>——
onMouseUpMouseEventHandler<HTMLButtonElement>——
onMouseUpCaptureMouseEventHandler<HTMLButtonElement>——
onSelectReactEventHandler<HTMLButtonElement>——
onSelectCaptureReactEventHandler<HTMLButtonElement>——
onTouchCancelTouchEventHandler<HTMLButtonElement>——
onTouchCancelCaptureTouchEventHandler<HTMLButtonElement>——
onTouchEndTouchEventHandler<HTMLButtonElement>——
onTouchEndCaptureTouchEventHandler<HTMLButtonElement>——
onTouchMoveTouchEventHandler<HTMLButtonElement>——
onTouchMoveCaptureTouchEventHandler<HTMLButtonElement>——
onTouchStartTouchEventHandler<HTMLButtonElement>——
onTouchStartCaptureTouchEventHandler<HTMLButtonElement>——
onPointerDownPointerEventHandler<HTMLButtonElement>——
onPointerDownCapturePointerEventHandler<HTMLButtonElement>——
onPointerMovePointerEventHandler<HTMLButtonElement>——
onPointerMoveCapturePointerEventHandler<HTMLButtonElement>——
onPointerUpPointerEventHandler<HTMLButtonElement>——
onPointerUpCapturePointerEventHandler<HTMLButtonElement>——
onPointerCancelPointerEventHandler<HTMLButtonElement>——
onPointerCancelCapturePointerEventHandler<HTMLButtonElement>——
onPointerEnterPointerEventHandler<HTMLButtonElement>——
onPointerLeavePointerEventHandler<HTMLButtonElement>——
onPointerOverPointerEventHandler<HTMLButtonElement>——
onPointerOverCapturePointerEventHandler<HTMLButtonElement>——
onPointerOutPointerEventHandler<HTMLButtonElement>——
onPointerOutCapturePointerEventHandler<HTMLButtonElement>——
onGotPointerCapturePointerEventHandler<HTMLButtonElement>——
onGotPointerCaptureCapturePointerEventHandler<HTMLButtonElement>——
onLostPointerCapturePointerEventHandler<HTMLButtonElement>——
onLostPointerCaptureCapturePointerEventHandler<HTMLButtonElement>——
onScrollUIEventHandler<HTMLButtonElement>——
onScrollCaptureUIEventHandler<HTMLButtonElement>——
onScrollEndUIEventHandler<HTMLButtonElement>——
onScrollEndCaptureUIEventHandler<HTMLButtonElement>——
onWheelWheelEventHandler<HTMLButtonElement>——
onWheelCaptureWheelEventHandler<HTMLButtonElement>——
onAnimationStartAnimationEventHandler<HTMLButtonElement>——
onAnimationStartCaptureAnimationEventHandler<HTMLButtonElement>——
onAnimationEndAnimationEventHandler<HTMLButtonElement>——
onAnimationEndCaptureAnimationEventHandler<HTMLButtonElement>——
onAnimationIterationAnimationEventHandler<HTMLButtonElement>——
onAnimationIterationCaptureAnimationEventHandler<HTMLButtonElement>——
onToggleToggleEventHandler<HTMLButtonElement>——
onBeforeToggleToggleEventHandler<HTMLButtonElement>——
onTransitionCancelTransitionEventHandler<HTMLButtonElement>——
onTransitionCancelCaptureTransitionEventHandler<HTMLButtonElement>——
onTransitionEndTransitionEventHandler<HTMLButtonElement>——
onTransitionEndCaptureTransitionEventHandler<HTMLButtonElement>——
onTransitionRunTransitionEventHandler<HTMLButtonElement>——
onTransitionRunCaptureTransitionEventHandler<HTMLButtonElement>——
onTransitionStartTransitionEventHandler<HTMLButtonElement>——
onTransitionStartCaptureTransitionEventHandler<HTMLButtonElement>——
variant"primary" | "outline" | "secondary" | "ghost" | "danger"——
pinnedboolean—常显胶囊展开态(不收回圆形)
trailingReact.ReactNode—展开态文本后追加的节点(如下拉箭头)
iconClassNamestring—追加到图标的类(如 animate-spin)
refRef<HTMLButtonElement>—Allows getting a ref to the component instance.

源码

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

用法说明

页面/工具栏操作钮:圆形仅图标,hover/focus 展开为胶囊;pinned 常显;label 同时作为无障碍名。