@searchfe/sandbox

@searchfe/sandbox

一个简易的 Sandbox，用来隔离不同的页面组件，使它们的执行互不干扰。使用 APM 安装：

apmjs install @searchfe/sandbox

其中 Fetch API 可能需要适当的 Polyfill：

• https://www.npmjs.com/package/whatwg-fetch
• https://github.com/taylorhakes/promise-polyfill

Classes

Sandbox

沙盒实例 创建后默认处于睡眠状态。需要调用 sandbox.run() 让它开始工作。

Window

沙盒上下文 提供给沙盒内的业务逻辑使用，相当于浏览器的 window。

Document

沙盒文档 局部的 DOM 文档对象，托管了所有事件，页面属性等。

Element

元素对象 这是 HTMLElement 的一个沙盒代理对象，封装并托管了 DOM 操作。

Members

scrollTo

滚动窗口，见 https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo

Interfaces

IEventTarget

事件接口，用于托管全局事件。Window 和 Document 对象实现了该接口。 根元素以下的事件监听不予监听，见：https://github.com/searchfe/sandbox/issues/2

IFetchAPI

Fetch API 的封装，见 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API 具体实现取决于当前浏览器版本，以及当前环境的 Fetch Polyfill

ITimeout

定时器接口，用于托管定时器。Window 对象使用了该接口。

IEventTarget

事件接口，用于托管全局事件。Window 和 Document 对象实现了该接口。 根元素以下的事件监听不予监听，见：https://github.com/searchfe/sandbox/issues/2

Kind: global interface

• IEventTarget
  • .addEventListener(event, cb, useCapture)
  • .removeEventListener(event, cb, useCapture)

IEventTarget.addEventListener(event, cb, useCapture)

Add an event listener to the hosted object

Kind: static method of IEventTarget

Param	Type	Description
event	String	The event type
cb	function	The event listener
useCapture	Boolean	Whether or not use capture

IEventTarget.removeEventListener(event, cb, useCapture)

Remove an event listener to the hosted object

Kind: static method of IEventTarget

Param	Type	Description
event	String	The event type
cb	function	The event listener
useCapture	Boolean	Whether or not use capture

IFetchAPI

Fetch API 的封装，见 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API 具体实现取决于当前浏览器版本，以及当前环境的 Fetch Polyfill

Kind: global interface

IFetchAPI.fetch(input, init)

发起一个被沙盒托管的网络请求，API 请参考： https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch

Kind: static method of IFetchAPI

Param	Type	Description
input	String	目标 url
init	function	请求参数

ITimeout

定时器接口，用于托管定时器。Window 对象使用了该接口。

Kind: global interface

• ITimeout
  • .setInterval(fn, timeout)
  • .clearInterval(id)
  • .setTimeout(fn, timeout)
  • .requestAnimationFrame(fn)
  • .clearTimeout(id)

ITimeout.setInterval(fn, timeout)

The setInterval() method repeatedly calls a function or executes a code snippet, with a fixed time delay between each call. It returns an interval ID which uniquely identifies the interval, so you can remove it later by calling clearInterval()

Kind: static method of ITimeout

Param	Type	Description
fn	function	The scheduled callback
timeout	Number	Time inteval in millisecond

ITimeout.clearInterval(id)

移除定时器

Kind: static method of ITimeout

Param	Type	Description
id	Number	定时器 ID，即 setInteval 的返回值

ITimeout.setTimeout(fn, timeout)

The setTimeout() method sets a timer which executes a function or specified piece of code once after the timer expires.

Kind: static method of ITimeout

Param	Type	Description
fn	function	The scheduled callback
timeout	Number	Time in millisecond

ITimeout.requestAnimationFrame(fn)

requestAnimationFrame() 是一个有 Polyfill 的 requestAnimationFrame()，相当于 16ms 的 timeout

Kind: static method of ITimeout

Param	Type	Description
fn	function	The scheduled callback

ITimeout.clearTimeout(id)

移除定时器

Kind: static method of ITimeout

Param	Type	Description
id	Number	定时器 ID，即 setTimeout 的返回值

Sandbox

沙盒实例 创建后默认处于睡眠状态。需要调用 sandbox.run() 让它开始工作。

Kind: global class

• Sandbox
  • new Sandbox(element, [context])
  • .run()
  • .stop()
  • .toggle()
  • .die()
  • .on(type, cb, once)
  • .one(type, cb)
  • .trigger(type)
  • .off(type, cb)
  • .spawn(child, [context]) ⇒ Sandbox

new Sandbox(element, [context])

创建后默认处于睡眠状态。需要调用 sandbox.run() 让它开始工作。

Param	Type	Description
element	function	沙盒对应的 DOM 根元素
[context]	Object	初始化作用域，会被合并到 sandbox.window

Example

require(['@searchfe/sandbox'], function(Sandbox){
  var sandbox = new Sandbox(document.querySelector('#app'))
  sandbox.run();
  sandbox.setInterval(() => console.log('timeout!'), 100)
  setTimeout(function(){
    sandbox.stop();
    // sandbox.die();
  }, 5000);
})

sandbox.run()

让沙盒开始工作，开始接管事件、定时器、以及网络回调。

Kind: instance method of Sandbox

sandbox.stop()

停止沙盒，冻结定时器和网络回调、忽略事件。

Kind: instance method of Sandbox

sandbox.toggle()

如果在跑，就让它停；如果已停，就让它跑

Kind: instance method of Sandbox

sandbox.die()

