flutterAppBar之SystemUiOverlayStyle源码解析(一)

在 Flutter 中，SystemUiOverlayStyle 是用来控制系统 UI 元素（比如状态栏和导航栏）的外观的。通过它，你可以定制状态栏的颜色、图标亮度，导航栏的外观等。

Brightness

ruby 复制代码

/// 描述主题或色彩调色板的对比度。
enum Brightness {
  /// 颜色较深，通常需要使用浅色文本才能达到良好的可读对比度。
  ///
  /// 例如，颜色可能是深灰色，需要使用白色文本。
  dark,

  /// 颜色较浅，通常需要使用深色文本才能达到良好的可读对比度。
  ///
  /// 例如，颜色可能是明亮的白色，需要使用黑色文本。
  light,
}

SystemUiOverlayStyle

kotlin 复制代码

/// 指定系统覆盖层样式的首选项。
///
/// 通过 [AppBar.systemOverlayStyle] 声明性地设置系统覆盖层的样式，
/// 通过 [SystemChrome.setSystemUIOverlayStyle] 命令式地设置系统覆盖层的样式。
@immutable
class SystemUiOverlayStyle {
  /// 创建一个新的 [SystemUiOverlayStyle] 实例。
  const SystemUiOverlayStyle({
    this.systemNavigationBarColor, // 底部导航栏颜色
    this.systemNavigationBarDividerColor, // 底部导航栏分隔线颜色
    this.systemNavigationBarIconBrightness, // 导航栏图标亮度
    this.systemNavigationBarContrastEnforced, // 是否强制执行导航栏对比度
    this.statusBarColor, // 状态栏颜色
    this.statusBarBrightness, // 状态栏亮度
    this.statusBarIconBrightness, // 状态栏图标亮度
    this.systemStatusBarContrastEnforced, // 是否强制执行状态栏对比度
  });
}

systemNavigationBarColor、systemNavigationBarDividerColor、systemNavigationBarIconBrightness、systemNavigationBarContrastEnforced

arduino 复制代码

/// 系统底部导航栏的颜色。
///
/// 仅在 Android O 及更高版本中生效。
final Color? systemNavigationBarColor;

/// 系统底部导航栏和应用内容之间的分隔线颜色。
///
/// 仅在 Android P 及更高版本中生效。
final Color? systemNavigationBarDividerColor;

/// 系统导航栏图标的亮度。
///
/// 仅在 Android O 及更高版本中生效。
/// 当设置为 [Brightness.light] 时，系统导航栏图标为浅色。
/// 当设置为 [Brightness.dark] 时，系统导航栏图标为深色。
final Brightness? systemNavigationBarIconBrightness;

/// 在设置透明导航栏时覆盖对比度强制执行。
///
/// 在 SDK 29+ 或 Android 10 及更高版本中设置透明导航栏时，
/// 可能会在按钮导航栏后面应用一个半透明的背景遮罩，
/// 以确保与按钮和应用背景之间的对比度。
///
/// SDK 28- 或 Android P 及更低版本不会应用这个背景遮罩。
///
/// 将此设置为 false 将覆盖默认的背景遮罩。
///
/// 另请参阅：
///
///   * [SystemUiOverlayStyle.systemNavigationBarColor]，在透明导航栏时，
///     此设置会覆盖默认的对比度策略。
final bool? systemNavigationBarContrastEnforced;

statusBarColor

arduino 复制代码

/// 顶部状态栏的颜色。
///
/// 仅在 Android M 及更高版本中生效。
final Color? statusBarColor;

statusBarColor：用于设置顶部状态栏的颜色。该属性仅在 Android M（Android 6.0）及更高版本中生效。

statusBarBrightness

arduino 复制代码

/// 顶部状态栏的亮度。
///
/// 仅在 iOS 中生效。
final Brightness? statusBarBrightness;

statusBarIconBrightness

arduino 复制代码

/// 顶部状态栏图标的亮度。
///
/// 仅在 Android M 及更高版本中生效。
final Brightness? statusBarIconBrightness;

statusBarIconBrightness ：用于设置顶部状态栏图标的亮度。该属性仅在 Android M（Android 6.0）及更高版本中生效。Brightness.light 表示浅色图标，Brightness.dark 表示深色图标。

systemStatusBarContrastEnforced

arduino 复制代码

/// 在设置透明状态栏时覆盖对比度强制执行。
///
/// 在 SDK 29+ 或 Android 10 及更高版本中设置透明状态栏时，
/// 可能会应用一个半透明的背景遮罩，以确保图标与应用背景之间的对比度。
///
/// 在 SDK 28- 或 Android P 及更低版本中，不会应用这个背景遮罩。
///
/// 将此设置为 false 将覆盖默认的背景遮罩。
///
/// 另请参阅：
///
///   * [SystemUiOverlayStyle.statusBarColor]，在透明状态栏时，
///     此设置会覆盖默认的对比度策略。
final bool? systemStatusBarContrastEnforced;

systemStatusBarContrastEnforced：用于在设置透明状态栏时，是否强制应用对比度遮罩。这个属性可以确保状态栏图标和背景之间有足够的对比度，以提高可读性。

在 Android 10 及更高版本（SDK 29+）中，如果设置透明状态栏，会自动应用半透明背景遮罩。
在 Android P 及更低版本中不会应用背景遮罩。
将此属性设置为 false 可以禁用这种对比度增强策略，使用默认行为。

light

less 复制代码

/// 系统覆盖层应使用浅色绘制，适用于背景为深色的应用程序。
/// 该样式适用于需要浅色图标和深色背景的场景，例如深色背景的应用。
static const SystemUiOverlayStyle light = SystemUiOverlayStyle(
  // 设置底部导航栏的背景颜色为黑色
  systemNavigationBarColor: Color(0xFF000000),
  
  // 设置底部导航栏图标的亮度为浅色（适合黑色背景）
  systemNavigationBarIconBrightness: Brightness.light,
  
  // 设置顶部状态栏图标的亮度为浅色（适合深色背景）
  statusBarIconBrightness: Brightness.light, 
  
  // 设置顶部状态栏背景颜色为深色，以便浅色图标更加突出
  statusBarBrightness: Brightness.dark,
);

dark

less 复制代码

/// 系统覆盖层应使用深色绘制，适用于背景为浅色的应用程序。
/// 该样式适用于需要深色图标和浅色背景的场景，例如浅色背景的应用。
static const SystemUiOverlayStyle dark = SystemUiOverlayStyle(
  // 设置底部导航栏的背景颜色为黑色
  systemNavigationBarColor: Color(0xFF000000),
  
  // 设置底部导航栏图标的亮度为浅色（适合黑色背景）
  systemNavigationBarIconBrightness: Brightness.light,
  
  // 设置顶部状态栏图标的亮度为深色（适合浅色背景）
  statusBarIconBrightness: Brightness.dark, 
  
  // 设置顶部状态栏背景颜色为浅色，以便深色图标更加突出
  statusBarBrightness: Brightness.light,
);