logo
简体中文

导航菜单

文档

layout

App Layout

简介

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

案例

    入门

    欢迎使用应用布局

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

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

    © 2025 CofficLab - 保留所有权利

      入门

      欢迎使用应用布局

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

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

      © 2025 CofficLab - 保留所有权利

      ---



import * as astroI18n from "astro:i18n";
import type { ISidebarItem } from "@coffic/cosy-ui";
import { AppLayout, Container, Heading } 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
  bodyOnly={true}
  metaConfig={{
    title: '应用布局示例',
    description: '这是一个应用布局的示例页面',
    keywords: '布局,示例,应用布局',
    author: 'CofficLab',
    robots: 'noindex,nofollow',
    background: 'primary/20',
  }}
  sidebarConfig={{
    sidebarItems: sidebarItems,
  }}
  headerConfig={{
    height: 'md',
    sticky: false,
    astroI18n: astroI18n,
  }}
  footerConfig={{
    siteName: '我的文档站点',
    homeLink: '/',
    slogan: '简单而强大的组件库',
    company: 'CofficLab',
    inspirationalSlogan: '让开发更加愉悦',
  }}
  mainContentConfig={{
    padding: 'md',
    verticalPadding: '4xl',
  }}
  bodyOnly={true}>
  <Container width="lg">
    <Heading level={1} margin="none">欢迎使用应用布局</Heading>
    <p>这是一个包含侧边栏、头部和页脚的完整布局示例。</p>
    <p>应用布局适合用于文档站点、管理后台等场景。</p>
  </Container>
</AppLayout>

      ---



import * as astroI18n from 'astro:i18n';
import type { ISidebarItem } from '@coffic/cosy-ui';
import { AppLayout, appLayoutProps, Container, Heading } 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 卡片' },
        ],
    },
];

const layout = appLayoutProps()
    .bodyOnly(true)
    .metaConfig({
        title: '应用布局示例',
        description: '这是一个应用布局的示例页面',
        keywords: '布局,示例,应用布局',
        author: 'CofficLab',
        robots: 'noindex,nofollow',
        background: 'primary/20',
    })
    .sidebarConfig({ sidebarItems })
    .headerConfig({ height: 'md', sticky: false, astroI18n })
    .footerConfig({
        siteName: '我的文档站点',
        homeLink: '/',
        slogan: '简单而强大的组件库',
        company: 'CofficLab',
        inspirationalSlogan: '让开发更加愉悦',
    })
    .mainContentConfig({ padding: 'md', verticalPadding: '4xl' })
    .build();
---

<AppLayout {...layout}>
    <Container width="lg">
        <Heading level={1} margin="none">欢迎使用应用布局</Heading>
        <p>这是一个包含侧边栏、头部和页脚的完整布局示例。</p>
        <p>应用布局适合用于文档站点、管理后台等场景。</p>
    </Container>
</AppLayout>

      Props

      enableClientRouter

      控制是否启用 Astro 的 ClientRouter，用于类似 SPA 的页面切换。

      • 默认值：true
      • 设为 false 时使用整页跳转（非客户端路由）。

      footerConfig

      页脚配置，包含站点信息、社交媒体链接等。详细配置选项请参考 Footer 组件文档。

      headerConfig

      头部配置，传递给AppHeader组件。详细配置选项请参考 Header 组件文档。

      loadingDelay

      加载中界面延迟显示的时间（毫秒），用于避免闪烁（默认 100）。

      mainContentConfig

      主内容区域配置：

      • padding：内边距
      • verticalPadding：垂直内边距
      • fullWidth：是否全宽

      metaConfig

      元数据配置：

      • title：页面标题
      • description：页面描述
      • keywords：页面关键词
      • author：作者
      • robots：爬虫策略
      • favicon：站点图标
      • basePath：基础路径（用于二级目录部署）
      • siteName：站点名称
      • lang：页面语言（默认 zh-CN）
      • viewport：是否包含 viewport 元标签（默认 true）
      • customStyles：自定义样式（注入到 head）
      • head：自定义头部内容（HTML）
      • background：预设背景色
      • theme：主题 ID

      showFooter

      是否显示页脚（true/false）。

      showHeader

      是否显示头部（true/false）。

      showSidebar

      是否显示侧边栏（true/false）。

      sidebarConfig

      侧边栏配置，包含导航项等。

      侧边栏配置

      ---



