Using the browser API

非标准
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

This API is available on Firefox OS for privileged or certified applications only.

概述

HTML Browser API 是对 HTML <iframe> 元素的扩展，允许 web app 用来实现浏览器或浏览器类似的应用。主要涉及到两个方面：

使 iframe 看起来像嵌入内容的顶层浏览器窗口。这就意味着 window.top, window.parent, window.frameElement, 等不应该反映 frame 的继承关系。Optionally, the notion that the embedded is an Open Web App can be expressed as well.
用来操作和监听嵌入内容状态的变化的 API。

除此之外，也可以表示成嵌入的内容就是一个 Open Web App。在那种情况下，页面内容就会在适当的 app 上下文（如权限）中被装载。

用法

<iframe> 可以通过设置 mozbrowser 属性而转化为浏览器框架

<iframe src="https://hostname.tld" mozbrowser>

要想嵌入一个 Open Web App, 必须要提供 mozapp 以及 app manifest 路径。

<iframe src="https://hostname.tld" mozapp='https://path/to/manifest.webapp' mozbrowser>

最后， <iframe> 的内容可以在它单独的子进程中装载，通过使用remote 属性可以单独嵌入到此页面的框架中。

<iframe src="https://hostname.tld" mozbrowser remote>

警告: That last attribute is necessary for security reasons if you plan to load content from an untrusted/unknown origin. If you don't use it, you take the risk of your application being compromised by a malicious web site.

权限

想要嵌入到 browser frame 中的任何应用必须要在其中的 app manifest 拥有 browser 权限。

{
  "permissions": {
    "browser": {}
  }
}

此外，要嵌入一个 Open Web App, app 必须具有 embed-apps 权限。

{
  "permissions": {
    "browser": {},
    "embed-apps": {}
  }
}

额外方法

Firefox OS 扩展了 HTMLIFrameElement DOM 接口以支持 browser <iframe> 所产生的需求。这些新的方法赋予 <iframe> 了一些强大的功能：

Navigation 方法

这些方法能够使 <iframe> 根据历史记录进行导航。此处也有必要来实现 back, forward, stop, and reload 按钮。

reload(): 重载 <iframe>.
stop(): 停止装载<iframe>'s content.
getCanGoBack(): 判断是否可以回到前一页面.
goBack():回到<iframe>历史记录的前一个位置
getCanGoForward(): 得知是否可以到达历史记录的后一个页面。
goForward(): Changes the location of the <iframe> for the next location in its browsing history.

性能方法

Those methods are used to manage the resources used by a browser <iframe>. This is especially useful for implementing tabbed browser application.

setVisible(): Changes the visibility state of a browser <iframe>. This can influence resources allocation and some function usage such as requestAnimationFrame.
getVisible(): Allows knowing the current visibility state of the browser <iframe>.
purgeHistory(): Allows clearing all the resources (cookies, localStorage, cache, etc.) associated with the browser <iframe>.

Event 方法

In order to manage the browser <iframe>'s content, many new events were added (see below). The following methods are used to deal with those events:

The <iframe> gains support for the methods of the EventTarget interface: addEventListener(), removeEventListener(), and dispatchEvent().
sendMouseEvent(): Allows sending a MouseEvent to the <iframe>'s content.
sendTouchEvent(): Allows sending a TouchEvent to the <iframe>'s content. Note that this method is available for touch enabled devices only.
addNextPaintListener(): Allows defining a handler to listen for the next MozAfterPaint event in the browser <iframe>.
removeNextPaintListener(): Allows removing a handler previously set with addNextPaintListener().

其他方法

Those methods are utilities, useful for apps that host a browser <iframe>.

getScreenshot(): Allows taking a screenshot of the browser <iframe>'s content. This is particularly useful to get thumbnails of tabs in a tabbed browser app.

Events

In order to allow an application to manage the browser <iframe>, the application can listen for new events about what's happening within the browser <iframe>. The following new events can be listened for:

mozbrowserasyncscroll: Sent when the scroll position within a browser <iframe> changes.
mozbrowserclose: Sent when window.close() is called within a browser <iframe>.
mozbrowsercontextmenu: Sent when a browser <iframe> tries to open a context menu. This allows handling <menuitem> element available within the browser <iframe>'s content.
mozbrowsererror: Sent when an error occurred while trying to load content within a browser <iframe>.
mozbrowsericonchange: Sent when the favicon of a browser <iframe> changes.
mozbrowserloadend: Sent when the browser <iframe> has finished loading all its assets.
mozbrowserloadstart: Sent when the browser <iframe> starts to load a new page.
mozbrowserlocationchange: Sent when a browser <iframe>'s location changes.
mozbrowseropenwindow: Sent when window.open() is called within a browser <iframe>.
mozbrowsersecuritychange: Sent when the SSL state changes within a browser <iframe>.
mozbrowsershowmodalprompt: Sent when alert(), confirm(), or prompt() is called within a browser <iframe>.
mozbrowsertitlechange: Sent when the document.title changes within a browser <iframe>.
mozbrowserusernameandpasswordrequired: Sent when an HTTP authentification is requested.
mozbrowseropensearch: Sent when a link to a search engine is found.

示例

In this example we'll see how to implement a very basic browser app.

HTML

In the HTML we just add a URL bar, a "Go" and "Stop" button, and a browser <iframe>.

<header>
  <input id="url">
  <button id="go">Go</button>
  <button id="stop">Stop</button>
</header>

<iframe src="about:blank" mozbrowser remote></iframe>

CSS

We switch between the go and stop button with a little css trick.

button:disabled {
  display: none;
}

JavaScript

Now we can add the required functionalities:

document.addEventListener("DOMContentLoaded", function () {
  var url  = document.getElementById("url");
  var go   = document.getElementById("go");
  var stop = document.getElementById("stop");

  var browser = document.getElementsByTagName("iframe")[0];

  // This function is used to switch the Go and Stop button
  // If the browser is loading content, "Go" is disabled and "Stop" is enabled
  // Otherwise, "Go" is enabled and "Stop" is disabled
  function uiLoading(isLoading) {
      go.disabled =  isLoading;
    stop.disabled = !isLoading;
  }

  go.addEventListener("touchend", function () {
    browser.setAttribute("src", url.value);
  });

  stop.addEventListener("touchend", function () {
    browser.stop();
  });

  // When the browser starts loading content, we switch the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadstart', function () {
    uiLoading(true);
  });

  // When the browser finishes loading content, we switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadend', function () {
    uiLoading(false);
  });

  // In case of error, we also switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowsererror', function (event) {
    uiLoading(false);
    alert("Loading error: " + event.detail);
  });

  // When a user follows a link, we make sure the new location is displayed in the address bar
  browser.addEventListener('mozbrowserlocationchange', function (event) {
    url.value = event.detail;
  });
});