组件Navigation
Command
@mox-hub/ui 组件 · Navigation · canonical
command@mox-hub/uiNavigationcanonicalsrc/components/command.tsx变体演示command
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| autoHighlight* | boolean | "always" | "always" | — |
| keepHighlight* | boolean | true | — |
源码
"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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
命令面板,由 Command、Input、List、Group、Item、Empty 组合;常配 Dialog 做 Ctrl+K 搜索。