import type { ISidebarItem } from "@coffic/cosy-ui";
import { Heading, Sidebar } from "@coffic/cosy-ui";

const sidebarItems: ISidebarItem[] = [
	{
		text: "侧边栏配置",
		href: "/sidebar",
		items: [
			{ href: "/sidebar/basic", text: "基础侧边栏" },
			{ href: "/sidebar/nested", text: "嵌套菜单" },
			{ href: "/sidebar/custom", text: "自定义样式" },
		],
	},
	{
		text: "组件库",
		href: "/components",
		items: [
			{ href: "/components/buttons", text: "按钮组件" },
			{ href: "/components/forms", text: "表单组件" },
			{ href: "/components/layout", text: "布局组件" },
			{ href: "/components/navigation", text: "导航组件" },
		],
	},
	{
		text: "文档",
		href: "/docs",
		items: [
			{ href: "/docs/getting-started", text: "快速开始" },
			{ href: "/docs/installation", text: "安装指南" },
			{ href: "/docs/tutorial", text: "教程" },
			{ href: "/docs/api", text: "API参考" },
		],
	},
];
---

<Sidebar sidebarItems={sidebarItems} />

      theme

      设置布局的主题。支持的主题包括：

      • light
      • dark
      • corporate
      • lemonade
      • nord
      • business
      • luxury

      默认值为 default。

      Slots

      background

      自定义背景层（最低层，z-index: 0）。用于创建全屏背景效果，如渐变、图片、装饰元素等。背景层固定定位在视口，不随内容滚动。

      💡 查看在线演示 - 体验完整的自定义背景功能

      使用场景：

      • 渐变背景：创建吸引眼球的渐变效果
      • 背景图片：添加品牌相关的背景图片
      • 装饰元素：添加模糊圆圈、几何图案等装饰
      • 动画背景：Canvas 动画、粒子效果等
      • 视频背景：全屏视频背景

      示例：

      <AppLayout
  metaConfig={{ title: "我的应用" }}
  showHeader={false}
  showSidebar={false}
>
  <!-- 自定义背景层 -->
  <div slot="background" class="cosy:fixed cosy:inset-0 cosy:bg-gradient-to-br cosy:from-blue-600 cosy:to-purple-800">
    <!-- 装饰性模糊元素 -->
    <div class="cosy:absolute cosy:top-10 cosy:left-10 cosy:w-96 cosy:h-96 cosy:bg-white/10 cosy:rounded-full cosy:blur-3xl"></div>
    <div class="cosy:absolute cosy:bottom-10 cosy:right-10 cosy:w-96 cosy:h-96 cosy:bg-white/10 cosy:rounded-full cosy:blur-3xl"></div>
  </div>

  <!-- 主内容（需要自行处理背景透明度） -->
  <div class="cosy:bg-white/80 cosy:backdrop-blur cosy:p-8 cosy:rounded-lg">
    <h1>页面内容</h1>
    <p>背景层会在所有内容下方渲染</p>
  </div>
