Installing_Extensions_and_Themes_From_Web_Pages(从网页安装扩展和主题)

There are a variety of ways you can install extensions and themes from web pages, including direct linking to the XPI files and using the InstallTrigger object.（译：要通过网页来安装扩展和主题，有多种方法可供选择，包括直接链接到XPI文件和使用InstallTrigger对象。）

Extension and web authors are encouraged to use the method described below to install XPIs, as it provides the best experience to users.（译：鼓励扩展和网页的开发者使用如下描述的方法来安装XPI文件，这将会给使用者最好的体验。）

Web Script Example

<script type="application/x-javascript">
<!--
function install (aEvent)
{
  var params = {
    "Foo": { URL: aEvent.target.href,
             IconURL: aEvent.target.getAttribute("iconURL"),
             Hash: aEvent.target.getAttribute("hash"),
             toString: function () { return this.URL; }
    }
  };
  InstallTrigger.install(params);

  return false;
}
-->
</script>

<a href="https://www.example.com/foo.xpi"
  iconURL="https://www.example.com/foo.png"
  hash="sha1:28857e60d043447c5f4550853f2d40770b326a13"
  onclick="return install(event);">Install Extension!</a>

Let's go through this piece by piece. The HTML <a> is the install link. The href attribute contains a direct link to the extension XPI file, this is what will show in the location bar when the link is moused over. Users can save the XPI file to disk easily by right clicking on the link and choosing "Save Link As..."[译：让我们一点一点地看这些代码。HTML标签<a>是用来安装的链接。href属性包含了一个到扩展XPI文件的连接，当鼠标经过时这个连接就会在地址栏中显示出来。使用者可以简单地通过点击右键选“另存为...”来保存该XPI文件到本地磁盘。]

When the link is clicked it calls the function install passing the event object as the parameter.[译：当这个链接被点击时，install函数会被调用，并传递一个事件对象作为参数。]

The install first creates a parameter block:[译：安装过程首先会创建一个如下的参数块：]

var params = {
  "Foo": { URL: aEvent.target.href,
           IconURL: aEvent.target.getAttribute("iconURL"),
           Hash: aEvent.target.getAttribute("hash"),
           toString: function () { return this.URL; }
};

This specifies the display name (Foo) for use in the confirmation dialog, the URL to the extension (which is the link href, recall), the Icon URL to display in the confirmation dialog, a hash of the xpi file contents (to protect against corrupted downloads), and a toString function which will allow this code to work with versions of Firefox 0.8 and earlier. You could also use the old style parameter block ({ "Foo": aEvent.target.href }) if you wanted - and didn't have an Icon to use for the confirmation dialog.[译：它指定了在确认对话框上的显示名字(Foo),到扩展的URL(连接的href属性)，显示在确认对话框上的图标的URL，xpi文件的hash值(防止下载过程中的错误)，和一个用来让该能在Firefox0.8及以前版本上工作的toString函数。如果愿意的话，你可以使用旧的编码风格来写这个参数块({ "Foo": aEvent.target.href }),你也可以不指定显示在确认对话框上的图标。]

InstallTrigger.install is then called to install the item with the parameter block.　[译：接下来InstallTrigger.install会被调用，它使用刚才的参数块来安装项目。]

return false;

This last part is the most important - the install function must return false so that when the link is clicked, only the script is run, and the link href is not navigated to. If you omit this step, the user may see two installation dialogs—since you've effectively invoked two install requests, one from the InstallTrigger, one from trying to load the XPI file directly.[译：最后一部分是最重要的，install函数必须返回false，这样当链接被点击时只有脚本被运行了，而并未导航到连接的地址。如果你忽略该步，使用者将看到两个安装对话框--因为你成功的调用了两次安装请求，一次来自于InstallTrigger，另一次来自于直接下载XPI文件。]

Available Parameters for the install object(install对象可使用的参数)

The InstallTrigger.install method accepts a JavaScript object as a parameter, with several properties on that object used to affect the install.[译：InstallTrigger.install 方法接收一个JavaScript对象作为参数，该参数对象中有一些属性来影响安装。]

URL

The URL property specifies the URL of the XPI to install. This property is required.[URL属性指定了将被安装的XPI文件的URL.该属性是必须的。]

IconURL

The IconURL property specifies an icon to be displayed in the installation dialog. This property is optional. If you do not specify an icon, the default icon will be used, usually a green puzzle piece. The icon can be any image format supported by Firefox, and should be 32x32 pixels in size.[译：IconURL属性指定一个显示在安装对话框上的图标。如果不指定图标，一个默认的图标就会被使用，通常是一个绿色的拼图块。图标可以是任意被Firefox支持的格式，但大小应是32x32像素的。]

Hash

The Hash property specifies a cryptographic hash of the XPI file contents. This is used to verify the downloaded file, to protect against a corrupted file being served by a mirror download server, for example. You can use any hash function supported by nsICryptoHash. The hash is specified as hash function:hash value, for example, sha1:28857e60d043447c5f4550853f2d40770b326a13.[译：Hash属性用于指定XPI文件内容的加密hash值。这被用来验证下载文件，例如，可以防止一个错误的XPI文件被放在镜像服务器上被下载。可以使用被nsICryptoHash支持的hash函数。该hash值的格式为　hash函数：hash值，例如：sha1:28857e60d043447c5f4550853f2d40770b326a13。]

toString()

The toString() property should return the XPI URL, for compatibility with Firefox browsers older than version 1.0, and other applications such as Seamonkey.[译：toString()属性应当返回XPI 的URL，主要是为了兼容早于1.0版本的浏览器和其它程序如Seamonkey。]

Themes

Pretty much everything I've described applies to themes too, except you'll use the installChrome function. Because so many sites installed extensions by direct-linking the XPI file and relying on content handling to invoke the confirmation UI, many sites are (incorrectly) doing so for theme JAR files too and wondering why they aren't auto-detected and installed. Well, XPI is a Mozilla-specific extension and so we can have special handling for it, but JAR is not - not all .jar files are Firefox themes, so if you click on a .jar link you'll be shown the Save As decision dialog. For this reason you should always use the InstallTrigger API to install themes.

A Note on updateEnabled()

InstallTrigger exposes a function called updateEnabled that some of you may be calling before you call InstallTrigger.install. This is not necessary as install calls updateEnabled itself internally. Furthermore, calling updateEnabled may lead to problems if your distribution site is not in the user's whitelist, because Firefox only displays the "Installation Blocked" message when install or installChrome are called, or when a XPI file is loaded. So, if you have code that looks like this:

if (InstallTrigger.updateEnabled())
  InstallTrigger.install({"Foo": "foo.xpi"});

... and your site is not in the whitelist, when the user invokes that code, updateEnabled will return false because your site isn't whitelisted, and since it was updateEnabled that discovered this, not a call to install, there will be no notification to the user.

Thus you should only use updateEnabled to display content in the page to alert the user that software installation is disabled, or your site is not in the whitelist—do not place it in the install code path.

(* by all means don't let this stop you from developing more ambitious install systems, I am providing this documentation only as a guide that I hope most extension distributors will use since it handles most cases well)