@searchfe/sandbox

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

apmjs install @searchfe/sandbox

其中 Fetch API 可能需要适当的 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 对象实现了该接口。根元素以下的事件监听不予监听，见：#2
IFetchAPI: Fetch API 的封装，见 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API 具体实现取决于当前浏览器版本，以及当前环境的 Fetch Polyfill
ITimeout: 定时器接口，用于托管定时器。Window 对象使用了该接口。

IEventTarget

事件接口，用于托管全局事件。Window 和 Document 对象实现了该接口。根元素以下的事件监听不予监听，见：#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

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])

创建后默认处于睡眠状态。需要调用 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 元素对象