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 to destroyInstance. During this period, we can import some extra data by refreshInstance.
  • To communicate with Native Engine, we have a couple of APIs: sendTasks and receiveTasks. 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 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.
    • In 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.
    • In 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: [...]}

Called from JavaScript and implemented with native code

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]},
  ...
])

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:

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.

results matching ""

    No results matching ""