Ordo UI
组件Navigation

Command

@mox-hub/ui 组件 · Navigation · canonical

command@mox-hub/uiNavigationcanonicalsrc/components/command.tsx
变体演示command
↑↓ 选择↵ 确认

Props API

Prop类型默认值说明
autoHighlight*boolean | "always""always"—
keepHighlight*booleantrue—

源码

packages/ui/src/components/command.tsx
"use client"

import { Dialog as CommandDialogPrimitive } from "@base-ui/react/dialog"
import { SearchIcon } from "lucide-react"
import type * as React from "react"
import { useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Kbd, KbdGroup } from "./kbd"
import { SURFACE_MENU_CLASS, menuItemVariants } from "./menu-styles"
import {
  Autocomplete,
  AutocompleteCollection,
  AutocompleteEmpty,
  AutocompleteGroup,
  AutocompleteGroupLabel,
  AutocompleteInput,
  AutocompleteItem,
  AutocompleteList,
  AutocompleteSeparator,
} from "./autocomplete"

/*
 * coss ui Command(registry @coss/command,p-command/p-command-2 的原语层)
 * 引擎 = base-ui Autocomplete(过滤/分组/键盘导航/高亮全内置),壳 = base-ui Dialog。
 * 适配:import 路径改本仓别名(utils / autocomplete,本仓 autocomplete 已是 @coss/autocomplete 移植),
 * 其余与上游 registry 条目保持逐行同构,便于后续 re-sync。
 * 旧 cmdk 实现已废弃移除(cmdk 依赖随之退场)。
 */

export const CommandDialog: typeof CommandDialogPrimitive.Root =
  CommandDialogPrimitive.Root

export const CommandDialogPortal: typeof CommandDialogPrimitive.Portal =
  CommandDialogPrimitive.Portal

export const CommandCreateHandle: typeof CommandDialogPrimitive.createHandle =
  CommandDialogPrimitive.createHandle

export function CommandDialogTrigger(
  props: CommandDialogPrimitive.Trigger.Props
): React.ReactElement {
  return (
    <CommandDialogPrimitive.Trigger
      data-slot="command-dialog-trigger"
      {...props}
    />
  )
}

export function CommandDialogBackdrop({
  className,
  ...props
}: CommandDialogPrimitive.Backdrop.Props): React.ReactElement {
  return (
    <CommandDialogPrimitive.Backdrop
      className={cn(
        "fixed inset-0 z-modal bg-scrim-overlay supports-backdrop-filter:backdrop-blur-sm transition-opacity duration-normal data-ending-style:opacity-0 data-starting-style:opacity-0",
        className
      )}
      data-slot="command-dialog-backdrop"
      {...props}
    />
  )
}

export function CommandDialogViewport({
  className,
  ...props
}: CommandDialogPrimitive.Viewport.Props): React.ReactElement {
  return (
    <CommandDialogPrimitive.Viewport
      className={cn(
        "fixed inset-0 z-modal flex flex-col items-center px-4 py-[max(--spacing(4),4vh)] sm:py-[10vh]",
        className
      )}
      data-slot="command-dialog-viewport"
      {...props}
    />
  )
}

export function CommandDialogPopup({
  className,
  children,
  portalProps,
  ...props
}: CommandDialogPrimitive.Popup.Props & {
  portalProps?: CommandDialogPrimitive.Portal.Props
}): React.ReactElement {
  const M = useMessages()
  return (
    <CommandDialogPortal {...portalProps}>
      <CommandDialogBackdrop />
      <CommandDialogViewport>
        <CommandDialogPrimitive.Popup
          className={cn(
            // overflow-hidden:头部条/内容板裁进弹层圆角——否则方角色块顶出圆角形成「上角小角」
            "relative flex max-h-[min(26.25rem,85vh)] min-h-0 w-full min-w-0 max-w-xl -translate-y-[calc(1.25rem*var(--nested-dialogs))] scale-[calc(1-0.1*var(--nested-dialogs))] flex-col overflow-hidden not-dark:bg-clip-padding opacity-[calc(1-0.1*var(--nested-dialogs))] outline-none transition-[scale,opacity,translate] duration-normal ease-in-out will-change-transform before:pointer-events-none before:absolute before:inset-0 before:rounded-inset-menu before:bg-muted/72 before:shadow-[0_1px_--theme(--color-black/4%)] data-nested:data-ending-style:translate-y-8 data-nested:data-starting-style:translate-y-8 data-nested-dialog-open:origin-top data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0 **:data-[slot=scroll-area-viewport]:data-has-overflow-y:pe-1 dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
            SURFACE_MENU_CLASS,
            className
          )}
          data-slot="command-dialog-popup"
          aria-label={M.command.label}
          {...props}
        >
          {children}
        </CommandDialogPrimitive.Popup>
      </CommandDialogViewport>
    </CommandDialogPortal>
  )
}

export function Command({
  autoHighlight = "always",
  keepHighlight = true,
  ...props
}: React.ComponentProps<typeof Autocomplete>): React.ReactElement {
  return (
    <Autocomplete
      autoHighlight={autoHighlight}
      inline
      keepHighlight={keepHighlight}
      open
      {...props}
    />
  )
}

