# @djangocfg/layouts 中文文档

规范地址：https://npmcn.com/package/%40djangocfg/layouts/

版本：2\.1\.653
npm 元数据更新时间：2026-11-12T05:24:00.548Z
中文译文更新时间：2026-11-12T12:12:00.284Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40djangocfg/layouts
原文对照：https://npmcn.com/package/%40djangocfg/layouts/?lang=original
项目主页：https://djangocfg.com/
源码仓库：https://github.com/markolofsen/django-cfg

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：967 kB，333 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：swr ^2\.3\.7，zod ^4\.3\.6，next ^16\.4\.5，react ^19\.0\.0，moment ^2\.30\.1，sonner ^2\.0\.7，consola ^3\.4\.2，p-retry ^7\.0\.0，zustand ^5\.0\.0，next-intl ^4\.9\.1，react-dom ^19\.0\.0，tailwindcss ^4\.1\.18，lucide-react ^1\.68\.0，@djangocfg/api ^2\.1\.653，@djangocfg/i18n ^2\.1\.653，react-hook-form ^7\.69\.0，@djangocfg/ui-core ^2\.1\.653，@djangocfg/devtools ^2\.1\.653，@hookform/resolvers ^5\.2\.2 \|\| ^7\.0\.2，tailwindcss-animate ^1\.0\.7，@djangocfg/analytics ^2\.1\.653
- 首次发布：2025-10-13T00:46:58.081Z
- 最新版本发布：2026-11-12T05:24:00.337Z
- 近 30 天下载量：15306（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：671（近 12 个月 629 个）

## 中文简介

Next.js 的简单而直截了当的布局组件 - 用道具导入和使用

## 安装

```sh
npm install @djangocfg/layouts
```

也可以使用：`pnpm add @djangocfg/layouts`、`yarn add @djangocfg/layouts`、`bun add @djangocfg/layouts`

## README

