JS Framework APIs
0.4 cn
Intro about JS Runtime
These APIs are designed for JS Framework and Native Engine working together.
Considering the limitation of mobile phone resource, Weex runs only one JS runtime to handle all Weex instances. So it need a multi-instance management layer in JavaScript. These JS Framework APIs are just designed to do the management job.
- First, each Weex instance have a lifecycle, from
createInstance
todestroyInstance
. During this period, we can import some extra data byrefreshInstance
. - To communicate with Native Engine, we have a couple of APIs:
sendTasks
andreceiveTasks
. They are used to call each other by some commands and messages. - And when JS runtime start at the beginning of the app launching, we need something initialized and configured. So we supply some APIs like
registerComponents
,registerModules
. - The last API is just for debugging, we supply an API named
getRoot
to return the whole virtual-DOM data for developers. - If any of these API calls failed, an
Error
object should be returned.
Called by native and supplied from JS Framework
createInstance(instanceId, code, options, data)
Create a Weex instance from Native Engine
instanceId
: The unique id for a Weex instance, generated by Native Engine.code
: The JS bundle code send from Native Engine. It will be executed bynew Function(code)
in JS Framework. The code format depends on JS Bundle Foramtoptions
: Optional. An options object. Currently it supportsdebug
flag which enable printing log andbundleUrl
flag which the url of bundle.data
: Optional. It's an chance to supply external data instead of the original data in JS bundle.
Example:
createInstance('x', 'define(...); define(...); define(...); bootstrap(...)')
createInstance('x', '...', { bundleUrl, debug, ... }, { a: 1, b: 2 }})
destroyInstance(instanceId)
Destroy an existed Weex instance by id from Native Engine
refreshInstance(instanceId, data)
Refresh data to an existed Weex instance with certain external data from Native Engine
Example:
refreshInstance('x', {a: 100, b: 200})
registerComponents(components)
Register all native components
components
: A array of whose items are component options that are force part to use. Currently it supportsappend
attribute which forces the appending mechanism (tree
ornode
) when first time rendering.
Example:
registerComponents([
{ type: 'container' },
{ type: 'text' },
{ type: 'image' },
{ type: 'slider', append: 'tree' },
{ type: 'list' },
{ type: 'cell', append: 'tree' },
...
])
registerModules(modules)
Register the name, methods and args format of each module
modules
: A map that collects all native module definitions. Each module definition is an array which has several API definitions. Each API definition has aname
string and anargs
array which contains a list of each parameter's type.
NOTE: the node
type data will actually return its ref
property. And the function
type data will actually return a unique function id referring to it.
Example:
registerModules({
event: [
{name: 'openURL', args: ['string']}
],
...
})
receiveTasks(instanceId, tasks)
Fire events or callbacks to an existed Weex instance from Native Engine
tasks[]
: A task list. Each task has amethod="fireEvent|callback"
property and a list ofargs
.- In
fireEvent
method, theargs
isref
of the target, eventtype
, eventdata
anddomChanges
description in order. Note: if some event make virtual-DOM data changed (e.g. value changed in<input>
or current index changed in<slider>
), the changing of the target element will be passed asdomChanges
. - In
callback
method, theargs
isfuncId
of a handler,data
andifKeepAlive
which describes whether this callback handler should be keeping called. (Each callback handler is matched with afuncId
when the original call happens.)
- In
Example:
receiveTasks('x', [{method: 'fireEvent', args: ['x', '13', 'click', {a: 100, b: 200}]}])
receiveTasks('x', [{method: 'callback', args: ['x', '7', {a: 100, b: 200}, true]}])
getRoot(instanceId)
Return a JSON object which describes the whole virtual DOM body of an existed Weex instance, which designed for debugging
Example:
getRoot('x')
// {ref: '_root', type: 'container', attr: {...}, style: {...}, children: [...]}
Called from JavaScript and implemented with native code
sendTasks(instanceId, tasks)
Make native calls from JS Framework
tasks[]
: A task list. Each task has amodule
name, amethod
name, and aargs[]
list.
Example:
sendTasks('x', [
{module: 'dom', method: 'addElement', args: ['_root', {ref: '1', type: 'container'}, -1]},
{module: 'dom', method: 'addElement', args: ['1', {ref: '2', type: 'text', ...}, -1]},
{module: 'dom', method: 'addElement', args: ['1', {ref: '3', type: 'image', ...}, -1]},
...
])
Supporting other JS Framework (experimental)
Register a new JS Framework
// lib/frameworks/index.js
import Vue from '...'
import React from '...'
import Angular from '...'
export const frameworks = {
Vue,
React,
Angular
}
Expose JS Framework APIs
// 3rd-party-framework.js
export function createInstance (id, code, config, data) { ... }
export function destroyInstance (id) { ... }
export function refreshInstance (id, data) { ... }
export function registerComponents (components) { ... }
export function registerModules (modules) { ... }
export function recieveTasks (id, tasks) { ... }
export function getRoot (id) { ... }
The virtual-DOM tasks should follow virtual-DOM spec.
Framework Helper
You can import lib/runtime/helper.js
to get two important things:
Document
class, see virtual-DOM spec for more.sendTasks
method.
JS Bundle format
You must ensure the JS Bundle has its first line of code like this:
// { "framework": "Vue" }
...
to allow JS Runtime to detect which JS Framework it should be opened by.
If no valid annotation found. The JS Bundle will be opened by default JS Framework of Weex.