export function CommandInput({
  className,
  placeholder = undefined,
  ...props
}: React.ComponentProps<typeof AutocompleteInput>): React.ReactElement {
  return (
    <div className="bg-muted/50 px-2.5 py-1.5">
      <AutocompleteInput
        autoFocus
        className={cn(
          // 聚焦不加粗不描边(coss p-command 观感),但保留可见焦点指示:
          // 删除原先的 `!important` 压制,避免盖掉高对比度/强制色下的 3px outline(审计 P1-07)。
          "border-transparent bg-transparent shadow-none outline-none before:hidden focus-visible:border-transparent focus-visible:shadow-none focus-visible:ring-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring transition-none",
          className
        )}
        placeholder={placeholder}
        size="lg"
        startAddon={<SearchIcon />}
        {...props}
      />
    </div>
  )
}

export function CommandList({
  className,
  scrollAreaClassName,
  ...props
}: React.ComponentProps<typeof AutocompleteList> & {
  scrollAreaClassName?: string
}): React.ReactElement {
  return (
    <AutocompleteList
      className={cn("not-empty:scroll-py-2 not-empty:p-2", className)}
      data-slot="command-list"
      scrollAreaClassName={scrollAreaClassName}
      {...props}
    />
  )
}

export function CommandEmpty({
  className,
  ...props
}: React.ComponentProps<typeof AutocompleteEmpty>): React.ReactElement {
  return (
    <AutocompleteEmpty
      className={cn("not-empty:py-6", className)}
      data-slot="command-empty"
      {...props}
    />
  )
}

export function CommandPanel({
  className,
  ...props
}: React.ComponentProps<"div">): React.ReactElement {
  return (
    <div
      className={cn(
        "relative -mx-px not-has-[+[data-slot=command-footer]]:-mb-px min-h-0 rounded-t-(--surface-menu-radius) not-has-[+[data-slot=command-footer]]:rounded-b-(--surface-menu-radius) border border-b-0 border-(--surface-menu-border) bg-(--surface-menu-bg) bg-clip-padding shadow-xs/5 [clip-path:inset(0_1px)] not-has-[+[data-slot=command-footer]]:[clip-path:inset(0_1px_1px_1px_round_0_0_calc(var(--surface-menu-radius)-1px)_calc(var(--surface-menu-radius)-1px))] before:pointer-events-none before:absolute before:inset-0 before:rounded-t-inset-menu **:data-[slot=scroll-area-scrollbar]:mt-2",
        className
      )}
      {...props}
    />
  )
}

export function CommandGroup({
  className,
  ...props
}: React.ComponentProps<typeof AutocompleteGroup>): React.ReactElement {
  return (
    <AutocompleteGroup
      className={className}
      data-slot="command-group"
      {...props}
    />
  )
}

export function CommandGroupLabel({
  className,
  ...props
}: React.ComponentProps<typeof AutocompleteGroupLabel>): React.ReactElement {
  return (
    <AutocompleteGroupLabel
      className={cn(
        "px-3 py-1.5 text-xs font-semibold tracking-wide text-muted-foreground",
        className
      )}
      data-slot="command-group-label"
      {...props}
    />
  )
}

export const CommandCollection = AutocompleteCollection

export function CommandItem({
  className,
  ...props
}: React.ComponentProps<typeof AutocompleteItem>): React.ReactElement {
  return (
    <AutocompleteItem
      className={cn(menuItemVariants(), "gap-3 px-3", className)}
      data-slot="command-item"
      {...props}
    />
  )
}

export function CommandSeparator({
  className,
  ...props
}: React.ComponentProps<typeof AutocompleteSeparator>): React.ReactElement {
  return (
    <AutocompleteSeparator
      className={cn("my-2", className)}
      data-slot="command-separator"
      {...props}
    />
  )
}

export function CommandShortcut({
  className,
  children,
  ...props
}: React.ComponentProps<"kbd">): React.ReactElement {
  // 快捷键一律走系统 Kbd 标准件(槽位 API 保持 CommandShortcut 不变,视觉收敛到 kbd 基线)。
  // 组合键按空格拆为多枚 Kbd("Alt A" = Alt、A 两枚物理键;formatComboForDisplay 产出即空格分隔),
  // 单键保持单 Kbd。
  const parts =
    typeof children === "string" ? children.trim().split(/\s+/) : []
  if (parts.length > 1) {
    return (
      <KbdGroup className={cn("ms-auto", className)} data-slot="command-shortcut">
        {parts.map((part) => (
          <Kbd key={part}>{part}</Kbd>
        ))}
      </KbdGroup>
    )
  }
  return (
    <Kbd
      className={cn("ms-auto", className)}
      data-slot="command-shortcut"
      {...props}
    >
      {children}
    </Kbd>
  )
}

export function CommandFooter({
  className,
  ...props
}: React.ComponentProps<"div">): React.ReactElement {
  return (
    <div
      className={cn(
        "flex items-center justify-between gap-2 rounded-b-inset-menu border-t bg-muted/50 px-4 py-1.5 text-muted-foreground text-xs",
        className
      )}
      data-slot="command-footer"
      {...props}
    />
  )
}

export { CommandDialogPrimitive }

可访问性与 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。

用法说明

命令面板,由 Command、Input、List、Group、Item、Empty 组合;常配 Dialog 做 Ctrl+K 搜索。