OpenService 加速器开发人员指南

在 Internet Explorer 8 中，加速器是一些可从任何网页快速访问应用程序或 Web 服务的上下文菜单选项。 用户可以 从 Internet Explorer 8 服务库（可能为英文网页）或通过任何发布加速器的网站安装加速器。 利用加速器，可以更轻松地将信息从一个网页复制到另一个网页。 本文介绍如何定义和部署基于 XML 的加速器。

本文包含以下几节：

• 要点
• 简介
• 类别
• 变量
  • URL 模板参数
  • 基于表单的参数
  • 选择类型
  • 文档变量的安全隐患
• 预览
  • 大小
  • 内容
  • 导航
• 本地化
  • 英语示例
  • 西班牙语示例
• 安装
• OpenService 加速器格式
• 相关主题

要点

• 在 Internet Explorer 中，加速器将出现在网页的右键单击快捷菜单上。 这些加速器按功能进行分组，以便用户能够快速访问所需任务。
• 加速器支持两类方案： 用户可以“预览”信息，而无需离开网页，也可以“执行操作”以将内容直接发送到应用程序或 Web 服务。
• 基于 XML 的加速器使用 XML 文件描述对 Web 服务器的 HTTP 请求的格式。 目标的上下文（context，取值为 selection、link 或 document）中的数据将作为变量通过 URL 参数和/或表单数据传递。
• 若需要从网站安装基于 XML 的加速器，请使用 window.external.AddService 方法以提示用户这样做。

简介

利用加速器，您可以对网页中的数据执行操作。 可以选择几行文本，然后通过一次单击操作，将这些文本发送到博客或以电子邮件的形式发送。 利用先前安装的加速器，此操作将通过导航到所需网站（编辑字段中已包含文章的选定部分）来“执行”所需活动。 此外，可以使用“预览”加速器对数据执行操作，而无需转到另一个网站；例如，可以翻译某个单词或在地图上查找某个地址。 将鼠标指针悬停在加速器的上方可查看预览窗口。

图 1： 使用预览加速器在地图中查找某个地址。

加速器是声明性的， 它们使用 HTTP 提交在浏览器和网站之间进行通信。 用户可以轻松创建、测试和部署基于 XML 的加速器。

类别

加速器按功能进行分组，以便用户能够快速访问所需任务。 可以在安装加速器时或通过“管理加载项”对话框设置给定类别的默认加速器。

现在存在的服务示例：

• 添加： del.icio.us、Digg、Reddit
• 博客： Windows Live Spaces、Windows Live Writer、Blogger
• 定义： Encarta、Wikipedia、Dictionary.com
• 地图： Windows Live Map、Google Maps、Yahoo! Maps、MapQuest
• 发送： Windows Live Mail、Gmail、Yahoo! Mail
• 翻译： Windows Live Translation、AltaVista Babel Fish、Google Translation

如果加速器不符合建议的类别，则可以定义自己的加速器。

<os:activity category="Share">  

类别应为一个用户可以识别的谓词，并且未与特定的品牌或应用程序关联，以便类似功能的其他加速器可以使用该类别。 此外，由于“管理加载项”会使用 category 属性的值对加速器进行分组，因此该值应为用户可以读懂的并适当使用大写字母的值。

变量

文档的属性和内容将通过 HTTP GET 和/或 POST 提交发送给加速器服务提供程序。 这些属性将表示为可作为表单字段或 URL 参数传递的替换变量。 可以直接在 os:execute 和 os:preview（称作“URL 模板”）的 action 属性中或在 os:parameter 元素中指定变量。

注意  可以使用 Cookie 来存储状态和用户凭据。

可以使用以下变量：

变量	Context	说明
{documentUrl}	全部†	文档的 href。
{documentTitle}	全部	文档的 title（如果有）。
{documentDomain}	全部	文档的 href 中的有效二级域。
{documentHost}	全部	文档的 href 中的完全限定域。
{selection}	selection	当前选定的文本。
{link}	link	选定链接的 href。
{linkText}	link	选定链接的 innerText。
{linkRel}	link	选定链接的 rel（如果可用）。
{linkType}	link	选定链接的 type（如果可用）。
{linkDomain}	link	链接的 href 中的有效二级域。
{linkHost}	link	链接的 href 中的完全限定域。

