Cordova Email Plugin

Плагин Cordova Email предоставляет доступ к стандартному интерфейсу, который управляет редактированием и отправкой сообщения электронной почты. Вы можете использовать этот контроллер представления для отображения стандартного вида электронной почты внутри вашего приложения и заполнения полей этого вида начальными значениями, такими как тема, получатели электронной почты, основной текст и вложения. Пользователь может редактировать указанное вами исходное содержимое и выбрать отправку электронного письма или отменить операцию.

Использование этого интерфейса не гарантирует немедленную доставку соответствующего сообщения электронной почты. Пользователь может отменить создание сообщения, и если пользователь всё же решит отправить сообщение, оно будет помещено в очередь исходящих сообщений приложения «Почта». Это позволяет вам генерировать электронные письма даже в ситуациях, когда у пользователя нет доступа к сети, например, в режиме полёта. Этот интерфейс не предоставляет способа проверить, были ли электронные письма отправлены на самом деле.

Цель плагина

Цель плагина — создать независимый от платформы интерфейс JavaScript для мобильных приложений на основе Cordova для доступа к определённому API составления электронной почты на каждой платформе.

Обзор

1. Поддерживаемые платформы.
2. Установка.
3. ChangeLog.
4. Использование плагина.
5. Примеры.
6. Особенности.

Поддерживаемые платформы — iOS (до iOS8). — Android (до KitKat и L). — WP 8.0 и WP 8.1 Silverlight. — Windows.

Установка Плагин можно установить из репозитория Git, из локальной файловой системы через интерфейс командной строки [CLI] или из облака через PhoneGap Build [PGB].

Локальная среда разработки Из мастера:

# ~~ из ветки master ~~
cordova plugin add https://github.com/katzer/cordova-plugin-email-composer.git

из локальной папки:

# ~~ локальная папка ~~
cordova plugin add de.appplant.cordova.plugin.email-composer --searchpath path/to/plugin

или чтобы использовать последнюю стабильную версию:

# ~~ стабильная версия ~~
cordova plugin add de.appplant.cordova.plugin.email-composer@0.8.2

PhoneGap Build Добавьте следующий XML в ваш config.xml, чтобы всегда использовать последнюю версию этого плагина:

<gap:plugin name="de.appplant.cordova.plugin.email-composer" version="0.8.2" />

Более подробную информацию можно найти здесь [PGB_plugin].

ChangeLog

Версия 0.8.2 (ещё не выпущена)

— Добавлено новое пространство имён cordova.plugins.email
Примечание: прежнее пространство имён plugin.email теперь устарело и будет удалено со следующим основным выпуском. — [change:] Объединены absolute: и relative: в file: — [change:] Переименован isServiceAvailable в isAvailable — [функция:] app: позволяет указать целевое почтовое приложение на Android — [функция:] префикс res: для собственных вложений ресурсов — [улучшение:] Поддержка вложений на Windows Phone 8.1 — [улучшение:] open поддерживает обратные вызовы — [улучшение:] isHTML можно использовать после isHtml — [исправление ошибок:] Значения по умолчанию игнорировались

Известные проблемы

— Вложения res:// не отправляются, даже если они присутствуют при редактировании черновика. — Теги <img> не работают на Android. — Обратные вызовы для платформы WP8/Windows вызываются немедленно. — isAvailable всегда возвращает true для платформы WP8/Windows. — Плагин может аварийно завершить работу на WP8.1/Windows, если вложение не существует.

Дополнительная информация

— См. CHANGELOG.md [changelog], чтобы получить полный журнал изменений для плагина.

Использование плагина Плагин создаёт объект cordova.plugins.email со следующими методами:

1. email.isAvailable[available].
2. email.open[open].

Инициализация плагина

Плагин и его методы недоступны до тех пор, пока не произойдёт событие deviceready. ### Определение возможности отправки электронных писем

Возможность отправки электронных писем можно проверить через интерфейс email.isAvailable. Метод принимает функцию обратного вызова, которой передаётся логическое свойство. При необходимости область действия обратного вызова может быть задана в качестве второго параметра.

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

cordova.plugins.email.isAvailable(
    function (isAvailable) {
        // alert('Service is not available') unless isAvailable;
    }
);

Открытие черновика электронного письма

Черновик электронного письма можно открыть через интерфейсы email.open или email.openDraft. Метод принимает хеш в качестве аргумента для указания свойств электронного письма. Все свойства являются необязательными. Кроме того, он принимает функцию обратного вызова, которая вызывается после закрытия представления электронного письма.

После открытия черновика пользователь может редактировать, удалять или отправлять электронное письмо.

Дополнительная информация

• Для отправки электронных писем требуется настроенная учётная запись.
• Вложениями могут быть данные в кодировке base64, файлы из хранилища устройства или ресурсы из папки www.
• По умолчанию для isHTML установлено значение true.
• На Android можно указать почтовое приложение.
• Примеры показывают, как создать и показать черновик электронного письма.

cordova.plugins.email.open({
    to:          Array, // адреса электронной почты для поля TO
    cc:          Array, // адреса электронной почты для поля CC
    bcc:         Array, // адреса электронной почты для поля BCC
    attachments: Array, // пути к файлам или потоки данных в кодировке base64
    subject:    String, // тема электронного письма
    body:       String, // тело электронного письма (для HTML установите isHtml в true)
    isHtml:    Boolean, // указывает, является ли тело HTML или обычным текстом
}, callback, scope);

Примеры

Открыть черновик электронного письма

Следующий пример показывает, как создать и отобразить черновик электронного письма с различными свойствами.

