从版本演进看 shared_preferences_webFlutter Web 端本地存储插件实现与升级指南【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/pluginsshared_preferences_web 是 Flutter 官方维护的联邦插件体系中 Web 平台的实现负责把shared_preferences的 API 映射到浏览器localStorage上。本文以本仓库中该包的 CHANGELOG.md 为脉络梳理其版本演进历程并结合 lib/shared_preferences_web.dart 的源码实现与集成测试讲解 Web 端本地存储的底层原理、联邦插件注册机制以及开发者升级到 2.x 时需要关注的破坏性变化。读完本文你将掌握该插件的运行机制、测试方法与版本兼容要点。一、版本演进全景从 0.1.0 到 2.0.4CHANGELOG 完整记录了该包从诞生到成熟的全部变更可以清晰看出三条主线平台适配、工程质量与空安全迁移。1. 早期阶段0.1.0 ~ 0.1.28补齐平台占位与依赖约束0.1.0初始发布随后在0.1.01中移除 pubspec 中废弃的author:字段并要求 Flutter SDK ≥ 1.10.0。0.1.1新增了配套的shared_preferences_macos包联邦插件体系开始成型。0.1.2提升 Flutter 版本下限并添加 stub podspec 文件为后续 Apple 平台接入做准备。0.1.21临时添加了一个空实现的android/目录用于规避 Flutter issue #46898Android 构建在缺少该目录时解析失败的问题。这是联邦插件早期占位目录的典型做法。0.1.22 ~ 0.1.28清理未使用的onMethodCall方法、升级 gradle 版本规避 Android 工程问题、显式声明 pedantic dev_dependency、将 Dart 下限提升到 2.1.0最终在0.1.27中移除 Android 占位目录宣告该包正式回归纯 Web 实现。从源码看Web 实现根本不需要任何原生目录——lib/shared_preferences_web.dart 只依赖dart:html与flutter_web_plugins因此占位目录的移除与声明 API 稳定性0.1.25共同标志着该包走向成熟。2. 2.0.0空安全迁移的破坏性升级2.0.0是唯一一个带破坏性语义的版本——迁移到 null-safety。这要求使用方 Dart SDK 必须 ≥ 2.12.0插件内部所有可空类型显式标注例如源码中setValue(String valueType, String key, Object? value)的Object?参数、registerWith(Registrar? registrar)的可空注册器。3. 2.0.1 ~ 2.0.4测试体系与代码质量收尾2.0.1更新 README 安装说明把测试迁移到 example 目录改用flutter drive作为集成测试运行方式。这解释了为什么包的 test/tests_exist_elsewhere_test.dart 里只有一个打印提示的占位测试——真正的测试已全部迁往 example。2.0.2在 pubspec 中为联邦插件添加implements声明详见下文第三节。2.0.3修复新启用的 analyzer 选项告警并移除对meta的依赖。2.0.4修复library_private_types_in_public_api、sort_child_properties_last、use_key_in_widget_constructors等 lint 警告。NEXT未发布将最低 Flutter 版本提升至3.0。二、核心实现原理localStorage 上的 JSON 编解码层虽然 CHANGELOG 以变更条目为主但对应版本的行为可以从 lib/shared_preferences_web.dart 中完整还原。整个实现只有约 80 行围绕浏览器html.window.localStorage封装了四个核心操作方法对应 shared_preferences API底层行为getAll()getKeys/get*系列遍历所有flutter.前缀键并逐个json.decodesetValue()setString/setBool/setInt/setDouble/setStringListjson.encode后写入localStorage[key]remove()remove直接localStorage.remove(key)clear()clear只移除flutter.前缀的键实现中有三个值得注意的设计点键前缀校验_checkPrefix要求所有键必须以flutter.开头否则抛出FormatException源码 L53-L61。这是为了避免污染同一域名下其他应用的数据。clear 的精确删除源码注释明确强调不要使用localStorage.clear()因为它会清掉该域名下所有站点的数据而不仅是flutter.前缀键源码 L22-L28。泛型恢复JSON 往返会丢失泛型信息ListString解码后变成Listdynamic因此_decodeValue对 List 显式执行castString()恢复 RTTI源码 L75-L80。这正是2.0.0空安全迁移得以成立的基础——Object?值通过json.encode序列化读取时再json.decode还原整个编解码链路在 null-safety 下依然完整。三、联邦插件结构implements 声明与自动注册2.0.2添加的implements是理解该包运行方式的关键。查看 pubspec.yamlflutter: plugin: implements: shared_preferences platforms: web: pluginClass: SharedPreferencesPlugin fileName: shared_preferences_web.dart这表示shared_preferences_web是shared_preferences联邦插件在 Web 端的认可endorsed实现。开发者只需在工程中依赖shared_preferencesFlutter 工具链在构建 Web 目标时会自动拉入本包无需手动注册任何平台代码。插件入口是 SharedPreferencesPlugin.registerWith其内部只有一行核心逻辑SharedPreferencesStorePlatform.instance SharedPreferencesPlugin();即把SharedPreferencesStorePlatform来自shared_preferences_platform_interface的默认实例替换为 Web 实现。集成测试 shared_preferences_web_test.dart 专门验证了这一注册行为先用MethodChannelSharedPreferencesStore占位调用registerWith后断言实例已变为SharedPreferencesPlugin。四、测试体系为什么测试都在 example 目录CHANGELOG 2.0.1 提到的Move tests toexampledirectory需要结合测试文件理解。包级目录下 test/tests_exist_elsewhere_test.dart 只负责在flutter test时打印指引说明真实测试位置而真正的行为测试位于 example/integration_test/shared_preferences_web_test.dart因为 Web 插件的dart:html与localStorage只能在真实浏览器环境中运行。测试覆盖了本节前述的全部关键行为getAll只返回flutter.前缀键unprefixed_key被过滤setValue断言写入值与json.encode结果一致并验证StringList恢复为ListStringremove / clear验证非前缀键抛FormatException、clear保留非 Flutter 键registerWith验证插件注册逻辑。运行方式见 run_test.sh依赖 chromedriverflutter drive -d web-server --web-port7357 --browser-namechrome \ --drivertest_driver/integration_test.dart \ --targetintegration_test/shared_preferences_web_test.dart五、升级到 2.x 的实操清单综合 CHANGELOG 各版本约束开发者迁移到shared_preferences_web2.x 需要满足SDK 版本Dart ≥ 2.12.02.0.0 空安全、Flutter ≥ 3.0NEXT 版本要求pubspec 中已显式声明sdk: 2.12.0 3.0.0、flutter: 3.0.0依赖方式工程中只需依赖shared_preferences无需直接声明本包endorsed 机制自动引入键名规范自定义键需以flutter.开头否则运行时会抛FormatException数据兼容性Web 端数据以 JSON 字符串存储于localStorage跨版本读取依赖编解码一致性升级后旧键值仍可正常读取。结语从 0.1.0 的初始发布到 2.0.4 的 lint 收尾CHANGELOG.md 完整折射出一个官方联邦插件走向稳定的全过程平台占位的增删、空安全迁移、测试体系重构、工程质量收敛。而其 80 行的核心实现与详尽的集成测试则为 Web 端本地存储提供了麻雀虽小、五脏俱全的最佳范本。读者如需深入可继续查看 README.md 与同目录下的 pubspec.yaml。【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从版本演进看 shared_preferences_web：Flutter Web 端本地存储插件实现与升级指南
从版本演进看 shared_preferences_webFlutter Web 端本地存储插件实现与升级指南【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/pluginsshared_preferences_web 是 Flutter 官方维护的联邦插件体系中 Web 平台的实现负责把shared_preferences的 API 映射到浏览器localStorage上。本文以本仓库中该包的 CHANGELOG.md 为脉络梳理其版本演进历程并结合 lib/shared_preferences_web.dart 的源码实现与集成测试讲解 Web 端本地存储的底层原理、联邦插件注册机制以及开发者升级到 2.x 时需要关注的破坏性变化。读完本文你将掌握该插件的运行机制、测试方法与版本兼容要点。一、版本演进全景从 0.1.0 到 2.0.4CHANGELOG 完整记录了该包从诞生到成熟的全部变更可以清晰看出三条主线平台适配、工程质量与空安全迁移。1. 早期阶段0.1.0 ~ 0.1.28补齐平台占位与依赖约束0.1.0初始发布随后在0.1.01中移除 pubspec 中废弃的author:字段并要求 Flutter SDK ≥ 1.10.0。0.1.1新增了配套的shared_preferences_macos包联邦插件体系开始成型。0.1.2提升 Flutter 版本下限并添加 stub podspec 文件为后续 Apple 平台接入做准备。0.1.21临时添加了一个空实现的android/目录用于规避 Flutter issue #46898Android 构建在缺少该目录时解析失败的问题。这是联邦插件早期占位目录的典型做法。0.1.22 ~ 0.1.28清理未使用的onMethodCall方法、升级 gradle 版本规避 Android 工程问题、显式声明 pedantic dev_dependency、将 Dart 下限提升到 2.1.0最终在0.1.27中移除 Android 占位目录宣告该包正式回归纯 Web 实现。从源码看Web 实现根本不需要任何原生目录——lib/shared_preferences_web.dart 只依赖dart:html与flutter_web_plugins因此占位目录的移除与声明 API 稳定性0.1.25共同标志着该包走向成熟。2. 2.0.0空安全迁移的破坏性升级2.0.0是唯一一个带破坏性语义的版本——迁移到 null-safety。这要求使用方 Dart SDK 必须 ≥ 2.12.0插件内部所有可空类型显式标注例如源码中setValue(String valueType, String key, Object? value)的Object?参数、registerWith(Registrar? registrar)的可空注册器。3. 2.0.1 ~ 2.0.4测试体系与代码质量收尾2.0.1更新 README 安装说明把测试迁移到 example 目录改用flutter drive作为集成测试运行方式。这解释了为什么包的 test/tests_exist_elsewhere_test.dart 里只有一个打印提示的占位测试——真正的测试已全部迁往 example。2.0.2在 pubspec 中为联邦插件添加implements声明详见下文第三节。2.0.3修复新启用的 analyzer 选项告警并移除对meta的依赖。2.0.4修复library_private_types_in_public_api、sort_child_properties_last、use_key_in_widget_constructors等 lint 警告。NEXT未发布将最低 Flutter 版本提升至3.0。二、核心实现原理localStorage 上的 JSON 编解码层虽然 CHANGELOG 以变更条目为主但对应版本的行为可以从 lib/shared_preferences_web.dart 中完整还原。整个实现只有约 80 行围绕浏览器html.window.localStorage封装了四个核心操作方法对应 shared_preferences API底层行为getAll()getKeys/get*系列遍历所有flutter.前缀键并逐个json.decodesetValue()setString/setBool/setInt/setDouble/setStringListjson.encode后写入localStorage[key]remove()remove直接localStorage.remove(key)clear()clear只移除flutter.前缀的键实现中有三个值得注意的设计点键前缀校验_checkPrefix要求所有键必须以flutter.开头否则抛出FormatException源码 L53-L61。这是为了避免污染同一域名下其他应用的数据。clear 的精确删除源码注释明确强调不要使用localStorage.clear()因为它会清掉该域名下所有站点的数据而不仅是flutter.前缀键源码 L22-L28。泛型恢复JSON 往返会丢失泛型信息ListString解码后变成Listdynamic因此_decodeValue对 List 显式执行castString()恢复 RTTI源码 L75-L80。这正是2.0.0空安全迁移得以成立的基础——Object?值通过json.encode序列化读取时再json.decode还原整个编解码链路在 null-safety 下依然完整。三、联邦插件结构implements 声明与自动注册2.0.2添加的implements是理解该包运行方式的关键。查看 pubspec.yamlflutter: plugin: implements: shared_preferences platforms: web: pluginClass: SharedPreferencesPlugin fileName: shared_preferences_web.dart这表示shared_preferences_web是shared_preferences联邦插件在 Web 端的认可endorsed实现。开发者只需在工程中依赖shared_preferencesFlutter 工具链在构建 Web 目标时会自动拉入本包无需手动注册任何平台代码。插件入口是 SharedPreferencesPlugin.registerWith其内部只有一行核心逻辑SharedPreferencesStorePlatform.instance SharedPreferencesPlugin();即把SharedPreferencesStorePlatform来自shared_preferences_platform_interface的默认实例替换为 Web 实现。集成测试 shared_preferences_web_test.dart 专门验证了这一注册行为先用MethodChannelSharedPreferencesStore占位调用registerWith后断言实例已变为SharedPreferencesPlugin。四、测试体系为什么测试都在 example 目录CHANGELOG 2.0.1 提到的Move tests toexampledirectory需要结合测试文件理解。包级目录下 test/tests_exist_elsewhere_test.dart 只负责在flutter test时打印指引说明真实测试位置而真正的行为测试位于 example/integration_test/shared_preferences_web_test.dart因为 Web 插件的dart:html与localStorage只能在真实浏览器环境中运行。测试覆盖了本节前述的全部关键行为getAll只返回flutter.前缀键unprefixed_key被过滤setValue断言写入值与json.encode结果一致并验证StringList恢复为ListStringremove / clear验证非前缀键抛FormatException、clear保留非 Flutter 键registerWith验证插件注册逻辑。运行方式见 run_test.sh依赖 chromedriverflutter drive -d web-server --web-port7357 --browser-namechrome \ --drivertest_driver/integration_test.dart \ --targetintegration_test/shared_preferences_web_test.dart五、升级到 2.x 的实操清单综合 CHANGELOG 各版本约束开发者迁移到shared_preferences_web2.x 需要满足SDK 版本Dart ≥ 2.12.02.0.0 空安全、Flutter ≥ 3.0NEXT 版本要求pubspec 中已显式声明sdk: 2.12.0 3.0.0、flutter: 3.0.0依赖方式工程中只需依赖shared_preferences无需直接声明本包endorsed 机制自动引入键名规范自定义键需以flutter.开头否则运行时会抛FormatException数据兼容性Web 端数据以 JSON 字符串存储于localStorage跨版本读取依赖编解码一致性升级后旧键值仍可正常读取。结语从 0.1.0 的初始发布到 2.0.4 的 lint 收尾CHANGELOG.md 完整折射出一个官方联邦插件走向稳定的全过程平台占位的增删、空安全迁移、测试体系重构、工程质量收敛。而其 80 行的核心实现与详尽的集成测试则为 Web 端本地存储提供了麻雀虽小、五脏俱全的最佳范本。读者如需深入可继续查看 README.md 与同目录下的 pubspec.yaml。【免费下载链接】pluginsPlugins for Flutter maintained by the Flutter team项目地址: https://gitcode.com/gh_mirrors/pl/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考