@searchfe/sandbox

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

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/FetchAPI 具体实现取决于当前浏览器版本，以及当前环境的 Fetch Polyfill

ITimeout

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

IEventTarget

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

• IEventTarget

* [.addEventListener(event, cb, useCapture)](#IEventTarget.addEventListener)
* [.removeEventListener(event, cb, useCapture)](#IEventTarget.removeEventListener)

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/FetchAPI 具体实现取决于当前浏览器版本，以及当前环境的 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)](#ITimeout.setInterval)
* [.clearInterval(id)](#ITimeout.clearInterval)
* [.setTimeout(fn, timeout)](#ITimeout.setTimeout)
* [.requestAnimationFrame(fn)](#ITimeout.requestAnimationFrame)
* [.clearTimeout(id)](#ITimeout.clearTimeout)

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])](#new_Sandbox_new)
* [.run()](#Sandbox+run)
* [.stop()](#Sandbox+stop)
* [.toggle()](#Sandbox+toggle)
* [.die()](#Sandbox+die)
* [.on(type, cb, once)](#Sandbox+on)
* [.one(type, cb)](#Sandbox+one)
* [.trigger(type)](#Sandbox+trigger)
* [.off(type, cb)](#Sandbox+off)
* [.spawn(child, [context])](#Sandbox+spawn) ⇒ [<code>Sandbox</code>](#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)](#new_Window_new)
* [.document](#Window+document) : [<code>Document</code>](#Document)
* [.location](#Window+location)
* [.pageXOffset](#Window+pageXOffset) : <code>Number</code>
* [.pageYOffset](#Window+pageYOffset) : <code>Number</code>
* [.innerHeight](#Window+innerHeight) : <code>Number</code>
* [.outerHeight](#Window+outerHeight) : <code>Number</code>
* [.innerWidth](#Window+innerWidth) : <code>Number</code>
* [.outerWidth](#Window+outerWidth) : <code>Number</code>

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)](#new_Document_new)
* [.querySelector](#Document+querySelector) : <code>function</code>
* [.querySelectorAll](#Document+querySelectorAll) : <code>function</code>
* [.sandbox](#Document+sandbox) : [<code>Sandbox</code>](#Sandbox)
* [.documentElement](#Document+documentElement) : <code>HTMLElement</code>
* [.scrollingElement](#Document+scrollingElement) : [<code>Element</code>](#Element)
* [.cookie](#Document+cookie) : [<code>Element</code>](#Element)
* [.createElement](#Document+createElement) : [<code>Element</code>](#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)](#new_Element_new)
* [.scrollTo](#Element+scrollTo) : [<code>Document</code>](#Document)
* [.offsetTop](#Element+offsetTop) : <code>Number</code>
* [.offsetLeft](#Element+offsetLeft) : <code>Number</code>
* [.offsetHeight](#Element+offsetHeight) : <code>Number</code>
* [.offsetWidth](#Element+offsetWidth) : <code>Number</code>
* [.scrollHeight](#Element+scrollHeight) : <code>Number</code>
* [.scrollWidth](#Element+scrollWidth) : <code>Number</code>
* [.clientHeight](#Element+clientHeight) : <code>Number</code>
* [.clientWidth](#Element+clientWidth) : <code>Number</code>
* [.scrollTop](#Element+scrollTop) : <code>Number</code>
* [.scrollLeft](#Element+scrollLeft) : <code>Number</code>

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