feat(page): add composable page primitives

2026-09-28 23:13:49 +08:00
parent 0ec968c344
commit d23deca0e7
18 changed files with 1979 additions and 0 deletions
@@ -0,0 +1,94 @@
+---
+title: 页面组合
+description: 组合标题、页面操作、面包屑和内容 Section。
+order: 10
+toc:
+  - id: stylesheet
+    title: 样式入口
+  - id: basic-page
+    title: 基础页面
+  - id: page-info
+    title: 页面信息
+  - id: breadcrumb
+    title: 面包屑
+---
+
+## 样式入口 {#stylesheet}
+
+在应用 Tailwind 样式入口加入：
+
+```css
+@import "@workspace/page/globals.css";
+```
+
+## 基础页面 {#basic-page}
+
+```tsx
+import {
+  PageBackButton,
+  PageBreadcrumb,
+  PageContainer,
+  PageDescription,
+  PageHeader,
+  PageHeaderExtra,
+  PageHeading,
+  PageHeadingExtra,
+  PageSection,
+  PageSubtitle,
+  PageTitle,
+} from "@workspace/page"
+import { Button } from "@workspace/ui/components/button"
+
+export function ProductsPage() {
+  return (
+    <PageContainer
+      info={{
+        breadcrumb: [
+          { label: "首页", href: "/" },
+          { label: "商品目录", href: "/products" },
+          { label: "商品" },
+        ],
+        description: "管理商品、价格和上架状态。",
+        subtitle: "商品目录",
+        title: "商品",
+      }}
+    >
+      <PageHeader>
+        <PageBreadcrumb />
+        <PageHeading>
+          <PageHeadingExtra align="start">
+            <PageBackButton href="/products">商品列表</PageBackButton>
+          </PageHeadingExtra>
+          <PageTitle />
+          <PageSubtitle />
+          <PageDescription />
+          <PageHeadingExtra align="end">
+            <Button>新建商品</Button>
+          </PageHeadingExtra>
+        </PageHeading>
+        <PageHeaderExtra>
+          <ProductStatus />
+        </PageHeaderExtra>
+      </PageHeader>
+
+      <PageSection aria-label="商品列表">
+        <ProductsTable />
+      </PageSection>
+    </PageContainer>
+  )
+}
+```
+
+## 页面信息 {#page-info}
+
+`PageContainer.info` 接受 `Partial<PageInfo>`，并通过 `usePageInfo()` 暴露解析后的值。外层 `PagesManager` 提供 `getPageInfo` 后，该函数会接收局部信息，并可使用路由或布局元数据将其补全。`PageTitle`、`PageSubtitle`、`PageDescription` 和 `PageBreadcrumb` 在自身未提供内容或 items 时读取对应的页面信息；组件显式提供的内容优先。两个来源都没有可渲染内容时，组件返回 `null`，不会在页面中留下空元素。
+
+`PageHeadingExtra` 接受 `align="start | end"`。同一侧的多个 Extra 会保持声明顺序，`PageHeaderExtra` 则提供标题下方不限定内容类型的区域。所有容器都保留 `className` 和原生 HTML props。
+
+`PageBackButton` 未指定目标地址时使用浏览器历史记录返回。传入 `href` 可渲染原生链接，传入 `render` 可接入特定路由库的 Link；自定义 `onClick` 调用 `preventDefault()` 后也会阻止默认的历史返回。
+
+## 面包屑 {#breadcrumb}
+
+按照从根节点到当前页面的顺序向 `PageBreadcrumb` 传入 `items`。最后一项会渲染为当前页面；带 `href` 的项目使用原生链接，`render` 则可以接入特定路由库的 Link。当路径超过 `maxItems`（默认 `4`）时，中间项目会收入支持键盘操作的溢出菜单。
+
+省略 `items` 后仍可使用原有组合 API，Breadcrumb Item、Link 和 Separator 继续从 `@workspace/ui/components/breadcrumb` 导入。