logo
简体中文
导航

App Layout

简介

AppLayout 组件适用于页面布局，提供一个包含侧边栏导航、头部、主内容区和页脚的完整布局框架。特别适合文档站点、博客、知识库等需要导航和内容展示的场景。

组件特性：

  • 🏗️ 完整布局 - 包含头部、侧边栏、主内容区和页脚的完整页面结构
  • 📱 响应式设计 - 移动端和桌面端不同的布局适配
  • 🎨 高度可配置 - 支持自定义头部、侧边栏、页脚和主内容区的配置
  • 📚 文档友好 - 专为文档站点设计，支持侧边栏导航和目录结构
  • 🔧 灵活组合 - 可以选择性显示/隐藏头部、侧边栏、页脚等部分
  • 🌙 主题支持 - 完整支持明暗主题切换

基础用法

最简单的应用布局使用方式：

最基本的应用布局使用方式，包含侧边栏、头部、主内容区和页脚

应用布局示例
logo
简体中文
导航

欢迎使用应用布局

这是一个包含侧边栏、头部和页脚的完整布局示例。

应用布局适合用于文档站点、管理后台等场景。

              ---
import { AppLayout, Container } from '@coffic/cosy-ui';
import type { ISidebarItem } from '@coffic/cosy-ui';

const sidebarItems: ISidebarItem[] = [
  {
    text: '入门',
    href: '/docs/getting-started',
    items: [
      { href: '/docs/getting-started', text: '快速开始' },
      { href: '/docs/installation', text: '安装' },
    ],
  },
  {
    text: '组件',
    href: '/docs/components',
    items: [
      { href: '/docs/components/button', text: 'Button 按钮' },
      { href: '/docs/components/card', text: 'Card 卡片' },
    ],
  },
];
---

<AppLayout
  metaConfig={{
    title: '应用布局示例',
    description: '这是一个应用布局的示例页面',
    keywords: '布局,示例,应用布局',
    author: 'CofficLab',
    robots: 'noindex,nofollow',
  }}
  sidebarConfig={{
    sidebarItems: sidebarItems,
  }}
  headerConfig={{
    height: 'md',
  }}
  footerConfig={{
    siteName: '我的文档站点',
    homeLink: '/',
    slogan: '简单而强大的组件库',
    company: 'CofficLab',
    copyright: '保留所有权利',
    inspirationalSlogan: '让开发更加愉悦',
  }}
  mainContentConfig={{
    padding: 'md',
    verticalPadding: '4xl',
  }}>
  <Container size="lg">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">欢迎使用应用布局</h1>
    <p class="cosy:mb-2">这是一个包含侧边栏、头部和页脚的完整布局示例。</p>
    <p>应用布局适合用于文档站点、管理后台等场景。</p>
  </Container>
</AppLayout>

使用示例

基本配置

---
import { AppLayout } from '@coffic/cosy-ui';

const sidebarItems = [
  {
    text: '入门',
    href: '/docs/getting-started',
    items: [
      { href: '/docs/getting-started', text: '快速开始' },
      { href: '/docs/installation', text: '安装' },
    ],
  },
  {
    text: '组件',
    href: '/docs/components',
    items: [
      { href: '/docs/components/button', text: 'Button 按钮' },
      { href: '/docs/components/card', text: 'Card 卡片' },
    ],
  },
];
---

<AppLayout
  metaConfig={{
    title: '文档标题',
    description: '文档描述'
  }}
  sidebarConfig={{
    sidebarItems: sidebarItems
  }}
>
  <h1>文档内容</h1>
  <p>这是文档的主要内容</p>
</AppLayout>

完整配置示例

<AppLayout
  metaConfig={{
    title: '我的文档站点',
    description: '一个功能完整的文档站点',
    keywords: '文档,组件库,教程',
    author: 'Your Name',
    robots: 'index,follow',
  }}
  sidebarConfig={{
    sidebarItems: sidebarItems,
  }}
  headerConfig={{
    height: 'lg',
  }}
  footerConfig={{
    siteName: '我的文档站点',
    homeLink: '/',
    slogan: '简单而强大的组件库',
    company: 'My Company',
    copyright: '2024 版权所有',
    inspirationalSlogan: '让开发更加愉悦',
    socialLinks: [
      'https://github.com/myorg/myrepo',
      'https://twitter.com/myorg'
    ],
  }}
  mainContentConfig={{
    padding: 'lg',
  }}
  showHeader={true}
  showSidebar={true}
  showFooter={true}
>
  <div class="prose">
    <h1>欢迎使用文档系统</h1>
    <p>这是一个完整的文档布局示例...</p>
  </div>
</AppLayout>

隐藏某些部分