† 在文档上下文的外部进行预览时不可用。

请注意有关变量的下列事项：

• 始终将变量名括在大括号 {} 内；例如 {selection}。 若要在请求中指定大括号字符，请使用反斜杠将其转义，如 \{{selection}\}。
• 在变量名后放置一个“?”可指示该变量名是可选的；例如，{documentTitle?}。
• 如果 URL 模板中的任何必需的（非可选的）变量不可用（例如，尝试对不带 rel 属性的链接执行一个加速器，而该加速器的 action 属性中包含 {linkRel}），则加速器无法执行，并且快捷菜单中对应的条目会变灰。
• 如果任何 os:parameter 元素出于任何原因包含一个空值，则该元素将不会出现在请求中。

URL 模板参数

URL 参数可将信息从网页传递到服务。 在 get 请求中，无论您是将参数指定为 os:parameter 元素还是将变量直接添加到 URL 模板，所有参数都将在 URL 上进行传递。

注意  如果指定 os:parameter 元素，则将不会使用 URL 模板中问号 (?) 后面 的 URL 参数。

请确保正确标识 URL 模板中的可选变量。 请注意以下模板：

<os:execute method="get"
    action="http://example.com/service.aspx?url={documentUrl}&title={documentTitle?}" />  

在此示例中，documentUrl 为必需的变量，而 documentTitle 为可选变量。 如果 documentTitle 的值为空，则将为 URL 上的 title 参数使用空字符串。 但如果 documentUrl 的必需值为空，则加速器快捷菜单上的加速器将不可用（变灰）。

基于表单的参数

在 post 请求中，os:parameter 元素指定表单输入的名称/值对。 以下示例将传递与上一个示例中相同的值。

<os:execute method="post" action="http://example.com/service.aspx>
    <os:parameter name="url" value="{documentUrl}" />
    <os:parameter name="title" value="{documentTitle?}" />
</os:execute>  

如果必需的（非可选）的参数未定义，则将忽略此参数。 例如，如果已指定 {selection}，但该参数不可用，则将从请求中删除该参数。

选择类型

可以按两种方式解释选定文本： 解释为纯“文本”（默认情况）或解释为“html”标记。 选定类型是在 os:parameter 元素上设置的。

将按照选定的 HTTP 请求方法的要求对选定文本进行编码。 在 URL 上，执行此操作意味着对非字母数字字符进行百分比编码，并且将换行符作为“CR LF”对 (%0D%0A) 传递。 如果用户选择发送选定部分中的多行文本，则 Web 服务必须能够正确处理“CR LF”。

安全警报  必须对接受 HTML 作为输入的 Web 服务进行正确配置以处理任意 HTML 输入。 允许在不筛选或编码的情况下进行任意输入的 Web 服务容易受到 HTML/脚本注入攻击的影响。

如果创建使用类型为 html 的 {selection} 参数的加速器，请确保将 Web 服务设置为正确解释该加速器。 请注意以下服务，该服务不加分辨地接受 URL 的查询字符串中的文本，并使用 Active Server Pages (ASP) 将该文本直接放置到文本 input 的 value 属性中。

<input name="txtQueryString" size="60" maxlength="65000" value="<%=Request.QueryString("q")%>" /> 

在此情况下，如果该服务从加速器接受 HTML，则传入文本可能提前关闭输入标记，并重新写入网页的各个部分。 更糟糕的是，通过此方式注入的恶意脚本或 SQL 语句可在承载网站的域的上下文中运行。 若要了解有关如何验证输入以保护应用程序不受注入攻击的详细信息，请参阅 如何： 在 ASP.NET 中防止注入攻击(可能为英文网页)。 另请参阅有关使用 innerHTML 进行客户端脚本注入的讨论。

文档变量的安全隐患

由于文档变量可用于在用户不知情的情况下跟踪用户，因此不能在某些上下文中使用这些变量。

• 预览加速器不能使用文档变量（在文档上下文中除外）。
• 禁止在 HTTP 和安全超文本传输协议 (HTTPS) 之间，以及从限制较低的安全区域到限制较高的安全区域（如从 Intranet 区域中的页面到 Internet 上的服务器）传递文档变量。

如果必需的文档变量因任何原因变得不可用，则快捷菜单中的相应加速器条目将灰显。

