组件Layout & Shells
Sidebar
@mox-hub/ui 组件 · Layout & Shells · canonical
sidebar@mox-hub/uiLayout & Shellscanonicalsrc/components/sidebar.tsx变体轴
sidestartend逻辑方向,RTL 下自动镜像
variantsidebarfloatinginset
collapsibleoffcanvasiconnone
变体演示sidebar
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| className* | string | — | — |
| children* | ReactNode | — | — |
源码
"use client"
import * as React from "react"
import { Button as ButtonPrimitive } from "@base-ui/react/button"
import { cva, type VariantProps } from "class-variance-authority"
import { PanelLeftIcon } from "lucide-react"
import { useDirection, useMessages } from "../i18n"
import { cn } from "../lib/utils"
import { Button } from "./button"
import { Input } from "./input"
import { Separator } from "./separator"
import {
Sheet,
SheetContent,
SheetDescription,
SheetHeader,
SheetTitle,
} from "./sheet"
import { Skeleton } from "./skeleton"
import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip"
const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 365
const SIDEBAR_MOBILE_BREAKPOINT = 768
type SidebarSide = "start" | "end"
type SidebarVariant = "sidebar" | "floating" | "inset"
type SidebarCollapsible = "offcanvas" | "icon" | "none"
type SidebarPersistence = "local" | "cookie" | false
interface SidebarContextValue {
state: "expanded" | "collapsed"
open: boolean
setOpen: (open: boolean) => void
openMobile: boolean
setOpenMobile: React.Dispatch<React.SetStateAction<boolean>>
isMobile: boolean
toggleSidebar: () => void
side: SidebarSide
variant: SidebarVariant
collapsible: SidebarCollapsible
sidebarId: string
}
const SidebarContext = React.createContext<SidebarContextValue | null>(null)
function useSidebar() {
const context = React.useContext(SidebarContext)
if (!context) {
throw new Error("useSidebar must be used within a SidebarProvider.")
}
return context
}
function useIsMobile() {
const [isMobile, setIsMobile] = React.useState(false)
React.useEffect(() => {
if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
return
}
const query = window.matchMedia(
`(max-width: ${SIDEBAR_MOBILE_BREAKPOINT - 1}px)`
)
const onChange = () => setIsMobile(query.matches)
onChange()
if (typeof query.addEventListener === "function") {
query.addEventListener("change", onChange)
return () => query.removeEventListener("change", onChange)
}
// Safari < 14 / jsdom 的旧 matchMedia 实现
query.addListener(onChange)
return () => query.removeListener(onChange)
}, [])
return isMobile
}
function readPersisted(
key: string,
persistence: Exclude<SidebarPersistence, false>
): boolean | null {
try {
if (persistence === "local") {
const value = window.localStorage.getItem(key)
return value === null ? null : value === "true"
}
const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
const match = document.cookie.match(
new RegExp(`(?:^|; )${escaped}=([^;]*)`)
)
return match ? match[1] === "true" : null
} catch {
return null
}
}
function writePersisted(
key: string,
persistence: Exclude<SidebarPersistence, false>,
open: boolean
) {
try {
if (persistence === "local") {
window.localStorage.setItem(key, String(open))
return
}
document.cookie = `${key}=${open}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}; samesite=lax`
} catch {
// 隐私模式 / 禁 cookie 时静默降级为会话内状态
}
}
interface SidebarProviderProps extends React.ComponentProps<"div"> {
defaultOpen?: boolean
open?: boolean
onOpenChange?: (open: boolean) => void
side?: SidebarSide
variant?: SidebarVariant
collapsible?: SidebarCollapsible
/** 展开宽度;number 按 px 处理。 */
width?: string | number
/** 折叠为图标轨时的宽度;number 按 px 处理。 */
widthIcon?: string | number
persistence?: SidebarPersistence
storageKey?: string
/** 是否启用 Ctrl/Cmd+B 切换。 */
keyboardShortcut?: boolean
}
function SidebarProvider({
defaultOpen = true,
open: openProp,
onOpenChange,
side = "start",
variant = "sidebar",
collapsible = "offcanvas",
width = "16rem",
widthIcon = "3rem",
persistence = "local",
storageKey = "ordo-sidebar",
keyboardShortcut = true,
className,
style,
children,
...props
}: SidebarProviderProps) {
const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen)
const [openMobile, setOpenMobile] = React.useState(false)
const [hydrated, setHydrated] = React.useState(false)
const isMobile = useIsMobile()
const sidebarId = React.useId()
const controlled = openProp !== undefined
const open = controlled ? openProp : uncontrolledOpen
const setOpen = React.useCallback(
(next: boolean) => {
if (!controlled) setUncontrolledOpen(next)
onOpenChange?.(next)
},
[controlled, onOpenChange]
)
const toggleSidebar = React.useCallback(() => {
if (isMobile) {
setOpenMobile((value) => !value)
return
}
setOpen(!open)
}, [isMobile, open, setOpen])
React.useEffect(() => {
if (persistence === false) {
setHydrated(true)
return
}
const stored = readPersisted(storageKey, persistence)
if (stored !== null && !controlled) setUncontrolledOpen(stored)
setHydrated(true)
}, [controlled, persistence, storageKey])
React.useEffect(() => {
if (!hydrated || persistence === false || controlled) return
writePersisted(storageKey, persistence, open)
}, [controlled, hydrated, open, persistence, storageKey])
React.useEffect(() => {
if (!keyboardShortcut) return
const onKeyDown = (event: KeyboardEvent) => {
if (
event.defaultPrevented ||
event.repeat ||
event.key.toLowerCase() !== "b" ||
!(event.metaKey || event.ctrlKey)
) {
return
}
const target = event.target as HTMLElement | null
if (
target?.isContentEditable ||
target?.tagName === "INPUT" ||
target?.tagName === "TEXTAREA" ||
target?.tagName === "SELECT"
) {
return
}
event.preventDefault()
toggleSidebar()
}
window.addEventListener("keydown", onKeyDown)
return () => window.removeEventListener("keydown", onKeyDown)
}, [keyboardShortcut, toggleSidebar])
const context = React.useMemo<SidebarContextValue>(
() => ({
state:
collapsible === "none" ? "expanded" : open ? "expanded" : "collapsed",
open,
setOpen,
openMobile,
setOpenMobile,
isMobile,
toggleSidebar,
side,
variant,
collapsible,
sidebarId,
}),
[
open,
setOpen,
openMobile,
isMobile,
toggleSidebar,
side,
variant,
collapsible,
sidebarId,
]
)
const widthValue = typeof width === "number" ? `${width}px` : width
const widthIconValue =
typeof widthIcon === "number" ? `${widthIcon}px` : widthIcon
return (
<SidebarContext.Provider value={context}>
<div
data-slot="sidebar-wrapper"
data-state={
collapsible === "none" ? "expanded" : open ? "expanded" : "collapsed"
}
data-side={side}
data-variant={variant}
className={cn(
// 视口高度约束(审计 P1-13):默认钉住一屏,侧栏内容区自行滚动;
// 嵌入型 demo / 小窗可用 className 的 h-* 覆写。
"group/sidebar-wrapper flex h-svh max-h-svh min-h-0 w-full overflow-hidden data-[variant=inset]:bg-sidebar",
className
)}
style={
{
"--sidebar-width": widthValue,
"--sidebar-width-icon": widthIconValue,
...style,
} as React.CSSProperties
}
{...props}
>
{children}
</div>
</SidebarContext.Provider>
)
}
interface SidebarProps extends React.ComponentProps<"div"> {
/**
* 不属于 `Sidebar`:折叠模式统一在 `<SidebarProvider collapsible=…>` 配置。
* 传在 Sidebar 上会被忽略,开发环境会打印告警。
*/
collapsible?: never
/** 不属于 `Sidebar`:在 `<SidebarProvider variant=…>` 配置。 */
variant?: never
/** 不属于 `Sidebar`:在 `<SidebarProvider side=…>` 配置。 */
side?: never
}
function Sidebar({ className, children, ...props }: SidebarProps) {
const {
isMobile,
openMobile,
setOpenMobile,
state,
side,
variant,
collapsible,
sidebarId,
} = useSidebar()
const M = useMessages()
const direction = useDirection()
if (process.env.NODE_ENV !== "production") {
const misplaced = ["collapsible", "variant", "side"].filter((key) =>
Object.prototype.hasOwnProperty.call(props, key)
)
if (misplaced.length > 0) {
console.warn(
`[Sidebar] Ignoring ${misplaced.join(
", "
)}: these belong to <SidebarProvider>. Move them to <SidebarProvider collapsible=… variant=… side=…>.`
)
}
}
if (isMobile) {
const physicalSide =
side === "start"
? direction === "rtl"
? "right"
: "left"
: direction === "rtl"
? "left"
: "right"
return (
<Sheet open={openMobile} onOpenChange={setOpenMobile}>
<SheetContent
data-sidebar="sidebar"
data-mobile="true"
side={physicalSide}
showCloseButton={false}
className="w-[var(--sidebar-width)] max-w-[calc(100vw-2rem)] bg-sidebar p-0 text-sidebar-foreground"
>
<SheetHeader className="sr-only">
<SheetTitle>{M.sidebar.label}</SheetTitle>
<SheetDescription>{M.sidebar.description}</SheetDescription>
</SheetHeader>
<div
id={sidebarId}
role="navigation"
aria-label={M.sidebar.label}
className="flex h-full w-full flex-col"
>
{children}
</div>
</SheetContent>
</Sheet>
)
}
const isFloating = variant === "floating" || variant === "inset"
const expandedWidth = isFloating
? "w-[calc(var(--sidebar-width)+var(--spacing-4))]"
: "w-[var(--sidebar-width)]"
const iconWidth = isFloating
? "w-[calc(var(--sidebar-width-icon)+var(--spacing-4))]"
: "w-[var(--sidebar-width-icon)]"
const widthClass =
state === "collapsed"
? collapsible === "offcanvas"
? "w-0 border-0 p-0"
: collapsible === "icon"
? iconWidth
: expandedWidth
: expandedWidth
const innerWidth =
state === "collapsed" && collapsible === "icon"
? "w-[var(--sidebar-width-icon)]"
: "w-[var(--sidebar-width)]"
return (
<div
data-slot="sidebar"
data-state={state}
data-collapsible={state === "collapsed" ? collapsible : undefined}
data-variant={variant}
data-side={side}
className={cn(
"group peer sticky top-0 hidden h-full max-h-full min-h-0 shrink-0 flex-col text-sidebar-foreground transition-[width] duration-slow ease-standard md:flex",
"data-[collapsible=offcanvas]:overflow-hidden",
isFloating ? "bg-transparent p-2" : "bg-sidebar",
!isFloating && (side === "start" ? "border-e" : "border-s"),
!isFloating && "border-sidebar-border",
widthClass,
className
)}
{...props}
>
<div
id={sidebarId}
data-sidebar="sidebar"
role="navigation"
aria-label={M.sidebar.label}
className={cn(
"flex h-full w-full flex-col overflow-hidden bg-sidebar transition-[width] duration-slow ease-standard",
innerWidth,
isFloating && "rounded-lg border border-sidebar-border shadow-xs"
)}
>
{children}
</div>
</div>
)
}
function SidebarTrigger({
className,
onClick,
...props
}: React.ComponentProps<typeof Button>) {
const { toggleSidebar, state, isMobile, openMobile, sidebarId } = useSidebar()
const M = useMessages()
const expanded = isMobile ? openMobile : state === "expanded"
return (
<Button
data-slot="sidebar-trigger"
data-sidebar="trigger"
variant="ghost"
size="icon-2sm"
className={cn("pointer-coarse:size-11", className)}
aria-label={M.sidebar.toggle}
aria-expanded={expanded}
aria-controls={isMobile && !openMobile ? undefined : sidebarId}
onClick={(event) => {
onClick?.(event)
toggleSidebar()
}}
{...props}
>
<PanelLeftIcon className="rtl:-scale-x-100" />
<span className="sr-only">{M.sidebar.toggle}</span>
</Button>
)
}
function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
const { toggleSidebar, side, collapsible, state } = useSidebar()
const M = useMessages()
const direction = useDirection()
if (collapsible === "none") return null
// rail 挂在 -end-4 / -start-4 上,中心对齐需要向容器内平移半宽;
// 平移方向由「side 与书写方向是否同向」决定,不是恒定 -translate-x-1/2。
const railTranslate =
(side === "start") === (direction === "rtl")
? "translate-x-1/2"
: "-translate-x-1/2"
return (
<button
data-slot="sidebar-rail"
data-sidebar="rail"
type="button"
tabIndex={-1}
aria-hidden="true"
title={state === "expanded" ? M.sidebar.collapse : M.sidebar.expand}
onClick={toggleSidebar}
className={cn(
"absolute inset-y-0 z-dropdown hidden w-4 cursor-col-resize after:absolute after:inset-y-0 after:start-1/2 after:w-0.5 after:transition-colors after:duration-fast hover:after:bg-sidebar-border sm:flex",
railTranslate,
side === "start" ? "-end-4" : "-start-4",
className
)}
{...props}
/>
)
}
function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
return (
<main
data-slot="sidebar-inset"
className={cn(
"relative flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto overscroll-contain bg-background",
"md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-xs",
className
)}
{...props}
/>
)
}
function SidebarInput({
className,
...props
}: React.ComponentProps<typeof Input>) {
return (
<Input
data-slot="sidebar-input"
data-sidebar="input"
controlSize="sm"
className={cn("w-full bg-background shadow-none pointer-coarse:h-11", className)}
{...props}
/>
)
}
function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-header"
data-sidebar="header"
className={cn("flex flex-col gap-2 p-2", className)}
{...props}
/>
)
}
function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-footer"
data-sidebar="footer"
className={cn("flex flex-col gap-2 p-2", className)}
{...props}
/>
)
}
function SidebarSeparator({
className,
...props
}: React.ComponentProps<typeof Separator>) {
return (
<Separator
data-slot="sidebar-separator"
data-sidebar="separator"
className={cn("mx-2 w-auto bg-sidebar-border", className)}
{...props}
/>
)
}
function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-content"
data-sidebar="content"
className={cn(
"flex min-h-0 flex-1 flex-col gap-2 overflow-auto overscroll-contain group-data-[collapsible=icon]:overflow-hidden",
className
)}
{...props}
/>
)
}
function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-group"
data-sidebar="group"
className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
{...props}
/>
)
}
function SidebarGroupLabel({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-group-label"
data-sidebar="group-label"
className={cn(
"flex h-control-sm shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground ring-sidebar-ring outline-none transition-[margin,opacity] duration-normal ease-standard focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0",
className
)}
{...props}
/>
)
}
function SidebarGroupAction({
className,
...props
}: ButtonPrimitive.Props) {
return (
<ButtonPrimitive
data-slot="sidebar-group-action"
data-sidebar="group-action"
className={cn(
"absolute top-3.5 end-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-none transition-colors duration-fast hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 pointer-coarse:after:-inset-3 pointer-fine:after:hidden group-data-[collapsible=icon]:hidden",
className
)}
{...props}
/>
)
}
function SidebarGroupContent({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-group-content"
data-sidebar="group-content"
className={cn("w-full text-sm", className)}
{...props}
/>
)
}
function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
return (
<ul
data-slot="sidebar-menu"
data-sidebar="menu"
className={cn("flex w-full min-w-0 flex-col gap-1", className)}
{...props}
/>
)
}
function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
return (
<li
data-slot="sidebar-menu-item"
data-sidebar="menu-item"
className={cn("group/menu-item relative", className)}
{...props}
/>
)
}
const sidebarMenuButtonVariants = cva(
"peer/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md px-2 py-1 text-start text-sm ring-sidebar-ring outline-none transition-[width,height,padding,color,background-color] duration-fast ease-standard pointer-coarse:min-h-11 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:font-medium data-[active=true]:text-sidebar-accent-foreground data-[state=open]:hover:bg-sidebar-accent data-[state=open]:hover:text-sidebar-accent-foreground group-data-[collapsible=icon]:size-control-sm! group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:p-2! group-data-[collapsible=icon]:[&>span]:hidden [&>span:last-child]:truncate [&>span:not([data-slot]):has(~[data-slot])]:truncate [&>svg]:size-4 [&>svg]:shrink-0",
{
variants: {
variant: {
default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
outline:
"border border-sidebar-border bg-background shadow-xs hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
},
size: {
default: "h-control-sm text-sm",
sm: "h-control-2xs text-xs",
lg: "h-control-xl text-sm",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
)
interface SidebarMenuButtonProps
extends ButtonPrimitive.Props,
VariantProps<typeof sidebarMenuButtonVariants> {
isActive?: boolean
/** 仅当该条目明确对应当前页面时传 true;isActive 只负责视觉态 */
current?: boolean
tooltip?: string | React.ReactNode
/**
* 行尾徽标槽:传数字/字符串时使用内建计数胶囊样式,传节点时原样渲染。
* 折叠为图标轨(collapsible="icon")时自动隐藏。
*/
badge?: React.ReactNode
/**
* 行尾自定义槽(快捷键、状态点、箭头等),排在 badge 之后。
* 折叠为图标轨(collapsible="icon")时自动隐藏。
*/
trailing?: React.ReactNode
}
function SidebarMenuButton({
className,
variant = "default",
size = "default",
isActive,
current,
tooltip,
badge,
trailing,
children,
render,
...props
}: SidebarMenuButtonProps) {
const { isMobile, state, side } = useSidebar()
const direction = useDirection()
const collapsed = !isMobile && state === "collapsed"
const button = (
<ButtonPrimitive
data-slot="sidebar-menu-button"
data-sidebar="menu-button"
data-size={size}
data-active={isActive ? "true" : undefined}
aria-current={current ? "page" : undefined}
aria-label={
collapsed && typeof tooltip === "string" ? tooltip : undefined
}
className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
render={render}
{...props}
>
{children}
{badge != null ? (
<span
data-slot="sidebar-menu-button-badge"
data-sidebar="menu-button-badge"
className="ms-auto flex shrink-0 items-center justify-center group-data-[collapsible=icon]:hidden"
>
{typeof badge === "string" || typeof badge === "number" ? (
<span className="inline-flex h-4 min-w-4 items-center justify-center rounded-full bg-sidebar-accent px-1.5 text-2xs font-medium tabular-nums text-sidebar-accent-foreground">
{badge}
</span>
) : (
badge
)}
</span>
) : null}
{trailing != null ? (
<span
data-slot="sidebar-menu-button-trailing"
data-sidebar="menu-button-trailing"
className={cn(
"flex shrink-0 items-center gap-1 group-data-[collapsible=icon]:hidden",
badge == null && "ms-auto"
)}
>
{trailing}
</span>
) : null}
</ButtonPrimitive>
)
if (!tooltip || !collapsed) return button
const tooltipSide =
side === "start"
? direction === "rtl"
? "left"
: "right"
: direction === "rtl"
? "right"
: "left"
return (
<Tooltip>
<TooltipTrigger render={button} />
<TooltipContent side={tooltipSide}>{tooltip}</TooltipContent>
</Tooltip>
)
}
interface SidebarMenuActionProps extends ButtonPrimitive.Props {
showOnHover?: boolean
}
function SidebarMenuAction({
className,
showOnHover = false,
...props
}: SidebarMenuActionProps) {
return (
<ButtonPrimitive
data-slot="sidebar-menu-action"
data-sidebar="menu-action"
className={cn(
"absolute top-1.5 end-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-none transition-colors duration-fast hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0 after:absolute after:-inset-2 pointer-coarse:after:-inset-3 pointer-fine:after:hidden group-data-[collapsible=icon]:hidden",
"peer-data-[size=sm]/menu-button:top-1 peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5",
showOnHover &&
"group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-sidebar-accent-foreground md:opacity-0",
className
)}
{...props}
/>
)
}
function SidebarMenuBadge({
className,
...props
}: React.ComponentProps<"div">) {
return (
<div
data-slot="sidebar-menu-badge"
data-sidebar="menu-badge"
className={cn(
"pointer-events-none absolute end-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[active=true]/menu-button:text-sidebar-accent-foreground group-data-[collapsible=icon]:hidden",
className
)}
{...props}
/>
)
}
function SidebarMenuSkeleton({
className,
showIcon = false,
width = "70%",
...props
}: React.ComponentProps<"div"> & {
showIcon?: boolean
width?: string
}) {
return (
<div
data-slot="sidebar-menu-skeleton"
data-sidebar="menu-skeleton"
className={cn("flex h-control-sm items-center gap-2 rounded-md px-2", className)}
{...props}
>
{showIcon && (
<Skeleton
data-sidebar="menu-skeleton-icon"
className="size-4 rounded-md"
/>
)}
<Skeleton
data-sidebar="menu-skeleton-text"
className="h-4 max-w-[var(--skeleton-width)] flex-1"
style={{ "--skeleton-width": width } as React.CSSProperties}
/>
</div>
)
}
function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
return (
<ul
data-slot="sidebar-menu-sub"
data-sidebar="menu-sub"
className={cn(
"mx-3.5 flex min-w-0 flex-col gap-1 border-s border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
className
)}
{...props}
/>
)
}
function SidebarMenuSubItem({
className,
...props
}: React.ComponentProps<"li">) {
return (
<li
data-slot="sidebar-menu-sub-item"
data-sidebar="menu-sub-item"
className={cn("group/menu-sub-item relative", className)}
{...props}
/>
)
}
interface SidebarMenuSubButtonProps extends ButtonPrimitive.Props {
size?: "sm" | "md"
isActive?: boolean
/** 仅当该子条目明确对应当前页面时传 true;isActive 只负责视觉态 */
current?: boolean
}
function SidebarMenuSubButton({
className,
size = "md",
isActive,
current,
...props
}: SidebarMenuSubButtonProps) {
return (
<ButtonPrimitive
data-slot="sidebar-menu-sub-button"
data-sidebar="menu-sub-button"
data-size={size}
data-active={isActive ? "true" : undefined}
aria-current={current ? "page" : undefined}
className={cn(
"flex h-control-2xs min-w-0 items-center gap-2 overflow-hidden rounded-md px-2 text-start text-sidebar-foreground transition-colors duration-fast pointer-coarse:min-h-11 ring-sidebar-ring outline-none hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-accent data-[active=true]:text-sidebar-accent-foreground data-[size=md]:text-sm data-[size=sm]:text-xs [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground group-data-[collapsible=icon]:hidden",
className
)}
{...props}
/>
)
}
export {
Sidebar,
SidebarContent,
SidebarContext,
SidebarFooter,
SidebarGroup,
SidebarGroupAction,
SidebarGroupContent,
SidebarGroupLabel,
SidebarHeader,
SidebarInput,
SidebarInset,
SidebarMenu,
SidebarMenuAction,
SidebarMenuBadge,
SidebarMenuButton,
SidebarMenuItem,
SidebarMenuSkeleton,
SidebarMenuSub,
SidebarMenuSubButton,
SidebarMenuSubItem,
SidebarProvider,
SidebarRail,
SidebarSeparator,
SidebarTrigger,
sidebarMenuButtonVariants,
useSidebar,
}
可访问性与 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。
用法说明
应用侧栏,由 SidebarProvider、Sidebar、SidebarInset 组合;side/variant/collapsible/宽度/持久化全部配置在 SidebarProvider,Sidebar 只负责结构(传错在 TS 报错、开发环境告警);支持 offcanvas/icon 折叠、移动端 Sheet、Ctrl/Cmd+B、localStorage 或 cookie 持久化;side 用 start/end 以适配 RTL;SidebarMenuButton 的 badge/trailing 行尾槽内建折叠隐藏。
配置位置(先读)
side / variant / collapsible / width / widthIcon / persistence / storageKey / keyboardShortcut 都是 <SidebarProvider> 的 props,不是 <Sidebar> 的。<Sidebar> 只负责结构(Header / Content / Menu / Footer / Rail)。
// ✅ 正确:配置统一放在 Provider
<SidebarProvider collapsible="icon" variant="inset" side="start">
<Sidebar>{/* 结构 */}</Sidebar>
</SidebarProvider>
// ❌ 错误:collapsible 不是 Sidebar 的 prop
// TypeScript 会报错;JS 消费方会在开发环境控制台看到告警
<Sidebar collapsible="icon">{/* 结构 */}</Sidebar>快速接入
import {
Sidebar,
SidebarInset,
SidebarProvider,
SidebarTrigger,
} from "@mox-hub/ui";
<SidebarProvider>
<Sidebar>{/* SidebarHeader / Content / Menu / Footer */}</Sidebar>
<SidebarInset>
<SidebarTrigger />
{/* 页面内容 */}
</SidebarInset>
</SidebarProvider>;Provider 配置
| Prop | 取值 | 默认 | 说明 |
|---|---|---|---|
side | start / end | start | 逻辑方向;RTL 下自动镜像,不用写 left/right |
variant | sidebar / floating / inset | sidebar | 贴边、浮动卡片或内嵌式侧栏 |
collapsible | offcanvas / icon / none | offcanvas | 收起为 0 宽、图标轨或不可收起 |
defaultOpen | boolean | true | 非受控初始展开状态 |
open | boolean | — | 受控展开状态 |
onOpenChange | (open: boolean) => void | — | 受控状态回调 |
persistence | local / cookie / false | local | 展开状态持久化方式 |
storageKey | string | ordo-sidebar | 持久化键名 |
keyboardShortcut | boolean | true | Ctrl/Cmd+B 切换;输入框、文本域内不劫持 |
width | string / number | 16rem | 展开宽度,number 按 px 处理 |
widthIcon | string / number | 3rem | 图标轨宽度,number 按 px 处理 |
- 视口小于 768px 时自动切换为 Sheet;
SidebarTrigger可放在SidebarInset的页头。 SidebarMenuButton在collapsible="icon"下自动居中图标,并通过tooltip显示名称。SidebarRail提供侧栏边缘的拖拽式点击热区;useSidebar()可在业务组件里读取state、isMobile与toggleSidebar。SidebarProvider默认就是h-svh max-h-svh overflow-hidden的应用壳,侧栏内容区(SidebarContent)与SidebarInset各自滚动;嵌入到卡片/弹窗时可传className="h-[420px]"覆写高度。
行尾徽标与自定义槽
SidebarMenuButton 提供 badge / trailing 两个行尾槽,均内建折叠隐藏(collapsible="icon" 时自动消失),不需要再手写 group-data-[collapsible=icon]:hidden。
<SidebarMenuButton tooltip="待办" badge={4}>
<ListTodo />
<span>待办</span>
</SidebarMenuButton>
<SidebarMenuButton
tooltip="搜索"
trailing={<span className="text-2xs text-sidebar-foreground">⌘K</span>}
>
<Search />
<span>搜索</span>
</SidebarMenuButton>badge传数字/字符串时使用内建计数胶囊;传 ReactNode 时原样渲染(例如自定义<Badge>)。trailing排在badge之后,适合快捷键、状态点、展开箭头等非计数内容。- 两个槽都参与行尾布局(
ms-auto),长标题仍会正常截断。