Using the browser API

This is an archived page. It's not actively maintained.

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.

此 API 仅在 Firefox OS高权限或已认证应用程序上可用。


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

  • 使 iframe 看起来像嵌入内容的顶层浏览器窗口。这就意味着, 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="http://hostname.tld" mozbrowser>

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

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

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

<iframe src="http://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> 了一些强大的功能:

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


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

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:


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.


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:


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


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

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

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


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

button:disabled {
  display: none;


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 () {

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

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

  // In case of error, we also switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowsererror', function (event) {
    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;