diff --git a/public/documentation/android/embedding_crosswalk/crosswalk_aar_zh.md b/public/documentation/android/embedding_crosswalk/crosswalk_aar_zh.md new file mode 100644 index 000000000..f66ae469c --- /dev/null +++ b/public/documentation/android/embedding_crosswalk/crosswalk_aar_zh.md @@ -0,0 +1,289 @@ +# Crosswalk AAR开发篇 + +Crosswalk AAR组件是`xwalk_core_library`的二进制发布形式并且它包含了x86和armv7两种架构。开发者不再需要手动下载crosswalk-webview组件，可以使用Gradle或者Maven工程去指定一个版本自动下载。 + +## 配置主机 + +### 安装JDK + +Gradle需要JDK 6或者更高的版本。环境变量JAVA_HOME必须设置成正确的JDK安装路径。 + + $ export JAVA_HOME= + +### 安装Android SDK + +1. 从http://developer.android.com/sdk/index.html下载Android SDK。 + +2. 从下载文件中提取SDK。 + +3. 添加Android SDK路径到您的PATH: + ``` + $ export PATH=:$PATH + $ export PATH=/tools:$PATH + $ export PATH=/platform-tools:$PATH + ``` + +4. 在SDK Manager窗口中，在列表中选择下面的条目： + ``` + [ ] Tools + [x] Android SDK Platform-tools 19.0.1 + [x] Android SDK Build tools 18.0.1 + [ ] Android 4.3 (API 18) + [x] SDK Platform + ``` + + 注意：如果您的安卓版本高于4.3，那么您需要下载对应版本的`platform tools`，`build tools`和`SDK platform`。 + +### 使用Gradle工程开发 + +#### 安装Gradle + +1. 下载最新版本的`gradle`二进制文件(~40MB): [http://www.gradle.org/downloads/](http://www.gradle.org/downloads) + +2. 解压： + + $ unzip gradle--bin.zip + +3. 方便起见，添加`gradle`到您的环境变量PATH中： + + $ export PATH=$PATH:/bin + +### 使用Maven工程开发 + +#### 安装Maven + +1. 从http://maven.apache.org/download.cgi下载Maven。版本3.2.2是被验证过可以工作的。 + +2. 解压： + + $ tar -zxvf apache-maven-3.2.2-bin.tar.gz + +3. 将Maven环境变量设置成安装目录： + + $ M2_HOME=/path/to/apache-maven-3.2.2 + $ export MAVEN_OPTS="-Xms256m -Xmx512m" + $ export PATH=$M2_HOME/bin:$PATH + +#### 安装Maven Android SDK Deployer + +1. 使用[git](https://github.com/mosabua/maven-android-sdk-deployer)获取Maven Android SDK deployer + + $ git clone git@github.com:mosabua/maven-android-sdk-deployer.git + +2. 使用Maven Android SDK deployer为安卓4.4*安装Maven组件： + + $ cd maven-android-sdk-deployer + $ mvn install -P 4.4 + +#### 安装Maven Android插件 + +1. 使用[git](https://github.com/jayway/maven-android-plugin)获取Maven Android插件 + + $ git clone git@github.com:jayway/maven-android-plugin.git + +2. 安装Maven Android插件到您本地的Maven仓库 + + $ cd maven_android_plugin + $ mvn clean install + +## Crosswalk AAR版本 + +AAR的远程Maven仓库在https://download.01.org/crosswalk/releases/crosswalk/android/maven2/。 [stable](https://download.01.org/crosswalk/releases/crosswalk/android/maven2/org/xwalk/xwalk_core_library/)和[beta](https://download.01.org/crosswalk/releases/crosswalk/android/maven2/org/xwalk/xwalk_core_library_beta/)版是可用的。如果您需要canary版本，您可以使用下面的命令下载： + + $ wget https://download.01.org/crosswalk/releases/crosswalk/android/canary/9.38.207.0/crosswalk-9.38.207.0.aar + +然后安装Crosswalk AAR到本地Maven仓库： + + $ mvn install:install-file -DgroupId=org.xwalk -DartifactId=xwalk_core_library_canary \ + -Dversion=9.38.207.0 -Dpackaging=aar -Dfile=crosswalk-9.38.207.0.aar \ + -DgeneratePom=true + +## 用Crosswalk AAR创建并编译安卓工程 + +1. 使用Crosswalk embedding APIs创建安卓工程。 + + 参考嵌入模式中的章节[添加代码集成webview](/documentation/android/embedding_crosswalk_zh.html#Add-code-to-integrate-the-webview)。 + +2. 在build.gradle文件中关于Maven仓库的代码如下： + + ``` + Repositories { + Maven { + url 'https://download.01.org/crosswalk/releases/crosswalk/android/maven2' + } + } + ``` + + 使用mavenLocal()替代上面的远程仓库链接，指向本地的aar： + ``` + Repositories { + mavenLocal() + } + ``` + +3. AAR库的依赖关系如下所示(9.38.208.8是crosswalk版本)： + + ``` + Dependencies { + Compile 'org.xwalk:xwalk_core_library_beta:9.38.208.8' + } + ``` + + 在build.gradle文件中，最新版本的AAR需要把compileSdkVersion设置成21。 + + Gradle把AAR库放到工程中下面的位置： + + ~/.gradle/caches/modules-2/files-2.1/ + +4. 支持不同架构的CPU(例如ARM，x86)。 + + 开发者可以定制不同版本的应用。我们可以通过配置产生不同架构下的多个APK。 + + android { + ... + productFlavors { + armv7 { + ndk { + abiFilters "armeabi-v7a", "" + } + } + x86 { + ndk { + abiFilters "x86", "" + } + } + } + } + + 通过manifest获取版本号。在版本号的最后添加一个指定架构的数字。数字4代表x86，2代表arm。 + + versionCode manifest.versionCode + 4 + +5. 使用Gradle编译工程，使用下面的命令可以在build/apk目录下产生相应架构的APK。 + + $ gradle assemblex86 + $ gradle assemblearmv7 + + 使用`$ gradle build`同时产品arm和x86架构的APK。 + +## 使用Maven编译 + +Maven android插件有一个问题，不同自动编译不同架构下的APK。我们需要在classifier中指定x64/aar。您可以尝试[示例](/documentation/samples/AAR-Sample.tar.gz)。 + +### 创建Maven工程 + +1. 使用Crosswalk webview APIs创建安卓工程 + + 参考嵌入模式中的章节[添加代码集成webview](/documentation/android/embedding_crosswalk_zh.html#Add-code-to-integrate-the-webview)。 + +2. 在pom.xml中指定远程仓库的代码如下： + + + + 01-org + o1 org repo + https://download.01.org/crosswalk/releases/crosswalk/android/maven2 + default + + + +3. 在pom.xml中指定x86 AAR库的依赖关系代码如下： + + + org.xwalk + xwalk_core_library_beta + 9.38.208.8 + x86 + aar + + + 如果您需要在Maven工程中使用arm AAR，可以设置classifier的值为arm： + + arm + + Maven将会自动下载AARs到工程仓库中： + + ~/.m2/repository/ + +4. 支持多个APK。 + + * 使用'Build profile'编译不同的APK + + 编译文件是很多用于配置的元素组成。这些元素用来设置或者覆盖Maven编译时的默认值。 + + + x86 + + + 执行下面的mvn命令。使用-P选项传入CPU架构的属性值。 + + $ mvn install -Px86 + + * 更新manifest的versioncode和versionname。参考[stackoverflow](http://stackoverflow.com/questions/10803088/how-do-i-change-my-androidmanifest-as-its-being-packaged-by-maven) + + android-maven-plugin支持esource filtering，更新manifest。 + + 修改AndroidManifest.xml： + + + + 设置versioncode和versionname。 + + arm情况下： + + 1.0.0.2 + 1.0.0-SNAPSHOT + + x86情况下： + + 1.0.0.4 + 1.0.0-SNAPSHOT + + 过滤manifest并且把过滤的文件放到target/filtered-manifest: + + + ${project.basedir} + true + ${project.build.directory}/filtered-manifest + + src/main/AndroidManifest.xml + + + ... + + + com.jayway.maven.plugins.android.generation2 + android-maven-plugin + true + + true + + ${project.build.directory}/src/main/filtered-manifest/AndroidManifest.xml + + + ... + + * 输出不同名字的APK： + + ${project.artifactId}-${project.version}-${profile-id} + x86 + arm + +5. 使用Maven编译工程，使用下面的命令将会在target/目录下产生相应架构的APK： + + $ mvn clean install -Px86 + $ adb install ./target/xwalk-aar-example-1.0.0-SNAPSHOT-x86.apk + $ mvn clean install -Parm + $ adb install ./target/xwalk-aar-example-1.0.0-SNAPSHOT-arm.apk + +## 示例 + +您可以从crosswalk示例获取Crosswalk库的示例程序，Crosswalk库是在Android Studio中被使用的。示例程序使用Maven中的classifier AAR，您可以从xwalkEmbed-Maven.tar.gz获取。 + +下载完成之后，使用命令解压： + + $ tar -xzvf xwalkEmbed-Maven.tar.gz + diff --git a/public/documentation/android/embedding_crosswalk/extensions_zh.md b/public/documentation/android/embedding_crosswalk/extensions_zh.md new file mode 100644 index 000000000..220985105 --- /dev/null +++ b/public/documentation/android/embedding_crosswalk/extensions_zh.md @@ -0,0 +1,127 @@ +# 通过embedding API使用Crosswalk插件 + +[embedding API](/documentation/apis/embedding_api_zh.html)从2.1版本及其之后开始支持[插件](https://crosswalk-project.org/apis/embeddingapidocs_v2/reference/org/xwalk/core/XWalkExtension.html)。extensions API与[Crosswalk插件](/documentation/android/android_extensions_zh.html)类似，除了在*嵌入模式应用*的用法上存在一些差异。(也就是使用Java嵌入Crosswalk的安卓应用)： + +* 不支持生命周期管理。插件*不能*使用`onResume()`，`onPause()`，`onDestroy()`，或者`onActivityResult()`。在嵌入模式下应该谨慎使用诸如此类的事件。 +* 不需要配置文件，因为嵌入模式中是由Java代码负责创建和销毁插件的。 +* 不支持[`make_apk.py`]。嵌入模式是通过Android SDK tools，ant等进行编译的；作为编译的一部分，插件代码也由相同的工具进行编译。 + +下面将介绍如何在插件中添加代码并在嵌入模式下使用插件。在此之前，您首先需要[创建嵌入模式的应用](/documentation/android/embedding_crosswalk_zh.html)。 + +## 编写插件 + +创建一个继承[`XWalkExtension`](https://crosswalk-project.org/apis/embeddingapidocs_v2/reference/org/xwalk/core/XWalkExtension.html)的Java类。比如： + +**`org/crosswalkproject/sample/ExtensionEcho.java`:** + +``` +package org.crosswalkproject.sample; + +import org.xwalk.core.XWalkExtension; + +public class ExtensionEcho extends XWalkExtension { + private static String name = "echo"; + + private static String jsapi = "var echoListener = null;" + + "extension.setMessageListener(function(msg) {" + + " if (echoListener instanceof Function) {" + + " echoListener(msg);" + " };" + "});" + + "exports.echo = function (msg, callback) {" + + " echoListener = callback;" + " extension.postMessage(msg);" + + "};" + "exports.echoSync = function (msg) {" + + " return extension.internal.sendSyncMessage(msg);" + "};"; + + public ExtensionEcho() { + super(name, jsapi); + } + + @Override + public void onMessage(int instanceID, String message) { + postMessage(instanceID, "From java: " + message); + } + + @Override + public String onSyncMessage(int instanceID, String message) { + return "From java sync: " + message; + } + +} +``` + +上面的插件做了一些基本的字符串操作，但是一个真正的插件可能像其他导入的Java包一样，使用很多Android APIs。 + +代码解释： + +* 构造函数中的JavaScript字符串可以有多种传入方式：可以作为一个`String`传入(就像上面做的一样)，从`assets/`目录下读入一个js文件，从web server端获取等等。 + +* 可以将方法`onMessage()`和`onSyncMessage()`返回的字符串序列/反序列化成JSON格式以便进行更加复杂的操作。详情参见[插件文档](/documentation/android/android_extensions/write_an_extension_zh.html)。 + +注意在嵌入模式下的应用可以将插件以二进制形式，比如jar或者`.class`形式的文件包含进来。那么插件就可以按照其他导入的Java类一样使用。 + +## 嵌入模式下使用插件 + +使用插件，需要在嵌入模式的main activity启动之前实例化它。例如，如果您的activity是`src/org/crosswalkproject/sample/MainActivity.java` (参见[嵌入模式教程](/documentation/android_extensions/write_an_extension_zh.html))，那么您可以如下使用插件： + +1. 当activity准备好之后，添加创建插件实例化的代码到main activity： + + ``` + import org.crosswalkproject.sample.ExtensionEcho; + + public class MainActivity extends Activity { + private XWalkView mXWalkView; + private ExtensionEcho mExtension; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + // here is where the extension instance is created + mExtension = new ExtensionEcho(); + + // create the main Crosswalk view + mXWalkView = (XWalkView) findViewById(R.id.activity_main); + mXWalkView.load("file:///android_asset/index.html", null); + } + } + ``` + + 注意：推荐您在创建`XWalkView`实例前创建插件。 + + 同时需要注意的是如果您创建了多个含有相同名字的插件实例(像上面例子中的`"mExtension"`)，只有第一个有效。后续创建的实例将不会发挥任何作用(Crosswalk中的C++代码忽略任何名字与之前重复的实例)。 + +2. web应用的JavaScript模块中使用插件。下面的代码对插件进行了一个简单的测试并将结果写入到p元素中： + + ``` + + ``` diff --git a/public/documentation/android/embedding_crosswalk_zh.md b/public/documentation/android/embedding_crosswalk_zh.md new file mode 100644 index 000000000..cde8cc707 --- /dev/null +++ b/public/documentation/android/embedding_crosswalk_zh.md @@ -0,0 +1,343 @@ +# Crosswalk嵌入模式 + +Crosswalk embedding API允许您将Crosswalk runtime嵌入到应用中。在嵌入的rutime中，您可以加载一个网页，用法类似于安卓[WebView](http://developer.android.com/guide/webapps/webview.html)。 + +当您的应用中有大量的Java代码，但是又想要使用web技术来写UI界面时，我们才推荐您使用embedding API。如果您仅仅希望打包您的web应用到安卓平台，有两种方式可以选择： + +* [使用Crosswalk默认的打包工具](/documentation/android/build_an_application_zh.html)来生成安卓应用包APK文件。 +* [使用带有Crosswalk的Cordova](/documentation/cordova_zh.html)：使用这种方式，您将可以使用标准的设备APIS，同时也可以使用先进的web APIs，使用web技术来编译您的应用。 + +如果您需要使用embedding API, 请参照下面的步骤： + +## 使用embedding API创建应用 + +本教程中叙述了如何使用嵌入式Crosswalk webview来创建安卓应用。 + +在开始教程之前，您需要对安卓开发环境熟悉。因为通常是使用[ADT](http://developer.android.com/tools/sdk/eclipse-adt.html)创建安卓应用，本教程也使用了这个工具；因此熟悉此工具将会非常有用。 + +教程中的所有步骤都已经在Linux (Fedora 20)平台上测试过，因此本教程也适用于其他平台和操作系统(比如Windows)。 + +**阅读完本教程**，您将可以开发含有嵌入式Crosswalk runtime的安卓应用。 + +### 配置开发主机以及目标机 + +在使用embedding API之前，请确保您已经[为主机配置过安卓开发环境](/documentation/android/system_setup_zh.html)。 + +您也需要设置能够运行安卓应用的目标机，请参见[配置安卓目标机](/documentation/android/android_target_setup_zh.html)页面。 + +由于教程使用了ADT，请确保您的主机上已经[安装必要的ADT插件](http://developer.android.com/tools/sdk/eclipse-adt.html)。 + +### 下载Crosswalk webview bundle + + + +下载Crosswalk webview bundle到开发机中。Webview bundle包含一些在嵌入式Crosswalk应用中必须的库以及支持工具。注意webview是区分cpu架构的，所以您可能需要编译出基于ARM,x64以及64位平台上的多个APK。 + +解压下载的`.zip`文件。 + +### 导入Crosswalk webview到ADT + +下一步是通过导入的解压文件Crosswalk webview bundle,在ADT中创建一个工程。您可以参考下面的工程，编译属于您自己的Crosswalk嵌入模式应用。 + +创建工程： + +1. 打开ADT。 + +2. 选择*File* > *New* > *Project...*, 然后*Android* > *Android Project From Existing Code*。 + +3. 设置*Root Directory*到解压的`crosswalk-webview/`目录下。 + +4. 单击*Finish*。**crosswalk-webview**工程将会在*Package Explorer*中呈现出来。 + +### 用ADT创建安卓应用 + +接下来，创建一个将会使用Crosswalk embedding API的安卓应用。(依然在ADT中)： + +
    +
  1. +

    选择File > New > Android Application Project.

    + +

    在New Android Application弹出框中填入如下的类似内容：

    + +
      +
    • Application Name: XWalkEmbed
      • +
    • Project Name: XWalkEmbed
      • +
    • Package Name: org.crosswalkproject.xwalkembed
      • +
    • Minimum Required SDK: API 14 (Crosswalk支持的最低版本)
      • +
    • Target SDK: API 19 (或者您环境中有的版本)
      • +
    • Compile With: API 19
      • +
    • Theme: None
      • +
    + +

    如下图所示：

    + + + +

    点击Next.

    +
    2. + +
  2. +

    在Configure Project 面板中, 设置如下：

    + +
      +
    • 不打钩Create custom launcher icon.
      • +
    • 打钩Create activity.
      • +
    • 不打钩 Mark this project as a library.
      • +
    • 打钩create the project或者选择系统中其他路径。Add to working sets可以随意。
      • +
    + +

    结果如下图所示：

    + + + +

    点击Next.

    +
    3. + +
  3. +

    在Create Activity面板中, 选择Create Activity和Blank Activity:

    + + + +

    点击 Next.

    +
    4. + +
  4. +

    在Blank Activity中填入如下类似内容：

    + +
      +
    • Activity Name: MainActivity
      • +
    • Layout Name: activity_main
      • +
    • Fragment Layout Name: fragment_main
      • +
    • Navigation Type: none
      • +
    + +

    结果如下图所示：

    + + + +

    点击Finish.

    +
    5. +
