add PageTransition

docs/.vitepress/components.ts

@@ -36,6 +36,13 @@ export interface ComponentMeta {
 
 export const COMPONENT_LIST: ComponentMeta[] = [
 	// ---------- 布局组件 ----------
+	{
+		name: "PageTransition",
+		title: "PageTransition 页面过渡",
+		description: "为 Vue Router 页面提供可配置的层级滑动过渡与按路由缓存能力。",
+		category: "布局组件",
+		entry: "src/components/page-transition/index.vue"
+	},
 	{
 		name: "RootLayout",
 		title: "RootLayout 根布局",

docs/components/index.md

@@ -1,11 +1,12 @@
 # 组件总览
 
-共 15 个组件，分为布局、编辑器、交互与 AI 对话四类。
+共 16 个组件，分为布局、编辑器、交互与 AI 对话四类。
 
 ## 布局组件
 
 | 组件 | 说明 |
 | --- | --- |
+| [PageTransition](/components/page-transition) | 为 Vue Router 页面提供可配置的层级滑动过渡与按路由缓存能力。 |
 | [RootLayout](/components/root-layout) | 移动端页面骨架，主体内容之外自动渲染版权与备案信息。 |
 | [Space](/components/space) | 控制子元素之间的间距与排列方向，支持分隔符。 |
 

docs/components/page-transition.md

@@ -0,0 +1,37 @@
+# PageTransition 页面过渡
+
+为 Vue Router 页面提供可配置的页面过渡和按路由缓存能力。
+
+## 基础用法
+
+`PageTransition` 必须放在 `RouterView` 所在的路由布局中，并且自身需要有明确的宽高。
+
+```vue
+<template>
+	<div class="layout">
+		<page-transition :keep-alive="route => route.meta.keepAlive === true" />
+	</div>
+</template>
+
+<style scoped lang="less">
+.layout {
+	height: 100vh;
+}
+</style>
+```
+
+组件默认根据路由层级选择 `push-left` 和 `push-right`。层级的解析顺序是：`transitionDepth` query、`depth` meta、动态层级 meta，最后回退到 `matched.length`。业务路由结构特殊时，直接传入 `get-route-depth`，不要让组件猜测业务规则。
+
+## 缓存页面
+
+`keep-alive` 支持布尔值或路由谓词。谓词返回 `true` 的页面会进入缓存，`keep-alive-max` 用于限制缓存数量。默认不缓存页面，避免通用布局意外保留业务表单状态。
+
+## 自定义过渡
+
+`transition` 默认值为 `auto`，也可以传入 `false` 禁用过渡、传入字符串使用自定义过渡名，或传入函数按目标路由和来源路由返回过渡名。组件内置 `push-left`、`push-right` 和 `fade`。
+
+组件默认尊重系统的“减少动态效果”设置；如果业务必须保持页面翻页动画，可以设置 `:respect-reduced-motion="false"`。
+
+## API
+
+<api-table name="PageTransition" />