@searchfe/sandbox

A lightweight sandbox implementation for the frontend

Stats

StarsIssuesVersionUpdatedCreatedSize
@searchfe/sandbox
1241.5.62 years ago4 years agoMinified + gzip package size for @searchfe/sandbox in KB

Readme

@searchfe/sandbox

Build Status Coverage Status

一个简易的 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 对象实现了该接口。 根元素以下的事件监听不予监听,见: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

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)

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.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

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

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

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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.