+ +您的工程现在已经可以工作了。 + +### 在工程中引用Crosswalk webview + +下一步是添加Crosswalk webview到您的应用工程中 + +具体如下(在ADT)： + +1. 右键点击*Package Explorer*并选择*Properties*. + +2. 选择*Android*。 + +3. 在*Library*下，点击*Add*。选择**crosswalk-webview-${XWALK-BETA-ANDROID-X86}-x86**并点击OK。 + +点击Ok。 + +您的工程就可以链接到Crosswalk webview。 + +### 添加代码，集成webview + +1. Crosswalk在安卓上需要一些权限。打开这些权限，需要修改`AndroidManifest.xml`文件， 在``元素上面添加权限。Crosswalk WebView最少需要如下权限去取渲染页面： + ``` + + + + ``` + + 您可以添加其他权限，这取决您的应用开发需求。不过，只添加应用真正需要的权限，是一种公认的安全做法。 + + *获取地理位置信息* + ``` + + ``` + + *获取照相机，摄像机以及麦克风* + ``` + + + + ``` + + *写数据到SD Card* + ``` + + ``` + + *保持cpu运行状态* + ``` + + ``` + +2. 当生成application时，一些默认的布局资源会添加到工程中。用下面的内容替换主布局文件中的内容，`res/layout/activity_main.xml`： + + ``` + + + ``` + + 这将会用`XWalkView` (Crosswalk webview)资源去替换应用默认的view。 + + 您可以移除其他的文件，例如`res/layout/fragment_main.xml`，如果您不需要它。 + +3. 修改`MainActivity`类 (通过*Package Explorer*， 在`src/org.crosswalkproject.xwalkembed/MainActivity.java`中找到它)。用下面的内容替换默认内容： + + ``` + package org.crosswalkproject.xwalkembed; + + import org.xwalk.core.XWalkView; + + import android.app.Activity; + import android.os.Bundle; + + public class MainActivity extends Activity { + private XWalkView mXWalkView; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + mXWalkView = (XWalkView) findViewById(R.id.activity_main); + mXWalkView.load("http://crosswalk-project.org/", null); + } + } + ``` + + `R.layout.activity_main`指的是`activity_main`您上面定义的布局文件： 通过embedding API暴漏出来的Crosswalk runtime中webview部分。Activity的主content view就被设置成了这个webview。 + + 上面的代码把布局模块设置成`XWalkView`，因此加载web资源的方法就可以调用了。在这个例子中，调用了`load()`方法去加载Crosswalk官方网站并且在webview模块中渲染该网页。请注意`loadAppFromManifest()`方法也是可以调用的，这个方法通过manifest文件加载Crosswalk应用。详情参见[Embedding API文档](/apis/embeddingapidocs/reference/org/xwalk/core/XWalkView.html)。 + +您现在可以运行应用了，像平常一样：右键点击*Package Explorer*中的工程，选择 *Run As* > *Android Application*。 + +### 在Crosswalk webview中加载页面 + +在之前的章节中，您在webview中加载了一个页面，证明了Android应用可以"加载"网站。然而，如果你想让web应用作为Android应用的一部分运行，而不是在网站上运行网页，那么，您可以在Crosswalk webview中加载本地资源。 + +加载本地web资源，您需要把web文件添加到安卓应用里面作为应用包(`.apk`文件)的一部分。 + +参照下面步骤，添加web资源并把它们和您的应用打包在一起： + +1. 创建`assets/`目录。这是Android应用资源的标准路径，因此存放web资源比较合适。 + +2. 添加具有如下内容的`index.html`文件到`assets/`目录下： + + ``` + + + + + + simple + + +

