0.4
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.
createInstance
to destroyInstance
. During this period, we can import some extra data by refreshInstance
.
sendTasks
and receiveTasks
. They are used to call each other by some commands and messages.
registerComponents
, registerModules
.
getRoot
to return the whole virtual-DOM data for developers.
Error
object should be returned.
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 by new Function(code)
in JS Framework. The code format depends on JS Bundle Foramt
options
: Optional. An options object. Currently it supports debug
flag which enable printing log and bundleUrl
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 supports append
attribute which forces the appending mechanism (tree
or node
) 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 a name
string and an args
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 a method="fireEvent|callback"
property and a list of args
.
fireEvent
method, the args
is ref
of the target, event type
, event data
and domChanges
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 as domChanges
.
callback
method, the args
is funcId
of a handler, data
and ifKeepAlive
which describes whether this callback handler should be keeping called. (Each callback handler is matched with a funcId
when the original call happens.)
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: [...]}
sendTasks(instanceId, tasks)
Make native calls from JS Framework
tasks[]
: A task list. Each task has a module
name, a method
name, and a args[]
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]},
...
])
// lib/frameworks/index.js import Vue from '...' import React from '...' import Angular from '...' export const frameworks = { Vue, React, Angular }
// 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.
You can import lib/runtime/helper.js
to get two important things:
Document
class, see virtual-DOM spec for more.
sendTasks
method.
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.