企业官网建设流程全解析

• 前端
• UI组件

导读

Navigation是 React Toolbox 中专门用于承载一组链接（<Link>）或按钮（<Button>）的通用容器组件，它负责统一布局、语义化标记与间距处理，让导航栏的搭建保持一致的视觉与行为规范。本指南将围绕 components/navigation/readme.md 的核心内容，结合源码、样式与类型声明，深入讲解它的两种布局模式、三种内容注入方式、完整配置属性与主题定制方法，帮助读者在实际项目中快速搭建横向导航栏、纵向菜单以及混合型操作区。

组件定位：为“一组导航元素”提供语义与布局

Navigation的设计意图非常明确——它不生产具体的交互元素，而是作为一个通用包装器（common wrapper），统一管理一组链接或按钮的最小化布局（minimal layout）、语义化标记（semantic markup）与间距（spacing）。这一点在其源码 components/navigation/Navigation.js 中体现得淋漓尽致：

const factory = (Button, Link) => { const Navigation = ({ actions, children, className, routes, theme, type, }) => { const _className = classnames(theme[type], className); const buttons = actions.map((action, index) => ( <Button className={theme.button} key={index} {...action} /> )); const links = routes.map((route, index) => ( <Link className={theme.link} key={index} {...route} /> )); return ( <nav>.horizontal { & > [data-react-toolbox='button'], & > [data-react-toolbox='link'] { display: inline-block; margin: 0 calc(var(--navigation-space) / 2); } } .vertical { & > [data-react-toolbox='button'], & > [data-react-toolbox='link'] { display: block; margin: calc(var(--navigation-space) / 2); } } .vertical, .horizontal { padding: calc(var(--navigation-space) / 2); @apply --reset; & > [data-react-toolbox='link'] { color: var(--navigation-color); } }

• 横向模式（horizontal）：子元素采用inline-block排布，左右各留calc(var(--navigation-space) / 2)的间距，适合放在页面顶部或卡片头部作为工具条；
• 纵向模式（vertical）：子元素采用block排布并垂直留白，适合作为侧边菜单或抽屉（Drawer）内的导航列表；
• 两种模式共享统一的padding、color与 reset 样式。间距与颜色来自 config.module.css 中定义的 CSS 变量：

:root { --navigation-space: var(--unit); --navigation-color: var(--color-black); }

其中--unit、--color-black等变量定义于仓库根部的 components/variables.module.css 与 components/colors.module.css，读者可以通过覆盖这些全局变量或替换主题类来调整导航的视觉密度。

快速上手：最小可用示例

components/navigation/readme.md 提供了一个可直接运行的示例，同时该示例也以真实文档演示的形式存在于 docs/app/components/layout/main/modules/examples/navigation_example_1.txt，说明它是官方文档站实际渲染的演示代码：

import Navigation from 'react-toolbox/lib/navigation'; import Link from 'react-toolbox/lib/link'; const actions = [ { label: 'Alarm', raised: true, icon: 'access_alarm'}, { label: 'Location', raised: true, accent: true, icon: 'room'} ]; const NavigationTest = () => ( <div> <Navigation type='horizontal' actions={actions} /> <Navigation type='vertical'> <Link href='http://' label='Inbox' icon='inbox' /> <Link href='http://' active label='Profile' icon='person' /> </Navigation> </div> );

这段示例同时展示了 Navigation 的两种内容注入方式：

1. 通过actions属性传入按钮配置：数组中的每个对象都会被展开（spread）为<Button>的 props，所以raised、accent、icon、label等字段都会按 Button 组件 的规则生效；
2. 通过children直接放置<Link>组件：Link的active属性会让当前项高亮，icon与label分别渲染图标与文字。

在真实项目中，Navigation 也常与 AppBar 配合使用，官方文档示例 docs/app/components/layout/main/modules/examples/app_bar_example_1.txt 中即在 AppBar 内部嵌套了type="horizontal"的 Navigation。

属性详解

根据 components/navigation/readme.md 的 Properties 表，并结合 Navigation.d.ts 的类型声明，Navigation支持以下属性：

各属性的补充说明如下：

• actions与routes：在源码 components/navigation/Navigation.js 中，二者分别通过actions.map(action => <Button {...action} />)与routes.map(route => <Link {...route} />)实现。因此actions中可用的键涵盖 Button 的全部 props（如label、icon、raised、flat、floating、primary、accent、disabled、href等），routes中可用的键则涵盖 Link 的 props（如label、icon、active、count、href等）。这意味着声明式的导航数据可以直接对应到具体的组件能力。
• className：会与主题类合并（classnames(theme[type], className)），用于追加业务侧的自定义样式。
• type：同时决定根元素的主题类名（theme[type]）与内部元素的排布方式，可参考上文样式分析。
• children：虽然原文档 Properties 表未列出，但 Navigation.d.ts 明确声明了children?: React.ReactNode，源码中也将其渲染在导航容器内，用于注入任意自定义节点。

内容注入的三种方式对比

从源码与类型声明可以总结出 Navigation 的三种内容注入方式，读者可根据场景选择：

1. routes属性（声明式链接）：适合数据驱动、需要统一生成多个链接的场景。每个配置对象的键直接映射到Link的 props。
2. actions属性（声明式按钮）：适合将一组操作按钮（如“闹钟”“定位”）作为配置数据统一声明，例如文档示例中的raised+accent主按钮组合。
3. children（组合式 JSX）：适合需要精细控制每个子元素或混入自定义节点（表单控件、图标、分组等）的场景。官方示例即以 children 方式组合<Link>。

三种方式可以同时使用，渲染顺序固定为routes的链接在前、actions的按钮居中、children的自定义节点在后（见 Navigation.js）。

主题定制（Theming）

Navigation通过react-css-themr接入 React Toolbox 的主题系统，主题键为RTNavigation（定义于 components/identifiers.js）。在 components/navigation/readme.md 的 Theming 表中列出四个主题类：

对应的 TypeScript 接口NavigationTheme也在 Navigation.d.ts 中得到完整定义，与文档一一对应。

自定义主题的两种途径：

1. 通过 themr 定制主题：与 React Toolbox 其他组件一致，将自定义主题对象传入组件的theme属性，或在使用ThemeProvider时按RTNavigation键提供主题。默认主题由 index.js 中的themr(NAVIGATION, theme)绑定到 theme.module.css。
2. 覆盖 CSS 变量：由于默认主题直接引用--navigation-space与--navigation-color（来自 config.module.css），在项目样式表中重新定义这两个变量即可全局调整间距与链接文字颜色。

此外，button与link类会分别施加到 Button 与 Link 的根元素上（见 Navigation.js），如果希望精细调整导航内按钮与链接的细节（如按钮的primary/accent级别、链接的active高亮），仍可通过 Button 与 Link 自身的主题键RTButton、RTLink进行定制——链接的悬停与激活态样式定义在 components/link/theme.module.css。

使用建议与注意事项

• 语义化与可访问性：Navigation渲染为<nav>语义元素，适合放置主导航、分页或页面内跳转链接，不建议用于纯装饰性分组；
• 横向导航的间距对称：横向模式下子元素使用margin: 0 calc(var(--navigation-space) / 2)，左右间距由容器 padding 兜底，首尾元素不会产生视觉偏置；
• 纵向导航的堆叠：纵向模式下子元素为display: block，适合抽屉与侧栏中的垂直链接列表，配合Link的active属性可以清晰标识当前页面；
• 数据驱动的声明式写法：当导航项来自路由表或权限配置时，优先使用routes/actions属性，将配置数据直接映射为组件 props，减少手工 JSX 样板代码；
• 类型安全：TypeScript 用户可直接从 components/navigation/index.d.ts 导入Navigation、NavigationProps与NavigationTheme类型，获得完整的属性提示。

总结

Navigation是 React Toolbox 中轻量但实用的布局容器：它以语义化的<nav>为基础，通过type切换横向/纵向两种布局，以routes、actions、children三种方式承载链接与按钮，并通过RTNavigation主题键与 CSS 变量实现灵活定制。掌握它的属性语义与源码实现，即可在工具栏、侧边菜单、卡片操作区等场景中快速构建风格统一、结构清晰的导航界面。

• 前端
• UI组件