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

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:

示例

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;
  });
});

参考

文档标签和贡献者

 此页面的贡献者: ReyCG_sub
 最后编辑者: ReyCG_sub,