Создаём плагины для Capacitor в мобильных приложен

Почему плагины – ядро Capacitor

Capacitor представляет собой слой, который связывает веб‑код с нативными API операционных систем. Самый мощный механизм взаимодействия – плагины. Через них WebView получает доступ к камере, геолокации, файловой системе, push‑уведомлениям, Bluetooth и другим возможностям, недоступным в чистом браузере. Плагин состоит из JavaScript‑интерфейса и нативных реализаций для Android и iOS, что позволяет писать единый код‑блок, который будет работать на обеих платформах без дублирования логики.

Установка официальных плагинов

Официальные плагины распространяются через npm и включают преднастроенные нативные модули. Установка происходит в три шага:

Добавление пакета
```
npm install @capacitor/camera
```
Аналогично для любого другого официального плагина (@capacitor/filesystem, @capacitor/push-notifications и т.д.).
Синхронизация проекта
```
npx cap sync
```
Команда копирует JavaScript‑модуль в node_modules/@capacitor/…, а также генерирует или обновляет нативные файлы в каталогах android/ и ios/.

Импорт и использование

import { Camera, CameraResultType } from '@capacitor/camera';

async function takePhoto() {
  const photo = await Camera.getPhoto({
    quality: 90,
    resultType: CameraResultType.Uri
  });
  console.log(photo.webPath);
}

После синхронизации в проектах Android Studio и Xcode появляются готовые классы, которые можно сразу вызывать из JavaScript.

Работа с community‑плагинами

Community‑плагины создаются независимыми разработчиками и публикуются в npm под собственными именами. Принцип установки такой же, как у официальных пакетов, но существуют нюансы:

Совместимость: проверяйте, поддерживает ли плагин текущую версию Capacitor (2.x, 3.x, 4.x).
Настройки нативных зависимостей: иногда требуется добавить стороннюю библиотеку в build.gradle (Android) или Podfile (iOS).
Типы данных: некоторые плагины используют собственные типы, которые нужно импортировать из их пакетов.

Пример установки плагина для работы с QR‑кодами:

npm install capacitor-qr-scanner
npx cap sync

Затем в коде:

import { QRScanner } from 'capacitor-qr-scanner';

await QRScanner.prepare();
const result = await QRScanner.scan();
console.log('Scanned text:', result.text);

Переход с Cordova к Capacitor

Миграция с Cordova часто требуется при желании использовать более современную архитектуру. Основные шаги:

Создание нового проекта Capacitor
```
npm init @capacitor/app
```
Перенос веб‑части – скопируйте src/ и www/ в новый проект, сохраните зависимости в package.json.
Установка заменяющих плагинов
Большинство Cordova‑плагинов имеют аналоги в Capacitor. Если аналог отсутствует, можно воспользоваться community‑плагином или написать свой.
Миграция конфигураций
Файлы config.xml Cordova заменяются на capacitor.config.json. Параметры вроде appId, appName, webDir указываются в этом файле.

Обновление вызовов API
Cordova использует глобальный объект cordova, а Capacitor – импортируемые модули. Пример замены:

// Cordova
navigator.camera.getPicture(onSuccess, onError, { quality: 50 });

// Capacitor
import { Camera, CameraResultType } from '@capacitor/camera';
const photo = await Camera.getPhoto({ quality: 50, resultType: CameraResultType.Uri });

Тестирование – запустите npx cap open android и npx cap open ios, проверьте работу всех функций.

Создание собственного плагина: пример отправки SMS

1. Структура проекта

my-plugin/
├─ android/
│  └─ src/main/java/com/example/myplugin/
│     └─ MyPlugin.java
├─ ios/
│  └─ MyPlugin/
│     └─ MyPlugin.swift
├─ src/
│  └─ definitions.ts
├─ package.json
└─ capacitor.config.json

2. JavaScript‑интерфейс

src/definitions.ts описывает типы методов, которые будут доступны в веб‑коде:

export interface MyPlugin {
  sendSMS(options: { phoneNumber: string; message: string }): Promise<{ result: string }>;
}

Экспортируем плагин через registerPlugin:

import { registerPlugin } from '@capacitor/core';
export const MySMS = registerPlugin<MyPlugin>('MySMS');

3. Реализация для Android

MyPlugin.java наследует Plugin из Capacitor:

@NativePlugin()
public class MyPlugin extends Plugin {

  @PluginMethod()
  public void sendSMS(PluginCall call) {
    String phone = call.getString("phoneNumber");
    String text = call.getString("message");

    if (phone == null || text == null) {
      call.reject("Missing parameters");
      return;
    }

    Intent intent = new Intent(Intent.ACTION_VIEW);
    intent.setData(Uri.parse("smsto:" + phone));
    intent.putExtra("sms_body", text);
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

    try {
      getContext().startActivity(intent);
      call.resolve(JSObject.fromObject(Collections.singletonMap("result", "sent")));
    } catch (ActivityNotFoundException e) {
      call.reject("SMS app not found", e);
    }
  }
}

4. Реализация для iOS

MyPlugin.swift использует MFMessageComposeViewController:

@objc(MyPlugin)
public class MyPlugin: CAPPlugin, MFMessageComposeViewControllerDelegate {

  @objc func sendSMS(_ call: CAPPluginCall) {
    guard let phone = call.getString("phoneNumber"),
          let text = call.getString("message") else {
      call.reject("Missing parameters")
      return
    }

    if MFMessageComposeViewController.canSendText() {
      let controller = MFMessageComposeViewController()
      controller.recipients = [phone]
      controller.body = text
      controller.messageComposeDelegate = self
      self.bridge?.viewController?.present(controller, animated: true, completion: nil)
      call.resolve(["result": "opened"])
    } else {
      call.reject("SMS not supported on this device")
    }
  }

  public func messageComposeViewController(_ controller: MFMessageComposeViewController,
                                            didFinishWith result: MessageComposeResult) {
    controller.dismiss(animated: true, completion: nil)
  }
}

5. Регистрация плагина

В capacitor.config.json добавляем запись:

{
  "plugins": {
    "MySMS": {
      "package": "com.example.myplugin"
    }
  }
}

Для iOS в Podfile указываем путь к плагину:

pod 'MyPlugin', :path => '../my-plugin/ios'

6. Использование в приложении

import { MySMS } from './my-plugin';

async function send() {
  try {
    const res = await MySMS.sendSMS({
      phoneNumber: '+79161234567',
      message: 'Hello from Capacitor!'
    });
    console.log(res.result);
  } catch (e) {
    console.error('SMS error', e);
  }
}

7. Тестирование и отладка

Android: запустите adb logcat для отслеживания исключений в MyPlugin.java.
iOS: используйте Xcode console, проверяйте, вызывается ли делегат messageComposeViewController.

При работе с реальными устройствами необходимо добавить разрешения в AndroidManifest.xml (<uses-permission android:name="android.permission.SEND_SMS"/>) и в Info.plist (NSMessageComposeUsageDescription).

8. Публикация плагина

После проверки можно собрать npm‑пакет и опубликовать его под именем capacitor-sms-sender. В package.json укажите capacitor в peerDependencies, чтобы пользователи автоматически получали совместимую версию ядра.

Разработанный плагин демонстрирует общий процесс: определение TypeScript‑интерфейса, написание нативных реализаций, их регистрация и вызов из JavaScript. Такой подход позволяет расширять возможности любого проекта на Capacitor без необходимости покидать привычный стек веб‑технологий.

Capacitor: от веб‑технологий к нативным мобильным функциям – как написать свой плагин