</AppLayout>

      技术特性：

      • 固定定位（position: fixed），不随内容滚动
      • 最低 z-index（z-index: 0），在所有内容下方
      • 默认 pointer-events: none，不影响用户交互
      • 完全自定义，支持任何 HTML/CSS/Canvas

      注意事项：

      • 背景层会覆盖整个视口（inset: 0）
      • 主内容需要适当的背景色和透明度以保持可读性
      • 使用 CSS 渐变优于图片（性能更好）
      • 避免过度使用阴影和模糊效果（影响性能）
      • 如果需要交互元素，需在 background slot 内容中设置 pointer-events: auto

      default

      主内容区域，用于放置页面的主要内容。

      默认插槽示例

        快速开始

        默认插槽示例

        这是通过默认插槽放置的主要内容。

        内容区域

        你可以在这里放置任何内容，包括文本、图片、组件等。

        功能特性

        • • 响应式布局
        • • 侧边栏导航
        • • 头部导航

        使用场景

        • • 文档站点
        • • 博客系统
        • • 知识库

        © 2025 Cosy UI - 保留所有权利

        ---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "默认插槽示例",
	description: "展示如何使用默认插槽放置主要内容",
	keywords: "AppLayout, 默认插槽, default slot",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div class="cosy:p-6">
    <h1 class="cosy:text-3xl cosy:font-bold cosy:mb-6">默认插槽示例</h1>
    <div class="cosy:space-y-4">
      <p class="cosy:text-lg cosy:text-gray-700">
        这是通过默认插槽放置的主要内容。
      </p>
      <div class="cosy:bg-gray-100 cosy:p-4 cosy:rounded-lg">
        <h2 class="cosy:text-xl cosy:font-semibold cosy:mb-2">内容区域</h2>
        <p class="cosy:text-gray-600">
          你可以在这里放置任何内容，包括文本、图片、组件等。
        </p>
      </div>
      <div class="cosy:grid cosy:grid-cols-2 cosy:gap-4 cosy:mt-6">
        <div class="cosy:bg-blue-50 cosy:p-4 cosy:rounded-lg">
          <h3 class="cosy:font-semibold cosy:mb-2">功能特性</h3>
          <ul class="cosy:text-sm cosy:space-y-1">
            <li>• 响应式布局</li>
            <li>• 侧边栏导航</li>
            <li>• 头部导航</li>
          </ul>
        </div>
        <div class="cosy:bg-green-50 cosy:p-4 cosy:rounded-lg">
          <h3 class="cosy:font-semibold cosy:mb-2">使用场景</h3>
          <ul class="cosy:text-sm cosy:space-y-1">
            <li>• 文档站点</li>
            <li>• 博客系统</li>
            <li>• 知识库</li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</AppLayout>

        自定义全局 header（优先级最高）。当提供此 slot 时，会替代内置的 AppHeader，并横跨整个页面宽度（不受侧边栏限制）。

        💡 查看在线演示 - 体验完整的自定义 header 功能

        使用场景：

        • 品牌定制：需要完全自定义的 header 设计
        • 特殊交互：实现透明渐变、滚动变化等效果
        • 复杂布局：需要特殊的布局结构
        • 第三方集成：集成第三方 header 组件

        示例：

        <AppLayout
  metaConfig={{ title: "我的应用" }}
  sidebarConfig={{ sidebarItems: [] }}
>
  <!-- 自定义 header，横跨整个页面宽度 -->
  <header slot="header" class="cosy:bg-primary cosy:text-white cosy:p-4">
    <div class="cosy:container cosy:mx-auto cosy:flex cosy:items-center cosy:justify-between">
      <h1 class="cosy:text-xl cosy:font-bold">我的品牌</h1>
      <nav class="cosy:flex cosy:gap-4">
        <a href="/" class="cosy:hover:underline">首页</a>
        <a href="/docs" class="cosy:hover:underline">文档</a>
      </nav>
    </div>
  </header>

  <!-- 主内容 -->
  <h1>页面内容</h1>
</AppLayout>

        注意事项：

        • 自定义 header 的优先级最高，会覆盖 showHeader 和 headerConfig 配置
        • 建议使用容器（如 cosy:container cosy:mx-auto）来限制内容宽度
        • 需要自行处理响应式布局和样式
        • z-index 建议设置为 40-50 之间

        自定义全局 footer（优先级最高）。当提供此 slot 时，会替代内置的 Footer，并横跨整个页面宽度（不受侧边栏限制）。

        💡 查看在线演示 - 体验完整的自定义 footer 功能

        使用场景：

        • 品牌定制：需要完全自定义的 footer 设计
        • 特殊交互：实现复杂的布局结构
        • 多列布局：需要在 footer 中实现多列内容
        • 第三方集成：集成第三方 footer 组件

        示例：

        <AppLayout
  metaConfig={{ title: "我的应用" }}
  sidebarConfig={{ sidebarItems: [] }}