hello world

+ + + ``` + +3. 修改`MainActivity`类(`src/org.crosswalkproject.xwalkembed/MainActivity.java`)： + + ``` + package org.crosswalkproject.xwalkembed; + + import org.xwalk.core.XWalkView; + + import android.app.Activity; + import android.os.Bundle; + + public class MainActivity extends Activity { + private XWalkView mXWalkView; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + mXWalkView = (XWalkView) findViewById(R.id.activity_main); + + // this loads a file from the assets/ directory + mXWalkView.load("file:///android_asset/index.html", null); + } + } + ``` + + 这里主要的不同是传到`load()`方法中的参数是一个本地资源的URL，而不是一个远程的web URL： + + ``` + mXWalkView.load("file:///android_asset/index.html", null); + ``` + + URL是以"file:///android_asset/"为前缀，后面添加上您需要加载的文件路径，路径名字是相对于`assets/`目录。 + + 当首页HTML网页加载之后，网页中的其他URLs将会被当做标准的web应用来处理，同时会把`assets/`目录作为应用的根目录。例如，如果在`assets/`目录下您有一个`page2.html`的网页，您可以用一个标准的超链接来链接到这个网页： + + ``` + Page 2 + ``` + + 类似地，任何CSS或者媒体文件(音频，视频)文件都可以被添加到`assets/`目录并像平常那样使用，例如： + + ``` + +