README.ru.md

[EN](README.md) | **RU**

# flutter_image_cropper_aurora

Исходный ReadMe плагина image_cropper: [README](https://github.com/hnvn/flutter_image_cropper/blob/master/README.md)

### Описание

Этот плагин является реализацией [image_cropper](https://pub.dev/packages/image_cropper) для операционной системы Аврора. Этот плагин используется для обрезки изображений.

Плагин использует [Dart-код](#dart-component) для предоставления настраиваемого визуального интерфейса для обрезки изображений. Однако сам процесс обрезки выполняется [платформенным компонентом](#cpp-component).

ReadMe примера использования: [README](example/README.ru.md)

#### Быстрый запуск

```dart
    CroppedFile? resultImage =
        await ImageCropper()
            .cropImage(
                sourcePath: filePath,
                uiSettings: AuroraUiSettings(context: context),
            );
```

### Содержание

- [Описание](#описание)
- [Ветки](#ветки)
- [Подробное описание](#подробное-описание)
  - [Dart компонент](#dart-компонент)
    - [cropImage](#cropimage)
    - [recoverImage](#recoverimage)
    - [AuroraUiSettings](#aurorauisettings)
  - [C++ компонент](#cpp-компонент)
    - [Сохранение результата](#сохранение-результата)
- [Сборка и установка](#сборка-и-установка)
- [Пример использования](#пример-использования)
- [Совместимость](#совместимость)
- [Правила использования](#правила-использования)

### Сборка и установка

**pubspec.yaml**

```yaml
dependencies:
    image_cropper: ^9.1.0
    image_cropper_aurora:
        path: https://developer.auroraos.ru/git/flutter/flutter-community-plugins/image_cropper_aurora.git
```

**desktop**

```desktop
Permissions=UserDirs;
```

**spec**

```spec
BuildRequires: pkgconfig(Qt5Core)
```

**main.cpp**

```cpp
#include <flutter/flutter_aurora.h>
#include <flutter/flutter_compatibility_qt.h> // <- Enable Qt
#include "generated_plugin_registrant.h"

int main(int argc, char *argv[]) {
    aurora::EnableQtCompatibility(); // <- Enable Qt
    aurora::Initialize(argc, argv);
    aurora::RegisterPlugins();
    aurora::Launch();
    return 0;
}
```

### Подробное описание

#### Dart Компонент

#### cropImage

Метод `cropImage` предназначен для обрезки изображений. Он принимает путь к исходному изображению в качестве входных данных и возвращает обрезанное изображение в качестве результата. При вызове этого метода открывается экран обрезки изображения, позволяющий пользователю в интерактивном режиме настроить область обрезки. Экран реализован с помощью кроссплатформенного плагина [crop_image](https://pub.dev/packages/crop_image), который предоставляет гибкий интерфейс для операций обрезки.
Когда вызывается метод `cropImage`, он выполняет следующие действия:
1. **Сохранение пути**: Метод принимает параметр `sourcePath`, который указывает путь к исходному файлу изображения. Этот путь хранится во внутренней переменной `_sourcePath`. Это позволяет сохранять ссылку на исходное изображение для операции восстановления.
2. **Инициализация диалогового окна**: Отображается экран обрезки, позволяющий пользователю выбрать область обрезки. Этот экран можно настроить с помощью конфигурации [AuroraUiSettings](#aurorauisettings).
3. **Делегирование обрезки**: Как только пользователь подтверждает область обрезки, метод делегирует задачу обработки и сохранения изображения [платформенному компоненту](#cpp-компонент). Платформенный компонент отвечает за фактическую обрезку и сохранение обработанного изображения его в новом файле.
4. **Обработка результатов**: Метод получает путь к обрезанному изображению из платформенного компонента и возвращает `Future<CroppedFile?>`, который преобразуется в объект [CroppedFile](https://github.com/hnvn/flutter_image_cropper/blob/99d967d04e174f62dee298ca61b1dae900c6eda8/image_cropper_platform_interface/lib/src/models/cropped_file/io.dart#L14), представляющий обрезанное изображение в случае, если операция выполнена успешно. Если пользователь отменяет операцию или возникает ошибка, метод возвращает значение `null`.

#### recoverImage

Метод recoverImage предназначен для восстановления исходного изображения, которое ранее было настроено на обрезку. Этот метод необходим, когда вам нужно восстановить исходное изображение, использованное во время последней операции обрезки, не требуя от пользователя повторного выбора.

При вызове метод проверяет, был ли указан путь к исходному изображению (`sourcePath`) во время последнего вызова метода [cropImage](#cropimage). Если такой путь сохранен в `_sourcePath`, метод возвращает объект [CroppedFile](https://github.com/hnvn/flutter_image_cropper/blob/99d967d04e174f62dee298ca61b1dae900c6eda8/image_cropper_platform_interface/lib/src/models/cropped_file/io.dart#L14) - исходное изображение. Если путь к исходному изображению не был установлен, метод возвращает значение null.

Важно отметить, что ***этот метод не выполняет никакой дополнительной обработки или восстановления ранее обрезанных изображений***. Его цель - предоставить доступ к исходному изображению, путь к которому был указан в методе обрезки. Метод проверяет, имеет ли значение `null` переменная `_sourcePath`, в которой хранится путь к исходному изображению. Если значение `_sourcePath` равно `null`, метод возвращает значение `Future.value(null)`. В противном случае он оборачивает `_sourcePath` в объект `CroppedFile` и возвращает его.

#### AuroraUiSettings
Класс `AuroraUiSettings` предоставляет набор параметров настройки для диалогового окна обрезки изображений. Этот класс расширяет класс [PlatformUiSettings](https://github.com/hnvn/flutter_image_cropper/blob/99d967d04e174f62dee298ca61b1dae900c6eda8/image_cropper_platform_interface/lib/src/models/settings.dart#L128) и позволяет разработчикам настраивать интерфейс обрезки в соответствии с дизайном своего приложения. Вы можете прочитать больше о возможных настройках [здесь](/lib/src/aurora_ui_settings.dart).

***Передача аргумента "context" в AuroraUiSettings для Aurora OS необходима для того, чтобы плагин мог показывать пользователю экран редактирования изображения.***

#### Cpp-компонент

C++-компонент предназначен для обработки вызовов только одного метода: `cropImage`. Этот метод вызывается, когда пользователь нажимает кнопку "Crop" на экране обрезки Dart-компонента. Метод `cropImage` принимает набор аргументов, которые определяют параметры для операции обрезки.

К обязательным аргументам относятся:

- `source_path`: путь к исходному файлу изображения.
- `crop_top`: верхняя граница области обрезки.
- `crop_bottom`: Нижняя граница области обрезки.
- `crop_left`: левая граница области обрезки.
- `crop_right`: правая граница области обрезки.

Эти параметры необходимы для определения области обрезки и обеспечения возможности обработки изображения компонентом платформы. Без этих аргументов операция обрезки не может быть выполнена.

В дополнение к обязательным аргументам, метод `cropImage` может принимать несколько необязательных параметров. К ним относятся:

- `max_width`: Максимальная ширина обрезанного изображения.
- `max_height`: максимальная высота обрезанного изображения.
- `ratio_x`: x-составляющая соотношения сторон для области кадрирования.
- `ratio_y`: y-составляющая соотношения сторон для области кадрирования.
- `compress_format`: формат, в котором будет сохранено обрезанное изображение (jpg, png).
- `compress_quality`: уровень качества сжатия изображения в диапазоне от 0 до 100.
- `rotation`: угол поворота, применяемый к изображению во время обрезки.

Если эти необязательные параметры не указаны, они либо будут заменены значениями по умолчанию, либо не повлияют на результат операции обрезки. Например, если не указаны значения `max_width` и `max_height`, обрезанное изображение сохранит свои первоначальные размеры, ограниченные границами сетки обрезки. Аналогично, если не указано значение `compress_format` или `compress_quality`, компонент платформы будет использовать настройки сжатия по умолчанию.

Эти параметры передаются компоненту платформы через `MethodChannel`.

Следует отметить, что ***визуальный интерфейс позволяет пользователю выбрать область, размер которой превышает значения maxWidth и maxHeight, переданные методу cropImage***. В этом случае после обрезки по координатам изображение будет обрезано до максимальной длины и ширины относительно его центра, а затем обрезано до заданного соотношения сторон.

#### Сохранение результата

Метод `cropImage` сохраняет обрезанное изображение как новое, следуя определенным правилам именования и хранения. Путь к выходному файлу генерируется с использованием предопределенного шаблона, который обеспечивает уникальность и согласованность. Каждое обрезанное изображение сохраняется в каталоге изображений пользователя с префиксом имени файла `ImageCropper-`, за которым следует временная метка в формате `гггг-ММ-дд-ЧЧ-мм-сс`. Временная метка генерируется динамически на основе текущей даты и времени, чтобы избежать конфликтов имён файлов. Полный выходной путь создается путем добавления сгенерированного имени файла и указанного формата сжатия (jpg или png) к базовому пути к каталогу, который определяется как папка изображений в домашнем каталоге. Пример: `ImageCropper-2025-04-17-15-05-08.jpg`.

#### Пример использования

Вы можете найти пример [здесь](example/lib/main.dart).

### Ветки

Версии приложения соответствуют соглашению о наименовании веток, которое можно найти [здесь](https://developer.auroraos.ru/doc/software_development/examples#branches).

### Совместимость

* Aurora OS: 5.1.3+

### Правила использования

* Исходный код проекта предоставляется по [лицении](LICENSE.BSD-3-Clause.md), которая позволяет использовать его в сторонних приложениях.
* Для участия в развитии проекта, пожалуйста, ознакомьтесь с [cоглашением](https://developer.auroraos.ru/git/flutter/demos/call_api/-/blob/master/CONTRIBUTING.md) участника.
Если Вы планируете присылать свой исходный код для включения в состав проекта, Вам понадобится принять [условия CLA](https://developer.auroraos.ru/git/wiki/-/wikis/CLA.ru).
* Информация об участниках указана в файле [AUTHORS](AUTHORS)
* [Кодекс поведения](https://developer.auroraos.ru/git/wiki/-/wikis/Code_of_Conduct.ru) —  это действующий набор правил компании «Открытая Мобильная Платформа», который информирует об ожиданиях по взаимодействию между членами сообщества при общении и работе над проектами.