@searchfe/sandbox
一个简易的 Sandbox,用来隔离不同的页面组件,使它们的执行互不干扰。使用 APM 安装:
apmjs install @searchfe/sandbox
其中 Fetch API 可能需要适当的 Polyfill:
Classes
- Sandbox
-
沙盒实例 创建后默认处于睡眠状态。需要调用
sandbox.run()
让它开始工作。 - Window
-
沙盒上下文 提供给沙盒内的业务逻辑使用,相当于浏览器的 window。
- Document
-
沙盒文档 局部的 DOM 文档对象,托管了所有事件,页面属性等。
- Element
-
元素对象 这是 HTMLElement 的一个沙盒代理对象,封装并托管了 DOM 操作。
Members
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)
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
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)
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
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
sandbox.spawn(child, [context]) ⇒ 生成一个子沙盒对象,子沙盒会跟随父沙盒的生命周期。子沙盒会继承当前沙盒的状态,即: 如果当前沙盒处于 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 |
绑定到的沙盒对象 |
Document
window.document : 沙盒的文档对象
Kind: instance property of Window
window.location
Location 对象的封装
Kind: instance property of Window
Number
window.pageXOffset : Kind: instance property of Window
Read only: true
Number
window.pageYOffset : Kind: instance property of Window
Read only: true
Number
window.innerHeight : Kind: instance property of Window
Read only: true
Number
window.outerHeight : Kind: instance property of Window
Read only: true
Number
window.innerWidth : Kind: instance property of Window
Read only: true
Number
window.outerWidth : 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 |
对应的沙盒对象 |
function
document.querySelector : 封装 querySelector
Kind: instance property of Document
Read only: true
function
document.querySelectorAll : 封装 querySelectorAll,限制:返回值类型为 Array 而非 NodeList,这意味着返回列表不是 Live 的。
Kind: instance property of Document
Read only: true
Sandbox
document.sandbox : 与当前文档绑定的沙盒对象
Kind: instance property of Document
HTMLElement
document.documentElement : Kind: instance property of Document
Read only: true
Element
document.scrollingElement : Kind: instance property of Document
Read only: true
Element
document.cookie : Kind: instance property of Document
Read only: true
Element
document.createElement : 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 元素对象 |
Document
element.scrollTo : Kind: instance property of Element
Number
element.offsetTop : Kind: instance property of Element
Read only: true
Number
element.offsetLeft : Kind: instance property of Element
Read only: true
Number
element.offsetHeight : Kind: instance property of Element
Read only: true
Number
element.offsetWidth : Kind: instance property of Element
Read only: true
Number
element.scrollHeight : Kind: instance property of Element
Read only: true
Number
element.scrollWidth : Kind: instance property of Element
Read only: true
Number
element.clientHeight : Kind: instance property of Element
Read only: true
Number
element.clientWidth : Kind: instance property of Element
Read only: true
Number
element.scrollTop : Kind: instance property of Element
Number
element.scrollLeft : Kind: instance property of Element
scrollTo
滚动窗口,见 https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo
Kind: global variable