>
  <!-- 主内容 -->
  <h1>页面内容</h1>

  <!-- 自定义 footer，横跨整个页面宽度 -->
  <footer slot="footer" class="cosy:bg-base-200 cosy:p-8">
    <div class="cosy:container cosy:mx-auto">
      <div class="cosy:grid cosy:grid-cols-1 cosy:md:grid-cols-3 cosy:gap-8">
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">关于我们</h3>
          <p class="cosy:text-sm">我们致力于提供最好的产品和服务</p>
        </div>
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">快速链接</h3>
          <ul class="cosy:space-y-2">
            <li><a href="/docs" class="cosy:link cosy:link-hover">文档</a></li>
            <li><a href="/blog" class="cosy:link cosy:link-hover">博客</a></li>
          </ul>
        </div>
        <div>
          <h3 class="cosy:font-bold cosy:text-lg cosy:mb-4">联系方式</h3>
          <p class="cosy:text-sm">email@example.com</p>
        </div>
      </div>
      <div class="cosy:mt-8 cosy:pt-8 cosy:border-t cosy:text-center cosy:text-sm">
        <p>&copy; 2025 我的公司. All rights reserved.</p>
      </div>
    </div>
  </footer>
</AppLayout>

        注意事项：

        • 自定义 footer 的优先级最高，会覆盖 showFooter 和 footerConfig 配置
        • 建议使用容器（如 cosy:container cosy:mx-auto）来限制内容宽度
        • 需要自行处理响应式布局和样式
        • 与 header slot 保持一致的设计模式

        导航栏开始位置的内容，传递给AppHeader组件。

        导航栏开始位置插槽示例
        C

        Cosy UI

          快速开始

          导航栏开始位置插槽

          这个示例展示了如何使用 navbar-start 插槽在导航栏开始位置添加自定义内容。

          可以看到导航栏左侧显示了自定义的 Logo 和标题。

          © 2025 Cosy UI - 保留所有权利

          ---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏开始位置插槽示例",
	description: "展示如何使用 navbar-start 插槽自定义导航栏开始位置的内容",
	keywords: "AppLayout, navbar-start, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-start" class="cosy:flex cosy:items-center cosy:gap-2">
    <div
      class="cosy:w-8 cosy:h-8 cosy:bg-primary cosy:rounded-lg cosy:flex cosy:items-center cosy:justify-center">
      <span class="cosy:text-white cosy:font-bold">C</span>
    </div>
    <h1 class="cosy:text-xl cosy:font-bold cosy:text-primary">Cosy UI</h1>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏开始位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-start 插槽在导航栏开始位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏左侧显示了自定义的 Logo 和标题。
    </p>
  </div>
</AppLayout>

          导航栏中间位置的内容，传递给AppHeader组件。

          导航栏中间位置插槽示例

            快速开始

            导航栏中间位置插槽

            这个示例展示了如何使用 navbar-center 插槽在导航栏中间位置添加自定义内容。

            可以看到导航栏中间显示了自定义的导航链接。

            © 2025 Cosy UI - 保留所有权利

            ---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏中间位置插槽示例",
	description: "展示如何使用 navbar-center 插槽自定义导航栏中间位置的内容",
	keywords: "AppLayout, navbar-center, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-center" class="cosy:flex cosy:gap-6">
    <a href="/docs" class="cosy:link cosy:link-hover cosy:font-medium">文档</a>
    <a href="/components" class="cosy:link cosy:link-hover cosy:font-medium"
      >组件</a
    >
    <a href="/examples" class="cosy:link cosy:link-hover cosy:font-medium"
      >示例</a
    >
    <a href="/blog" class="cosy:link cosy:link-hover cosy:font-medium">博客</a>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏中间位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-center 插槽在导航栏中间位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏中间显示了自定义的导航链接。
    </p>
  </div>
