549 lines
14 KiB
Markdown
549 lines
14 KiB
Markdown
# 页面规范与验证系统
|
|
|
|
本文档说明如何使用页面规范系统和页面验证系统，确保所有页面遵循统一的开发标准。
|
|
|
|
---
|
|
|
|
## 目录
|
|
|
|
- [页面规范系统](#页面规范系统)
|
|
- [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:mom_kitchen/src/standards/page_validator.dart';
|
|
import 'package:mom_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 开发团队
|