npm package: @mxmweb/zui-layouts
Description: 一个现代化的文档容器布局组件库，提供优雅的文档展示和导航体验。
Author: hanfeng_Zhang
Latest version: 1.4.1

# @mxmweb/zui-layouts

一个现代化的文档容器布局组件库，提供优雅的文档展示和导航体验。

## 特性

- 🎨 优雅的文档容器布局
- 📱 响应式设计，支持桌面和移动端
- 🌙 内置深色/浅色主题切换
- 📖 自动生成目录导航
- 🔍 智能滚动高亮
- 🎯 模块化导航系统
- 📝 支持 Markdown 渲染
- ⚡ 流畅的动画过渡
- 🔧 高度可配置



## 快速开始

### 安装

```bash
pnpm add @mxmweb/zui-layouts
```

### 基础用法

```tsx
import React from 'react';
import { DocmentContainer } from '@mxmweb/zui-layouts';
import Markdownit from '@mxmweb/slate';

const App = () => {
  const modules = [
    { key: 'home', label: '首页' },
    { key: 'docs', label: '文档' },
    { key: 'api', label: 'API' }
  ];

  const sidebarItems = [
    { id: 'intro', label: '介绍', group: '基础' },
    { id: 'install', label: '安装', group: '基础' },
    { id: 'usage', label: '使用', group: '指南' }
  ];

  return (
    <DocmentContainer
      headerLogo={<div>My Docs</div>}
      modules={modules}
      activeModuleKey="docs"
      onModuleChange={(key) => console.log('切换模块:', key)}
      sidebarItems={sidebarItems}
      activeSidebarId="intro"
      onSidebarItemClick={(item) => console.log('点击侧边栏:', item)}
      themes={[
        { key: 'light', label: '浅色' },
        { key: 'dark', label: '深色' }
      ]}
      activeThemeKey="light"
      onThemeChange={(key) => console.log('切换主题:', key)}
    >
      <Markdownit
        dataSource={{
          type: 'markdown',
          content: '# 欢迎使用 DocmentContainer'
        }}
        theme={{
          primaryColor: '#3b82f6',
          backgroundColor: '#ffffff',
          textColor: '#24292f'
        }}
      />
    </DocmentContainer>
  );
};
```

## DocmentContainer API

### Props

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `headerLogo` | `ReactNode` | - | 顶部导航栏 Logo |
| `modules` | `TopNavItem[]` | - | 顶部模块导航项 |
| `activeModuleKey` | `string` | - | 当前激活的模块 |
| `onModuleChange` | `(key: string) => void` | - | 模块切换回调 |
| `languages` | `SelectItem[]` | - | 语言选项 |
| `activeLanguageKey` | `string` | - | 当前语言 |
| `onLanguageChange` | `(key: string) => void` | - | 语言切换回调 |
| `themes` | `SelectItem[]` | - | 主题选项 |
| `activeThemeKey` | `string` | - | 当前主题 |
| `onThemeChange` | `(key: string) => void` | - | 主题切换回调 |
| `sidebarItems` | `SidebarItem[]` | - | 左侧边栏导航项 |
| `activeSidebarId` | `string` | - | 当前激活的侧边栏项 |
| `onSidebarItemClick` | `(item: SidebarItem) => void` | - | 侧边栏项点击回调 |
| `tocItems` | `TocItem[]` | - | 右侧目录项（可选，不传则自动解析） |
| `activeTocId` | `string` | - | 当前激活的目录项 |
| `onTocItemClick` | `(item: TocItem) => void` | - | 目录项点击回调 |
| `collapsibleSidebar` | `boolean` | `true` | 是否可收起侧边栏 |
| `contentKey` | `string` | - | 内容切换键，用于触发淡入淡出动画 |
| `styles` | `Styles` | - | 自定义样式配置 |

### 类型定义

