pub repository

mirror.p-hatan.ir

cross_file

0.4.0

An abstraction to allow working with files across multiple platforms.

Download archive

Readme

cross_file

An abstraction to allow working with files across multiple platforms.

pub package

	Android	iOS	Linux	macOS	Web	Windows
Support	SDK 24+	iOS 13+	Any	10.15+	Any	Windows 10+

Overview

This package provides a unified API for interacting with resources across platforms through two primary implementation types:

FileSystem

The FileSystem implementation represents resources on a traditional file system. It is used when resources are identified by standard file paths or file:// URIs.

Classes: FileSystemXFile, FileSystemXDirectory.
Use Cases: Desktop applications, app-private storage on mobile, or any environment where direct file system access is available.

ScopedStorage

The ScopedStorage implementation represents resources that are managed or restricted by the platform. These resources are typically identified by platform-specific URIs rather than direct paths.

Classes: ScopedStorageXFile, ScopedStorageXDirectory.
Use Cases: Android Content URIs, iOS Security-Scoped bookmarks, Web Object URLs, or Photo Library assets.
Key Characteristic: Access to these resources may be ephemeral or requires explicit lifecycle management (e.g., using dispose() or specific platform extensions).

Usage

Instantiate a XFile using a uri or path and use its methods and properties to access the file and its metadata.

Example:

final file = XFile.fileSystem(path: 'assets/hello.txt');

debugPrint('File information:');
debugPrint('- URI: ${file.uri}');
debugPrint('- Name: ${await file.name()}');

if (await file.exists()) {
  final String fileContent = await file.readAsString();
  debugPrint('Content of the file: $fileContent');
}

You can find links to the API docs on the pub page.

Implementation-Specific Features

Classes in this package contain an underlying platform implementation that provides features that are specific to an implementation.

To access implementation-specific features, start by adding the platform implementation packages to your app or package:

dart:io cross_file_io
Android Scoped Storage: cross_file_android
iOS/macOS App Sandbox: cross_file_darwin
Web: cross_file_web

Next, add the imports of the implementation packages to your app or package:

// Import for Darwin App Sandbox features.
import 'package:cross_file_darwin/cross_file_darwin.dart';
// Import for Web features.
import 'package:cross_file_web/cross_file_web.dart';

Now, additional features can be accessed through the platform implementations. Classes FileSystemXFile, FileSystemXDirectory, ScopedStorageXFile, and ScopedStorageXDirectory pass their functionality to a class provided by the current platform. Below are a couple of ways to access additional functionality provided by the platform and is followed by an example.

Pass a creation params class provided by a platform implementation to a fromCreationParams constructor (e.g. FileSystemXFile.fromCreationParams, ScopedStorageXFile.fromCreationParams, etc.).
Call methods on an implementation of a class by using getExtension method (e.g. XFile.getExtension, XDirectory.getExtension, etc.).

Below is an example of using additional iOS/macOS and Web features for a XFile.

late final XFile file;

switch (CrossFile.implementation) {
  case CrossFileWeb():
    final params = WebScopedStorageXFileCreationParams.fromObjectUrl(
      objectUrl: 'blob:https://some/url:for/file',
    );
    file = ScopedStorageXFile.fromCreationParams(params);
  case CrossFileDarwin():
    file = ScopedStorageXFile.fromUri(Uri.file('/my/file.txt'));
  default:
    file = XFile.fileSystem(path: '/my/file.txt');
}

await file
    .getExtension<SecurityScopedDarwinScopedStorageXFileExtension>()
    ?.startAccessingSecurityScopedResource();

debugPrint(await file.readAsString());

if (file is ScopedStorageXFile) {
  await file.dispose();
}

See https://pub.dev/documentation/cross_file_darwin/latest/cross_file_darwin/cross_file_darwin-library.html for more details on iOS/macOS App Sandbox features.

See https://pub.dev/documentation/cross_file_android/latest/cross_file_android/cross_file_android-library.html for more details on Android Scoped Storage features.

See https://pub.dev/documentation/cross_file_io/latest/cross_file_io/cross_file_io-library.html for more details on dart:io features.

See https://pub.dev/documentation/cross_file_web/latest/cross_file_web/cross_file_web-library.html for more details on Web features.

Changelog

0.4.0

Updates cross_file to a package-separated federated plugin.
Adds XDirectory to access resource containers.
Adds implementation for file systems. See FileSystemXFile and FileSystemXDirectory.
Adds implementation for scoped storage APIs that use ephemeral URLS. See ScopedStorageXFile and ScopedStorageXDirectory.
BREAKING CHANGES:
- Replaces XFile(String path) with XFile.fileSystem({required String path}) or FileSystemXFile(String path).
- Removes XFile.fromData. XFiles can no longer be instantiated with a Uint8List. The web implementation can use WebScopedStorageXFileCreationParams.fromBlob to instantiate one with a Blob/File. See README to see how to access platform-specific features.
- Removes XFile.saveTo(). FileSystemXFile.writeAsBytes has been added and the web implementation can use WebScopedStorageXFileExtension.download. See README to see how to access platform-specific features.
- Removes XFile.mimeType.
- Removes XFile.path. This has been replaced by XFile.uri or FileSystemXFile.path.
- Changes XFile.name to a method that returns Future<String> rather than a field that returns String.
- Adds Flutter as a dependency.
- Updates minimum supported SDK version to Flutter 3.41/Dart 3.11.

