@mxmweb/zui-layouts

v1.3.21

Published

12 hours ago

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

0High
0Medium
0Low

mxmweb

@mxmweb/zui-layouts

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

特性

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

快速开始

安装

pnpm add @mxmweb/zui-layouts

基础用法

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 | - | 自定义样式配置 |

类型定义

interface TopNavItem {
  key: string;
  label: string;
}

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 属性进行主题定制：

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

本地开发

克隆仓库

git clone https://github.com/your-username/mxmweb.git
cd mxmweb/ui/zui-layouts

安装依赖

pnpm install

启动开发服务器

pnpm dev

构建

pnpm build

代码规范

使用 TypeScript 编写代码
遵循 ESLint 和 Prettier 配置
使用 EditorConfig 保持一致的代码风格
编写清晰的提交信息，遵循 Conventional Commits

提交规范

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

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

<body>

<footer>

类型（type）：

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

发布流程

确保代码已经提交并推送到 main 分支
运行发布命令：

pnpm release

或者使用预发布测试：

pnpm release:dry

GitHub Actions 配置

在 GitHub 仓库设置中添加以下 Secrets：
- NPM_TOKEN: npm 发布令牌
- GITHUB_TOKEN: GitHub 令牌（自动提供）
确保仓库设置中启用了 Actions：
- 进入仓库的 Settings > Actions > General
- 在 "Actions permissions" 中选择 "Allow all actions and reusable workflows"
推送代码到 main 分支，Actions 将自动运行：
- 安装依赖
- 构建项目
- 运行测试
- 发布到 npm
- 创建 GitHub Release
- 更新 CHANGELOG.md

目录结构

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

贡献指南

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

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

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mxmweb/zui-layouts

特性

快速开始

安装

基础用法

DocmentContainer API

Props

类型定义

主题配置

响应式设计

自动目录生成

开发指南

环境要求

本地开发

构建

代码规范

提交规范

发布流程

GitHub Actions 配置

目录结构

贡献指南

许可证