520kiss/kitchen

Fork 0

Files

Developer cbe11d5db1 fix: add ToastStyle enum and currentStyle property to ToastService

2026-04-08 01:51:02 +08:00

14 KiB

Raw Blame History

页面规范与验证系统

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

页面规范系统

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	缩放外边距

使用示例：

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 实例。

使用示例：

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。

使用示例：

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 提供了便捷的扩展方法。

使用示例：

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

注册示例：

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），页面验证系统会自动：

检测页面是否已注册
验证页面是否遵循规范
在控制台输出验证结果

控制台输出示例：

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

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

未注册页面错误：

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

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

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

手动获取验证报告：

// 获取验证历史
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();

调试面板：

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

最佳实践

1. 创建新页面

推荐方式： 继承 StandardPage 基类

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 中添加：

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 中添加：

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

4. 响应式布局

使用 LayoutBuilder 和 PageStandards 实现响应式：

@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. 深色模式支持

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

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

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

6. 多语言支持

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

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

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

7. 动画配置

使用 AnimationService 的配置：

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         # 页面注册表

14 KiB

Raw Blame History

页面规范与验证系统

目录

页面规范系统

PageStandards 类

PageStandardsMixin 混入

StandardPage 基类

扩展方法

页面验证系统

页面注册

规范检查项

验证报告

最佳实践

1. 创建新页面

2. 注册新页面

3. 添加路由

4. 响应式布局

5. 深色模式支持

6. 多语言支持

7. 动画配置

文件结构

相关文档

14 KiB Raw Blame History

页面规范与验证系统

目录

页面规范系统

PageStandards 类

PageStandardsMixin 混入

StandardPage 基类

扩展方法

页面验证系统

页面注册

规范检查项

验证报告

最佳实践

1. 创建新页面

2. 注册新页面

3. 添加路由

4. 响应式布局

5. 深色模式支持

6. 多语言支持

7. 动画配置

文件结构

相关文档

14 KiB

Raw Blame History