@searchfe/sandbox

v1.5.6

Published

2 months ago

A lightweight sandbox implementation for the frontend

Downloads

@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

Members

Interfaces

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

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 元素对象 |