Package Exports
- @mlibai/native.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@mlibai/native.js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
native.js API 文档
说明
一般情况下，HTML 与 App 交互，并不是从 App 创建 WebView 对象后立即就可以进行交互操作，而且不同的平台处理交互的方式也不尽相同。为了解决此问题，框架 native.js 提供了统一的交互接口，并在内部实现与 App 的不同交互方式，简化 HTML 与 App 的交互操作。
HTML
如何使用
- 推荐使用 npm 安装
@mlibai/native.js。
var native = require('@mlibai/native.js');
// 或者
import '@mlibai/native.js'- 直接引用。
下载 Products/native.js 到项目中，然后引入到 HTML 页面中.
<script src="./native/native.js"></script>在 ready 回调中处理所有涉及到 JavaScript 与 App 交互的操作。
window.native.ready(function() {
Native.log("native is ready：" + Native.version);
});交互机制
运行流程
- App 创建
WebView并加载 HTML 页面。 - HTML 加载
native.js框架，创建native对象（已创建，但是逻辑上未初始化，交互功能不可用）。 - 包装所有跨平台交互操作在
native.ready(fn)回调函数中，等待执行。 - 调用
native.core.register()方法，注册与 App 的交互方式，并在合适的时机向 App 发送ready消息，向原生请求请求初始化native对象。 - 原生收到
native的初始化消息，执行初始化并响应消息（调用native.core.callback()方法处理回调）。 - 对象
native完成初始化，并按顺序逐一执行步骤3中包装的操作。 - 调用
native的交互方法，App 就可以按照步骤4中约定的交互方式收到交互的消息，然后执行消息代表的操作，从而实现交互。
与其它框架兼容
将所有涉及交互的操作放到 native.ready() 回调中，或者保证所有交互操作是在 native 对象 ready 之后进行。
因此，在保证 native 对象在业务逻辑中能正常使用且兼顾其它JS框架开发流程的情况下，需处理各框架间的执行顺序。
- JQuery
因为 JQuery 提供了暂停的方法，所以可以在不改变原有编程风格的前提下，通过暂停来实现 native 与 JQuery 的顺序执行。
// 使用 JQuery 实现业务逻辑
$(function() {
// 业务逻辑。
});
// 暂停 JQuery.ready 事件执行。。
$.holdReady(true);
// 在 native 初始化后，恢复 JQuery.ready
native.ready(function() {
$.holdReady(false);
});- AngularJS
AngularJS 没有暂停执行的方法，但是可以设置它不自动执行，然后在 native 初始化后再启动即可。
// 1. 禁止 AngularJS 自动执行：在 HTML 代码中，去掉标签上的 `ng-app` 属性。
// 2. 使用 AngularJS 实现业务逻辑。
var app = angular.module('App', []);
app.controller('main', function($scope) {
// 业务逻辑代码
});
// 3. 使用 `angular.bootstrap` 方法在 `native.ready` 中启动 AngularJS 模块。
native.ready(function () {
// 在 angular.ready 中启动模块
angular.element(document).ready(function () {
// 第一个参数表示模块的根 DOM 元素。
// 第二个参数就是模块名字。
angular.bootstrap(document.body, ['App']);
});
});接口文档
ready(fn)
- 说明
注册在 native 对象初始化完成后执行的操作。如果 native 对象没有初始化，则在 native 对象初始化后按注册 顺序依次执行所有已注册的操作；如果已初始化，则操作立即（异步）执行。
- 参数
fn: 待执行的操作。
- 示例
native.ready(function(){
console.log("Native is ready.");
});extend(fn)
- 说明
- 参数
- 示例
core: NativeCore
callback(fn): string
- 说明
注册回调函数，并获取回调函数的标识符。
- 参数
| fn | Function | 1.0.0 | 回调函数 |
- 示例
callback(identifier[, needsRemove])
- 说明
通过标识符获取已注册的回调函数。
- 参数
| identifier | String | 1.0.0 | 回调函数的标识符 | | needsRemove | Bool | 1.0.0 | 是否需要删除，默认 true |
- 示例
perform(method: string, args...: any): void
- 说明
- 参数
- 示例
register(delegate: any, mode: string): void
- 说明
- 参数
- 示例
scheme: string
isReady: bool
delegate: any
mode: string
login(fn: () -> void): void
- 说明
- 参数
- 示例
currentUser: NativeUser
navigation: NativeNavigation
- bar: NativeNavigationBar
- push(url: string, animated: bool): void
- pop(animated: bool): void
- popTo(index: number, animated: bool): void
networking: NativeNetworing
- isViaWiFi: bool
- status: string
- isReachable: bool
- statusChange(fn: () -> void): void
- http(request: object, fn: () -> void): void
通过 native.core 的 perform(method, args...) 方法，可以直接调用原生平台的方法。
比如，调用原生的登录方法，则可如下调用。
// 示例：执行原生的 login 方法。
native.core.perform("login", {"account": "foo", "password": "bar"}, function () {
});native.core 是与原生交互的核心功能，将 JS 调用的 method 通过消息机制传递给原生，并由原生来解析消息并执行相应的方法。
但是不同平台、环境的交互方式存在差异，为了解决此问题，native.js 在核心部分封装了几种常见的交互方式，并对外提供了统一的接口，从而实现跨平台开发。
交互机制
目录
[TOC]
说明
本协议，规范 App 内 HTML 页面与 App 的交互方式，提高开发效率，降低维护成本。
基本规范
- 通过 URL 参数传递数据时，使用 Key-Value 形式，如果 Value 不是基本数据类型，则用
URL 编码后的 JSON 串表示。 - 所有标注为只读的属性，请在业务逻辑中，不要去修改这些值。它们虽然可能可写，但只是供 App 初始化值时使用。
- 只读的属性，即使修改其值，也不会影响 App 里的内容。
第一部分：HTML 访问 App
HTML 页面通过 App 提供 JavaScript 接口，来实现对 App 功能的访问。
1. 浏览器环境
- HTML 若要判断是否处于 App 提供的浏览器环境中，可以通过
User-Agent判断。// 无特殊说明，所有代码均为 JavaScript 代码。 // 判断是否在 App 中。 var isApp = /Onemena/.test(window.navigator.userAgent); - 交互说明：
- App 须在初始化 WebView 时修改
User-Agent。
- App 须在初始化 WebView 时修改
2. 接口获取方式
- App 提供的接口统一定义在
omApp对象上，所有 HTML 与 App 的交互都通过此对象进行。// 打印 App 提供的 JavaScript 接口 console.log(omApp); // 或者 console.log(window.omApp); - 在不同的环境下，
omApp可能并不是相同的对象，因此除本文档提供的方法、属性外，不要对omApp的其它属性或方法产生依赖。 - 交互说明：
- 基于对象注入的方式，须在 WebView 创建 JavaScript 环境时注入
omApp对象。 - 需保证
omApp对象在使用前已初始化完成。
- 基于对象注入的方式，须在 WebView 创建 JavaScript 环境时注入
3. 开发调试
- 引入
OMApp.js交互框架，文件在 OMApp 目录下； - 在桌面浏览器中开发调试；
- 在 App 中开发调试；
- 请尽量保持
OMApp.js为最新版本。
4. 接口列表
4.1 debug(configuration)
接口说明： 为了方便在浏览器中开发调试，通过此接口设置
omApp对象的初始值。此接口只在浏览器中生效，在 App 中不执行任何操作。需在调用omApp对象之前设置，否则不生效。参数说明：
Name Type Description configuration Object 一个结构类似 omApp 的数据对象 代码示例：
// omApp 初始化配置参数。
omApp.debug({
currentTheme: OMAppTheme.night, // 主题
currentUser: { // 当前用户
id: "09",
name: "John",
type: OMAppUserType.facebook,
coin: 1000,
token: "Test"
},
network: {
type: OMAppNetworkType.unknown, // 网络类型
ajaxSettings: { // 网络请求默认配置
headers: {
"Access-Token": "OMApp",
"User-Token": "Onemena"
},
data: { }
}
},
navigation: { // 导航初始状态
bar: {
title: "Onemena",
titleColor: "#FFFFFF",
backgroundColor: "#000000",
isHidden: false
}
}
});4.2 ready(callback)
2017-07-27： 新增接口。接口说明：
为了保证
omApp对象在使用时已完成初始化，请将所有用到omApp方法或属性的代码，放在此方法中进行。该方法可以调用多次，且所有代码会在初始化完成时，按次序执行。 注意：此方法若不调用，App 不会对omApp执行初始化操作。参数说明：
Name Type Description callback Function 回调函数，无参数 代码示例：
- 常规用法。
// 本方法类似但不能替代 JQuery.ready 方法。 // 在基于URL拦截的交互方式中，该方法监听的是 DOMContentLoaded 事件，与 JQuery 一样。 // 在基于对象注入的交互方式中，调用该方法时，回调可能被立即执行。 omApp.ready(function() { // 基于 omApp 对象的业务逻辑代码。比如：获取 App 的主题设置。 console.log(omApp.currentTheme); });- 与第三方框架一起使用。
// 因为基于 omApp 的业务逻辑需要在 ready 方法中执行， // 但是往往第三方框架有自己的执行机制，所以需要设置第三方框架延迟执行。 // 例如 angular 的延迟执行步骤如下： // 1. 删除 HTML 标签中的 `ng-app` 属性，因为添加了该属性 angular 在加载时就会自动执行。 // 2. 定义 angular 模块。 var moduleName = angular.module('moduleName', []); // more settings such as `moduleName.controller`, `moduleName.directive` // 3. 在 omApp.ready 中启动模块。 omApp.ready(function () { // 为了兼容性，建议在 angular 的 ready 中启动模块。 angular.element(document).ready(function() { // 第一个参数表示 angular 的根 DOM 元素。 // 第二个参数就是`步骤2`中定义的模块名字。 // `步骤2`模块的定义也可以放在这里进行，也就是在调用 bootstrap 方法前，模块必须被定义。 angular.bootstrap(document, ['moduleName']); }); });交互说明：
- 基于 URL 的交互方式，
omApp对象的初始化，请在监听到此事件时进行。 - 需初始化的属性，详见各接口。
- 交互协议：
- URL：
app://documentisready - 回调：
omApp.didFinishLoading()
- URL：
- 基于 URL 的交互方式，
4.3 currentTheme
变更日志：
2017-06-17： `theme` -> `currentTheme` 接口说明：
此接口用于获取或设置 App 当前的主题外观，String 类型。
属性说明：
非空，可写，OMAppTheme 枚举值。
-
Name Type Description OMAppTheme.day String 新闻栏目 ID OMAppTheme.night String 新闻栏目 ID 代码示例：
if (omApp.currentTheme == OMAppTheme.day) { // do something when the theme is day. } else if (omApp.currentTheme == OMAppTheme.night) { // do something when the theme is night. }交互说明：
- 基于 URL 的交互方式，需在 ready 中初始化此属性。
- 交互协议：
- URL：
app://currenttheme/?name=...
- URL：
4.4 currentUser
接口说明：
只读，非空，Object 类型。当 HTML 需要获取 App 当前用户信息时，调用此接口。例如，判断用户是否登录可通过
isOnline属性来确定。属性说明：
Name Type Description isOnline Bool 只读。是否已登录 id String 只读。用户ID name String 只读。用户名 type String 只读。见 OMAppUserType枚举 coin Int 只读。用户金币数 token String 只读。user token * 说明： token 字段对外并不是一个好的 API 设计，未来优化的版本中将去掉此值。
-
Name Type Description OMAppUserType.visitor String 游客用户 OMAppUserType.google String Google 登录用户 OMAppUserType.facebook String Facebook 登录用户 OMAppUserType.twitter String Twitter 登录用户 代码示例：
// 判断用户是否登录 if (omApp.currentUser.isOnline) { // do something when user is logged. } else { // do something } // get the user name var userName = omApp.currentUser.name;交互说明：
- 基于 URL 的交互方式，需在 ready 方法中初始化 currentUser 的各个属性。
- currentUser 属性声明为只读，表示在业务逻辑中，不要去修改它，但是它们实际上是可修改的。
- 因此在 ready 事件中，直接调用 JS 修改各属性值即可。
4.5 navigation
接口说明：
Object，只读，非空。 为了使 HTML 提供类似原生 App 的操作体验，
navigation接口给 HTML 提供了创建新窗口的能，并通过导航栈来管理这一系列窗口。
4.5.1 navigation.push(url, animated)
接口说明：
创建一个新窗口并打开指定 URL，常用于导航到下级页面。新窗口将压入到导航栈顶。
参数说明：
Name Type Description url String 必选。下级页面的 URL animated Bool 可选。是否展示转场动画，默认 true 代码示例：
omApp.navigation.push('http://8.dev.arabsada.com/'); omApp.navigation.push('http://8.dev.arabsada.com/', true);基于 URL 的交互方式：
- URL：
app://navigation.push/?url=...&animated=...
- URL：
4.5.2 navigation.pop(animated)
接口说明：
关闭当前窗口，并返回到上一个窗口，常用于返回到上级页面。当前窗口从导航栈中弹出。
参数说明：
Name Type Description animated Bool 可选。是否展示转场动画，默认 true 代码示例：
omApp.navigation.pop(true);基于 URL 的交互方式：
- URL：
app://navigation.pop/?animated=...
- URL：
4.5.3 navigation.popTo(index, animated)
接口说明：
返回到导航栈内指定级页面。如果当前导航栈内已经有很多页面，此方法可以快速回到指定页面。
参数说明：
Name Type Description index Int 必选。正数，目的页面所在的位置索引，0 为第一个 HTML 页面 animated Bool 可选。是否展示转场动画，默认 true 代码示例：
omApp.navigation.popTo(0, true);基于 URL 的交互方式：
- URL：
app://navigation.popto/?index=...&animated=...
- URL：
4.5.4 navigation.bar
接口说明：
只读，Object。代表了 App 的原生导航条对象。通过此对象，可以控制导航条的外观。
属性说明：
Name Type Description isHidden Bool 导航条是否隐藏 title String 标题 titleColor String 标题颜色 backgroundColor String 背景色 代码示例：
omApp.navigation.bar.isHidden = false; omApp.navigation.bar.title = '自定义的标题'; omApp.navigation.bar.titleColor = '#FF0000'; omApp.navigation.bar.backgroundColor = '#0000FF';交互说明：
- 基于 URL 的交互方式 App 需在 ready 方法中初始化 bar 各属性的初始值。
- 交互协议：
- URL：
app://navigation.bar/?isHidden=...&title=...&titleColor=...
- URL：
4.6 login(callback)
接口说明：
当 HTML 页面需要调用 App 的
登录功能时，调用此接口。参数说明：
Name Type Description callback Function 可选。登录回调函数，用户返回登录结果 - callback 函数参数：
Name Type Description success Bool 是否登录成功。 * 请通过 omApp.currentUser 来获取当前已登录用户信息。
代码示例：
// 调起 App 的登录流程 omApp.login(function(success) { if (success) { // do suceess actions. } else { // do something when failed. } });基于 URL 的交互方式：
URL：
app://login/?callbackID=...回调：
omApp.didFinishLogin(callbackID, success)Name Type Description callbackID String url 中的 callbackID success Bool 登录是否成功
4.7 networking
接口说明：
只读，非空，Object 类型。判断是否可联网
isReachable属性来确定。属性说明：
Name Type Description isReachable Bool 只读。是否能联网。 isViaWiFi Bool 只读。是否是 WiFi 。 type OMAppNetworkingType 只读。OMAppNetworkingType 枚举。