nex_design/docs/components/PageTitleBar.md

PageTitleBar 组件

组件说明

页面标题栏组件，用于显示页面的标题、描述信息、操作按钮和可选的展开/收起控制按钮。

组件位置

src/components/PageTitleBar/PageTitleBar.jsx
src/components/PageTitleBar/PageTitleBar.css

参数说明

参数名	类型	必填	默认值	说明
title	string	是	-	页面标题文本
badge	ReactNode	否	-	标题右侧的徽章内容（如状态标签等）
description	string	否	-	页面描述文本，显示在标题下方
actions	ReactNode	否	-	右侧操作按钮区域内容
showToggle	boolean	否	false	是否显示展开/收起按钮
onToggle	function(expanded: boolean)	否	-	展开/收起状态变化时的回调函数，接收当前展开状态
defaultExpanded	boolean	否	false	默认展开状态

使用示例

基础用法

import PageTitleBar from '../components/PageTitleBar/PageTitleBar'

function MyPage() {
  return (
    <div>
      <PageTitleBar
        title="用户列表"
        description="管理系统用户，包括用户信息、权限和授权管理"
      />
      {/* 页面内容 */}
    </div>
  )
}

带徽章的标题

import { Tag } from 'antd'

<PageTitleBar
  title="主机详情"
  badge={<Tag color="green">在线</Tag>}
  description="查看主机的详细信息和运行状态"
/>

带展开/收起功能

import { useState } from 'react'
import { Card, Row, Col, Statistic } from 'antd'
import { DesktopOutlined, CheckCircleOutlined, CloseCircleOutlined, SearchOutlined } from '@ant-design/icons'
import PageTitleBar from '../components/PageTitleBar/PageTitleBar'

function MyPage() {
  const [showStatsPanel, setShowStatsPanel] = useState(false)

  return (
    <div>
      <PageTitleBar
        title="主机列表"
        description="查看和管理所有接入的主机终端"
        showToggle={true}
        defaultExpanded={false}
        onToggle={(expanded) => setShowStatsPanel(expanded)}
      />

      {/* 可展开/收起的统计面板 */}
      {showStatsPanel && (
        <div className="stats-panel">
          <Row gutter={[16, 16]}>
            <Col xs={24} sm={12} lg={6}>
              <Card hoverable>
                <Statistic
                  title="总主机数"
                  value={50}
                  prefix={<DesktopOutlined />}
                  valueStyle={{ color: '#1677ff' }}
                />
              </Card>
            </Col>
            <Col xs={24} sm={12} lg={6}>
              <Card hoverable>
                <Statistic
                  title="在线主机"
                  value={35}
                  prefix={<CheckCircleOutlined />}
                  valueStyle={{ color: '#52c41a' }}
                />
              </Card>
            </Col>
            <Col xs={24} sm={12} lg={6}>
              <Card hoverable>
                <Statistic
                  title="离线主机"
                  value={15}
                  prefix={<CloseCircleOutlined />}
                  valueStyle={{ color: '#8c8c8c' }}
                />
              </Card>
            </Col>
            <Col xs={24} sm={12} lg={6}>
              <Card>
                <Statistic
                  title="筛选结果"
                  value={50}
                  prefix={<SearchOutlined />}
                  valueStyle={{ color: '#faad14' }}
                />
              </Card>
            </Col>
          </Row>
        </div>
      )}
    </div>
  )
}

带操作按钮

import { Button } from 'antd'
import { PlusOutlined } from '@ant-design/icons'

<PageTitleBar
  title="用户列表"
  description="管理系统用户"
  actions={
    <Button type="primary" icon={<PlusOutlined />}>
      新增用户
    </Button>
  }
/>

样式定制

组件提供以下 CSS 类名供自定义样式：

• .page-title-bar - 组件根容器
• .title-bar-content - 标题栏内容容器
• .title-bar-left - 左侧内容区域
• .title-bar-right - 右侧内容区域
• .title-group - 标题和徽章组合
• .page-title - 标题文本
• .title-badge - 徽章容器
• .page-description - 描述文本
• .title-actions - 操作按钮区域
• .toggle-button - 展开/收起按钮

使用场景

1. 列表页面 - 显示列表页面的标题和描述
2. 详情页面 - 显示详情页的标题和状态标签
3. 带统计面板的页面 - 通过展开/收起按钮控制外部统计面板的显示，保持页面简洁
4. 需要快捷操作的页面 - 通过 actions 参数在标题栏添加常用操作按钮

设计理念

PageTitleBar 采用分体式设计，组件本身只负责标题栏的展示和展开/收起状态管理，不包含扩展内容。这种设计具有以下优势：

1. 职责单一 - 组件专注于标题栏功能，代码更清晰
2. 灵活性高 - 扩展内容由父组件管理，可以自由定制样式和布局
3. 易于维护 - 标题栏和扩展内容相互独立，修改互不影响
4. 复用性强 - 同一个 PageTitleBar 可以控制不同类型的扩展内容

注意事项

1. title 参数为必填项，建议简洁明了
2. 当使用 showToggle 时：
   • 必须提供 onToggle 回调函数来响应状态变化
   • 在父组件中管理扩展内容的显示/隐藏状态
   • 扩展内容应该独立于 PageTitleBar 组件之外渲染
3. defaultExpanded 默认值为 false，扩展面板默认收起，推荐保持此默认值以保持页面简洁
4. badge 参数支持任何 React 节点，常用的如 Ant Design 的 Tag、Badge 组件
5. actions 区域不建议放置过多按钮，以保持界面简洁
6. 扩展内容（如统计面板）应该在父组件中独立管理，不要嵌入到 PageTitleBar 内部