@pwc-ra/components/README.md

PwC RA shared components library

# PwC RA Components - PageHeader 组件

PageHeader 是 PwC RA Components 组件库中的一个核心组件，用于提供统一的页面头部导航栏，包含产品菜单、用户信息、租户选择等功能。

## 安装

### 1. 添加依赖

```bash
# 使用 npm
npm install @pwc-ra/components

# 使用 yarn
yarn add @pwc-ra/components
```

### 2. 安装对等依赖

该组件库依赖以下包，请确保它们已安装：

```bash
npm install react react-dom antd @ant-design/icons axios keycloak-js react-router-dom
```

## 使用方法

### 基本用法

```tsx
import React, { useState } from 'react';
import { Layout } from 'antd';
import { PageHeader, PageHeaderProvider } from '@pwc-ra/components';

const { Content } = Layout;

const App: React.FC = () => {
  const [collapsed, setCollapsed] = useState(false);

  const handleCollapse = () => {
    setCollapsed(!collapsed);
  };

  return (
    <Layout style={{ minHeight: '100vh' }}>
      <PageHeader 
        collapsed={collapsed} 
        onCollapse={handleCollapse} 
      />
      <Content style={{ marginTop: 64, padding: 24 }}>
        {/* 页面内容 */}
      </Content>
    </Layout>
  );
};

export default App;
```

### 产品切换回调

```tsx
import React, { useState } from 'react';
import { Layout } from 'antd';
import { PageHeader } from '@pwc-ra/components';

const { Content } = Layout;

const App: React.FC = () => {
  const [collapsed, setCollapsed] = useState(false);

  const handleCollapse = () => {
    setCollapsed(!collapsed);
  };

  const handleProductChange = (productId: string) => {
    console.log(`切换到产品: ${productId}`);
    // 可以在这里处理产品切换逻辑，例如跳转到对应产品页面
  };

  return (
    <Layout style={{ minHeight: '100vh' }}>
      <PageHeader 
        collapsed={collapsed} 
        onCollapse={handleCollapse} 
        onProductChange={handleProductChange}
      />
      <Content style={{ marginTop: 64, padding: 24 }}>
        {/* 页面内容 */}
      </Content>
    </Layout>
  );
};

export default App;
```

### 使用全局状态

PageHeader 组件提供了全局状态管理，可以在应用的任何地方访问用户信息和租户信息：

```tsx
import React from 'react';
import { PageHeaderState } from '@pwc-ra/components';

const UserInfo: React.FC = () => {
  // 获取当前用户信息
  const currentUser = PageHeaderState.getCurrentUser();
  
  // 获取当前选中的租户
  const selectedTenant = PageHeaderState.getSelectedTenant();
  
  // 监听状态变化
  React.useEffect(() => {
    const unsubscribe = PageHeaderState.subscribe((state) => {
      console.log('状态已更新:', state);
    });
    
    // 组件卸载时取消订阅
    return unsubscribe;
  }, []);
  
  return (
    <div>
      <h2>当前用户: {currentUser?.username}</h2>
      <h3>当前租户: {selectedTenant?.name}</h3>
    </div>
  );
};

export default UserInfo;
```

## API

### PageHeader

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| collapsed | 侧边栏是否折叠 | boolean | - |
| onCollapse | 侧边栏折叠状态改变时的回调函数 | () => void | - |
| onProductChange | 产品切换时的回调函数 | (productId: string) => void | - |
| extra | 自定义额外内容，将显示在顶部导航栏右侧 | ReactNode | - |

### PageHeaderProvider

PageHeaderProvider 是一个 Context Provider，用于提供用户信息、租户信息等全局状态。通常不需要直接使用，因为 PageHeader 组件内部已经包含了 PageHeaderProvider。

### usePageHeader

usePageHeader 是一个自定义 Hook，用于在组件中访问 PageHeader 的上下文。

```tsx
const { 
  currentUser,       // 当前用户信息
  loading,           // 加载状态
  error,             // 错误信息
  selectedTenant,    // 当前选中的租户
  setSelectedTenant, // 设置当前租户
  logout             // 登出函数
} = usePageHeader();
```

### PageHeaderState

PageHeaderState 是一个全局状态对象，可以在应用的任何地方访问 PageHeader 的状态。

| 方法 | 说明 | 参数 | 返回值 |
| --- | --- | --- | --- |
| getCurrentUser | 获取当前用户信息 | - | User \| null |
| getSelectedTenant | 获取当前选中的租户 | - | { id: string; code: string; name: string; } \| null |
| isLoading | 获取加载状态 | - | boolean |
| getError | 获取错误信息 | - | string \| null |
| subscribe | 订阅状态变化 | (state: GlobalPageHeaderState) => void | () => void |

### MainLayout

| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| menuItems | 侧边栏菜单项配置 | MenuItem[] | - |
| productName | 产品名称 | string | - |
| productIcon | 产品图标 | ReactNode | - |
| children | 内容区域 | ReactNode | - |
| breadcrumb | 面包屑组件 | ReactNode | - |
| defaultCollapsed | 初始侧边栏是否折叠 | boolean | false |
| contentStyle | 自定义内容区域样式 | CSSProperties | - |
| contentWrapperStyle | 自定义内容包装区域样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| headerExtra | 自定义顶部导航栏额外内容 | ReactNode | - |

## 类型定义

### User

```typescript
interface User {
  id: string;
  username: string;
  email: string;
  tenants: Array<{
    id: string;
    code: string;
    name: string;
  }>;
}
```

### Product

```typescript
interface Product {
  id: string;
  name: string;
  url: string;
  icon?: string;
  category?: string;
  order?: number;
}
```

## 注意事项

1. PageHeader 组件需要配置 Keycloak 认证服务，默认会从 `/api/public/keycloak-config` 获取配置信息。

2. 产品菜单数据默认从 `/api/public/product-menu` 获取，需要后端提供相应的 API。

3. 用户信息默认从 `/auth/users/me` 获取，需要后端提供相应的 API。

4. 组件默认使用 Ant Design 的样式，请确保项目中已正确配置 Ant Design。

## 应用模板生成器

本库包含一个应用模板生成器，可以帮助您快速创建一个集成了 MainLayout、Sidebar、Breadcrumb 和 PageHeader 组件的 React 应用。

### 使用方法

```bash
# 使用 npx 直接运行
npx @pwc-ra/components/templates/create-ra-app my-app

# 或者在安装了 @pwc-ra/components 的项目中
npx ./node_modules/@pwc-ra/components/templates/create-ra-app my-app
```

### 命令行选项

- `--use-npm`: 使用 npm 而不是 yarn 安装依赖
- `--skip-install`: 跳过依赖安装

示例：

```bash
npx @pwc-ra/components/templates/create-ra-app my-app --use-npm
```

更多信息请参考 [模板生成器文档](./templates/create-ra-app/README.md)。