<!-- 只显示主内容，隐藏其他部分 -->
<AppLayout
  metaConfig={{
    title: '简洁页面',
    description: '只有主内容的简洁页面'
  }}
  showHeader={false}
  showSidebar={false}
  showFooter={false}
>
  <div class="hero min-h-screen bg-base-200">
    <div class="hero-content text-center">
      <h1 class="text-5xl font-bold">Hello world!</h1>
    </div>
  </div>
</AppLayout>

Props 参考

AppLayout Props

属性类型必需默认值描述
metaConfigIMetaConfig✅-页面元数据配置
sidebarConfigISidebarConfig❌-侧边栏配置
headerConfigIHeaderConfig❌-头部配置
footerConfigIFooterConfig❌-页脚配置
mainContentConfigIMainContentConfig❌-主内容区配置
showHeaderboolean❌true是否显示头部
showSidebarboolean❌true是否显示侧边栏
showFooterboolean❌true是否显示页脚
debugboolean❌false是否启用调试模式
classstring❌-自定义类名
class:listany❌-类名列表

IMetaConfig 接口

interface IMetaConfig {
  title: string;           // 页面标题
  description: string;     // 页面描述
  keywords?: string;       // 关键词
  author?: string;         // 作者
  robots?: string;         // 搜索引擎爬虫指令
  head?: astroHTML.JSX.Element; // 自定义头部内容
  favicon?: string;        // 网站图标
}

ISidebarConfig 接口

interface ISidebarConfig {
  sidebarItems: ISidebarItem[]; // 侧边栏导航项
}

interface ISidebarItem {
  text: string;            // 显示文本
  href: string;            // 链接地址
  items?: ISidebarItem[];  // 子项目
}

IHeaderConfig 接口

interface IHeaderConfig {
  height?: 'sm' | 'md' | 'lg'; // 头部高度
}

IFooterConfig 接口

interface IFooterConfig {
  siteName?: string;           // 站点名称
  homeLink?: string;           // 首页链接
  slogan?: string;             // 站点口号
  company?: string;            // 公司名称
  copyright?: string;          // 版权信息
  inspirationalSlogan?: string; // 激励口号
  socialLinks?: string[];      // 社交媒体链接
}

IMainContentConfig 接口

interface IMainContentConfig {
  padding?: 'none' | 'sm' | 'md' | 'lg'; // 内边距大小
}

布局效果

移动端布局

+------------------+
|     Header       |
+------------------+
| Sidebar (1 line) |
+------------------+
|                  |
|   Main Content   |
|                  |
|                  |
+------------------+
|     Footer       |
+------------------+

桌面端布局

+------------------+
|      Header      |
+--------+---------+
|        |         |
|Sidebar | Content |
|        |         |
|        |         |
+--------+---------+
|      Footer      |
+------------------+

使用场景

1. 文档站点

<AppLayout
  metaConfig={{
    title: '组件库文档',
    description: '完整的组件库使用文档'
  }}
  sidebarConfig={{
    sidebarItems: documentationItems
  }}
>
  <div class="prose max-w-none">
    <!-- 文档内容 -->
  </div>
</AppLayout>

2. 博客网站

<AppLayout
  metaConfig={{
    title: '我的博客',
    description: '分享技术和生活'
  }}
  sidebarConfig={{
    sidebarItems: blogCategories
  }}
  footerConfig={{
    socialLinks: ['https://github.com/username']
  }}
>
  <article class="prose">
    <!-- 博客文章内容 -->
  </article>
</AppLayout>

3. 知识库

<AppLayout
  metaConfig={{
    title: '企业知识库',
    description: '内部知识管理系统'
  }}
  sidebarConfig={{
    sidebarItems: knowledgeCategories
  }}
  showFooter={false}
>
  <!-- 知识库内容 -->
</AppLayout>

最佳实践

1. 导航结构设计

  • 层次清晰 - 使用合理的导航层级，不超过3层
  • 分类明确 - 相关内容归类到同一分组
  • 命名一致 - 使用一致的命名规范

2. 内容组织

  • 结构化内容 - 使用标题、段落、列表等结构化元素
  • 适当留白 - 合理使用间距提升阅读体验
  • 响应式考虑 - 确保内容在各种设备上的可读性

3. 性能优化

  • 懒加载 - 大型内容考虑懒加载
  • 图片优化 - 合理压缩和格式化图片
  • 缓存策略 - 利用浏览器缓存机制

样式定制

AppLayout 组件遵循 cosy-ui 的样式规范：

  • 使用 daisyUI 的布局和组件类
  • Tailwind CSS 类需要添加 cosy: 前缀
  • 支持完整的响应式设计
  • 内置明暗主题支持
/* 自定义样式示例 */
.custom-layout {
  background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
}