预览

加速器可以提供可选的 HTML 预览，当用户将鼠标指针悬停在菜单上的加速器上方时将显示该预览。 对于快速获取地图、就地定义或翻译、内容分级或相关内容的链接，预览很有用。

应将预览窗口用于轻型交互。 它可以包含用于向用户发送完整网页以供其获取详细信息的链接。 预览不会阻止用户单击加速器菜单项。

在 OpenService 加速器文件中，预览功能 由 os:preview 元素表示。 当用户将鼠标指针悬停在该菜单项上方时，Internet Explorer 会发送一个 HTTP 请求，并在 HTML 预览窗口中显示生成的 HTML。

大小

预览窗口的大小不得超过 320（宽度）x 240（高度），且分辨率不得超过 96 点/英寸 (dpi)。 该区域外的所有内容将被剪切掉。 建议插入的内容不含带滚动条的控件。 预览功能旨在使用户能够快速查看信息，而无需进行过多地交互。

内容

预览将脚本资源限制为与 加速器的 os:homepageUrl 相同的域。 如果该域的用户已安装 Microsoft ActiveX 控件，则预览也支持这些控件。

导航

用户可以使用链接在预览窗口中进行导航。 若要向用户发送完整网页，请将链接设置为以新窗口打开。 可以通过两种方式来执行此操作：

1. 将 target 属性设置为“_blank”并作为超链接的一部分使用。 当用户调用此超链接时，浏览器会将此超链接作为新选项卡打开。

   <a href="gotosite.html" target="_blank">view full site</A>  

2. 使用 open 方法并将输入 URL 设置为希望用户导航到的网站。

   <FORM>
   <INPUT type="button" value="View Full Site"
   onClick="window.open(gotosite.html')" />
   </FORM>  

本地化

OpenService 加速器文件只能支持单个区域设置。 如果服务支持多个区域设置，则它将需要各个语言版本的单独的 XML 文件。 除了使用针对 os:name 和 os:description 的适合于区域设置的文本外，还必须将 category 属性的值本地化为用户语言。 发布这些加速器的网页应使用请求的 accept-language 标头确定并显示正确的 XML 文件,以供用户安装。

英语示例

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Map with Yahoo!</os:name>
    </os:display>
    <os:activity category="Map">
    ...
</os:openServiceDescription>  

西班牙语示例

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Mapa con Yahoo!</os:name>
    </os:display>
    <os:activity category="Mapa">
    ...
</os:openServiceDescription>  

如果用户已安装多个区域设置的加速器，则将显示每个加速器。

安装

