UPage：页面标题与状态容器

用 UPage 统一面包屑、标题、操作区、加载/错误状态及页脚。它不负责鉴权、路由注册或数据请求；这些仍由应用内核和页面的数据层处理。

完整示例：加载与重试

父页面传入一个返回统计值的 load 函数。示例使用组件局部语言包，实际项目可将这些键合并进业务模块语言包。

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { useI18n } from 'vue-i18n'
import { UPage, UCard } from '@uadmin/ui'

const props = defineProps<{ load: () => Promise<number> }>()
const { t } = useI18n({
  useScope: 'local',
  messages: {
    'zh-CN': { title: '统计', refresh: '刷新', count: '记录数', failed: '加载失败，请重试' },
    'en-US': {
      title: 'Statistics',
      refresh: 'Refresh',
      count: 'Records',
      failed: 'Unable to load. Retry.',
    },
  },
})
const loading = ref(false)
const error = ref<string | null>(null)
const count = ref(0)
async function reload() {
  loading.value = true
  error.value = null
  try {
    count.value = await props.load()
  } catch {
    error.value = t('failed')
  } finally {
    loading.value = false
  }
}
onMounted(reload)
</script>

<template>
  <UPage :title="t('title')" :loading="loading" :error="error" :on-retry="reload">
    <template #actions>
      <el-button :loading="loading" @click="reload">{{ t('refresh') }}</el-button>
    </template>
    <UCard :title="t('count')">{{ count }}</UCard>
  </UPage>
</template>

loading 优先于 error；任一状态生效时，正文插槽会卸载。需要保留表格选择或编辑器状态时，在子组件上使用自己的 loading，而不要用页面级 loading 替换整段正文。

选择滚动模式

scrollMode	用途	容器要求
'page'（默认）	表单、普通内容页	由外层滚动容器承担滚动
'inner'	保持标题不动、正文内部滚动	父级有确定高度；内部使用 el-scrollbar
'fit'	表格主体滚动、分页停在底部	从布局到页面建立完整高度链；子表格启用 fit-height

<UPage :title="t('users.title')" scroll-mode="fit">
  <UCard class="u-fit-card" flush>
    <UDataTable :data="rows" :columns="columns" fit-height />
  </UCard>
</UPage>

这段是布局片段：rows/columns 和分页由页面维护，完整数据示例见 UDataTable。u-fit-card 是 UPage 内置识别的类名；单独设置 fit-height 不会凭空产生父容器高度。

API

Prop	类型	默认 / 行为
title	string	页面 h1
description	string	标题下说明；需存在 title 或 header 插槽才显示标题区
breadcrumb	boolean	true；false 不渲染面包屑
breadcrumbItems	Crumb[]	传给 UBreadcrumb；未传时按菜单/路由推导
scrollMode	'page' | 'inner' | 'fit'	'page'
loading	boolean	false；正文显示骨架屏
error	string | null	null；非空时显示错误
onRetry	() => void	存在时显示重试按钮；通过 prop 传入函数

Slot	用途
default	正文；仅正常状态显示
header	替换标题与说明
actions	标题右侧按钮
footer	页面页脚，独立于正文加载状态

没有自定义 emits 或公开实例方法。只有 actions、没有 title/header 时，整个标题区不会出现。全局面包屑关闭后，单页 breadcrumb=true 不能重新开启；详见 面包屑。