0.3.5+5

Fixes native readAsString returning mojibake for XFile.fromData, which decoded the bytes as UTF-16 code units instead of using the encoding argument.

0.3.5+4

Adds a runnable main entry point and an additional XFile.fromData demonstration to the example.

0.3.5+3

Clarifies native XFile.mimeType documentation.
Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.

0.3.5+2

Separates "Save As" implementation details from XFile web class.

0.3.5+1

Replaces README mentions of dart:html with package:web.
Updates minimum supported SDK version to Flutter 3.32/Dart 3.8.

0.3.5

Fixes a bug where the bytes of an XFile, that is created using the XFile.fromData constructor, are ignored on web.
Updates minimum supported SDK version to Flutter 3.29/Dart 3.7.

0.3.4+2

Adds support for web: ^1.0.0.

0.3.4+1

Removes a few deprecated API usages.

0.3.4

Updates to web code to package web: ^0.5.0.
Updates SDK version to Dart ^3.3.0.

0.3.3+8

Now supports dart2wasm compilation.
Updates minimum supported SDK version to Flutter 3.16/Dart 3.2.

0.3.3+7

Updates README to improve example of instantiating an XFile.
Updates minimum supported SDK version to Flutter 3.10/Dart 3.0.

0.3.3+6

Improves documentation about ignored parameters in IO implementation.

0.3.3+5

Adds pub topics to package metadata.
Updates minimum supported SDK version to Flutter 3.7/Dart 2.19.

0.3.3+4

Reverts an accidental change in a constructor argument's nullability.

0.3.3+3

RETRACTED
Updates code to fix strict-cast violations.
Updates minimum SDK version to Flutter 3.0.

0.3.3+2

Fixes lint warnings in tests.
Dartdoc correction for readAsBytes and readAsString.

0.3.3+1

Fixes lastModified unimplemented error description.

0.3.3

Removes unused Flutter dependencies.

0.3.2

Improve web implementation so it can stream larger files.

0.3.1+5

Unify XFile interface for web and mobile platforms

0.3.1+4

The dart:io implementation of saveTo now does a file copy for path-based XFile instances, rather than reading the contents into memory.

0.3.1+3

Fix example in README

0.3.1+2

Fix package import in README
Remove 'Get Started' boilerplate in README

0.3.1+1

Rehomed to flutter/packages repository.

0.3.1

Fix nullability of XFileBase's path and name to match the implementations to avoid potential analyzer issues.

0.3.0

Migrated package to null-safety.
breaking change According to our unit tests, the API should be backwards-compatible. Some relevant changes were made, however:
- Web: lastModified returns the epoch time as a default value, to maintain the Future<DateTime> return type (and not null)

0.2.1

Prepare for breaking package:http change.

0.2.0

breaking change Make sure the saveTo method returns a Future so it can be awaited and users are sure the file has been written to disk.

0.1.0+2

