From b69e7d5ab4fc4449c9acbed912e6e03307d39491 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 11:43:00 +0800
Subject: [PATCH 1/6] feat: `page` component support fixed header

---
 .../ui-kit/layout-ui/src/vben-layout.vue      |  2 +-
 packages/effects/common-ui/package.json       |  1 +
 .../common-ui/src/components/page/page.vue    | 27 ++++++++++++++++++-
 playground/src/views/examples/modal/index.vue |  1 +
 pnpm-lock.yaml                                |  3 +++
 5 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/packages/@core/ui-kit/layout-ui/src/vben-layout.vue b/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
index 3cdd3d1eae6..33624755736 100644
--- a/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
+++ b/packages/@core/ui-kit/layout-ui/src/vben-layout.vue
@@ -503,7 +503,7 @@ function handleHeaderToggle() {
 
     <div
       ref="contentRef"
-      class="flex flex-1 flex-col overflow-hidden transition-all duration-300 ease-in"
+      class="flex flex-1 flex-col transition-all duration-300 ease-in"
     >
       <div
         :class="[
diff --git a/packages/effects/common-ui/package.json b/packages/effects/common-ui/package.json
index 2ff5fdf3b81..ac0a61469b9 100644
--- a/packages/effects/common-ui/package.json
+++ b/packages/effects/common-ui/package.json
@@ -22,6 +22,7 @@
   "dependencies": {
     "@vben-core/form-ui": "workspace:*",
     "@vben-core/popup-ui": "workspace:*",
+    "@vben-core/preferences": "workspace:*",
     "@vben-core/shadcn-ui": "workspace:*",
     "@vben-core/shared": "workspace:*",
     "@vben/constants": "workspace:*",
diff --git a/packages/effects/common-ui/src/components/page/page.vue b/packages/effects/common-ui/src/components/page/page.vue
index e8c486ebef7..6859fc814b4 100644
--- a/packages/effects/common-ui/src/components/page/page.vue
+++ b/packages/effects/common-ui/src/components/page/page.vue
@@ -1,5 +1,14 @@
 <script setup lang="ts">
-import { computed, nextTick, onMounted, ref, useTemplateRef } from 'vue';
+import {
+  computed,
+  nextTick,
+  onMounted,
+  ref,
+  type StyleValue,
+  useTemplateRef,
+} from 'vue';
+
+import { preferences } from '@vben-core/preferences';
 
 interface Props {
   title?: string;
@@ -9,6 +18,8 @@ interface Props {
    * 根据content可见高度自适应
    */
   autoContentHeight?: boolean;
+  /** 头部固定 */
+  fixedHeader?: boolean;
 }
 
 defineOptions({
@@ -20,6 +31,7 @@ const {
   description = '',
   autoContentHeight = false,
   title = '',
+  fixedHeader = false,
 } = defineProps<Props>();
 
 const headerHeight = ref(0);
@@ -29,6 +41,18 @@ const shouldAutoHeight = ref(false);
 const headerRef = useTemplateRef<HTMLDivElement>('headerRef');
 const footerRef = useTemplateRef<HTMLDivElement>('footerRef');
 
+const headerStyle = computed<StyleValue>(() => {
+  return fixedHeader
+    ? {
+        position: 'sticky',
+        zIndex: 200,
+        top:
+          preferences.header.mode === 'fixed' ? 'var(--vben-header-height)' : 0,
+        borderBottom: '1px solid hsl(240 5.9% 90%)',
+      }
+    : undefined;
+});
+
 const contentStyle = computed(() => {
   if (autoContentHeight) {
     return {
@@ -69,6 +93,7 @@ onMounted(() => {
         $slots.extra
       "
       ref="headerRef"
+      :style="headerStyle"
       class="bg-card relative px-6 py-4"
     >
       <slot name="title">
diff --git a/playground/src/views/examples/modal/index.vue b/playground/src/views/examples/modal/index.vue
index d6db2fba294..22e9ed8c876 100644
--- a/playground/src/views/examples/modal/index.vue
+++ b/playground/src/views/examples/modal/index.vue
@@ -77,6 +77,7 @@ function openFormModal() {
 <template>
   <Page
     description="弹窗组件常用于在不离开当前页面的情况下，显示额外的信息、表单或操作提示，更多api请查看组件文档。"
+    fixed-header
     title="弹窗组件示例"
   >
     <template #extra>
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 731ef2e24b3..f6706332fda 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1460,6 +1460,9 @@ importers:
       '@vben-core/popup-ui':
         specifier: workspace:*
         version: link:../../@core/ui-kit/popup-ui
+      '@vben-core/preferences':
+        specifier: workspace:*
+        version: link:../../@core/preferences
       '@vben-core/shadcn-ui':
         specifier: workspace:*
         version: link:../../@core/ui-kit/shadcn-ui

From 42b22bbc20231206d7688ac9362e345247c92683 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 12:14:31 +0800
Subject: [PATCH 2/6] docs: `page`  component documentation

---
 docs/.vitepress/config/zh.mts         | 10 +++++++
 docs/src/components/introduction.md   |  4 +++
 docs/src/components/layout-ui/page.md | 43 +++++++++++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 docs/src/components/layout-ui/page.md

diff --git a/docs/.vitepress/config/zh.mts b/docs/.vitepress/config/zh.mts
index 6b31658edb9..27fb96c0435 100644
--- a/docs/.vitepress/config/zh.mts
+++ b/docs/.vitepress/config/zh.mts
@@ -148,6 +148,16 @@ function sidebarComponents(): DefaultTheme.SidebarItem[] {
         },
       ],
     },
+    {
+      collapsed: false,
+      text: '布局组件',
+      items: [
+        {
+          link: 'layout-ui/page',
+          text: 'Page 页面',
+        },
+      ],
+    },
     {
       collapsed: false,
       text: '通用组件',
diff --git a/docs/src/components/introduction.md b/docs/src/components/introduction.md
index 039ec8cd832..438470e9a36 100644
--- a/docs/src/components/introduction.md
+++ b/docs/src/components/introduction.md
@@ -6,6 +6,10 @@
 
 :::
 
+## 布局组件
+
+布局组件一般在页面内容区域用作顶层容器组件，提供一些统一的布局样式和基本功能。
+
 ## 通用组件
 
 通用组件是一些常用的组件，比如弹窗、抽屉、表单等。大部分基于 `Tailwind CSS` 实现，可适用于不同 UI 组件库的应用。
diff --git a/docs/src/components/layout-ui/page.md b/docs/src/components/layout-ui/page.md
new file mode 100644
index 00000000000..456b131f101
--- /dev/null
+++ b/docs/src/components/layout-ui/page.md
@@ -0,0 +1,43 @@
+---
+outline: deep
+---
+
+# Page 常规页面组件
+
+提供一个常规页面布局的组件，包括头部、内容区域、底部三个部分。
+
+::: info 写在前面
+
+本组件是一个基本布局组件。如果有更多的通用页面布局需求（比如双列布局等），可以根据实际需求自行封装。
+
+:::
+
+## 基础用法
+
+将`Page`作为你的业务页面的根组件即可。
+
+### Props
+
+| 属性名            | 描述                     | 类型      | 默认值  |
+| ----------------- | ------------------------ | --------- | ------- |
+| title             | 页面标题                 | `string`  | -       |
+| description       | 页面描述（标题下的内容） | `string`  | -       |
+| contentClass      | 内容区域的class          | `string`  | -       |
+| autoContentHeight | 自动调整内容区域的高度   | `boolean` | `false` |
+| fixedHeader       | 固定头部                 | `boolean` | `false` |
+
+::: tip 注意
+
+如果`title`、`description`、`extra`三者均未提供有效内容（通过`props`或者`slots`均可），则页面头部区域不会渲染。
+
+:::
+
+### Slots
+
+| 插槽名称    | 描述         |
+| ----------- | ------------ |
+| default     | 页面内容     |
+| title       | 页面标题     |
+| description | 页面描述     |
+| extra       | 页面头部右侧 |
+| footer      | 页面底部     |

From 28283ddb10a496252affa0161972a1ba5b89f185 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 12:34:53 +0800
Subject: [PATCH 3/6] docs: Improve `props` types of `page`

---
 docs/src/components/layout-ui/page.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/src/components/layout-ui/page.md b/docs/src/components/layout-ui/page.md
index 456b131f101..038ddb49cd7 100644
--- a/docs/src/components/layout-ui/page.md
+++ b/docs/src/components/layout-ui/page.md
@@ -18,13 +18,13 @@ outline: deep
 
 ### Props
 
-| 属性名            | 描述                     | 类型      | 默认值  |
-| ----------------- | ------------------------ | --------- | ------- |
-| title             | 页面标题                 | `string`  | -       |
-| description       | 页面描述（标题下的内容） | `string`  | -       |
-| contentClass      | 内容区域的class          | `string`  | -       |
-| autoContentHeight | 自动调整内容区域的高度   | `boolean` | `false` |
-| fixedHeader       | 固定头部                 | `boolean` | `false` |
+| 属性名            | 描述                     | 类型           | 默认值  |
+| ----------------- | ------------------------ | -------------- | ------- |
+| title             | 页面标题                 | `string\|slot` | -       |
+| description       | 页面描述（标题下的内容） | `string\|slot` | -       |
+| contentClass      | 内容区域的class          | `string`       | -       |
+| autoContentHeight | 自动调整内容区域的高度   | `boolean`      | `false` |
+| fixedHeader       | 固定头部                 | `boolean`      | `false` |
 
 ::: tip 注意
 

From 38c3f26a1970b8069a753decb0c4a5ea32ea11a9 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 12:45:17 +0800
Subject: [PATCH 4/6] docs: improve `fixedHeader` description of `page`

---
 docs/src/components/layout-ui/page.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/src/components/layout-ui/page.md b/docs/src/components/layout-ui/page.md
index 038ddb49cd7..4bd78f29dba 100644
--- a/docs/src/components/layout-ui/page.md
+++ b/docs/src/components/layout-ui/page.md
@@ -18,13 +18,13 @@ outline: deep
 
 ### Props
 
-| 属性名            | 描述                     | 类型           | 默认值  |
-| ----------------- | ------------------------ | -------------- | ------- |
-| title             | 页面标题                 | `string\|slot` | -       |
-| description       | 页面描述（标题下的内容） | `string\|slot` | -       |
-| contentClass      | 内容区域的class          | `string`       | -       |
-| autoContentHeight | 自动调整内容区域的高度   | `boolean`      | `false` |
-| fixedHeader       | 固定头部                 | `boolean`      | `false` |
+| 属性名 | 描述 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| title | 页面标题 | `string\|slot` | - |
+| description | 页面描述（标题下的内容） | `string\|slot` | - |
+| contentClass | 内容区域的class | `string` | - |
+| autoContentHeight | 自动调整内容区域的高度 | `boolean` | `false` |
+| fixedHeader | 固定头部在页面内容区域顶部，在滚动时保持可见 | `boolean` | `false` |
 
 ::: tip 注意
 

From 11cf5de649ff4f95a13495b93b193edf402cdfc3 Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 13:35:10 +0800
Subject: [PATCH 5/6] fix: `page` header border color with fixedHeader

---
 packages/effects/common-ui/src/components/page/page.vue | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/effects/common-ui/src/components/page/page.vue b/packages/effects/common-ui/src/components/page/page.vue
index 6859fc814b4..d6664f359b2 100644
--- a/packages/effects/common-ui/src/components/page/page.vue
+++ b/packages/effects/common-ui/src/components/page/page.vue
@@ -9,6 +9,7 @@ import {
 } from 'vue';
 
 import { preferences } from '@vben-core/preferences';
+import { cn } from '@vben-core/shared/utils';
 
 interface Props {
   title?: string;
@@ -48,7 +49,6 @@ const headerStyle = computed<StyleValue>(() => {
         zIndex: 200,
         top:
           preferences.header.mode === 'fixed' ? 'var(--vben-header-height)' : 0,
-        borderBottom: '1px solid hsl(240 5.9% 90%)',
       }
     : undefined;
 });
@@ -93,8 +93,13 @@ onMounted(() => {
         $slots.extra
       "
       ref="headerRef"
+      :class="
+        cn(
+          'bg-card relative px-6 py-4',
+          fixedHeader ? 'border-border border-b' : '',
+        )
+      "
       :style="headerStyle"
-      class="bg-card relative px-6 py-4"
     >
       <slot name="title">
         <div v-if="title" class="mb-2 flex text-lg font-semibold">

From d287febf0fba7fbb4a7994fcbafc11851db3d5ea Mon Sep 17 00:00:00 2001
From: Netfan <netfan@foxmail.com>
Date: Wed, 4 Dec 2024 15:19:21 +0800
Subject: [PATCH 6/6] feat: add `headerClass` for `Page`

---
 docs/src/components/layout-ui/page.md         |  2 ++
 .../common-ui/src/components/page/page.vue    | 10 +++++++-
 playground/src/views/examples/form/basic.vue  | 23 ++++++++++++++++---
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/src/components/layout-ui/page.md b/docs/src/components/layout-ui/page.md
index 4bd78f29dba..8a33775c4c9 100644
--- a/docs/src/components/layout-ui/page.md
+++ b/docs/src/components/layout-ui/page.md
@@ -23,6 +23,8 @@ outline: deep
 | title | 页面标题 | `string\|slot` | - |
 | description | 页面描述（标题下的内容） | `string\|slot` | - |
 | contentClass | 内容区域的class | `string` | - |
+| headerClass | 头部区域的class | `string` | - |
+| footerClass | 底部区域的class | `string` | - |
 | autoContentHeight | 自动调整内容区域的高度 | `boolean` | `false` |
 | fixedHeader | 固定头部在页面内容区域顶部，在滚动时保持可见 | `boolean` | `false` |
 
diff --git a/packages/effects/common-ui/src/components/page/page.vue b/packages/effects/common-ui/src/components/page/page.vue
index d6664f359b2..9ae16ee6090 100644
--- a/packages/effects/common-ui/src/components/page/page.vue
+++ b/packages/effects/common-ui/src/components/page/page.vue
@@ -21,6 +21,8 @@ interface Props {
   autoContentHeight?: boolean;
   /** 头部固定 */
   fixedHeader?: boolean;
+  headerClass?: string;
+  footerClass?: string;
 }
 
 defineOptions({
@@ -96,6 +98,7 @@ onMounted(() => {
       :class="
         cn(
           'bg-card relative px-6 py-4',
+          headerClass,
           fixedHeader ? 'border-border border-b' : '',
         )
       "
@@ -125,7 +128,12 @@ onMounted(() => {
     <div
       v-if="$slots.footer"
       ref="footerRef"
-      class="bg-card align-center absolute bottom-0 left-0 right-0 flex px-6 py-4"
+      :class="
+        cn(
+          footerClass,
+          'bg-card align-center absolute bottom-0 left-0 right-0 flex px-6 py-4',
+        )
+      "
     >
       <slot name="footer"></slot>
     </div>
diff --git a/playground/src/views/examples/form/basic.vue b/playground/src/views/examples/form/basic.vue
index 5124a3cfda0..4c1d3cadcd5 100644
--- a/playground/src/views/examples/form/basic.vue
+++ b/playground/src/views/examples/form/basic.vue
@@ -1,13 +1,17 @@
 <script lang="ts" setup>
+import { ref } from 'vue';
+
 import { Page } from '@vben/common-ui';
 
-import { Button, Card, message } from 'ant-design-vue';
+import { Button, Card, message, TabPane, Tabs } from 'ant-design-vue';
 import dayjs from 'dayjs';
 
 import { useVbenForm } from '#/adapter/form';
 
 import DocButton from '../doc-button.vue';
 
+const activeTab = ref('basic');
+
 const [BaseForm, baseFormApi] = useVbenForm({
   // 所有表单项共用，可单独在表单内覆盖
   commonConfig: {
@@ -331,18 +335,31 @@ function handleSetFormValue() {
   <Page
     content-class="flex flex-col gap-4"
     description="表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。"
+    fixed-header
+    header-class="pb-0"
     title="表单组件"
   >
+    <template #description>
+      <div class="text-muted-foreground">
+        <p>
+          表单组件基础示例，请注意，该页面用到的参数代码会添加一些简单注释，方便理解，请仔细查看。
+        </p>
+      </div>
+      <Tabs v-model:active-key="activeTab" :tab-bar-style="{ marginBottom: 0 }">
+        <TabPane key="basic" tab="基础示例" />
+        <TabPane key="layout" tab="自定义布局" />
+      </Tabs>
+    </template>
     <template #extra>
       <DocButton path="/components/common-ui/vben-form" />
     </template>
-    <Card title="基础示例">
+    <Card v-show="activeTab === 'basic'" title="基础示例">
       <template #extra>
         <Button type="primary" @click="handleSetFormValue">设置表单值</Button>
       </template>
       <BaseForm />
     </Card>
-    <Card title="使用tailwind自定义布局">
+    <Card v-show="activeTab === 'layout'" title="使用tailwind自定义布局">
       <CustomLayoutForm />
     </Card>
   </Page>