杀死沙盒，销毁内部的定时器、网络、事件回调。一旦杀死不可重新开始工作。

Kind: instance method of Sandbox

sandbox.on(type, cb, once)

Add a listener to the sandbox, available event types: run, stop, die

Kind: instance method of Sandbox

Param	Type	Description
type	string	the event type
cb	function	the callback
once	boolean	execute only once

sandbox.one(type, cb)

Attach a handler to an event for the sandbox. The handler is executed at most once per event type.

Kind: instance method of Sandbox
Throws:

• Error event type not defined

Param	Type	Description
type	string	the event type
cb	function	the callback

sandbox.trigger(type)

Execute all handlers and behaviors attached to the sandbox for the given event type

Kind: instance method of Sandbox

Param	Type	Description
type	string	the event type

sandbox.off(type, cb)

Remove a listener to the sandbox, available event types: run, stop, die

Kind: instance method of Sandbox
Throws:

• Error event type not defined

Param	Type	Description
type	string	the event type
cb	function	the callback

sandbox.spawn(child, [context]) ⇒ Sandbox

生成一个子沙盒对象，子沙盒会跟随父沙盒的生命周期。子沙盒会继承当前沙盒的状态，即： 如果当前沙盒处于 RUNNING 状态，子沙盒会立即执行。

Kind: instance method of Sandbox
Returns: Sandbox - 子沙盒对象
Throws:

• Error 沙盒已死
• Error 指定的节点是当前沙盒的祖先

Param	Type	Description
child	HTMLElement | string	子 HTMLElement 或子元素选择符
[context]	Object	子 HTMLElement 或子元素选择符

Window

沙盒上下文 提供给沙盒内的业务逻辑使用，相当于浏览器的 window。

Kind: global class
Implements: IEventTarget, ITimeout, IFetchAPI

• Window
  • new Window(element, sandbox)
  • .document : Document
  • .location
  • .pageXOffset : Number
  • .pageYOffset : Number
  • .innerHeight : Number
  • .outerHeight : Number
  • .innerWidth : Number
  • .outerWidth : Number

new Window(element, sandbox)

创建一个沙盒上下文

Param	Type	Description
element	HTMLElement	沙盒的根 DOM 元素
sandbox	Sandbox	绑定到的沙盒对象

window.document : Document

沙盒的文档对象

Kind: instance property of Window

window.location

Location 对象的封装

Kind: instance property of Window

window.pageXOffset : Number

Kind: instance property of Window
Read only: true

window.pageYOffset : Number

Kind: instance property of Window
Read only: true

window.innerHeight : Number

Kind: instance property of Window
Read only: true

window.outerHeight : Number

Kind: instance property of Window
Read only: true

window.innerWidth : Number

Kind: instance property of Window
Read only: true

window.outerWidth : Number

Kind: instance property of Window
Read only: true

Document

沙盒文档 局部的 DOM 文档对象，托管了所有事件，页面属性等。

Kind: global class

• Document
  • new Document(element, sandbox)
  • .querySelector : function
  • .querySelectorAll : function
  • .sandbox : Sandbox
  • .documentElement : HTMLElement
  • .scrollingElement : Element
  • .cookie : Element
  • .createElement : Element

new Document(element, sandbox)

创建一个文档对象

Param	Type	Description
element	Element	沙盒上下文
sandbox	Sandbox	对应的沙盒对象

document.querySelector : function

封装 querySelector

Kind: instance property of Document
Read only: true

document.querySelectorAll : function

封装 querySelectorAll，限制：返回值类型为 Array 而非 NodeList，这意味着返回列表不是 Live 的。

Kind: instance property of Document
Read only: true

document.sandbox : Sandbox

与当前文档绑定的沙盒对象

Kind: instance property of Document

document.documentElement : HTMLElement

Kind: instance property of Document
Read only: true

document.scrollingElement : Element

Kind: instance property of Document
Read only: true

document.cookie : Element

Kind: instance property of Document
Read only: true

document.createElement : Element

Kind: instance property of Document
Read only: true

Element

元素对象 这是 HTMLElement 的一个沙盒代理对象，封装并托管了 DOM 操作。

Kind: global class
Implements: IEventTarget

• Element
  • new Element(element)
  • .scrollTo : Document
  • .offsetTop : Number
  • .offsetLeft : Number
  • .offsetHeight : Number
  • .offsetWidth : Number
  • .scrollHeight : Number
  • .scrollWidth : Number
  • .clientHeight : Number
  • .clientWidth : Number
  • .scrollTop : Number
  • .scrollLeft : Number

new Element(element)

创建一个元素对象

Param	Type	Description
element	HTMLElement	HTML 元素对象

element.scrollTo : Document

Kind: instance property of Element

element.offsetTop : Number

Kind: instance property of Element
Read only: true

element.offsetLeft : Number

Kind: instance property of Element
Read only: true

element.offsetHeight : Number

Kind: instance property of Element
Read only: true

element.offsetWidth : Number

Kind: instance property of Element
Read only: true

element.scrollHeight : Number

Kind: instance property of Element
Read only: true

element.scrollWidth : Number

Kind: instance property of Element
Read only: true

element.clientHeight : Number

Kind: instance property of Element
Read only: true

element.clientWidth : Number

Kind: instance property of Element
Read only: true

element.scrollTop : Number

Kind: instance property of Element

element.scrollLeft : Number

Kind: instance property of Element

scrollTo

滚动窗口，见 https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo

Kind: global variable