Internet Explorer 8 通过 服务指南(可能为英文网页）网页来安装加速器。 此外，各个网站也可以推广其自己的加速器。

首先，在 Web 服务器上发布 OpenService 加速器 XML 文件。 不允许从本地系统安装加速器 XML 文件；不过，可以出于测试目的使用 Microsoft Internet Information Server (IIS) 本地主机或 Microsoft Visual Studio 的 ASP.NET 服务器。

然后，添加一个“安装加速器”按钮，单击此按钮可调用 AddService。

<button id="myButton"
    onclick="window.external.AddService('http://www.example.com/activity.xml')">
    Add MyMap to the shortcut menu in Internet Explorer 8</button> 

通过调用 IsServiceInstalled，可验证用户当前是否已安装加速器。 若要执行此检查，网页的域必须与 OpenService 加速器文件中指定的 os:homepageUrl 的域匹配。

window.onload = function() {
    if (window.external.IsServiceInstalled('http://www.example.com','map')) {
        document.getElementById('myButton').disabled = true;
    }
}

如果返回值为 0，则表示未安装加速器。

OpenService 加速器格式

此节说明 OpenService 加速器文件格式的元素、属性和值。

示例

以下基于 XML 的加速器描述了浏览器和地图服务之间的交互。

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.example.com</os:homepageUrl>
    <os:display>
        <os:name>Map with MyMap</os:name>
        <os:icon>http://www.example.com/favicon.ico</os:icon>
        <os:description>Map addresses easily with MyMap.</os:description>
    </os:display>
    <os:activity category="Map">
        <os:activityAction context="selection">
            <os:preview action="http://maps.example.com/preview.php?addr={selection}" />
            <os:execute action="http://maps.example.com/" method="get">
                <os:parameter name="addr" value="{selection}" type="text" /> 
            </os:execute>
        </os:activityAction>
    </os:activity>
</os:openServiceDescription> 

os:openServiceDescription

<os:openServiceDescription
    xmlns:os="https://www.microsoft.com/schemas/openservicedescription/1.0">

OpenService 加速器文件的根元素为 os:openServiceDescription。 xmlns 属性是必需属性，并且必须为 https://www.microsoft.com/schemas/openservicedescription/1.0。

os:homepageUrl

<os:homepageUrl>http://maps.example.com</os:homepageUrl>

必需。 os:homepageUrl 元素定义了加速器的主 URL—用户可通过浏览来访问相应的服务。 OpenService 加速器文件中声明的所有 URL 使用的域都必须与 os:homepageUrl 使用的域相同。

os:display

<os:display> 

必需。 os:display 元素描述如何向用户呈现加速器。 此元素包含 os:name 和 os:icon 元素。

os:name

<os:name>Map with MyMap</os:name>

必需。 加速器 的 os:name，此元素在上下文菜单上向用户显示。 加速器名称应以一个谓词开始，并且后跟服务提供程序。 例如，“Map on Windows Live”或“Define with Encarta”。

os:icon

<os:icon>http://www.example.com/favicon.ico</os:icon>

可选。 os:icon 元素提供指向此加速器的 16 x 16 像素图标的 URL。 使用的域名必须与 os:homepageUrl 匹配。

os:description

<os:description>Map addresses easily with MyMap.</os:description> 

可选。 os:description 元素提供一个有关加速器的较长说明，此说明显示在“管理加载项”对话框中。

os:activity

<os:activity category="Map">

必需。 os:activity 元素包含加速器的所有功能。

每个 os:activity 元素都必须指定一个 category 属性，用来描述它提供的功能的类型。 在浏览器的上下文菜单中，加速器将按类别进行排列，以便用户能够快速访问所需的操作类型。 用户可以在安装加速器时或通过使用“管理加载项”对话框选择给定类别的默认加速器。 默认加速器将显示在浏览器的上下文菜单中，而所有其他加速器将在子菜单中列出。 有关详细信息，请参阅类别一节。

os:activityAction

<os:activityAction context="selection">

必需。 每个 os:activityAction 根据加速器的目标指定与服务提供程序进行的交互。 加速器目标由可选的 context 属性指定。 默认值为 selection。

Context	说明
document	当前文档。 始终可用。
selection	默认设置。 选定的文本。 加速器仅在单击选定区域时可用。
link	超链接。 加速器仅对链接可用。

os:preview

<os:preview action="http://maps.example.com/preview.php?addr={selection}" />

可选。 os:preview 元素定义在用户将鼠标指针悬停在加速器上方时显示的 HTML 窗口的内容。 该元素与 os:execute 元素共享相同的属性和子元素。 有关详细信息，请参阅预览一节。

可以在执行命令时替换 action 属性 URL 包含的变量名。 有关详细信息，请参阅变量一节。

os:execute

<os:execute action="http://maps.example.com/" method="get"> 

必需。 os:execute 元素指定在用户调用加速器时触发的主操作。 与 os:preview 元素类似，此元素可以在 action 属性中包含替换变量，也可以用单独的 os:parameter 元素包含替换变量。

为 os:execute 和 os:preview 定义了以下属性：

属性	是否必需？	说明
action	是	用于 HTTP 提交的 URL 模板。
method	否	要使用的 HTTP 方法的类型（get、post）。 默认值为 get。
enctype	否	提交到服务器的内容的类型。 默认值为 application/x-www-form-urlencoded。
accept-charset	否	用于提交的字符集。 默认值为 utf-8。

os:parameter

<os:parameter name="addr" value="{selection}" type="text" /> 

可选。 os:parameter 元素提供用于表示要使用的值的替代方式。 必需的 name 和 value 属性定义了特定于服务的字符串输入，并且通常会引用加速器变量。 有关列表，请参阅变量一节。

可选的 type 属性用于将 {selection} 变量转换为 HTML 或纯文本。 默认值为 text。

相关主题

• 将加速器提供程序添加到 Internet Explorer 8(可能为英文网页)