CupertinoDynamicColor

专门用于实现iOS/macOS风格动态颜色的类

CupertinoDynamicColor是Flutter中专门用于实现iOS/macOS风格动态颜色的类。它本身不是一个可视化的Widget，而是一个Color对象。其核心逻辑是根据当前系统的外观模式(浅色/深色)或高对比度设置，自动返回对应的颜色值。这极大地简化了应用主题适配的工作，确保了应用界面在不同系统主题下都能具备良好的视觉效果和原生体验。

使用场景

适配iOS/macOS系统主题: 当你的Flutter应用需要与iOS或macOS 设备系统设置中的“浅色/深色”外观无缝切换时。
支持高对比度模式: 为视觉障碍用户提供更好的可访问性，当用户开启系统的高对比度设置时，自动切换到更易辨认的颜色。
构建遵循Cupertino设计语言的App: 使用该系统提供的动态颜色，可以使你的应用看起来更像一个真正的原生iOS应用。

示例

基础使用 - 设置容器背景色

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';

class DynamicColorDemo extends StatelessWidget {
  const DynamicColorDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      width: 200,
      height: 200,
      // 使用 CupertinoDynamicColor 定义颜色
      // 系统为浅色模式时，颜色为白色；深色模式时，颜色为黑色。
      color: CupertinoDynamicColor.withBrightness(
        color: CupertinoColors.white, // 浅色模式颜色
        darkColor: CupertinoColors.black, // 深色模式颜色
      ),
      child: const Center(
        child: Text('动态背景色'),
      ),
    );
  }
}

在Cupertino组件中使用系统预定义颜色

import 'package:flutter/cupertino.dart';

class CupertinoAppDemo extends StatelessWidget {
  const CupertinoAppDemo({super.key});

  @override
  Widget build(BuildContext context) {
    return CupertinoPageScaffold(
      // navigationBar 的背景色会自动适应主题
      navigationBar: const CupertinoNavigationBar(
        middle: Text('设置'),
      ),
      // CupertinoColors.systemBackground 是预定义的动态颜色
      backgroundColor: CupertinoColors.systemBackground,
      child: Center(
        child: Text(
          '这是一段文本',
          // CupertinoColors.label 是另一个预定义的动态文本颜色
          style: TextStyle(color: CupertinoColors.label.resolveFrom(context)),
        ),
      ),
    );
  }
}

创建自定义的动态颜色

import 'package:flutter/cupertino.dart';

class CustomDynamicColorWidget extends StatelessWidget {
  const CustomDynamicColorWidget({super.key});

  // 定义一个自定义的动态颜色
  static const myCustomDynamicColor = CupertinoDynamicColor(
    debugLabel: 'myCustomColor',
    color: Color(0xFF007AFF), // 浅色模式下的蓝色
    darkColor: Color(0xFF0A84FF), // 深色模式下的亮蓝色
    highContrastColor: Color(0xFF0040DD), // 高对比度下的深蓝色
    darkHighContrastColor: Color(0xFF409CFF), // 深色+高对比度下的蓝色
  );

  @override
  Widget build(BuildContext context) {
    return Container(
      padding: const EdgeInsets.all(20),
      decoration: BoxDecoration(
        color: myCustomDynamicColor.resolveFrom(context), // 解析颜色
        borderRadius: BorderRadius.circular(10),
      ),
      child: const Text(
        '自定义动态颜色按钮',
        style: TextStyle(color: CupertinoColors.white),
      ),
    );
  }
}

注意点

常见问题与陷阱

在MaterialApp中不生效: 在MaterialApp中，系统主题变化默认不会触发CupertinoDynamicColor重新解析。你需要确保有一个CupertinoApp在Widget树中作为祖先，或者使用MediaQuery监听主题变化并手动触发重建。
忘记调用.resolveFrom(context): 自定义的CupertinoDynamicColor对象需要调用.resolveFrom(context)方法，传入BuildContext，才能根据当前主题解析出正确的静态Color值。直接使用它本身是无效的。
颜色对比度不足: 在自定义颜色时，务必确保浅色和深色模式下的颜色都有足够的对比度，以满足可访问性标准。

优化技巧与最佳实践

优先使用系统预定义颜色: CupertinoColors中如systemBackground, label, secondaryLabel, systemGrey等颜色是经过Apple精心设计的，能提供最佳的原生体验。尽量使用它们。
考虑高对比度: 在设计自定义动态颜色时，最好同时提供highContrastColor和darkHighContrastColor，以完善对可访问性的支持。
与Theme Extension结合: 对于大型项目，可以创建自定义的ThemeExtension，将你的CupertinoDynamicColor定义在其中，实现主题数据的集中管理。

构造函数

CupertinoDynamicColor类提供了两个主要的构造函数：

CupertinoDynamicColor

描述: 最完整的构造函数，允许你定义所有可能的颜色状态。
参数列表:
- {required Color color}: 普通浅色模式下的颜色。
- {required Color darkColor}: 普通深色模式下的颜色。
- {Color? highContrastColor}: 浅色模式+高对比度下的颜色(可选)。
- {Color? darkHighContrastColor}: 深色模式+高对比度下的颜色(可选)。
- {String? debugLabel}: 调试标签，用于在开发工具中识别该颜色。

CupertinoDynamicColor.withBrightness

描述: 简化版的构造函数，只处理浅色/深色模式，不处理高对比度。是高对比度不敏感场景下的便捷选择。
参数列表:
- {required Color color}: 浅色模式下的颜色。
- {required Color darkColor}: 深色模式下的颜色。
- {String? debugLabel}: 调试标签。

属性

属性名	属性类型	说明
`color`	`Color`	普通浅色模式下的默认颜色。
`darkColor`	`Color`	普通深色模式下的默认颜色。
`highContrastColor`	`Color?`	浅色模式且开启高对比度时使用的颜色。如果为 null，则回退到 `color`。
`darkHighContrastColor`	`Color?`	深色模式且开启高对比度时使用的颜色。如果为 null，则回退到 `darkColor`。
`debugLabel`	`String?`	用于调试的标识字符串。

关键属性解释

color和darkColor(核心属性): 这两个是必须提供的属性，构成了动态颜色最基本的功能。它们直接决定了应用在绝大多数用户设备上的视觉表现。选择这两个颜色时，应确保它们在各自背景下(白底/黑底)都具有良好的可读性和美观性。
highContrastColor和darkHighContrastColor(可访问性属性): 这两个是可选但强烈推荐提供的属性。它们专门用于提升应用的可访问性。当用户因为视力原因开启系统的高对比度选项时，这些颜色会被自动应用，通常比普通颜色具有更高的对比度，使界面元素更加清晰。提供它们是你应用专业性和对用户关怀的体现。

CupertinoDialogRoute

CupertinoFormRow