# 页面规范与验证系统

本文档说明如何使用页面规范系统和页面验证系统，确保所有页面遵循统一的开发标准。

---

## 目录

- [页面规范系统](#页面规范系统)
  - [PageStandards 类](#pagestandards-类)
  - [PageStandardsMixin 混入](#pagestandardsmixin-混入)
  - [StandardPage 基类](#standardpage-基类)
  - [扩展方法](#扩展方法)
- [页面验证系统](#页面验证系统)
  - [页面注册](#页面注册)
  - [规范检查项](#规范检查项)
  - [验证报告](#验证报告)
- [最佳实践](#最佳实践)

---

## 页面规范系统

### PageStandards 类

`PageStandards` 是页面规范配置类，提供统一的页面构建标准。

**包含的规范属性：**

| 类别 | 属性 | 类型 | 说明 |
|------|------|------|------|
| **主题颜色** | `primaryColor` | Color | 主题色 |
| | `secondaryColor` | Color | 次要色 |
| | `textColor` | Color | 文字颜色 |
| | `backgroundColor` | Color | 背景颜色 |
| **字体大小** | `fontSize` | double | 基础字体大小 |
| | `textStyle` | TextStyle | 主题文字样式 |
| | `primaryTextStyle` | TextStyle | 主题色文字样式 |
| | `secondaryTextStyle` | TextStyle | 次要色文字样式 |
| **动画配置** | `animationEnabled` | bool | 动画开关 |
| | `animationSpeed` | double | 动画速度 |
| | `animationIntensity` | double | 动画强度 |
| | `animationPreset` | AnimationPreset | 动画预设 |
| | `animationCurve` | AnimationCurveType | 动画曲线 |
| **响应式布局** | `scaleEnabled` | bool | 缩放开关 |
| | `screenWidth` | double | 屏幕宽度 |
| | `screenHeight` | double | 屏幕高度 |
| | `statusBarHeight` | double | 状态栏高度 |
| | `bottomBarHeight` | double | 底部安全区高度 |
| **多语言** | `l10n` | AppLocalizations | 多语言实例 |
| | `currentLocale` | Locale | 当前语言 |
| | `languageCode` | String | 语言代码 |
| **屏幕方向** | `orientation` | Orientation | 当前方向 |
| | `isPortrait` | bool | 是否竖屏 |
| | `isLandscape` | bool | 是否横屏 |
| **消息样式** | `toastStyle` | ToastStyle | 消息提示样式 |
| **状态栏** | `isStatusBarImmersive` | bool | 状态栏沉浸开关 |
| | `systemUiOverlayStyle` | SystemUiOverlayStyle | 系统UI样式 |
| **深色模式** | `isDarkMode` | bool | 是否深色模式 |
| | `brightness` | Brightness | 当前亮度 |
| **设备类型** | `deviceType` | DeviceType | 设备类型 |
| | `isMobile` | bool | 是否手机 |
| | `isTablet` | bool | 是否平板 |
| | `isWeb` | bool | 是否 Web |
| | `isDesktop` | bool | 是否桌面端 |
| | `isHarmonyOS` | bool | 是否鸿蒙 |

**缩放方法：**

| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `scaledWidth()` | double | double | 缩放宽度 |
| `scaledHeight()` | double | double | 缩放高度 |
| `scaledFontSize()` | double | double | 缩放字体 |
| `scaledRadius()` | double | double | 缩放圆角 |
| `scaledPadding()` | EdgeInsets | EdgeInsets | 缩放内边距 |
| `scaledMargin()` | EdgeInsets | EdgeInsets | 缩放外边距 |

**使用示例：**

```dart
final standards = PageStandards.of(context);

// 获取主题色
Container(
  color: standards.backgroundColor,
  child: Text(
    'Hello',
    style: standards.textStyle,
  ),
);

// 使用缩放方法
Container(
  width: standards.scaledWidth(100),
  height: standards.scaledHeight(50),
  padding: standards.scaledPadding(EdgeInsets.all(16)),
);
```

---

### PageStandardsMixin 混入

使用 `PageStandardsMixin` 可以自动注入页面规范，无需手动创建 `PageStandards` 实例。

**使用示例：**

```dart
class MyPage extends StatefulWidget {
  const MyPage({super.key});
  
  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> with PageStandardsMixin {
  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      backgroundColor: backgroundColor,  // 直接访问主题背景色
      child: Column(
        children: [
          Text(
            l10n.appTitle,  // 直接访问多语言
            style: textStyle,  // 直接访问主题文字样式
          ),
          Container(
            width: scaledWidth(100),  // 使用缩放方法
            height: scaledHeight(50),
          ),
        ],
      ),
    );
  }
}
```

---

### StandardPage 基类

`StandardPage` 和 `StandardPageState` 是标准页面基类，自动集成了 `PageStandardsMixin`。

**使用示例：**

```dart
class MyPage extends StandardPage {
  const MyPage({super.key});
  
  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends StandardPageState<MyPage> {
  @override
  Widget buildPage(BuildContext context) {
    return CupertinoPageScaffold(
      backgroundColor: backgroundColor,
      child: Text(
        l10n.appTitle,
        style: textStyle,
      ),
    );
  }
}
```

---

### 扩展方法

`PageStandardsExtension` 为 `BuildContext` 提供了便捷的扩展方法。

**使用示例：**

```dart
Widget build(BuildContext context) {
  return Container(
    color: context.backgroundColor,  // 主题背景色
    child: Text(
      context.l10n.appTitle,  // 多语言
      style: TextStyle(
        color: context.textColor,  // 主题字体色
        fontSize: context.fontSize,  // 主题字体大小
      ),
    ),
  );
}
```

**可用的扩展方法：**

| 扩展属性 | 类型 | 说明 |
|----------|------|------|
| `context.standards` | PageStandards | 完整规范实例 |
| `context.l10n` | AppLocalizations | 多语言实例 |
| `context.primaryColor` | Color | 主题色 |
| `context.textColor` | Color | 文字颜色 |
| `context.backgroundColor` | Color | 背景颜色 |
| `context.fontSize` | double | 字体大小 |

---

## 页面验证系统

### 页面注册

所有页面必须在 `AppPages` 中注册，以便进行规范验证。

**注册位置：** `lib/src/standards/app_pages.dart`

**注册示例：**

```dart
import 'package:cute_kitchen/src/standards/page_validator.dart';
import 'package:cute_kitchen/src/pages/my_page.dart';

class AppPages {
  static final List<PageInfo> pages = [
    PageInfo(
      route: '/my_page',
      name: '我的页面',
      description: '示例页面说明',
      requiredStandards: [
        StandardCheck.themeColors,      // 主题颜色
        StandardCheck.textColors,       // 字体颜色
        StandardCheck.fontSize,         // 字体大小
        StandardCheck.animation,        // 动画配置
        StandardCheck.responsive,       // 响应式布局
        StandardCheck.localization,     // 多语言
      ],
      builder: () => const MyPage(),
      metadata: {  // 可选的元数据
        'icon': 'person',
        'category': 'user',
      },
    ),
  ];
}
```

**PageInfo 属性说明：**

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `route` | String | ✅ | 路由路径 |
| `name` | String | ✅ | 页面名称 |
| `description` | String | ✅ | 页面描述 |
| `requiredStandards` | List\<StandardCheck\> | ✅ | 必须遵循的规范 |
| `builder` | Widget Function() | ✅ | 页面构建函数 |
| `metadata` | Map\<String, dynamic\>? | ❌ | 自定义元数据 |

---

### 规范检查项

`StandardCheck` 枚举定义了 12 种规范检查项：

| 检查项 | 标签 | 说明 |
|--------|------|------|
| `themeColors` | 主题颜色 | 检查是否使用主题色、次要色 |
| `textColors` | 字体颜色 | 检查是否使用主题字体色 |
| `fontSize` | 字体大小 | 检查是否使用主题字体大小 |
| `spacing` | 间距规范 | 检查是否使用标准间距 |
| `animation` | 动画配置 | 检查是否遵循动画配置 |
| `responsive` | 响应式布局 | 检查是否适配不同屏幕 |
| `localization` | 多语言 | 检查是否使用多语言 |
| `orientation` | 屏幕方向 | 检查是否处理屏幕方向 |
| `toastStyle` | 消息样式 | 检查是否使用标准消息样式 |
| `statusBarImmersive` | 状态栏沉浸 | 检查是否处理状态栏沉浸 |
| `darkMode` | 深色模式 | 检查是否支持深色模式 |
| `deviceType` | 设备类型 | 检查是否适配不同设备类型 |

---

### 验证报告

**开发模式自动验证：**

在开发模式下（`kDebugMode == true`），页面验证系统会自动：
1. 检测页面是否已注册
2. 验证页面是否遵循规范
3. 在控制台输出验证结果

**控制台输出示例：**

```
✅ 已注册 3 个页面
  - 首页 (/)
  - 主题设置 (/theme)
  - 示例页面 (/example)

🔍 开始验证页面: 首页 (/)
  ✓ 主题颜色
  ✓ 字体颜色
  ✓ 字体大小
  ✓ 多语言
  ✓ 深色模式
✅ 页面验证完成: 首页
```

**未注册页面错误：**

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ 页面未注册错误
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
路由: /unknown_page

该页面未在 AppPages 中注册，请检查：
1. 是否已在 AppPages.pages 中添加页面信息
2. 路由名称是否正确
3. 是否调用了 AppPages.registerAll()

已注册的页面:
  - /: 首页
  - /theme: 主题设置
  - /example: 示例页面
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**手动获取验证报告：**

```dart
// 获取验证历史
final history = PageValidator.history;

// 获取失败的验证结果
final failed = PageValidator.getFailedResults();

// 生成验证报告
final report = PageValidator.generateReport();
print('总检查数: ${report['totalChecks']}');
print('通过: ${report['passed']}');
print('失败: ${report['failed']}');
print('通过率: ${report['passRate']}%');

// 打印报告
PageValidator.printReport();
```

**调试面板：**

```dart
// 在页面中显示调试面板
if (kDebugMode) {
  showCupertinoDialog(
    context: context,
    builder: (context) => const PageValidationDebugPanel(),
  );
}
```

---

## 最佳实践

### 1. 创建新页面

**推荐方式：** 继承 `StandardPage` 基类

```dart
class NewPage extends StandardPage {
  const NewPage({super.key});
  
  @override
  State<NewPage> createState() => _NewPageState();
}

class _NewPageState extends StandardPageState<NewPage> {
  @override
  Widget buildPage(BuildContext context) {
    return CupertinoPageScaffold(
      backgroundColor: backgroundColor,
      navigationBar: CupertinoNavigationBar(
        middle: Text(l10n.appTitle),
      ),
      child: SafeArea(
        child: ListView(
          padding: scaledPadding(EdgeInsets.all(16)),
          children: [
            Text(
              l10n.welcomeMessage,
              style: textStyle,
            ),
            SizedBox(height: scaledHeight(20)),
            CupertinoButton.filled(
              onPressed: _handlePress,
              child: Text(l10n.getStarted),
            ),
          ],
        ),
      ),
    );
  }
  
  void _handlePress() {
    // 处理点击
  }
}
```

### 2. 注册新页面

在 `lib/src/standards/app_pages.dart` 中添加：

```dart
PageInfo(
  route: '/new_page',
  name: '新页面',
  description: '新页面说明',
  requiredStandards: [
    StandardCheck.themeColors,
    StandardCheck.textColors,
    StandardCheck.fontSize,
    StandardCheck.localization,
    StandardCheck.darkMode,
  ],
  builder: () => const NewPage(),
),
```

### 3. 添加路由

在 `lib/main.dart` 的 `getPages` 中添加：

```dart
GetPage(
  name: '/new_page',
  page: () {
    AppPages.validateRoute('/new_page');
    return const NewPage();
  },
),
```

### 4. 响应式布局

使用 `LayoutBuilder` 和 `PageStandards` 实现响应式：

```dart
@override
Widget buildPage(BuildContext context) {
  return LayoutBuilder(
    builder: (context, constraints) {
      if (isTablet && isLandscape) {
        return _buildTabletLandscape(constraints);
      } else if (isTablet) {
        return _buildTabletPortrait(constraints);
      } else if (isMobile && isLandscape) {
        return _buildMobileLandscape(constraints);
      } else {
        return _buildMobilePortrait(constraints);
      }
    },
  );
}

Widget _buildMobilePortrait(BoxConstraints constraints) {
  return CupertinoPageScaffold(
    backgroundColor: backgroundColor,
    child: Column(
      children: [
        Expanded(
          child: ListView(
            padding: scaledPadding(EdgeInsets.all(16)),
            children: [
              // 竖屏布局
            ],
          ),
        ),
      ],
    ),
  );
}
```

### 5. 深色模式支持

确保所有颜色使用主题值：

```dart
// ❌ 错误：硬编码颜色
Container(
  color: Colors.white,
  child: Text(
    'Hello',
    style: TextStyle(color: Colors.black),
  ),
)

// ✅ 正确：使用主题值
Container(
  color: backgroundColor,
  child: Text(
    'Hello',
    style: textStyle,
  ),
)
```

### 6. 多语言支持

确保所有文本使用多语言：

```dart
// ❌ 错误：硬编码文本
Text('欢迎使用')

// ✅ 正确：使用多语言
Text(l10n.welcomeMessage)
```

### 7. 动画配置

使用 `AnimationService` 的配置：

```dart
AnimatedContainer(
  duration: AppService.instance.animation.config.baseDuration,
  curve: AppService.instance.animation.config.curve,
  // ...
)
```

---

## 文件结构

```
lib/src/standards/
├── page_standards.dart    # 页面规范系统
├── page_validator.dart    # 页面验证系统
└── app_pages.dart         # 页面注册表
```

---

## 相关文档

- [README.md](./README.md) - 项目基础支撑库说明
- [CHANGELOG.md](../../CHANGELOG.md) - 更新日志

---

**最后更新时间：** 2026-04-08
**维护者：** Cute Kitchen 开发团队