license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Этот раздел содержит сведения о том, как реализовать плагин в коде на платформе Android. Прежде чем читать этот раздел, изучите раздел “Расширения приложения” для обзора структуры плагина и его общий интерфейс JavaScript. Этот раздел продолжает демонстрировать пример echo плагина, который соообщается из WebView Cordova с кодом платформы и в обратную строну. Еще один пример см. также комментарии в файле CordovaPlugin.java.
Android плагины основаны на проекте Cordova-Android, который состоит из Android WebView с хуками, прилагаемыми к нему. Плагины представляются как сопоставления классов в файле config.xml
. Модуль состоит из по крайней мере из одного Java-класса, который расширяет класс CordovaPlugin
, и переопределяющий один из его методов - execute
. Как лучшая практика, плагин также должен обрабатывать pause
и resume
события, наряду с любой передачи сообщений между плагинами. Плагины с длительные запросы, фоновой активностью такие как воспроизведение мультимедиа, слушатели или внутреннее состояние следует также реализовать метод onReset()
. Он выполняется, когда WebView
переходит на новую страницу или обновляется, что приводит к перезагрузке JavaScript.
Интерфейс JavaScript плагин использует метод cordova.exec
следующим образом:
Exec (< successFunction >, < failFunction >, < служба >, < действия > [< args >]);
Это маршалирует запрос от WebView к коду Android, вызывая метод action
класса service
, с дополнительными аргументами, передаваемые в массиве args
.
Распространяете ли вы плагин как Java-файл или файл jar, плагин должен быть указан в вашем файле res/xml/config.xml
Cordova-Android приложения. См. “Расширения приложения” для получения дополнительной информации о том, как использовать файл plugin.xml
для вставки следующего элемента feature
:
<feature name="<service_name>"> <param name="android-package" value="<full_name_including_namespace>" /> </feature>
Имя службы должен соответствовать той службе, которая используется в JavaScript вызове exec
. Значение является идентификатором класса Java включая полное пространство имен. В противном случае плагин может компилировать, но по-прежнему будет недоступным для Cordova.
Один экземпляр объекта плагин создается для каждого WebView
. Плагины не создаются до тех пор, пока они первый раз не ссылается из JavaScript вызова, за исключением если <param>
с атрибутом с атрибутом name
тега onload
имеющим значение "true"
в config.xml
. Например:
<feature name="Echo"> <param name="android-package" value="<full_name_including_namespace>" /> <param name="onload" value="true" /> </feature>
Следует использовать метод плагина initialize
для логики инициализации плагина.
@Override public void initialize(CordovaInterface cordova, CordovaWebView webView) { super.initialize(cordova, webView); // your init code here }
Вызов из JavaScript выполняет запрос к стороне платформы, и соответствующий Java плагин привязан корректно в файле config.xml
, но как выглядит окончательный Java-класс плагина для Android? Все, что отправляется в плагин с JavaScript функцией exec
передается в метод класса execute
. Большинство реализаций execute
выглядят следующим образом:
@Override общественного boolean выполнение (строка действия, JSONArray args, CallbackContext callbackContext) бросает JSONException {если («beep".equals(action)) {this.beep(args.getLong(0)); callbackContext.success(); Возвращает значение true; } Возвращает значение false; / / Возвращения ложные результаты в сообщение об ошибке «MethodNotFound». }
Параметр action
функции JavaScript exec
соответствует закрытому методу класса куда диспетчиризуются необязательные параметры.
При перехвате исключений и возвращении ошибки, важно для ясности, чтобы ошибки возвращены в JavaScript соотвествовали именам исключений Java как можно больше.
JavaScript плагине не выполняются в основном потоке интерфейса WebView
, вместо этого, он работает в потоке WebCore
, как это делает метод execute
. Если вам нужно взаимодействовать с интерфейсом пользователя, следует использовать следующие изменения:
@Override public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { if ("beep".equals(action)) { final long duration = args.getLong(0); cordova.getActivity().runOnUiThread(new Runnable() { public void run() { ... callbackContext.success(); // Thread-safe. } }); return true; } return false; }
Используйте следующее, если вам не нужно запускать в главном потоке интерфейсе, но не хотите также блокировать поток WebCore
:
@Override public boolean execute(String action, JSONArray args, final CallbackContext callbackContext) throws JSONException { if ("beep".equals(action)) { final long duration = args.getLong(0); cordova.getThreadPool().execute(new Runnable() { public void run() { ... callbackContext.success(); // Thread-safe. } }); return true; } return false; }
Для сопоставления интерфейса JavaScript функция echo, описанная в разделе “Плагины приложения”, используйте plugin.xml
для вставки спецификации feature
в файл config.xml
платформы:
<platform name="android"> <config-file target="config.xml" parent="/*"> <feature name="Echo"> <param name="android-package" value="org.apache.cordova.plugin.Echo"/> </feature> </config-file> </platform>
Затем добавить следующий файл src/org/apache/cordova/plugin/Echo.java
:
package org.apache.cordova.plugin; import org.apache.cordova.CordovaPlugin; import org.apache.cordova.CallbackContext; import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; /** * This class echoes a string called from JavaScript. */ public class Echo extends CordovaPlugin { @Override public boolean execute(String action, JSONArray args, CallbackContext callbackContext) throws JSONException { if (action.equals("echo")) { String message = args.getString(0); this.echo(message, callbackContext); return true; } return false; } private void echo(String message, CallbackContext callbackContext) { if (message != null && message.length() > 0) { callbackContext.success(message); } else { callbackContext.error("Expected one non-empty string argument."); } } }
Необходимые импорты в верхней части файла наследуют класс от CordovaPlugin
, чей метод execute()
переопределяется для получения сообщений от exec()
. Метод execute()
сначала проверяет значение action
, для которого в этом случае есть только одно действительное значение - echo
. Любое другое значение параметра action возвращает false
и приводит к ошибке INVALID_ACTION
, которая передается интерфейсу обратного вызова об ошибке на стороне JavaScript.
Далее, этот метод извлекает эхо-строку, используя метод getString
объекта args
, определяя первый параметр передаваемый методу. После того, как значение передается в закрытый метод echo
, это параметр проверяется, чтобы убедиться, что это не null
и не является пустой строкой, в этом случае callbackContext.error()
вызывает ошибку на стороне JavaScript. Если различные проверки проходят успешно, callbackContext.success()
передает исходное значение строки message
обратно в JavaScript в качестве параметре функции успешного вызова.
Android предоставляет систему Intent
, которая позволяет процессам взаимодействовать друг с другом. Плагины имеют доступ к объекту CordovaInterface
, который можно получить доступ к Android Activity
которая запустила приложение. Это Context
необходимые для запуска нового Intent
Android. CordovaInterface
позволяет плагинам запускать Activity
для получения результата и установить функцию обратного вызова которая выполнится когда Intent
вернутся приложению.
По состоянию на Cordova 2.0, плагины больше не имеют прямого доступа к Context
и член класса ctx
член является устаревшим. Все ctx
методы существуют в Context
, так что оба getContext()
и getActivity()
могут возвращать требуемый объект.
Eclipse позволяет отлаживать плагины как исходный код Java, включенный в проект. Только последняя версия Android Developer Tools позволяет вам прикрепить исходный код к JAR зависимостям, так что эта функция пока не поддерживается полностью.