cordova.plugins.email.open({
    to:      'max@mustermann.de',
    cc:      'erika@mustermann.de',
    bcc:     ['john@doe.com', 'jane@doe.com'],
    subject: 'Greetings',
    body:    'How are you? Nice greetings from Leipzig'
});

Конечно, также можно открыть пустой черновик.

cordova.plugins.email.open();

Отправить тело в формате HTML

Электронное письмо можно отправить либо в виде текста, либо в формате HTML. В случае HTML необходимо установить свойство isHTML.

cordova.plugins.email.open({
    to:      'max@mustermann.de',
    subject: 'Greetings',
    body:    '<h1>Nice greetings from Leipzig</h1>',
    isHtml:  true
});

Получение уведомления при закрытии представления

Метод open поддерживает дополнительный обратный вызов для получения уведомления о закрытии представления.

cordova.plugins.email.open(properties, function () {
    console.log('представление электронного письма закрыто');
}, this);

Добавление вложений

Вложениями могут быть либо данные в кодировке Base64, либо файлы из хранилища устройства, либо ресурсы из папки www.

Добавление содержимого в кодировке Base64

Приведённый ниже код показывает, как добавить изображение в кодировке Base64 с именем icon.png.

cordova.plugins.email.open({
    subject:     'Cordova Icon',
    attachments: 'base64:icon.png//iVBORw0KGgoAAAANSUhEUgAAADwAAAA8CAYAAAA6/...'
});

Добавление файлов из хранилища устройства

Путь к файлам должен быть определён абсолютно от корня файловой системы.

cordova.plugins.email.open({
    attachments: 'file:///storage/sdcard/icon.png', //=> Android
});

Добавление ресурсов нативного приложения

Каждое приложение имеет папку с ресурсами, например, папка res для приложений Android или папка Resource для приложений iOS. Пример того, как прикрепить иконку приложения из папки ресурсов приложения.

cordova.plugins.email.open({
    attachments: 'res://icon.png' //=> res/drawable/icon (Android)
});

Как присоединить ресурсы из папки www.

Путь к файлам должен быть определён относительно корня папки мобильного веб-приложения, которая находится в папке www.

cordova.plugins.email.open({
    attachments: [
        'file://img/logo.png', //=> assets/www/img/logo.png (Android),
        'file://css/index.css' //=> www/css/index.css (iOS)
    ]
});

Особенности работы на разных платформах

Указание почтового приложения

На Android можно указать почтовое приложение, которое должно открыть черновик для дальнейшего редактирования. По умолчанию email.open показывает средство выбора со всеми доступными приложениями.

Приложение можно указать по псевдониму или его имени пакета. Псевдоним gmail доступен по умолчанию.

// Добавляем псевдоним приложения
cordova.plugins.email.addAlias('gmail', 'com.google.android.gm');

// Указываем приложение по имени или псевдониму
cordova.plugins.email.open({
  app: 'gmail',
  subject: 'Sent from Gmail'
})

Нюансы

HTML и CSS на Android

Даже Android может отображать электронные письма с форматированным HTML, но большинство собственных почтовых клиентов, таких как стандартное приложение или Gmail, поддерживают только форматированный текст при написании писем. Это означает, что CSS использовать нельзя (нет поддержки class и style).

В следующей таблице представлен обзор тегов и атрибутов, которые можно использовать:

HTML, CSS и вложения на Windows Phone 8

Вложения и сообщения с телом, отформатированным с помощью HTML+CSS, не поддерживаются собственным API для Windows Phone 8.0 и Windows Phone 8.1 Silverlight.

Ошибка компиляции на iOS

Ошибка указывает на то, что MessageUI.framework не связан с вашим проектом. Фреймворк связывается автоматически при установке плагина, но позже может быть удалён.

Undefined symbols for architecture i386:
  "_OBJC_CLASS_$_MFMailComposeViewController", referenced from:
      objc-class-ref in APPEmailComposer.o
ld: symbol(s) not found for architecture i386
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Вклад

1. Форкните проект.
2. Создайте свою ветку функций (git checkout -b my-new-feature).
3. Внесите изменения (git commit -am 'Add some feature').
4. Отправьте изменения в ветку (git push origin my-new-feature).
5. Создайте новый запрос на вытягивание.

Лицензия

Это программное обеспечение выпущено под лицензией Apache 2.0.

© 2013–2014 appPlant UG, Inc. Все права защищены. Кордова (Apache Cordova) — это платформа с открытым исходным кодом, которая позволяет разработчикам создавать мобильные приложения для разных платформ с использованием HTML, CSS и JavaScript.

В документации по платформе Apache Cordova можно найти информацию о том, как использовать интерфейс командной строки (Command-line Interface). Подробные инструкции доступны на сайте: http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html.

Также в документации есть ссылки на другие ресурсы, которые могут быть полезны при работе с платформой:

• документация по сборке приложений с помощью PhoneGap: http://docs.build.phonegap.com/en_US/index.html;
• список плагинов PhoneGap: https://build.phonegap.com/plugins/705;
• информация об ошибке компиляции на iOS: #compile-error-on-ios;
• журнал изменений платформы: https://github.com/katzer/cordova-plugin-email-composer/blob/master/CHANGELOG.md;
• проверка возможности отправки электронных писем с устройства: #determine-if-the-device-is-capable-to-send-emails;
• открытие предварительно заполненного черновика электронного письма: #open-a-pre-filled-email-draft;
• указание приложения электронной почты: #specify-email-app;
• примеры использования платформы: #examples.

Платформа Apache Cordova распространяется под лицензией Apache 2.0. С ней можно ознакомиться по ссылке: http://opensource.org/licenses/Apache-2.0.