跨平台移动开发前端UI组件OpenHarmony图形学【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载本文以 CPF-Flutter/flutter_flutter 开源仓库Flutter SDK 与 Engine 的 OpenHarmony 适配版本为基础系统梳理 Flutter 3.27 到 3.35 三个大版本之间的全部破坏性变更Breaking Changes。文章覆盖变更来源版本、是否需要适配、具体 API 迁移方式并逐项对照当前仓库源码给出实现层面的证据与迁移示例帮助开发者在升级 SDK 或迁移存量项目时一次性完成适配评估。从 Flutter 3.27 到 Flutter 3.35框架层面的演进集中在性能优化、新功能引入与框架 API 规范化三方面。官方共发布 26 项破坏性变更其中 3.29 引入 6 项、3.32 引入 10 项、3.35 引入 10 项按适配要求划分有 4 项无需适配多为平台层内部行为或移除旧 API其余 22 项均要求开发者调整代码。下文按版本分组逐项说明并在每项后给出本仓库中的源码落点作为迁移依据。一、变更总览26 项变更的分组与适配优先级先给出全部 26 项变更的速查总表。适配标记为是的项在升级后大概率触发编译告警deprecated注解或行为变化需要主动迁移标记为否的项通常由 SDK/引擎侧自动处理开发者只需知晓即可。版本变更主题是否需要适配3.29删除 v1 Android 嵌入 Java API否3.29弃用 WebGoldenComparator是3.29弃用 ThemeData.dialogBackgroundColor改用 DialogThemeData.backgroundColor是3.29ImageFilter.blur 默认瓦片模式自动选择是3.29更新 Material 3 滑块是3.29更新 Material 3 进展指标是3.32弃用 SystemContextMenuController.show否3.32弃用 ExpansionTileController改用 ExpansibleController是3.32弃用 RouteTransitionRecord.markFor改用 markForComplete是3.32弃用 ThemeData.indicatorColor改用 TabBarThemeData.indicatorColor是3.32Material 主题系统更新是3.32.flutter-plugins-dependencies 代替 .flutter-plugins是3.32本地化消息生成在源端而不是合成包是3.32更改默认 goldenFileComparator 以支持 integration_test是3.32弃用 InputDecoration.maintainHintHeight改用 maintainHintSize是3.32更改欠阻尼弹簧公式是3.35组件主题规范化更新是3.35弃用 DropdownButtonFormField 的 value改用 initialValue是3.35弃用应用栏颜色AppBar 的 color是3.35重新设计 Radio 部件是3.35删除语义Semantics的 elevation 与 thickness是3.35Form 组件不再支持作为 sliver 使用是3.35Android 构建默认设置 abiFilters否3.35macOS / Windows 合并线程否3.35Visibility 在 maintainState 下默认不再可聚焦是3.35$FLUTTER_ROOT/version 被 bin/cache/flutter.version.json 取代是二、Flutter 3.29 引入的 6 项变更2.1 删除 v1 Android 嵌入 Java API无需适配Flutter 3.29 移除了 Android 第一代v1嵌入层的 Java API。v1 嵌入方案早已被基于FlutterEngine/FlutterEngineGroup的 v2 嵌入取代因此移除对存量项目影响极小。仍在使用io.flutter.app.FlutterActivityv1 基类的宿主工程需要迁移到io.flutter.embedding.android.FlutterActivity。在 CPF-Flutter 仓库中v2 嵌入的配套示例可见于 dev/integration_tests/android_module_host_with_custom_build_v2_embedding该目录展示了基于 v2 embedding 的宿主工程组织方式仓库中大量 Android 宿主示例如 examples/flutter_view/android也都使用 v2 嵌入模型可作为迁移参考。2.2 弃用 WebGoldenComparator需要适配Flutter 3.29 起 WebGoldenComparator 被弃用。Golden黄金文件测试在 Web 平台上原本依赖 WebGoldenComparator 这一专用比较器弃用后其能力被统一的比较器体系收敛。在 CPF-Flutter 仓库的 flutter_test 包中黄金文件比较器的核心入口位于 packages/flutter_test/lib/src/goldens.dart其中定义了全局的goldenFileComparator默认值为占位的TrivialComparator在运行flutter test时由测试框架替换为真实比较器。该文件同时也提供了临时替换比较器的标准写法保存旧比较器 → 赋新值 →addTearDown恢复如果你的项目实现了自定义比较器请按同样的模式迁移到非弃用 API并在 Web 上使用与新默认行为兼容的比较器实现。2.3 弃用 ThemeData.dialogBackgroundColor需要适配ThemeData.dialogBackgroundColor在 3.29 被弃用官方要求改用DialogThemeData.backgroundColor。这符合 Flutter 将散落在ThemeData上的组件属性逐步下沉到对应组件主题类的总趋势。在 CPF-Flutter 仓库中弃用注解与替代指引清晰可见packages/flutter/lib/src/material/theme_data.dart 中dialogBackgroundColor参数被Deprecated标注提示迁移到DialogThemeData.backgroundColorpackages/flutter/lib/src/material/dialog_theme.dart 中DialogTheme.backgroundColor的文档明确说明please use the [DialogThemeData.backgroundColor] property in [data] instead请改用data中的DialogThemeData.backgroundColor。迁移示例// 旧写法3.29 起弃用 ThemeData( dialogBackgroundColor: Colors.white, ); // 新写法 ThemeData( dialogTheme: DialogThemeData(backgroundColor: Colors.white), );2.4 ImageFilter.blur 默认瓦片模式自动选择需要适配ImageFilter.blur的默认TileMode从固定值改为自动选择。此前模糊操作在图像边缘采用固定的采样模式升级后引擎会根据模糊核的大小与作用区域自动挑选合适的瓦片模式clamp / repeated / mirror 等以改善边缘效果与性能。在 CPF-Flutter 仓库的 framework 中ImageFilter.blur在 widget 层的典型用法位于 packages/flutter/lib/src/widgets/basic.dart例如imageFilter: ui.ImageFilter.blur(sigmaX: 6, sigmaY: 6)这类背影模糊backdrop blur场景相关渲染实现参考 packages/flutter/lib/src/rendering/proxy_box.dart。如果应用对边缘模糊行为有严格预期建议在调用blur时显式传入TileMode避免依赖新默认值导致视觉效果变化。2.5 更新 Material 3 滑块需要适配Material 3 的Slider外观与交互被更新涉及滑块轨道、手柄thumb尺寸与悬停/拖拽状态的表现。适配要点是确认基于SliderThemeData的自定义样式是否仍与新版默认样式兼容。在 CPF-Flutter 仓库中滑块相关实现位于 packages/flutter/lib/src/material/slider.dartSlider类与_SliderStateslider.dart。从源码可见滑块状态的解析已基于MaterialState集合如disabled、hovered、focused、dragged见 slider.dart。如果你的主题里用MaterialStateProperty自定义了overlayColor等属性需重新走查这些状态分支在新版默认样式下的表现。2.6 更新 Material 3 进展指标需要适配Material 3 的进展指示器LinearProgressIndicator、CircularProgressIndicator新增了轨道间距track gap与分段样式等能力。仓库源码 packages/flutter/lib/src/material/progress_indicator.dart 中_LinearProgressIndicatorPainter接收trackGap参数LinearProgressIndicator本身也新增了trackGap与year2023两个兼容开关progress_indicator.darttrackGap轨道与进度条之间的间隙宽度设 0 可隐藏间隙默认取ProgressIndicatorThemeData.trackGapyear2023为保持 2023 年旧版视觉而设的兼容开关置false或ThemeData.useMaterial3为false时会关闭新分段/间隙样式。迁移建议接受新默认样式即可若需恢复旧外观可在LinearProgressIndicator或主题层显式设置year2023: true、trackGap: 0。三、Flutter 3.32 引入的 10 项变更3.1 弃用 SystemContextMenuController.show无需适配3.32 弃用了SystemContextMenuController.show。该 API 用于在文本选择等场景显示系统级上下文菜单弃用后由框架内部走新的调用路径普通应用无需改动因此标记为无需适配。3.2 弃用 ExpansionTileController改用 ExpansibleController需要适配3.32 将ExpansionTileController迁移为更通用的ExpansibleController同时新增了Expansible基础组件。ExpansionTile本身保留但其控制器类被标记弃用。在 CPF-Flutter 仓库中packages/flutter/lib/src/widgets/expansible.dart 定义了ExpansibleController extends ChangeNotifier提供isExpanded状态查询L89、expand()L106与collapse()等编程式控制方法packages/flutter/lib/src/material/expansion_tile.dart 中ExpansionTileController已被Deprecated标注推荐使用ExpansibleController.of获取自动创建的控制器配套的自动修复规则位于 packages/flutter/lib/fix_data/fix_material/fix_expansion_tile.yaml。迁移示例// 旧写法3.32 起弃用 ExpansionTileController _controller ExpansionTileController(); ExpansionTile(controller: _controller, ...); // 新写法 ExpansibleController _controller ExpansibleController(); ExpansionTile(controller: _controller, ...); _controller.expand(); _controller.collapse();3.3 弃用 RouteTransitionRecord.markFor改用 markForComplete需要适配RouteTransitionRecord的markForPop/markForRemove被统一收拢为markForComplete。该类型用于 Navigator 2.0 页面路由过渡的记录与决策resolve/_transition流程自定义路由过渡的开发者需要更新调用点。仓库源码 packages/flutter/lib/src/widgets/navigator.dart 中清晰可见markForComplete是新方法而markForPop等旧方法被Deprecated标注并提示 Call markForComplete instead.markForRemove也改为直接委托markForComplete()。框架内部如resolve中对退出路由统一调用exitingPageRoute.markForComplete()见 navigator.dart已全部切换到新 API。3.4 弃用 ThemeData.indicatorColor改用 TabBarThemeData.indicatorColor需要适配ThemeData.indicatorColorTabBar 下划线指示器颜色被弃用改由TabBarThemeData.indicatorColor承担。仓库中弃用注解见 packages/flutter/lib/src/material/theme_data.dart提示 Use TabBarThemeData.indicatorColor instead.对应的新属性定义在 packages/flutter/lib/src/material/tab_bar_theme.dart 中。迁移示例// 旧写法3.32 起弃用 ThemeData(indicatorColor: Colors.blue); // 新写法 ThemeData( tabBarTheme: TabBarThemeData(indicatorColor: Colors.blue), );3.5 Material 主题系统更新需要适配3.32 对 Material 主题系统做了一轮系统性调整核心是把组件级属性继续从ThemeData迁移到各自的*ThemeData类并统一部分组件的默认值。本仓库 packages/flutter/lib/src/material/theme_data.dart 中散布的Deprecated注解如dialogBackgroundColor、indicatorColor相关条目见 L368-L382即是这一轮主题去中心化的实例。建议升级后在flutter analyze输出中检索所有ThemeData属性告警逐条迁移到对应组件主题类。3.6 .flutter-plugins-dependencies 代替 .flutter-plugins需要适配插件清单文件.flutter-plugins被.flutter-plugins-dependencies取代。新版清单以 JSON 格式描述插件的依赖关系含平台插件注册信息供工具链解析。该文件由flutter pub get自动生成位于工程根目录。开发者通常无需手改但若存在 CI 脚本或自定义工具读取.flutter-plugins需要同步更新读取逻辑。3.7 本地化消息生成在源端而不是合成包需要适配flutter gen-l10n的产物生成位置发生变化本地化消息不再在合成包synthetic package中生成而是直接生成在源端工程内的lib/生成目录。影响点是 import 路径依赖合成包路径的 import 需要改为源端相对路径。CPF-Flutter 仓库中的本地化资源组织可参考 packages/flutter_localizations/lib大量.arb文件与生成的 dart 文件共存存量项目可参照其目录结构调整自己的生成目录与 import 声明。3.8 更改默认 goldenFileComparator 以支持 integration_test需要适配3.32 更改了默认的黄金文件比较器使其支持在integration_test集成测试中运行 golden 测试。此前 golden 比较器主要面向单元测试环境新默认比较器能在集成测试的宿主环境中正确读取与比较黄金文件。仓库中 packages/flutter_test/lib/src/goldens.dart 定义了全局goldenFileComparator相关使用与替换模式可参考 packages/flutter_test/test/goldens_test.dart 与 packages/flutter_test/lib/src/matchers.dart。集成测试场景下的 golden 用例建议显式依赖matchesGoldenFile并在integration_test环境运行以验证新比较器的行为。3.9 弃用 InputDecoration.maintainHintHeight改用 maintainHintSize需要适配InputDecoration.maintainHintHeight被重命名为maintainHintSize。语义上从保持 hint 文本高度扩展为保持 hint 所占空间尺寸用于在无焦点/无内容时维持输入框高度稳定。仓库源码 packages/flutter/lib/src/material/input_decorator.dart 中_InputDecoratorState已改用maintainHintSize字段参与布局计算如 L1069 的decoration.maintainHintSize分支并在 L2763 等处以 Use maintainHintSize instead. 提示弃用。自动修复规则见 packages/flutter/lib/fix_data/fix_material/fix_input_decoration.yaml。迁移示例// 旧写法3.32 起弃用 InputDecoration(maintainHintHeight: true); // 新写法 InputDecoration(maintainHintSize: true);3.10 更改欠阻尼弹簧公式需要适配欠阻尼underdamped弹簧的物理公式被更新用于更准确地模拟真实弹簧。影响面是SpringDescription派生出的动画曲线如SpringSimulation自定义弹簧动画的时序与回弹幅度会略有变化。如果项目中有对弹簧动画的视觉断言或黄金帧测试升级后需要重新校准。该变更与动画物理引擎相关framework 侧无需改代码但建议在升级后走查flutter analyze中与SpringDescription/Curves相关的测试基线。四、Flutter 3.35 引入的 10 项变更4.1 组件主题规范化更新需要适配3.35 继续推进组件主题规范化各组件*ThemeData的默认值、属性名与copyWith行为进一步统一。本仓库中可观察到这类规范化的痕迹例如 packages/flutter/lib/src/material/app_bar_theme.dart 中color与backgroundColor被合并为同一语义并在构造参数中做一致性断言The color and backgroundColor parameters mean the same thing. Only specify one.见 L62-L63。升级时建议对自定义主题做一次全面flutter analyze逐条处理新增告警。4.2 弃用 DropdownButtonFormField 的 value改用 initialValue需要适配DropdownButtonFormField.value被弃用改用FormField.initialValue语义的initialValue。这一改动让 Dropdown 的初始值语义与其他FormField保持一致初始值只作用于首次构建。仓库源码 packages/flutter/lib/src/material/dropdown.dart 中DropdownButtonFormField的value参数带弃用注解 Use initialValue instead.内部通过initialValue: initialValue ?? value做兼容并在didUpdateWidget中仅当initialValue变化时setValueL1927-L1928。同一模式的DropdownMenuFormField也已迁移到initialSelection→initialValue见 packages/flutter/lib/src/material/dropdown_menu_form_field.dart。迁移示例// 旧写法3.35 起弃用 DropdownButtonFormFieldString( value: one, items: [...], onChanged: ..., ); // 新写法 DropdownButtonFormFieldString( initialValue: one, items: [...], onChanged: ..., );4.3 弃用应用栏颜色需要适配3.35 弃用了 AppBar 主题与AppBarTheme上的color以及与backgroundColor的并存使用。仓库源码 packages/flutter/lib/src/material/app_bar_theme.dart 中AppBarThemeData.color被Deprecated标注并提示 Use backgroundColor instead.构造函数同时要求color与backgroundColor二选一。与此配套ThemeData侧散落的 AppBar 颜色配置也需要收敛到appBarTheme。迁移示例// 旧写法3.35 起弃用 AppBarTheme(color: Colors.blue); // 新写法 AppBarThemeData(backgroundColor: Colors.blue);4.4 重新设计 Radio 部件需要适配3.35 重新设计了Radio部件的 APIgroupValue与onChanged从Radio自身迁移到新的祖先组件RadioGroupT由RadioGroup统一管理组内选中值与变更回调。仓库中的实现证据packages/flutter/lib/src/widgets/radio_group.dart 定义了RadioGroupT构造参数为groupValue、onChanged与childpackages/flutter/lib/src/material/radio.dart 中Radio.groupValue与Radio.onChanged均带弃用注解提示 Use a RadioGroup ancestor to manage group value instead. / Use RadioGroup to handle value change instead.RadioGroup额外带来了符合 ARIA APG 规范的键盘导航Tab/方向键/Space见 radio_group.dart与无障碍语义支持。迁移示例// 旧写法3.35 起弃用 RadioString( value: a, groupValue: _selected, onChanged: (v) setState(() _selected v), ); // 新写法 RadioGroupString( groupValue: _selected, onChanged: (v) setState(() _selected v), child: Row( children: [ RadioString(value: a), RadioString(value: b), ], ), );4.5 删除语义Semantics的 elevation 与 thickness需要适配Semantics节点上的elevation海拔与thickness厚度属性被删除。这两项原本服务于无障碍层对组件凸起感的描述因实际消费场景有限被移除。使用到Semantics(elevation: ...)或相关语义属性的代码需要删除对应参数。4.6 Form 组件不再支持作为 sliver 使用需要适配Form不再支持以 sliver 形式出现在滚动视图如CustomScrollView中。此前Form依赖的语义合并行为与 sliver 懒加载机制冲突官方决定移除该用法。如果你的布局中把Form直接作为SliverList/CustomScrollView的 sliver child需要改为在普通Column/ListView中承载Form或将语义合并逻辑下沉到具体字段组件。4.7 Android 构建默认设置 abiFilters无需适配3.35 起Android 构建默认设置了abiFiltersABI 过滤默认只打包构建目标设备/任务对应的 ABI从而缩小 APK 体积。该变更由 Gradle 插件自动处理应用无需改动仅当你的工程在build.gradle中显式覆盖了abiFilters时需确认覆盖值仍符合发布要求。4.8 macOS 与 Windows 上的合并线程无需适配3.35 在 macOS 与 Windows 平台将部分引擎线程合并如将 UI 线程与平台线程合并调度以减少线程切换开销。该变更由引擎侧处理Dart 侧代码无需改动。对于使用平台通道platform channel高频通信的桌面应用可以关注帧率与延迟表现仓库中桌面平台的相关宿主工程可参考 examples/flutter_view/macos 与 examples/flutter_view/windows。4.9 Visibility 在 maintainState 下默认不再可聚焦需要适配行为变更当Visibility.maintainState为true时隐藏的子组件默认不再保持可聚焦focusable。此前即使组件不可见只要maintainState开启焦点仍可落入隐藏子树导致键盘/读屏焦点掉进不可见区域。仓库实现 packages/flutter/lib/src/widgets/visibility.dart 中可见性通过ExcludeFocus(excluding: !visible !maintainFocusability, child: child)控制焦点排除新增的maintainFocusability参数L70默认false即maintainState开启时默认排除焦点。若确实需要隐藏后仍可聚焦需显式设置maintainFocusability: true注意其依赖maintainState。迁移示例// 3.35 起默认行为隐藏后不可聚焦 Visibility(visible: false, maintainState: true, child: child); // 需要隐藏后仍可聚焦时 Visibility( visible: false, maintainState: true, maintainFocusability: true, // 必须同时开启 maintainState child: child, );4.10 $FLUTTER_ROOT/version 被 bin/cache/flutter.version.json 取代需要适配Flutter SDK 根目录下的version文本文件被bin/cache/flutter.version.json取代。读取 SDK 版本号的脚本、CI 与本地化工具需要改为解析 JSON 文件中的flutterVersion字段。仓库源码 packages/flutter_tools/lib/src/version.dart 中getVersionFile明确返回flutterRoot/bin/cache/flutter.version.jsonSDK 版本解析逻辑version.dart 处GitTagVersion.parse(manifest[flutterVersion])也从该 JSON 读取版本信息。如果你的脚本此前读取$FLUTTER_ROOT/version请改为# 旧方式3.35 起失效 cat $FLUTTER_ROOT/version # 新方式 python3 -c import json;print(json.load(open($FLUTTER_ROOT/bin/cache/flutter.version.json))[flutterVersion])五、升级与适配路线图综合 26 项变更建议按以下顺序完成 CPF-Flutter 仓库对应 SDK 版本的升级适配先升级后分析切换 SDK 后立刻运行flutter analyze利用Deprecated注解一次性定位第 2.24.9 节中所有需要适配的 API 调用点借助自动修复本仓库 flutter 包中提供了多处 fix_data 规则如 fix_expansion_tile.yaml、fix_input_decoration.yamlIDE 会提示一键迁移 ExpansionTileController→ExpansibleController、maintainHintHeight→maintainHintSize 等机械性改动重点回归三类行为主题视觉2.3/2.5/2.6/3.4/4.1/4.3、表单与选择控件3.2/3.9/4.2/4.4/4.6、焦点与无障碍4.5/4.9更新外部依赖插件清单3.6、本地化生成路径3.7、版本读取脚本4.10属于工程级配置改动需在 CI 中同步验证确认无需适配项2.1、3.1、4.7、4.8 四项由 SDK/引擎自动处理仅需在 Release Notes 中记录供团队知晓行为变化即可。完成上述步骤后项目即可平滑过渡到 Flutter 3.35 语义并充分利用该版本在性能合并线程、ABI 过滤、组件规范RadioGroup、Expansible、主题收敛与开发体验integration_test golden、统一版本文件上的改进。赞分享跨平台移动开发前端UI组件OpenHarmony图形学【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载相关推荐PaddleSpeech TTS 数据集全景指南主流中英日语音语料库的统计、选型与预处理实践PaddleSpeech TTS 数据集全景指南主流中英日语音语料库的统计、选型与预处理实践 本指南以 PaddleSpeech 官方文档 docs/sou跨平台移动开发前端UI组件OpenHarmony图形学Flutter 3.22 到 3.27 破坏性变更深度解读10 项 API 变更与升级适配指南基于 flutter_flutter OpenHarmony 仓库Flutter 3.22 到 3.27 破坏性变更深度解读10 项 API 变更与升级适配指南基于 flutter_flutter OpenHarmony跨平台移动开发前端UI组件OpenHarmony图形学flutter_flutterCPF-Flutter OpenHarmony 适配版版本演进全解析从 Flutter 3.35 到 1.12 的变更日志深度解读flutter_flutterCPF Flutter OpenHarmony 适配版版本演进全解析从 Flutter 3.35 到 1.12 的变更日志深跨平台移动开发前端UI组件OpenHarmony图形学上一篇mise token 命令完全指南查看与调试 Git 平台认证令牌下一篇FastGPT 新资源权限接入实施指南从权限位定义、鉴权函数到协作者管理与 Owner 转移的完整落地清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
