docs(ui): expand bilingual component guides

2026-09-21 17:27:45 +08:00
parent fb985edb20
commit 4c61e79d0d
22 changed files with 1636 additions and 192 deletions
@@ -0,0 +1,64 @@
+---
+title: 锚定式个人菜单
+description: 使用 Popover 的连续尾巴、滚动视口和 Base UI render 组合个人菜单。
+order: 31
+toc:
+  - id: example
+    title: 示例
+  - id: why-these-props
+    title: 参数说明
+  - id: accessibility
+    title: 可访问性
+---
+
+## 示例 {#example}
+
+```tsx
+import { Avatar, AvatarFallback } from "@workspace/ui/components/avatar"
+import { Button } from "@workspace/ui/components/button"
+import { SettingsIcon } from "@workspace/ui/components/icon"
+import {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@workspace/ui/components/popover"
+
+export function AccountMenu() {
+  return (
+    <Popover>
+      <PopoverTrigger
+        render={<Button variant="ghost" size="icon" aria-label="账户菜单" />}
+      >
+        <Avatar>
+          <AvatarFallback>JF</AvatarFallback>
+        </Avatar>
+      </PopoverTrigger>
+
+      <PopoverContent
+        align="end"
+        side="bottom"
+        showArrow={{ cornerRadius: "2xl", tailSize: "sm" }}
+        className="w-80 gap-0 p-0"
+        viewportClassName="max-h-[min(28rem,var(--available-height))] p-4"
+      >
+        <PopoverTitle>Jaydon Frankie</PopoverTitle>
+        <PopoverDescription>demo@minimals.cc</PopoverDescription>
+        <Button variant="ghost" className="mt-4 w-full justify-start">
+          <SettingsIcon />
+          界面外观
+        </Button>
+      </PopoverContent>
+    </Popover>
+  )
+}
+```
+
+## 参数说明 {#why-these-props}
+
+`align="end"` 让面板尾部与触发器尾部对齐，逻辑方向会自动适配 RTL。`showArrow` 启用本地连续尾巴。外层 `className` 控制整个表面，内部 `viewportClassName` 控制滚动区域；这种分离能让长菜单滚动而不裁剪尾巴。
+
+## 可访问性 {#accessibility}
+
+触发按钮使用图标或头像时必须提供 `aria-label`。面板使用 `PopoverTitle` 与 `PopoverDescription`，关闭与焦点返回交给 Base UI Root 管理。若内容本质上是一组选项或命令，应改用 DropdownMenu 或 Command，而不是手工添加错误的 menu role。