Почему плагины – ядро 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.xmlCordova заменяются на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 без необходимости покидать привычный стек веб‑технологий.