magic_picker
File and image picking for a Magic app. The Pick facade opens the gallery, camera, file dialog, directory dialog and save dialog, and answers with core's MagicFile (a null or an empty list when the user cancels). PickerServiceProvider sets LocalAdapterContract.downloadHandler in boot(), so Storage.download opens the share sheet on mobile, macOS and Windows and the save dialog on Linux. XFile.toMagicFile() and MagicFile.toXFile() convert between the two file types.
This skill covers magic_picker only. The Magic framework itself (container, Storage, MagicFile, Http, config) is the magic-framework skill.
Install
flutter pub add magic_picker
dart run magic:dowel plugin:install magic_picker
Requires Dart >=3.13, Flutter >=3.47 and magic ^1.0.0. The installer registers PickerServiceProvider in lib/config/app.dart and publishes no config. Import only the barrel, package:magic_picker/magic_picker.dart, which also exports XFile and CameraDevice. The app owns the platform permissions: the photo library and camera usage descriptions in Info.plist and the file-access entitlements on macOS.
Pick rules
- Treat
null(and an empty list fromimagesandfiles) as a cancelled pick and return early. Cancelling is not an error. - Give
Pick.cameraandPick.recordVideoanonError,fallbackToGallery: true, or both. With neither, a refused camera permission rethrows. WithonErroralone the call answersnull. - Pass
extensionswithout the dot (['pdf']). Do not passwithDatatoPick.fileorPick.files; it no longer exists. Bytes load on demand throughreadAsBytes. Pick.directoryreturns a pathString?and is not available on the web.Pick.saveFilerequiresfileNameandbytesand answers aUri. Checkscheme == 'file'beforetoFilePath(): Android answerscontentand the webblob.MagicFile.sizeis filled for every pick, but a file removed after the pick leavesnullor0. Treat both as unknown when enforcing an upload limit.MagicFilelives inpackage:magic/magic.dart; import it when you name the type.
Download rules
- Register
PickerServiceProvider. Without it,Storage.downloadon mobile and desktop throwsUnsupportedErrornamingmagic_picker. The web ignores the handler and downloads through the browser. - On Linux
share_pluscannot share a file, so the handler opens the save dialog with the file's bytes instead of a share sheet; expect a dialog there, not a sheet. - The handler is a static (
LocalAdapterContract.downloadHandler). Assign your own afterMagic.inithas finished, becauseboot()overwrites it. PickerServiceProvider(app, share: ...)replaces the share sheet; use it in tests only. It is never called on Linux.
XFile rules
toXFile()is synchronous on mobile and desktop and aFuture<XFile>on the web. In code that builds for both, wrap it inFuture.valueorawaitit.- It throws
UnsupportedErrorfor aMagicFilewith nopathon IO, and with no bytes on the web.
Recipes
Pick an image and store it:
import 'package:magic_picker/magic_picker.dart';
Future<String?> chooseAvatar() async {
final image = await Pick.image(maxWidth: 512, imageQuality: 80);
if (image == null) return null;
return image.store('avatars/profile.jpg');
}
Take a photo, falling back to the gallery:
import 'package:magic_picker/magic_picker.dart';
Future<void> takePhoto() async {
final photo = await Pick.camera(
fallbackToGallery: true,
onError: (Object error) => print('Camera failed: $error'),
);
print(photo?.name);
}
Share a stored file:
import 'package:magic/magic.dart';
Future<void> export() {
return Storage.download('reports/2024.pdf', name: 'Annual Report.pdf');
}
Testing
No mocking library is needed. In setUp() call MagicApp.reset() and Magic.flush(). Boot the provider by hand with a recording callback, await PickerServiceProvider(Magic.app, share: (params) async => shared.add(params)).boot(), then call the handler or Storage.download. LocalAdapterContract.downloadHandler is a static that Magic.flush() does not clear, so set it to null in tearDown(). Fake the pickers by replacing ImagePickerPlatform.instance and FilePickerPlatform.instance and restoring the originals afterwards. The IO form of toXFile runs on the VM; the web form needs flutter test --platform chrome.