</AppLayout>

            导航栏结束位置的内容，传递给AppHeader组件。

            导航栏结束位置插槽示例

              快速开始

              导航栏结束位置插槽

              这个示例展示了如何使用 navbar-end 插槽在导航栏结束位置添加自定义内容。

              可以看到导航栏右侧显示了自定义的按钮组。

              © 2025 Cosy UI - 保留所有权利

              ---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "导航栏结束位置插槽示例",
	description: "展示如何使用 navbar-end 插槽自定义导航栏结束位置的内容",
	keywords: "AppLayout, navbar-end, 插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="navbar-end" class="cosy:flex cosy:items-center cosy:gap-3">
    <button class="cosy:btn cosy:btn-ghost cosy:btn-sm">登录</button>
    <button class="cosy:btn cosy:btn-primary cosy:btn-sm">注册</button>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">导航栏结束位置插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 navbar-end 插槽在导航栏结束位置添加自定义内容。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      可以看到导航栏右侧显示了自定义的按钮组。
    </p>
  </div>
</AppLayout>

              搜索模态框内容，当提供此slot时会显示搜索按钮，传递给AppHeader组件。

              搜索模态框插槽示例

                快速开始

                搜索模态框插槽

                这个示例展示了如何使用 modal-search 插槽添加搜索功能。

                当提供此插槽时，导航栏会自动显示搜索按钮，点击后打开搜索模态框。

                提示：点击导航栏右侧的搜索图标可以打开搜索模态框。

                © 2025 Cosy UI - 保留所有权利

                搜索

                热门搜索

                Button Card Layout Form
                ---



import { AppLayout } from "@coffic/cosy-ui";
import {
	defaultFooterConfig,
	defaultHeaderConfig,
	defaultMainContentConfig,
	defaultMetaConfig,
	defaultSidebarItems,
} from "./shared-config.ts";

const metaConfig = {
	...defaultMetaConfig,
	title: "搜索模态框插槽示例",
	description: "展示如何使用 modal-search 插槽添加搜索功能",
	keywords: "AppLayout, modal-search, 搜索插槽",
};
---

<AppLayout
  metaConfig={metaConfig}
  sidebarConfig={{
    sidebarItems: defaultSidebarItems,
  }}
  headerConfig={defaultHeaderConfig}
  footerConfig={defaultFooterConfig}
  mainContentConfig={defaultMainContentConfig}>
  <div slot="modal-search" class="cosy:space-y-4">
    <div class="cosy:form-control">
      <input
        type="text"
        placeholder="搜索文档..."
        class="cosy:input cosy:input-bordered cosy:w-full"
      />
    </div>
    <div class="cosy:flex cosy:gap-2">
      <button class="cosy:btn cosy:btn-primary cosy:btn-sm">搜索</button>
      <button class="cosy:btn cosy:btn-ghost cosy:btn-sm">清除</button>
    </div>
    <div class="cosy:divider"></div>
    <div class="cosy:space-y-2">
      <h3 class="cosy:font-semibold cosy:text-sm">热门搜索</h3>
      <div class="cosy:flex cosy:flex-wrap cosy:gap-2">
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Button</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Card</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Layout</span>
        <span class="cosy:badge cosy:badge-outline cosy:badge-sm">Form</span>
      </div>
    </div>
  </div>

  <div class="cosy:p-6">
    <h1 class="cosy:text-2xl cosy:font-bold cosy:mb-4">搜索模态框插槽</h1>
    <p class="cosy:text-gray-600">
      这个示例展示了如何使用 modal-search 插槽添加搜索功能。
    </p>
    <p class="cosy:text-gray-600 cosy:mt-2">
      当提供此插槽时，导航栏会自动显示搜索按钮，点击后打开搜索模态框。
    </p>
    <div class="cosy:mt-4 cosy:p-4 cosy:bg-blue-50 cosy:rounded-lg">
      <p class="cosy:text-sm cosy:text-blue-700">
        <strong>提示：</strong>点击导航栏右侧的搜索图标可以打开搜索模态框。
      </p>
    </div>
  </div>
</AppLayout>

                搜索