# native_file_preview

**Repository Path**: simplelove520/native_file_preview

## Basic Information

- **Project Name**: native_file_preview
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# native_file_preview

[![pub package](https://img.shields.io/pub/v/native_file_preview.svg)](https://pub.dev/packages/native_file_preview)

A Flutter plugin that opens local files with the operating system's native
viewer on iOS, Android, and OpenHarmony.

## Compatibility

This OpenHarmony adaptation targets `native_file_preview 1.0.1` and was built
with Flutter `3.27.5-ohos-1.0.4` and Dart `3.6.2`. The public Dart API and
MethodChannel contract are unchanged from upstream `1.0.1`.

```yaml
dependencies:
  native_file_preview: ^1.0.1
```

## Usage

```dart
import 'package:flutter/services.dart';
import 'package:native_file_preview/native_file_preview.dart';

final NativeFilePreview preview = NativeFilePreview();

try {
  await preview.previewFile('/absolute/app/sandbox/document.pdf');
} on PlatformException catch (error) {
  // Use error.code for stable programmatic handling.
}
```

Actual format support depends on the viewer applications installed on the
device. Common document, image, audio, video, archive, and text types are
delegated to the system viewer.

## Platform Setup

### iOS

No additional setup is required. The plugin uses QuickLook.

### Android

The host app must configure an AndroidX `FileProvider`. See the upstream Android
setup and make sure the provider exposes only the paths the application needs.

### OpenHarmony

No storage permission is requested by the plugin. Pass an app-sandbox absolute
path, a generic `file:///` URI that resolves inside the accessible sandbox, or
an OpenHarmony file URI. The plugin validates readability, converts paths with
`fileUri.getUriFromPath`, and calls `UIAbilityContext.startAbility` with
`ohos.want.action.viewData` and read-URI authorization.

The device must have an application capable of handling the selected file type.
Android `content://` URIs are intentionally rejected on OpenHarmony because
Android content providers do not exist there.

## Path Support

| Input | iOS | Android | OpenHarmony |
| --- | --- | --- | --- |
| Absolute local path | Yes | Yes | App-sandbox paths |
| `file:///...` | Yes | Yes | Accessible app-sandbox paths |
| OpenHarmony `file://bundle/path` URI | No | No | Yes |
| Android `content://...` URI | No | Yes | Rejected deterministically |
| Relative path or unrelated URL scheme | No | No | Rejected |

## Error Contract

| Code | OpenHarmony meaning |
| --- | --- |
| `INVALID_ARGUMENTS` | The `file` argument is absent, not a string, or empty. |
| `INVALID_FILE_URL` | The path/URI is malformed, relative, unsupported, or outside the accessible sandbox. |
| `FILE_NOT_FOUND` | The selected file does not exist. |
| `FILE_NOT_READABLE` | The file cannot be opened for reading. |
| `NO_ACTIVITY` | No foreground `UIAbility` is attached. |
| `NO_APP_FOUND` | The system reports that no application can handle the request. |
| `CONTENT_URI_INACCESSIBLE` | An Android-only `content://` URI was supplied. |
| `PREVIEW_ERROR` | An unclassified native preview failure occurred. |

Native error codes are preserved in `PlatformException.details.nativeCode` when
available. See [docs/error-contract.md](docs/error-contract.md) for platform
boundaries and classification rules.

## Example

The example creates deterministic TXT, PNG, and PDF files in the app sandbox,
offers real preview actions, and checks three stable error paths.

```shell
cd example
flutter pub get
flutter test
flutter run -d <ohos-device-id>
```

The example does not download files and does not require storage or network
permission.

## Adaptation Evidence

- [Source manifest](docs/source-manifest.md)
- [API mapping](docs/api-map.md)
- [Error contract](docs/error-contract.md)
- [Quality gates](docs/quality-gates.md)
- [Local verification](docs/verification/local-verification.md)

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).