Flutter MaterialApp 完全指南（四）本地化与调试

简介

本文详细介绍 MaterialApp 的本地化配置（包括多语言支持）以及调试工具的使用。

1. 本地化 (Localization) 配置

1.1 本地化相关属性

属性	类型	说明
locale	Locale?	强制指定应用的当前语言
localizationsDelegates	Iterable<LocalizationsDelegate>?	本地化代理列表
supportedLocales	Iterable<Locale>	应用支持的语言列表
localeListResolutionCallback	LocaleListResolutionCallback?	设备语言列表解析回调
localeResolutionCallback	LocaleResolutionCallback?	单个语言解析回调

1.2 基本本地化配置

import 'package:flutter_localizations/flutter_localizations.dart';

MaterialApp(
  localizationsDelegates: const [
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  supportedLocales: const [
    Locale('en', 'US'), // English (United States)
    Locale('zh', 'CN'), // Chinese (Simplified, China)
    Locale('zh', 'TW'), // Chinese (Traditional, Taiwan)
    Locale('ja', 'JP'), // Japanese
  ],
  locale: const Locale('en', 'US'),
)

1.3 GlobalMaterialLocalizations 支持的语言

GlobalMaterialLocalizations 支持以下语言代码：

代码	语言
af	Afrikaans
am	Amharic
ar	Arabic
be	Belarusian
bg	Bulgarian
bn	Bengali
bs	Bosnian
ca	Catalan
cs	Czech
da	Danish
de	German
el	Greek
en	English
es	Spanish
et	Estonian
eu	Basque
fa	Persian
fi	Finnish
fr	French
gl	Galician
gu	Gujarati
he	Hebrew
hi	Hindi
hr	Croatian
hu	Hungarian
id	Indonesian
is	Icelandic
it	Italian
ja	Japanese
ka	Georgian
kk	Kazakh
km	Khmer
kn	Kannada
ko	Korean
ky	Kyrgyz
lo	Lao
lt	Lithuanian
lv	Latvian
mk	Macedonian
ml	Malayalam
mn	Mongolian
mr	Marathi
ms	Malay
my	Burmese
nb	Norwegian Bokmål
nl	Dutch
or	Oriya
pa	Punjabi
pl	Polish
pt	Portuguese
ro	Romanian
ru	Russian
si	Sinhala
sk	Slovak
sl	Slovenian
sq	Albanian
sr	Serbian
sv	Swedish
sw	Swahili
ta	Tamil
te	Telugu
th	Thai
tl	Tagalog
tr	Turkish
uk	Ukrainian
ur	Urdu
uz	Uzbek
vi	Vietnamese
zh	Chinese

1.4 高级本地化定义

对于支持多种脚本的语言（如中文简体和繁体），建议完整定义：

supportedLocales: <Locale>[
  const Locale.fromSubtags(languageCode: 'zh'), // 通用中文
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans'), // 简体中文
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant'), // 繁体中文
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hans', countryCode: 'CN'), // 中国简体
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant', countryCode: 'TW'), // 台湾繁体
  const Locale.fromSubtags(languageCode: 'zh', scriptCode: 'Hant', countryCode: 'HK'), // 香港繁体
],

1.5 语言解析优先级

默认的语言解析算法 basicLocaleListResolution 按以下优先级匹配：

1. languageCode + scriptCode + countryCode
2. languageCode + scriptCode
3. languageCode + countryCode
4. languageCode only
5. countryCode only (作为最后手段)
6. 返回 supportedLocales 第一个元素

1.6 自定义语言解析

MaterialApp(
  localeListResolutionCallback: (deviceLocales, supportedLocales) {
    // deviceLocales: 设备语言列表
    // supportedLocales: 应用支持的语言列表
    // 返回最终选择的 Locale
    return deviceLocales.first;
  },
  localeResolutionCallback: (deviceLocale, supportedLocales) {
    // 单个设备语言的解析
    return deviceLocale;
  },
)

1.7 动态切换语言

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  Locale _locale = const Locale('en', 'US');

  void _changeLocale(Locale newLocale) {
    setState(() {
      _locale = newLocale;
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      locale: _locale,
      localizationsDelegates: const [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: const [
        Locale('en', 'US'),
        Locale('zh', 'CN'),
      ],
      home: LanguageSwitchScreen(onLocaleChange: _changeLocale),
    );
  }
}

1.8 使用 intl 包进行国际化

安装依赖：

dependencies:
  flutter_localizations:
    sdk: flutter
  intl: ^0.19.0

创建本地化文件 l10n.yaml：

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

创建 lib/l10n/app_en.arb：

{
  "@@locale": "en",
  "appTitle": "My App",
  "@appTitle": {
    "description": "The application title"
  },
  "helloWorld": "Hello World",
  "@helloWorld": {
    "description": "A greeting message"
  }
}

创建 lib/l10n/app_zh.arb：

{
  "@@locale": "zh",
  "appTitle": "我的应用",
  "helloWorld": "你好世界"
}

使用本地化：

import 'package:flutter_gen/gen_l10n/app_localizations.dart';

MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
  home: Builder(
    builder: (context) {
      final l10n = AppLocalizations.of(context)!;
      return Scaffold(
        appBar: AppBar(title: Text(l10n.appTitle)),
        body: Center(child: Text(l10n.helloWorld)),
      );
    },
  ),
)

2. 调试工具配置

2.1 调试相关属性总览

属性	类型	默认值	说明
debugShowCheckedModeBanner	bool	true	显示调试模式横幅
showPerformanceOverlay	bool	false	显示性能悬浮层
checkerboardRasterCacheImages	bool	false	棋盘格显示光栅缓存
checkerboardOffscreenLayers	bool	false	棋盘格显示离屏图层
showSemanticsDebugger	bool	false	显示语义调试器
debugShowMaterialGrid	bool	false	显示 Material 网格

2.2 隐藏调试横幅

MaterialApp(
  debugShowCheckedModeBanner: false,
  home: const HomeScreen(),
)

2.3 显示性能悬浮层

MaterialApp(
  showPerformanceOverlay: true,
  home: const HomeScreen(),
)

性能悬浮层显示：

• GPU 渲染时间：每帧渲染耗时
• CPU 使用率：界面构建和布局计算占用

2.4 棋盘格渲染

光栅缓存图像

MaterialApp(
  checkerboardRasterCacheImages: true,
  home: const HomeScreen(),
)

离屏图层

MaterialApp(
  checkerboardOffscreenLayers: true,
  home: const HomeScreen(),
)

注意

棋盘格渲染仅在调试模式下可见，用于诊断性能问题。

2.5 显示 Material 网格

MaterialApp(
  debugShowMaterialGrid: true,
  home: const HomeScreen(),
)

显示 8x8 的 Material Design 网格，用于对齐和布局验证。

2.6 语义调试器

MaterialApp(
  showSemanticsDebugger: true,
  home: const HomeScreen(),
)

显示组件的语义信息，用于无障碍功能测试。

3. 快捷键与操作

3.1 shortcuts 属性

MaterialApp(
  shortcuts: {
    LogicalKeySet(LogicalKeyboardKey.select): const ActivateIntent(),
    LogicalKeySet(LogicalKeyboardKey.escape): const DismissIntent(),
    LogicalKeySet(LogicalKeyboardKey.control, LogicalKeyboardKey.keyS): const SaveIntent(),
  },
  home: const HomeScreen(),
)

3.2 actions 属性

MaterialApp(
  actions: {
    ActivateIntent: CallbackAction<ActivateIntent>(
      onInvoke: (intent) {
        print('Activate triggered');
        return null;
      },
    ),
    SaveIntent: CallbackAction<SaveIntent>(
      onInvoke: (intent) {
        _saveData();
        return null;
      },
    ),
  },
)

3.3 常用 Intent 类型

Intent	说明
ActivateIntent	激活/确认操作
DismissIntent	关闭/取消操作
DoNothingIntent	空操作
CopySelectionTextIntent	复制文本
SelectAllTextIntent	全选文本
PasteTextIntent	粘贴文本

4. 状态恢复

4.1 restorationScopeId

MaterialApp(
  restorationScopeId: 'app_root',
  home: const HomeScreen(),
)

启用状态恢复后，应用退出后重新打开可以恢复到之前的状态。

4.2 使用 RestorationMixin

class HomeScreen extends StatefulWidget {
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> with RestorationMixin {
  final RestorableInt _counter = RestorableInt(0);

  @override
  String? get restorationId => 'home_screen';

  @override
  void restoreState(RestorationBucket? oldBucket, bool initialRestore) {
    registerForRestoration(_counter, 'counter');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(child: Text('Count: ${_counter.value}')),
      floatingActionButton: FloatingActionButton(
        onPressed: () => setState(() => _counter.value++),
        child: const Icon(Icons.add),
      ),
    );
  }
}

5. 全局滚动行为

5.1 scrollBehavior

MaterialApp(
  scrollBehavior: const BouncingScrollBehavior(),
  home: const HomeScreen(),
)

5.2 自定义 ScrollBehavior

class MyScrollBehavior extends ScrollBehavior {
  @override
  ScrollPhysics getScrollPhysics(BuildContext context) {
    return const BouncingScrollPhysics();
  }

  @override
  Widget buildOverscrollIndicator(BuildContext context, Widget child, ScrollableDetails details) {
    return GlowingOverscrollIndicator(
      child: child,
      color: Colors.blue,
      showTrailing: false,
    );
  }
}

MaterialApp(
  scrollBehavior: MyScrollBehavior(),
  home: const HomeScreen(),
)

6. 完整示例

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

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter i18n Demo',
      debugShowCheckedModeBanner: false,

      // 本地化配置
      locale: const Locale('en', 'US'),
      localizationsDelegates: const [
        GlobalMaterialLocalizations.delegate,
        GlobalWidgetsLocalizations.delegate,
        GlobalCupertinoLocalizations.delegate,
      ],
      supportedLocales: const [
        Locale('en', 'US'),
        Locale('zh', 'CN'),
        Locale('zh', 'TW'),
        Locale('ja', 'JP'),
      ],

      // 调试配置
      showPerformanceOverlay: false,
      checkerboardRasterCacheImages: false,
      checkerboardOffscreenLayers: false,
      showSemanticsDebugger: false,
      debugShowMaterialGrid: false,

      // 滚动行为
      scrollBehavior: const BouncingScrollBehavior(),

      // 状态恢复
      restorationScopeId: 'app_root',

      home: const HomeScreen(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Flutter i18n & Debug'),
      ),
      body: const Center(
        child: Text('Hello World!'),
      ),
    );
  }
}

7. 生产环境注意事项

生产环境

在发布版本（Release/Profile）中：

• debugShowCheckedModeBanner 强制为 false
• showPerformanceOverlay 强制为 false
• checkerboardRasterCacheImages 强制为 false
• checkerboardOffscreenLayers 强制为 false
• showSemanticsDebugger 强制为 false
• debugShowMaterialGrid 强制为 false
• debugPrint 输出被静默

8. 开发者工具建议

8.1 DevTools

• 使用 Flutter DevTools 的 Performance 视图分析帧率
• 使用 Widget Inspector 检查组件树
• 使用 Timeline 视图分析布局和渲染性能

8.2 调试技巧

1. 热重载 (Hot Reload)：r 键或点击 Flutter DevTools 的闪电图标
2. 热重启 (Hot Restart)：R 键完全重启应用
3. debugPrint：debugPrint('log message') 在调试模式下输出日志

最佳实践

1. 本地化配置应在应用早期完成，考虑支持的语言完整性
2. 生产环境禁用所有调试工具以优化性能
3. 使用 useMaterial3: true 配合 ColorScheme.fromSeed 获得最佳视觉效果
4. 定期使用无障碍工具测试应用的可访问性