diff --git a/packages/shared_preferences/shared_preferences/CHANGELOG.md b/packages/shared_preferences/shared_preferences/CHANGELOG.md index e9275c315ab..7dfad33da36 100644 --- a/packages/shared_preferences/shared_preferences/CHANGELOG.md +++ b/packages/shared_preferences/shared_preferences/CHANGELOG.md @@ -1,3 +1,7 @@ +## 2.3.5 + +* Adds information about Android SharedPreferences support. + ## 2.3.4 * Security update, requires shared_preferences_android to be 2.3.4. diff --git a/packages/shared_preferences/shared_preferences/README.md b/packages/shared_preferences/shared_preferences/README.md index bd9fd06dbc9..ad6c7268eed 100644 --- a/packages/shared_preferences/shared_preferences/README.md +++ b/packages/shared_preferences/shared_preferences/README.md @@ -50,9 +50,25 @@ latest data stored on the native platform regardless of what process was used to ### Android platform storage -The [SharedPreferences] API uses the native [Android Shared Preferences](https://developer.android.com/reference/android/content/SharedPreferences) tool to store data. +The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs can use [DataStore Preferences](https://developer.android.com/topic/libraries/architecture/datastore) or [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) to store data. +In most cases you should use the default option of DataStore Preferences, as it is the platform-recommended preferences storage system. +However, in some cases you may need to interact with preferences that were written to SharedPreferences by code you don't control. -The [SharedPreferencesAsync] and [SharedPreferencesWithCache] APIs use [DataStore Preferences](https://developer.android.com/topic/libraries/architecture/datastore) to store data. +To use the `Android SharedPreferences` backend, use the `SharedPreferencesAsyncAndroidOptions` when using [SharedPreferencesAsync] on Android. + +```dart +import 'package:shared_preferences_android/shared_preferences_android.dart'; +``` + +```dart +const SharedPreferencesAsyncAndroidOptions options = + SharedPreferencesAsyncAndroidOptions( + backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences, + originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions( + fileName: 'the_name_of_a_file')); +``` + +The [SharedPreferences] API uses the native [Android SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) tool to store data. ## Examples Here are small examples that show you how to use the API. @@ -187,7 +203,7 @@ the new prefix otherwise the old preferences will be inaccessible. | Platform | SharedPreferences | SharedPreferencesAsync/WithCache | | :--- | :--- | :--- | -| Android | SharedPreferences | DataStore Preferences | +| Android | SharedPreferences | DataStore Preferences or SharedPreferences | | iOS | NSUserDefaults | NSUserDefaults | | Linux | In the XDG_DATA_HOME directory | In the XDG_DATA_HOME directory | | macOS | NSUserDefaults | NSUserDefaults | diff --git a/packages/shared_preferences/shared_preferences/example/android/app/build.gradle b/packages/shared_preferences/shared_preferences/example/android/app/build.gradle index 72e4b4d6c02..2cd7b34c698 100644 --- a/packages/shared_preferences/shared_preferences/example/android/app/build.gradle +++ b/packages/shared_preferences/shared_preferences/example/android/app/build.gradle @@ -30,6 +30,10 @@ android { main.java.srcDirs += 'src/main/kotlin' } + kotlinOptions { + jvmTarget = '11' + } + defaultConfig { applicationId "io.flutter.plugins.sharedpreferencesexample" minSdkVersion flutter.minSdkVersion diff --git a/packages/shared_preferences/shared_preferences/example/lib/readme_excerpts.dart b/packages/shared_preferences/shared_preferences/example/lib/readme_excerpts.dart index 032409d4901..3df203c1614 100644 --- a/packages/shared_preferences/shared_preferences/example/lib/readme_excerpts.dart +++ b/packages/shared_preferences/shared_preferences/example/lib/readme_excerpts.dart @@ -4,6 +4,9 @@ // ignore_for_file: public_member_api_docs, unused_local_variable, invalid_use_of_visible_for_testing_member import 'package:shared_preferences/shared_preferences.dart'; +// #docregion Android_Options1 +import 'package:shared_preferences_android/shared_preferences_android.dart'; +// #enddocregion Android_Options1 Future readmeSnippets() async { // #docregion Write @@ -92,3 +95,11 @@ Future readmeTestSnippets() async { SharedPreferences.setMockInitialValues(values); // #enddocregion Tests } + +// #docregion Android_Options2 +const SharedPreferencesAsyncAndroidOptions options = + SharedPreferencesAsyncAndroidOptions( + backend: SharedPreferencesAndroidBackendLibrary.SharedPreferences, + originalSharedPreferencesOptions: AndroidSharedPreferencesStoreOptions( + fileName: 'the_name_of_a_file')); +// #enddocregion Android_Options2 diff --git a/packages/shared_preferences/shared_preferences/example/pubspec.yaml b/packages/shared_preferences/shared_preferences/example/pubspec.yaml index cbf79d353af..96753eed795 100644 --- a/packages/shared_preferences/shared_preferences/example/pubspec.yaml +++ b/packages/shared_preferences/shared_preferences/example/pubspec.yaml @@ -3,8 +3,8 @@ description: Demonstrates how to use the shared_preferences plugin. publish_to: none environment: - sdk: ^3.4.0 - flutter: ">=3.22.0" + sdk: ^3.5.0 + flutter: ">=3.24.0" dependencies: flutter: @@ -16,6 +16,7 @@ dependencies: # The example app is bundled with the plugin so we use a path dependency on # the parent directory to use the current plugin's version. path: ../ + shared_preferences_android: ^2.4.0 shared_preferences_platform_interface: ^2.4.0 dev_dependencies: diff --git a/packages/shared_preferences/shared_preferences/pubspec.yaml b/packages/shared_preferences/shared_preferences/pubspec.yaml index 856cd2a22cf..d819a46785f 100644 --- a/packages/shared_preferences/shared_preferences/pubspec.yaml +++ b/packages/shared_preferences/shared_preferences/pubspec.yaml @@ -3,7 +3,7 @@ description: Flutter plugin for reading and writing simple key-value pairs. Wraps NSUserDefaults on iOS and SharedPreferences on Android. repository: https://github.com/flutter/packages/tree/main/packages/shared_preferences/shared_preferences issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+shared_preferences%22 -version: 2.3.4 +version: 2.3.5 environment: sdk: ^3.5.0