```tsx
interface TopNavItem {
  key: string;
  label: string;
  href?: string;
  icon?: ReactNode;
  disabled?: boolean;
  children?: TopNavItem[];
}

interface SidebarItem {
  id: string;
  label: string;
  href?: string;
  group?: string;
}

interface TocItem {
  id: string;
  label: string;
  level?: number;
}

interface SelectItem {
  key: string;
  label: string;
}
```

## 主题配置

DocmentContainer 支持通过 `styles` 属性进行主题定制：

```tsx
const customStyles = {
  theme: {
    colors: {
      appBackground: '#ffffff',      // 应用背景色
      panelBackground: '#ffffff',    // 面板背景色
      text: '#24292f',              // 主文字颜色
      textSecondary: '#6b7280',     // 次要文字颜色
      border: '#e5e7eb',            // 边框颜色
      primary: '#3b82f6',           // 主色调
      secondary: '#6c757d',         // 次要色调
    },
    space: {
      radius: '8px',                // 圆角大小
      padding: '1rem',              // 内边距
      margin: '0.5rem',             // 外边距
    }
  },
  mode: 'light' // 'light' | 'dark'
};
```

## 响应式设计

组件内置了响应式断点：

- **桌面端** (> 1280px): 完整三栏布局（左侧栏 + 内容 + 右侧目录）
- **平板端** (960px - 1280px): 两栏布局（左侧栏 + 内容）
- **移动端** (< 960px): 单栏布局，侧边栏变为抽屉式

## 自动目录生成

当不提供 `tocItems` 时，组件会自动从内容中解析 `h1`、`h2`、`h3` 标签生成目录：

- 自动为标题添加 `id` 属性
- 支持滚动高亮当前可见标题
- 点击目录项平滑滚动到对应位置

## 开发指南

### 环境要求

- Node.js >= 18
- pnpm >= 8

### 本地开发

1. 克隆仓库
```bash
git clone https://github.com/your-username/mxmweb.git
cd mxmweb/ui/zui-layouts
```

2. 安装依赖
```bash
pnpm install
```

3. 启动开发服务器
```bash
pnpm dev
```

### 构建

```bash
pnpm build
```

### 代码规范

- 使用 TypeScript 编写代码
- 遵循 ESLint 和 Prettier 配置
- 使用 EditorConfig 保持一致的代码风格
- 编写清晰的提交信息，遵循 [Conventional Commits](https://www.conventionalcommits.org/)

### 提交规范

提交信息应该遵循以下格式：

```
<type>(<scope>): <subject>

<body>

<footer>
```

类型（type）：
- feat: 新功能
- fix: 修复
- docs: 文档
- style: 格式
- refactor: 重构
- test: 测试
- chore: 构建过程或辅助工具的变动

### 发布流程

1. 确保代码已经提交并推送到 main 分支
2. 运行发布命令：
```bash
pnpm release
```

3. 或者使用预发布测试：
```bash
pnpm release:dry
```

### GitHub Actions 配置

1. 在 GitHub 仓库设置中添加以下 Secrets：
   - `NPM_TOKEN`: npm 发布令牌
   - `GITHUB_TOKEN`: GitHub 令牌（自动提供）

2. 确保仓库设置中启用了 Actions：
   - 进入仓库的 Settings > Actions > General
   - 在 "Actions permissions" 中选择 "Allow all actions and reusable workflows"

3. 推送代码到 main 分支，Actions 将自动运行：
   - 安装依赖
   - 构建项目
   - 运行测试
   - 发布到 npm
   - 创建 GitHub Release
   - 更新 CHANGELOG.md

## 目录结构

```
src/
├── application/     # 应用入口
├── components/      # UI 组件
├── hooks/          # React Hooks
├── utils/          # 工具函数
└── types/          # 类型定义
```

## 贡献指南

欢迎提交 Pull Request 或创建 Issue。在提交代码前，请确保：

1. 代码符合项目规范
2. 添加了必要的测试
3. 更新了相关文档
4. 提交信息符合规范

## 许可证

MIT