![@djangocfg/layouts](https://raw.githubusercontent.com/markolofsen/assets/main/libs/djangocfg/layouts.webp)

# @djangocfg/ 传出

布局、应用程序外壳和提供者 **Next.js App路由器**部分内容 **[强哥CFG](https://djangocfg.com/)**。 。 。 .

```bash
pnpm add @djangocfg/layouts
```

```css
/* Golden path — bundles Tailwind + tokens + base + utilities, layer-safe */
@import "@djangocfg/ui-core/styles/full";
@import "@djangocfg/layouts/styles";
```

端点 : `@djangocfg/ui-core`, React 19, Next.js 16+,"尾风CSS 4.

* * *

## 快开始

两项责任,分开处理:

1.  **供应商** - 挂载 `BaseApp` ONCE 在应用根(主题、认证、i18n、SWR、, 监视器,土司。 框架-可知性(Wails/Vite中的工作也).
2.  **每节外壳** -每个下一个.js **路由组 `layout.tsx`** 进口 匹配 shell (`PrivateLayout` 编号 : `PublicLayout`)并自相传出. 没有运行时间布局路由器,没有 `enabledPath` 匹配 .

```tsx
// app/[locale]/layout.tsx — providers, once
import { BaseApp } from '@djangocfg/layouts';
<BaseApp project="my-app" theme={{ defaultTheme: 'system' }}
         auth={{ apiUrl: '…', routes: { auth: '/auth' } }}
         i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>
  {children}
</BaseApp>

// app/[locale]/(pages)/private/layout.tsx — the private shell
import { PrivateLayout } from '@djangocfg/layouts';
<PrivateLayout sidebar={sidebar} header={header}>{children}</PrivateLayout>
```

见 [**BaseApp 读取**](https://npmcn.com/package/%40djangocfg/layouts/src/layouts/AppLayout/README.md) 全文 供应商表面和Next.js vs Wails 接线,以及演示应用 (单位:千美元)`apps/demo/app/_layouts`完全参考.

> **过 `i18n`** 使用时 `next-intl` 或任何本地化的前置路由,所以 链接桥和本地化切换器解析正确.

* * *

## 布局

| 构成部分 | 使用 | 文档 |
| --- | --- | --- |
| **`PublicLayout`** | 销售/文件。 导航槽( R)`Floating`编号 :`Flush`编号 :`Minimal`) + foper + locale + 认证控件. | [读取](https://npmcn.com/package/%40djangocfg/layouts/src/layouts/PublicLayout/README.md) |
| **`PrivateLayout`** | 经认证的应用外壳——侧边栏(可拼接的图标栏杆,手风琴组,铁道/地上/CTA插槽)+弹出式账号页脚. | [读取](https://npmcn.com/package/%40djangocfg/layouts/src/layouts/PrivateLayout/README.md) |
| **`AuthLayout`** | 注册/注册流. 基于 shell 的 : `centered` (违约)或 `split` (两栏台式计算机). | [读取](https://npmcn.com/package/%40djangocfg/layouts/src/layouts/AuthLayout/README.md) |

> **管理员** 不是单独的布局——使用 `PrivateLayout` 有管理员 `sidebar` 在您的配置 `app/.../admin/layout.tsx`。 。 。 .

### 仅限工作人员的路线组

`PrivateLayout`警卫检查会话 表面也需要 工作人员,增加 `requireStaff` (从 `useAuth().isAdminUser`,则 `is_staff || is_superuser` 折叠 :

```tsx
<PrivateLayout sidebar={sidebar} header={header} requireStaff>{children}</PrivateLayout>
```

一个签到的编外用户 `ForbiddenState` 而不是壳 - **没有a 重定向到认证窗体**: 它们已经签入, 所以再次签入 无法授予此特权, 既然守护者首先保存当前 URL, a 重定向会回到这里 过 `forbiddenFallback` 供应自己 屏幕。 细节 : [二等兵拉尤特读取](https://npmcn.com/package/%40djangocfg/layouts/src/layouts/PrivateLayout/README.md)。 。 。 .

### `AuthLayout` 弹壳

两个可切换的可视变体 `variant` 道具 :

-   **`centered`** ——Apple HIG风格:无相框,中心形式,动画发光背景.
-   **`split`** ——桌面上双列卡(形式左,可自定义的侧边栏右);移动上单列. 覆盖+模糊的背景图像/梯度 `background` 道具 (英语).

```tsx
// Split variant with background image and testimonial sidebar
<AuthLayout
  variant="split"
  background={{ imageUrl: '/bg.jpg', overlay: 'hsl(var(--background) / 0.6)', blur: '8px' }}
  sidebar={<Testimonial />}
>
  {/* optional custom header, shown only on identifier step */}
</AuthLayout>
```

结构 : `AuthShell` 发往 `CenteredShell` 或者说 `SplitShell`。通过扩展添加新变量 `AuthShellVariant` 并创建新的 shell 组件.

### `ProfileLayout`

```tsx
<ProfileLayout enable2FA enableDeleteAccount tabs={tabs} slots={slots} />
```

| Prop | 作用 |
| --- | --- |
| `enable2FA` | 显示 2FA 管理的安全标签 . |
| `enableDeleteAccount` | 显示删除账户 `⋯` 菜单. |
| `tabs` | 额外 `ProfileTab[]` 内置后附后. |
| `slots.headerBadge` 编号 : `headerMenuItems` 编号 : `headerAfter` 编号 : `footer` | 在相机行,菜单,和标签体周围的槽内容. |

* * *

## 主题

主题由主机应用程序的 CSS 导入所选择. `BaseApp` 仅拥有 浅/暗类,而不在运行时注入符号样式:

```css
@import "@djangocfg/ui-core/styles/full";
@import "@djangocfg/ui-core/styles/presets/macos";
```

软件包导出 `ThemeStylePresetId` 财务报告和审定财务报表 `THEME_STYLE_PRESET_ORDER` 页:1 元数据和选择器。 预设的符号只活在静态 CSS 中 文件由 `@djangocfg/ui-core`。 。 。 .

* * *

## i18n (英语)

```tsx
import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
import { routing } from '@djangocfg/nextjs/i18n/routing';

const { locale, locales, changeLocale } = useLocaleSwitcher();
<BaseApp i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</BaseApp>
```

何时 `routing` 已经设定, `BaseApp` 挂载一个地方意识 `<Link>` 适配器,所以每个布局后接的链接都保留活性地块前缀. 放弃它用于默认本地化的应用程序 .

* * *

## 监视器调试( D)

`baseApp.project` 启用 `window.monitor`。调试面板 : `Cmd+D` 或者说 `?debug=1`。 。 。 .

### `MonitorBoundary`

自动报告错误到的错误边界 `@djangocfg/devtools`。在页面/放出级别上使用,这样会出人意料地使出错降落在您的后端仪表板上.

```tsx
import { MonitorBoundary } from '@djangocfg/layouts';

export default function Layout({ children }) {
  return (
    <MonitorBoundary variant="fullscreen" name="root-layout">
      {children}
    </MonitorBoundary>
  );
}

// Per-section, non-fatal:
<MonitorBoundary variant="card" name="dashboard-stats" resetKeys={[pathname]}>
  <StatsPanel />
</MonitorBoundary>

// Opt out of reporting (e.g. third-party iframe noise):
<MonitorBoundary reportToMonitor={false} variant="silent">
  <EmbeddedWidget />
</MonitorBoundary>
```

环绕 `Boundary` 从 `@djangocfg/ui-core` - 一样 `variant`编号 :`fallback`编号 :`resetKeys` API, 加自动 `FrontendMonitor.capture(...)`。 。 。 .

> **一个顶级边界.** `BaseApp` 已挂载全应用程序崩溃 边界(UiProviders' independent-one, feed an i18n fallback)——不要包装 整个应用程序的第二个 使用 `MonitorBoundary` 页:1 **每节** 孤立(所以一个面板的崩溃不取出页面),而不是重复 根边框。 所有边界都共享一个ui-core `Boundary` 抓起来.

对于不报告到后端的本地 UI 部件, 使用 `Boundary` 从 `@djangocfg/ui-core` 直接说.

## 分析和认证漏斗

`BaseApp` 挂载第一当事方 `AnalyticsProvider` 一次和桥梁事件 从 `@djangocfg/api/auth`。 。 。 . `AuthLayout` 添加一个小 `layouts.auth.step_viewed` 面包屑在可见的每个步骤; 服务器确认 `auth_login_success` 事件仍然是真理的转换来源.

对于定制产品目标,使用 `useAnalytics().event(name, props)` 从 `@djangocfg/analytics`。参见该软件包的 README 用于输入事件目录, 浏览器外观, 和扩展模式 。 不要创建第二个路由监听器或 从布局直接发送分析.

* * *

## 片断

小表面显示主机挂载一次, 导出自 `@djangocfg/layouts` 财务报告和审定财务报表 `@djangocfg/layouts/snippets`数字 :

| 导出 | 什麽 |
| --- | --- |
| `AuthDialog`, (中文(简体) ), `useAuthDialog` | 全球登录对话框 . `BaseApp` 挂载它 `auth` 启用; 任何东西都可以打开, 包括一个只有 `dialogStore`。 。 。 . |
| `TwoFactorSetup` | 一个设置页面的 Enrol 流程: QR,确认代码,备份代码. |
| `TwoFactorChallengeDialog` | 当登录步骤需要2FA时,打开页面的代码提示. `AuthLayout` 把它挂起来. |
| 分析 | 从 `@djangocfg/analytics` 旧进口;新编码进口该套件(见上文分析). |
| `Breadcrumbs` | 面包屑从 `items`,或者当没有给出时从当前路径. |

## 概念和决定

版式如何组合(滚动模型、安全区标志、PWA/移动行为、决定日志): [`@docs/`](https://npmcn.com/package/%40djangocfg/layouts/@docs/README.md)。 。 。 .

## 故事和测试

`@djangocfg/layouts/testing` 只用于故事书和测试: `MockAuthProvider` 财务报告和审定财务报表 `buildMockUser` 给 `useAuth()` 固定会议, `MockAuthFormProvider` 和步骤组件上载一个没有满分的登录步骤 `AuthLayout`不从生产代码导入它.

* * *

## 软件包出口

| 路径 | 目录 |
| --- | --- |
| `@djangocfg/layouts` | 巴雷尔. |
| `@djangocfg/layouts/layouts` | 布局组件 . |
| `@djangocfg/layouts/snippets` | `AuthDialog`2FA的表面, `Breadcrumbs`, (中文(简体) ), `Devtools`,分析再出口. |
| `@djangocfg/layouts/components` | 杂项+ `ErrorLayout`, (中文(简体) ), `RedirectPage`。 。 。 . |
| `@djangocfg/layouts/utils` | 路径匹配和侧边栏导航帮助器,登录器. |
| `@djangocfg/layouts/pages` | 页面模板`legal`) (中文(简体) ). |
| `@djangocfg/layouts/configurator` | JSON 斯克马斯 `<JsonSchemaForm>`\- 驱动配置器UI。 与 `@djangocfg/widget-forms`。 。 。 . |
| `@djangocfg/layouts/configurator/private` | 这个 `PrivateLayout` 化相相自相为相. |
| `@djangocfg/layouts/testing` | 故事书和测试助手;不用于生产代码. |
| `@djangocfg/layouts/styles` | 基础CSS. |
| `@djangocfg/layouts/styles/dashboard` | (原始内容存档于2018-09-29). Dashboard shell CSS. |

扩展名 : `@djangocfg/ext-newsletter`, (中文(简体) ), `ext-knowbase`, (中文(简体) ), `ext-leads`, (中文(简体) ), `ext-payments`, (中文(简体) ), `ext-support`,, , , , , , , ,

## 许可证

麻省理工学院 - [强哥CFG](https://djangocfg.com/)

## 常见问题

### @djangocfg/layouts 是什么？

Next\.js 的简单而直截了当的布局组件 - 用道具导入和使用

### 如何安装 @djangocfg/layouts？

在项目目录运行 npm install @djangocfg/layouts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：swr（^2\.3\.7）、zod（^4\.3\.6）、next（^16\.4\.5）、react（^19\.0\.0）、moment（^2\.30\.1）、sonner（^2\.0\.7）、consola（^3\.4\.2）、p-retry（^7\.0\.0）、zustand（^5\.0\.0）、next-intl（^4\.9\.1）、react-dom（^19\.0\.0）、tailwindcss（^4\.1\.18）、lucide-react（^1\.68\.0）、@djangocfg/api（^2\.1\.653）、@djangocfg/i18n（^2\.1\.653）、react-hook-form（^7\.69\.0）、@djangocfg/ui-core（^2\.1\.653）、@hookform/resolvers（^5\.2\.2 \|\| ^7\.0\.2）、tailwindcss-animate（^1\.0\.7）、@djangocfg/analytics（^2\.1\.653）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @djangocfg/layouts 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @djangocfg/layouts 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @djangocfg/layouts 可以商用吗？

@djangocfg/layouts 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @djangocfg/layouts 的下载量有多少？

根据 npm 官方下载统计，@djangocfg/layouts 在 2026/10/13 – 2026/11/11 这 30 天内被下载 15,306 次，日均约 510 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @djangocfg/layouts 还在维护吗？

最新版本 2\.1\.653 发布于 2026/11/12（今天）；至今共发布 671 个版本，其中过去 12 个月发布了 629 个；首次发布于 2025/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。