photo-editor/README.ru.md

Simple and customizable photo editor for web applications.

[![NPM](https://img.shields.io/npm/v/photo-editor.svg)](https://www.npmjs.com/package/photo-editor)
![dependencies status](https://img.shields.io/librariesio/release/npm/photo-editor)
# photo-editor-js
Простой кастомизируемый редактор фотографий для веб-приложений.

## Примеры

- [Простой карандаш](https://codesandbox.io/s/zrm68oko34)
- [Все встроенные инструменты](https://codesandbox.io/s/x768q8r68o)

## Установка

```
npm install photo-editor --save
yarn add photo-editor
bun add photo-editor
```

## Использование

### Инициализация редактора

```typescript
import { PhotoEditor } from 'photo-editor';

const photoEditor = new PhotoEditor(canvasEl, options);
```

`canvasEl` - DOM-элемент, на котором производится редактирование фотографий. Обязательно должен являться canvas-ом.

`options`:

| Параметр | Обязательный | Описание |
| -------- | ------------ | -------- |
| tools | + | Объект, ключами которого язляются id используемых интсрументов, а значениями - их классы. О создании инструментов ниже. |
| sourceType | - | Тип источника, из которого будет взято исходное изображение. Возможны значения: `current-canvas` (текущий canvas), `canvas` (другой canvas), `img` (картинка со страницы), `base64` (base64-строка изображения). По умолчанию `current-canvas`. |
| source | если `sourceType` - не `current-canvas` | Источник, из которого будет взято исходное изображение. Если sourceType - `current-canvas`, то не используется, если `canvas`, то HTMLCanvasElement, если `img`, то HTMLImageElement, если `base64`, то base64-строка. |

### Создание инструмента

```typescript
import { Tool } from 'photo-editor';

class MyTool extends Tool {
  ...
}
```

Свойства базового класса:

| Название | Описание |
| -------- | -------- |
| el | canvas-элемент, на котором происходит рисование. |
| enabled | Включен ли инструмент на данный момент. |

Методы базового класса:

| Название | Аргументы | Описание |
| -------- | --------- | -------- |
| pushState | base64-строка | Сохранить состояние для возможности вернуться к нему, используя методы `undo` и `redo` редактора. |
| updateState | base64-строка | Изменение последнего сохраненного состояния. |
| disable | - | Выключить инструмент. |

Методы инструмента:

| Название | Описание |
| -------- | -------- |
| onBeforeDisable | Вызывается перед выключением инструмента. |
| onAfterDisable | Вызывается после выключения инструмента. |
| onBeforeEnable | Вызывается перед включением инструмента. |
| onAfterEnable | Вызывается после включения инструмента. |
| onBeforeDestroy | Вызывается перед удалением инструмента. |

Также `Tool` унаследован от [EventEmitter](https://github.com/primus/eventemitter3).

### Использование редактора

#### Методы

| Название | Аргументы | Описание |
| -------- | --------- | -------- |
| getCurrentState | - | Получить base64 последнего сохранённого состояния (если нет, инициализационного). |
| enableTool | id инструмента | Включить определённый инструмент. Если включен какой-то другой инструмент, он будет выключен. |
| disableTool | - | Выключить включенный инструмент. |
| toggleTool | id инструмента | Если включен определённый инстумент, выключить его, если выключен - включить. Если включен какой-то другой инструмент, он будет выключен. |
| undo | - | Вернуть редактор к предыдущему сохранённому состоянию. |
| redo | - | Вернуть редактор к следующему сохранённому состоянию. |

#### События

`PhotoEditor` унаследован от [EventEmitter](https://github.com/primus/eventemitter3).

| Название события | Аргументы | Когда вызывается |
| ---------------- | --------- | -------- |
| ready | - | После того, как проинициализированы редактор и все инструменты, и на canvas-е нарисовано изображение для инициализации. |
| enableTool | toolId (id включенного инструмента) | После включения инструмента. |
| disableTool | - | После выключения инструмента. |

#### Доступ к инструментам

Все инструменты редактора доступны по ключу в поле `tools`, например,

```typescript
import { PhotoEditor } from 'photo-editor';
import { Crop } from 'photo-editor/tools';

const photoEditor = new PhotoEditor(canvasEl, {
  tools: {
    crop: Crop,
  },
});

photoEditor.tools.crop.applyCrop();
```

## Встроенные инструменты

```typescript
import {
  Blur,
  Brightness,
  Crop,
  Contrast,
  Rectangle,
  RotateLeft,
  RotateRight,
} from 'photo-editor/tools';
```

### Blur

Размытие части изображения с помощью кисти.

### Brightness

Изменение яркости всего изображения.

### Crop

Вырезка нужной части изображения. Сначала нужно ограничить область рисованием прямоугольника, затем вызвать метод `applyCrop` для применения вырезки.

#### События

| Название события | Аргументы | Когда вызывается |
| ---------------- | --------- | -------- |
| set | - | После того, как выбрана прямоугольная область. |
| unset | - | После того, как выбор прямоугольнай области отменён. |

### Contrast

Изменение контрастности всего изображения.

### Rectangle

Рисование красного прямоугольника.

### RotateLeft

Поворот изображения на 90 градусов против часовой стрелки. Срабатывает сразу после включения инструмента.

### RotateRight

Поворот изображения на 90 градусов по часовой стрелке. Срабатывает сразу после включения инструмента.