Fix outdated links across a number of markdown files (#3276)

0.1.0+1

Update Flutter SDK constraint.

0.1.0

Initial open-source release.

Installing

export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add cross_file

pubspec.yaml

name: cross_file
description: An abstraction to allow working with files across multiple platforms.
repository: https://github.com/flutter/packages/tree/main/packages/cross_file/cross_file
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+cross_file%22
version: 0.4.0

environment:
  sdk: ^3.11.0
  flutter: ">=3.41.0"

flutter:
  plugin:
    platforms:
      android:
        default_package: cross_file_android
      ios:
        default_package: cross_file_darwin
      linux:
        default_package: cross_file_io
      macos:
        default_package: cross_file_darwin
      web:
        default_package: cross_file_web
      windows:
        default_package: cross_file_io

dependencies:
  cross_file_android: ^1.0.0
  cross_file_darwin: ^1.0.0
  cross_file_io: ^1.0.0
  cross_file_platform_interface: ^1.0.0
  cross_file_web: ^1.0.0
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter

topics:
  - files
  - cross-file

Version history

Version	Published	Archive	SHA-256
0.1.0	2020-11-19T22:01:42.021634Z	Download	`689ed0a6813cd4459e5589cae886416008db8319e7788685ba3ec216522f83b7`
0.2.0	2021-01-05T19:51:03.474809Z	Download	`96bea5b81e60b388700f0c3d4c7559f0c4fa65476eab4c71e27b7b5a073184a1`
0.2.1	2021-01-26T19:21:51.489426Z	Download	`13cb37fdd8ff4e9c0f66a22af387c7f73e2476a0c9176ccab5ae0c59e3b44b8a`
0.3.0-nullsafety	2021-01-29T02:59:32.959027Z	Download	`6bac36c5bc958b64758c6a4ea09dd981932f54c6be21af852a673d9d171ad15b`
0.3.0	2021-02-22T19:46:24.016925Z	Download	`f46f215b6a2197bfc9cd1310d84383b76162fe9923e41e9eebf22406acd3cccb`
0.3.1	2021-02-25T04:41:21.054945Z	Download	`459de606f5902c14cd0dd1ad4848567689f5ddd1ad9a0e024aa904cb593d3f95`
0.3.1+1	2021-03-10T20:00:57.563253Z	Download	`2ae7cae8e6fd0d6360ef4b57fe123ee0980783770dac844c577252b33085a604`
0.3.1+3	2021-07-08T15:07:39.696345Z	Download	`e765bf8466c5fde96a2caba4c02924e9a7e9ff854ce33de08501c166db5a27af`
0.3.1+4	2021-07-12T19:31:01.089410Z	Download	`437b2b8da454fe1e01131f4410274fd607347325e9330f0b469ed5a204991068`
0.3.1+5	2021-09-09T00:24:24.087810Z	Download	`5388c401d0a12412f95c9ab01d358b03854da532f8f9189034d3187644e44da4`
0.3.2	2021-10-27T18:13:01.504437Z	Download	`552ffd2f851d4314958e6265452af1891959e00cd32b6d17452c5b836e27a0fa`
0.3.3	2022-05-05T01:54:30.843124Z	Download	`93ccb9d2a91854ce7233583809774e2d3fbac6eef03c255eb6cd4db8b1242f0f`
0.3.3+1	2022-05-24T10:17:21.904443Z	Download	`7632a2bcddc8cef4afde3c6f80e69b29a7060e176f01119c229fe4eb3a2a3d4f`
0.3.3+2	2022-09-15T01:41:26.537391Z	Download	`f71079978789bc2fe78d79227f1f8cfe195b31bbd8db2399b0d15a4b96fb843b`
0.3.3+3	2023-01-31T20:43:27.207410Z	Download	`b1c29cf742bde4d4d1e1f9e7aafd8c8a4942e45802f6b8bdd124443de5e760d5`
0.3.3+4	2023-02-02T00:08:11.581338Z	Download	`0b0036e8cccbfbe0555fd83c1d31a6f30b77a96b598b35a5d36dd41f718695e9`
0.3.3+5	2023-08-29T17:40:04.302276Z	Download	`fd832b5384d0d6da4f6df60b854d33accaaeb63aa9e10e736a87381f08dee2cb`
0.3.3+6	2023-10-12T02:15:44.763920Z	Download	`445db18de832dba8d851e287aff8ccf169bed30d2e94243cb54c7d2f1ed2142c`
0.3.3+7	2023-11-22T20:15:57.375871Z	Download	`2f9d2cbccb76127ba28528cb3ae2c2326a122446a83de5a056aaa3880d3882c5`
0.3.3+8	2023-12-01T00:30:05.834238Z	Download	`fedaadfa3a6996f75211d835aaeb8fede285dae94262485698afd832371b9a5e`
0.3.4	2024-02-20T22:22:10.384530Z	Download	`74a4727e030347edff3b6e5256b7fb0c3de8af8ed278e6c56718760786a1fa40`
0.3.4+1	2024-02-22T22:50:03.359440Z	Download	`55d7b444feb71301ef6b8838dbc1ae02e63dd48c8773f3810ff53bb1e2945b32`
0.3.4+2	2024-08-01T22:21:13.570051Z	Download	`7caf6a750a0c04effbb52a676dce9a4a592e10ad35c34d6d2d0e4811160d5670`
0.3.5	2025-10-29T19:28:19.082787Z	Download	`942a4791cd385a68ccb3b32c71c427aba508a1bb949b86dff2adbe4049f16239`
0.3.5+1	2025-11-18T16:48:52.278191Z	Download	`701dcfc06da0882883a2657c445103380e53e647060ad8d9dfb710c100996608`
0.3.5+2	2026-01-30T16:46:47.070561Z	Download	`28bb3ae56f117b5aec029d702a90f57d285cd975c3c5c281eaca38dbc47c5937`
0.3.5+3	2026-06-30T19:44:10.442458Z	Download	`d687bec93342bf6a764a116d15c8694ebeff10e633dc28a39dd3144f7195024e`
0.3.5+4	2026-07-01T19:26:18.677938Z	Download	`92c9c43c383bfa1c32079d3bc492d55d6d4318044b7b47edaff8971cbb555c51`
0.3.5+5	2026-08-25T15:16:10.239976Z	Download	`f141ea4f277af142a0356955707f6556f37b03947d39d55585981a06ca437bd6`
0.4.0	2026-09-24T15:21:42.778278Z	Download	`3bde17bce71488fc4dc99216da1d990642a726472874dcce4db700eb103d3fa4`

Dependencies

cross_file_android "^1.0.0"

cross_file_darwin "^1.0.0"

cross_file_io "^1.0.0"

cross_file_platform_interface "^1.0.0"

cross_file_web "^1.0.0"

flutter { "sdk": "flutter" }