Safari 扩展开发指南

由于想做 Stash 扩展的 Safari 版本，所以就了解了一下 Safari 扩展的实现流程。

但网络上的资料普遍较少，故在此将 “Safari Extensions Development Guide” ( Safari 扩展开发指南 ) 逐篇翻译成中文，以便后者参考。

如有偏差，欢迎指出。你的ID会将被加入贡献者列表当中。

---

 关于 Safari 扩展

原文链接：https://developer.apple.com/library/safari/documentation/Tools/Conceptual/SafariExtensionGuide/Introduction/Introduction.html

Safari 扩展提供给你一种新的方式来给 Safari 浏览器增加新特性。你可以为 Safari 工具栏 (toolbar) 添加自定义按钮，创建栏 (bar) ，增加关联菜单项 (contextual menu items) ，在栏 (bar) 或标签 (tabs) 中显示内容，以及为网页注入脚本和样式表。在Safari 5.1和后续的版本中，你甚至可以给工具栏增加菜单 (menus) 和弹出窗口 (popovers)。

你需要通过 HTML、CSS 和 JavaScript 来编写一个 Safari 扩展，同时支持 HTML5 和 CSS3。以及 JavaScript 的扩展接口允许你与普通脚本通常无法做到浏览器和网页内容进行交互。

重要：

要开发 Safari 扩展，你务必在线注册 Safari Developer Program，网址是 http://developer.apple.com。你需要一个已签名的证书，然后你的扩展才可以被安装。

 

Safari 扩展在桌面环境下被 Safari 5.0 和后续的版本所支持 (Mac 和 Windows)。Safari扩展当前不支持 iOS 环境。

速览

Safari 扩展让你为 Safari 添加长期使用的项目－控件 (controls) ，菜单 (menus) 和 关联菜单项 (contextual menu items)，本地或网络内容，以及修改 Safari 所显示内容的脚本。

扩展 (Extension) 和插件 (Plug-in) 的区别是什么？

插件 (Plug-in) 可以为浏览器提供媒体类型的支持。而扩展 (Extension) 则可以添加很多不同的特性。

扩展 (Extension) 和插件 (Plug-in) 都拓展了浏览器的功能。插件 (Plug-in) 让浏览器显示其不原生支持的媒体或者提供特别的媒体播放器体验。扩展 (Extension) 定制和提升对 HTML 网页内容的交互.

插件 (Plug-in) 不能与除显示特定 MIME 类型的媒体之外的网页内容交互。插件 (Plug-in) 不能为 Safari 增加如工具栏按钮 (toolbar buttons) 或关联菜单项 (contextual menu items) 那样的特性。

插件 (Plug-in) 是一个二进制文件和浏览器交互，但它自身本上还是是个应用－浏览器将特定的媒体类型交给插件处理。

扩展 (Extension) 是一组 HTML, JavaScript 和 CSS 文件集给浏览器扩展它的特性设置。扩展允许你重编码网页、屏蔽不想要的站点或资源、在栏或窗口显示 RSS 订阅和其他数据，以及无数种其他插件不能做的事情。

扩展拥有自己的 JavaScript 接口

扩展可以访问特殊的 JavaScript 接口用以接入 Safari 应用和网页内容。这个 API 文档被整理到了这里 Safari Extensions Reference.

相关章节：“扩展概述”

 

扩展在沙盒中运行

Safari 扩展在它们自己的“沙盒”或容器中运行。Safari 扩展在 Safari 应用指定的容器中运行普通的 HTML、CSS 和 JavaScript。这些特定的 JavaScript API 文档被整理到了这里 Safari Extensions Reference.

重要：扩展使用 <object> 或 <embed> 标签运行一个已安装的 Safari 插件是强烈不推荐的，但也不算禁止。任何使用插件作为在 Safari 应用之外运行代码的方法是被禁止的。

 

正确地创建 Safari 扩展

你将使用内嵌在 Safari 5.0 或后续版本中的 Safari 扩展创建器 (Extension Builder) 来创建扩展。打开扩展创建器 (Extension Builder)，让它去创建一个扩展专用的文件夹，将你的 HTML、JavaScript 和 CSS 样式表拖拽到这个文件夹里，填写好扩展创建器 (Extension Builder) 中的字段，然后你就可以开始了。

一个扩展主要包含以下部分：

•全局 HTML 页面 (Global HTML page)－代码只在 Safari 启动或者你的扩展被激活时候加载一次。这是将按钮放在 Safari 工具栏 (toolbar)、扩展菜单 (extension menus)、关联菜单 (contextual menus) 的理想位置。这个页面将不会被显示－只是用于逻辑。

•内容 (Content) (HTML, CSS, JavaScript, media)－HTML 内容和交互控件将会在弹出窗口 (popovers)、扩展栏 (extension bars)、或者标签(tabs) 中作为全页内容显示出来。扩展栏 (extension bars) 和弹出窗口 (popovers) 文件拥有 Safari 应用的权限可以包含菜单 (menus) 或 工具栏 (toolbar items) 的逻辑处理。

•菜单栏 (Menu Items) (标签，图片)－在你定义的扩展菜单 (extension menus) 中出现，或者被增加在 Safari 已有的关联菜单 (contextual menus) 中。

•注入脚本 (Injected scripts)－脚本将被插入到浏览器内容中，这些脚本可用来读取、修改、增加或删除内容。

•注入样式表 (Injected style sheets)－用户样式表可以通过覆盖或增加原本所应用的样式来修改网页内容的显示。

•图标(Icon image)－扩展的图标。

相关章节： “使用扩展创建器”

 

你可以在扩展创建器 (Extension Builder) 中定义用户设置

你的扩展可以有自己的用户设置，用户通过 Safari 偏好设置中的扩展 (Extensions) 面板来访问它。使用扩展创建器 (Extension Builder) ，你能够定义选项、用户界面项、使用的默认值。

同时有一个 API 类似 HTML5 的本地存储自动地访问和修改设置，为了安全你也可以使用加密设置。

相关章节：“设置和本地存储”

 

通过 Safari 的内建工具 Debug 你的扩展

你可以用 Safari 开发者工具 (developer tools) 帮助你 debug 你的扩展。开发者工具可以报告 HTML 错误 、JavaScript、在控制台 (console) log 信息，同时能让你交互地设置断点、获得变量的值、调用函数。Debug 工具支持扩展栏、全局 HTML 页面、注入脚本。每个扩展栏和全局页面都有自己的控制台 (console)。

相关章节：“Debugging 扩展”

 

自动在线更新你的扩展

Safari 提供了一个自动检查更新方法：Update Manifest。你声明一个网络地址，而 Safari 则周期性地对比所安装扩展的版本和站点上的最新版本。如果你的站点有更加新的版本，Safari 会提示用户更新。

相关章节：“升级扩展”

 

先决条件

你应当通晓 HTML、JavaScript 和基本的 CSS。熟悉 with HTML5 and CSS3 是很有帮助的。为了给工具栏增加一个按钮，你应当有创建一个带Alpha通道（半透明）图像的能力。

参见

•Safari Extensions Reference－仅 Safari 扩展可用的 JavaScript 类、方法和属性。

•Safari DOM Additions Reference－Safari 提供给 JavaScript 的类、方法和属性并不在所有浏览器中都被支持。

•Safari Web Inspector Guide－Safari 内建的网页开发工具。

Safari Extensions Conversion Guide－转换为其他浏览器所写扩展的指南。

---

扩展概述

原文链接：https://developer.apple.com/library/safari/documentation/Tools/Conceptual/SafariExtensionGuide/ExtensionsOverview/ExtensionsOverview.html

作为一个开发者，插件是你为 Safari 增加特性的一种方式。

你需要通过 HTML、CSS 和 JavaScript 来编写一个 Safari 扩展，同时支持 HTML5 和 CSS3。以及 JavaScript 的扩展接口允许你与普通脚本通常无法做到浏览器和网页内容进行交互。

Safari 扩展证书

要开发 Safari 扩展，你务必先在线注册 Safari Developer Program，网址是 http://developer.apple.com。你需要加入这个程序并获得证书，然后你的扩展才可以被安装。在 Safari 开发者首页有去 Developer Certificate Utility 的链接。只有你从 Apple 安装了证书以后，你的扩展才能被成功加载。

一个证书支持你所有的扩展。如果所有证书和私钥都从同一台源电脑到另一台新的电脑，则证书在多台电脑上都能起作用。

重要：如果你向另一台电脑移动了证书，你必须从源电脑导出私钥，然后导入私钥到新的钥匙串。私钥和证书必须匹配以生效。

 

当证书快失效时，只需从开发者站点创建和下载一个新的证书。因为这两个新老证书具有相同的开发者账号，你之前做的扩展可以识别出新的证书。在执行新证书之后，旧证书将会被注销。

扩展能做什么

Safari 扩展让你为 Safari 添加长久使用的项目，如控件 (controls) 、菜单 (menus) 、本地或网络内容，以及修改网页内容的脚本。

•你可以为 Safari 工具栏增加按钮。

•你可以为扩展所定义的工具栏插件增加菜单和子菜单。

•你可以自定义工具栏 －扩展栏 (extension bars)。

•你可以为 Safari 的关联菜单 (contextual menus) 增加项目。

•你可以为在扩展栏 (extension bar)、弹出窗口 (popover)、标签 (tab) 中显示 HTML 内容，或者向网页插入内容。

•你可以检测 Safari 文章阅读器 (article reader) 的可用性，自动进入阅读模式并向其中插入脚本和样式表。

•你的插件可以后台运行。

•你可以通过脚本和样式表修改和重编码网页内容。你的脚本和样式表既可以全局使用也可以选择性地使用。使用URL模式的白名单和黑名单来决定哪些网页需要被应用。

•你可以向通知中心 (Notification Center) 发送通知，OS X 的系统级通知系统， 这样你可以通过一个网页来使用 HTML5 通知，扩展就不必向用户请求明确的许可。想要得到更多的信息，请参见 Notification Programming Guide for Websites.

需要看Safari扩展的示例，请访问 Safari Extensions Gallery 网站 (https://extensions.apple.com/).

扩展的构成列表

扩展由一个文件夹开始。取决于你想要哪种类型的扩展，你需向这个文件夹放入以下列表中的一些或全部：

•全局 HTML 页面 (Global HTML page)－一个 HTML 页包含扩展的支持代码，通常为 JavaScript。这个页面不会被显示出来，但是它可以包含能被扩展的其他组件利用的 HTML 元素。全局 HTML 页面只在应用启动或者你的扩展被安装或激活时候加载一次－同时拥有应用 API 的访问权。这是为 Safari 工具栏 (toolbar)、扩展菜单 (extension menus)、关联菜单项 (contextual menu items) 写按钮代码的正确位置。

•内容文件 (Content files)－HTML、CSS 和 JavaScript 内容将被显示在扩展栏 (extension bars)、弹出窗口 (popovers)、全页标签 (full-page tabs) 中或者通过创建 iframe 被插入到网页里。弹出窗口 (popovers) 和扩展栏 (extension bars) 拥有权限去访问 Safari 应用级 API，同时也可以包含工具栏 (toolbar items) 或菜单栏 (menu items) 的代码。
标签的内容文件可以被部署在远程网络服务器上，但还是建议把它们放置到你的扩展包里。弹出窗口 (popovers) 或 扩展栏(extension bars) 的内容文件必须放置在扩展包里。

•注入脚本 (Injected scripts)－JavaScript 文件将被插入到浏览器内容中。这些脚本可用来读取、修改、增加或删除内容，也可以使用 URL 模式选择性地应用在网页中。

•注入样式表 (Injected style sheets)－用户样式表可以通过覆盖或增加原本所应用的样式来修改网页内容的显示。这些样式表也可以被URL模式选择性地应用。

•图标 (Icon)－扩展的图标。它至少是 64×64 像素，且图片的文件名为 Icon.png 。图标会被缩放到需要的大小。你也可以为优化显示提供特定大小的图片。如果你需要为不同尺寸的显示器提供多个图标，则命名 64×64 像素的图标为 Icon-64.png。为了最佳的体验，同时置入一个 Icon-48.png 和 Icon-32.png 的图标用于为小尺寸显示器优化。 另外最好通过置入一个 Icon-96.png 和 Icon-128.png 的图标，在高分辨率显示器上优化你的图标显示。

•其他图片和媒体－扩展需要的任何其他图片或媒体文件，例如在菜单中显示的图片。

扩展的体系结构

你可以想像扩展被分为两个部分：一部分与 Safari 应用交互，另一部分与网页内容交互。

插件与 Safari 应用交互的部分存在于全局HTML页 (global HTML page)、扩展栏(extension bar pages)，或者 弹出窗口页 (popover pages)。而与网页内容交互的部分存在于被插入到内容页的 JavaScript 文件或 CSS 样式表。

这两部分的划分是严格的，但是你可以使用代理在它们之间发送信息。如果全局 HTML 页 (global HTML page) 扩展栏页 (extension bar page) 需要作用于网页内容，可以通过网页代理发送一条消息，注入脚本则会生效。

同样的，如果注入脚本需要使用到全局 HTML 页 (global HTML page) 或 扩展栏 (extension bar) 的代码，可以通过标签代理发送消息。

图 1-1  扩展的体系结构

扩展没有必要包含全部这两部分－一个扩展可以只在 Safari 应用或者只在网页内容上起作用。例如，一个用来关闭窗口或插入标签工具栏按钮将只和应用程序交互，而用来把网站重新编码为黑色文字白色背景的样式表将只会在网页内容中起作用。

Safari 扩展的 JavaScript API

除了通常的 JavaScript 方法，扩展可以使用一个特殊的 JavaScript API，让其访问 Safari 应用和网页内容。全部的 API 被整理归档到了这里 Safari Extensions Reference，但是这个章节涵盖了你需要知道的主要的东西。

类 (Classes) 和属性 (Properties)

Safari 扩展 API 包含了多个类如 SafariBrowserWindow, SafariBrowserTab, and SafariWebPageProxy，分别代表窗体、标签和标签加载的网页。你极少在代码中使用真实的类名。反而扩展的 JavaScript 使用 SafariNamespace 对象－safari，后面有属性链 。例如：

•safari.application.activeBrowserWindow 返回 SafariBrowserWindow 的激活实例。

•safari.application.activeBrowserWindow.activeTab 返回 SafariBrowserTab 的激活实例。

•safari.application.activeBrowserWindow.activeTab.page 返回 SafariWebPageProxy 的激活实例。

通常在JavaScript中，有多种方式去定位一个特定的对象，而属性链有两种方式来操作－例如一个浏览器窗体用 tabs 属性代表它的标签，那么每个标签有一个 browserWindow 属性来代表它的父窗体。

Application 对象和 Extension 对象

SafariApplication 对象允许你操作窗口和标签、响应来自工具栏 (toolbar items) 和关联菜单项 (contextual menu items)－也被称为快捷菜单项 (shortcut menu items) 的命令。例如你可以像这样打开一个新的浏览器窗口：

safari.application.openBrowserWindow();

SafariExtension 对象允许你从扩展中增加和删除按钮 (buttons)、菜单项 (menu items)、脚本 (scripts) 和样式表 (style sheets)。例如，下面的代码片段向你插件注入的内容增加了白底黑字的样式表：

var bw = “body { color:black !important; background:white !important }” ;

safari.extension.addContentStyleSheet(bw);

你可以从插件的全局 HTML 页 (global HTML page)、扩展栏 (extension bar) 或弹出窗口 (popover) 访问 SafariApplication 和 SafariExtension 类。这些类以 safari.application 和 safari.extension 的方式访问。

网页交互内容

被注入网页内容中的脚本有权访问网页的 DOM 树来读取和修改内容。插入脚本使用普通的 JavaScript 接口－getElementsByTagName()、innerHTML 等等－但是由于它们被注入到了网页，它们也有加载和网页内容同域下面脚本的权限。你也可以指定样式表作为插入内容。注入样式表会被当作用户样式表对待，优先级由 W3C 定义。这就意味着如果声明为 important，它们可以覆盖原始网页的样式。例如，为了覆盖 body 元素的背景色，你可以这么声明：

body { background: #ffffff !important }

样式层叠顺序如下：

1.注入样式表的 normal 声明被应用。

2.原始网页的 normal 声明被应用。

3.原始网页的 important 声明被应用。

4.注入样式表的 important 声明被应用，覆盖前面所有的定义（你拥有最后的发言权）。

事件－命令 (Commands)、消息 (Messages) 和代理(Proxies)

通过安装一个事件监听器来对事件进行响应－一个处理指定类型事件的函数。如果你之前正好写过 JavaScript 事件的处理函数，你会知道你可以为事件的目标元素或者其任意父元素在树顶部的窗口上安装一个事件监听器。 这个窗口为网页上的所有元素接收事件。在 Safari 扩展中，依然存在一个更高级别的接收者：应用，接收着所有打开窗口的事件。

JavaScript 程序通常只有一个地方来安放事件处理函数：网页的脚本。在 Safari 扩展中，有多个地方可以安放事件处理函数，例如你的全局 HTML 页面、扩展栏、弹出窗口页或者注入脚本。不同的事件可以在不同的地方进行处理。

在 Safari 扩展的 API 中有很多不同种类的事件，但是你应当马上熟悉这三种基本的事件类型：“commande” 事件、“validate” 事件和 “message” 事件.

命令事件 (command events)

在用户点击扩展的工具栏或选择一个扩展的菜单（包括关联菜单）的时候产生。为”command”事件安装一个监听函数来操控命令。在你的监听函数中，测试你负责函数的命令名，test the command name for commands you are responsible for. 通过调用 addEventListener(“command”, function, capture) 来增加一个监听函数。

下面是一个向应用程序增加 “command” 事件处理函数的例子：

safari.application.addEventListener(“command”, myCmdHandler, false);

验证事件 (Validate events)

被发送给重要的浏览器事件－例如打开一个窗口或者载入一个页面。优先于任何命令事件或菜单显示，这些事件保证了菜单项和命令的有效性。你可以通过禁用工具栏项或菜单项、修改来它们的所做的来响应 “validate” 事件，如果命令被正常执行，也可以什么都不做。

你既可以在全局 HTML 页面（推荐）也可以在扩展栏或弹出窗口响应 “command” 和 “validate” 事件。

消息事件 (Message events)

用于在扩展的组件之前传递消息。使用 dispatchMessage(messageName, data) 来发送消息。通过为 “message” 事件安装一个监听函数来监听消息： addEventListener(“message”, functionName, false)。

消息 API 可以被扩展的所有组件访问－全局 HTML 页面、弹出窗口、扩展栏以及注入脚本。

代理 (Proxies)

被用于支持消息在应用程序和内容间传递。一个代理对象代表了边界两边的一对对象。它们分别是一个 page 代理对象（SafariContentWebPage / SafariWebPageProxy 类）用于向注入脚本发送信息，和一个 tab 代理对象（SafariBrowserTab / SafariContentBrowserTabProxy 类）用于向扩展栏或全局页面发送信息。

如何创建扩展

扩展使用内嵌在 Safari 5.0 和后续版本中的扩展创建器 (Extension Builder) 创建。在 Safari 偏好设置中勾选“在菜单栏中显示开发菜单” (Develop menu in the Advanced pane)。然后在“开发”菜单中选择“显示扩展创建器”。

注意：扩展在 Safari 5.0 版本中被引入并且默认禁用，所以在 Safari 5.0 中你必须在“开发”菜单中启用扩展来显示扩展创建器。

扩展在 Safari 5.0.1 和后续版本中被默认启用。

 

一个扩展由一个扩展包组成－一个已签名的、后缀是 .safariextz 的压缩文件夹，包含了扩展的所有文件和自动生成的 plist 文件用于告诉 Safari 你的扩展是如何组织的以及它的功能是什么。

注意：Safari 扩展包是一个 OS X bundle。你不需要了解 bundles 来创建扩展，但也许会挺有帮助的。要学习与 bundles 和 plist 的更多知识，请参见 Bundle Programming Guide。

 

要创建一个扩展，首先通过点击扩展创建器上的 + 按钮并选择“添加扩展…”来创建一个扩展文件夹。然后创建你需要的 HTML、CSS、JavaScript 和媒体文件并放入这个文件夹。这个文件夹被创建的时候，它会拥有 .safariextension 的后缀。

使用扩展创建器来规定关于扩展结构和行为的细节并创建一个扩展包。点击“创建软件包”来创建一个压缩包－带有.safariextz 后缀名的可安装版本。想要获得更多细节，请参见 “Using Extension Builder.”

这里是更多关于放入扩展文件夹内容的细节描述：

全局 HTML 页面 (Global HTML Page)

你的扩展可以有全局 HTML 页面 (global HTML page)，但这不是必须的。这个页面只在 Safari 第一次启动你的扩展时被加载，但它不会被显示出来。它作为 JavaScript 的一个容器存在。你可以向你的内联全局页面添加 JavaScript，或者在一个或几个单独的文件中将它置入 。

如果你正在向 Safari 主工具栏增加条目，最好写一个全局 HTML 页面来规定这个工具栏是用来干什么的。但是你也可以在扩展栏中规定。想要获得更多细节，请参见 “Adding Buttons to the Main Safari Toolbar.” 工具栏按钮也可以调用扩展菜单或弹出窗口。扩展菜单的逻辑通常包含在全局 HTML 文件中为好。而弹出窗口的逻辑既可以包含在全局 HTML 文件中，也可以包含在弹出窗口自身的文件中。想要获得更多细节，请参见 “Adding Extension Menus” 和 “Adding Popovers.”

如果你要向 Safari 关联菜单增加项目，最好写一个全局 HTML 页面并定义这些菜单项，但同样你也可以在扩展栏或弹出菜单文件中定义关联菜单项和操作。想要获得更多细节，请参见 “Adding Contextual Menu Items.”

将工具栏项、弹出菜单和关联菜单项的代码放在你的全局页面上比放在扩展栏文件中要更加高效。这是因为每打开一个窗口，扩展栏文件就会被重新加载一次，而全局文件只在应用程序的生命周期中只被加载一次。

如果你使用大量的代码或数据插入脚本，那么它们应当被移到全局 HTML 页面中， 这样用户打开一个网页的时间就不会花在每次大量代码或数据的重载中。在全局页面中，注入脚本不能直接调用函数定义，但是注入脚本可以向全局页面传递信息，同时全局页面的消息处理程序可以调用其他函数。想要获得更多细节，请参见 “Messages and Proxies.”

 

扩展栏 (Extension Bar) 文件

扩展栏 (Extension bars) 是一种工具栏－条状尺寸被增加到 Safari 框架中－在书签栏之下在标签栏之上－且应用于特定的扩展。工具栏上可以安装多个扩展，每个扩展也可以有多个工具栏。如果存在有多个扩展栏，则会被堆叠。扩展栏的示例见 图 1-2.

每个扩展栏都在“显示” (View) 菜单中拥有一个标签（显示菜单在Windows中默认隐藏，但是可以通过齿轮按钮来访问）同时这个菜单项可以用来切换每个栏在堆栈中的显示或隐藏。

图 1-2  扩展栏示例

你可以使用扩展栏来增加对 Safari 的控制或用来显示其他内容，例如股票行情、天气预报、航班信息或新闻头条。扩展栏只有 30 像素高，需要更高显示空间的内容应该被展示在弹出窗口自己的标签页内，或者插入到浏览器内容中。

扩展栏文件可以访问 Safari 应用来做类似于 打开和关闭窗口和标签页、加载 URL、响应 Safari 工具栏项目、响应扩展菜单或关联菜单的选择 之类的事情。然而扩展栏文件不能访问内容层来直接在浏览器标签页中操控内容的加载；为了做到它你许阿哟使用注入脚本或样式（参看see “About Safari Extensions”）。扩展栏可以收发来自你注入脚本的消息。

你使用 HTML（包括 CSS、JavaScrip和媒体文件）来创建扩展栏。你无需在 HTML 中做任何特别的事情来让你的内容展示到扩展栏中－只需告诉扩展创建器哪个是扩展栏的源文件。

如果你的扩展栏使用图像或者其他的媒体文件，它们可以被置入扩展包或者在运行的时候从网络中加载。强烈推荐你尽可能地使用本地媒体文件。

扩展栏文件在每次 Safari 打开一个浏览器窗口的时候被加载，同时在每个窗体创建一个扩展栏实例，所以如果你的扩展栏有只需加载一次的代码或数据，最好把这些素材放在一个全局 HTML 页面中。

如果想要创建一个扩展栏，请参见 “Adding Extension Bars.”

弹出窗口 (Popover) 文件

相较于去适应扩展栏的尺寸，如果你的扩展需要更多空间来显示内容，抑或你希望内容只在用户请求的时候出现，你可以创建可以弹出窗口 (popover)－一个在弹出的窗口中显示的 HTML 文件，然后在用户切换焦点的时候自动隐藏（例如点击了另一个窗口）。

弹出窗口文件拥有和扩展栏文件一样的入口和权限，但是它显示在弹出的窗口中而非长期存在的栏。一个弹出窗口在响应用户点击或长按扩展定义的工具栏的情况下被显示。

一个扩展可以拥有多个弹出窗口，但是同一事件只能显示一个。每个弹出窗口是 safari.extension.popovers 数组中的一个元素。如果弹出窗口在扩展创建器中定义过，每个弹出窗口文件会在扩展启动时加载一次。如果一个弹出窗口在运行的时候被创建，则这个定义的弹出窗口那时会被加载。记住无论有多少个窗口被打开，弹出窗口的实例只有一个。

在 Safari 5.1 和后续的版本中，你可以增加弹出窗口并把它们和 Safari 工具栏项关联起来。想要获得更多细节，请参见 “Adding Popovers.”

注入脚本 (Scripts) 和样式表 (Style Sheets)

你可以让 Safari 向加载的网页注入你提供的脚本或样式表。这些注入脚本和样式可以读取和修改浏览器内容。

脚本可以被作为结束脚本（在页面的 onload 事件发生时解析）或启动脚本（在页面被分析前解析）来定义。大多数脚本是结束脚本。在其显示之前阻止不希望的内容，是启动脚本的一般的用法。你可以同时有启动脚本和结束脚本。

样式表作为用户样式表被应用，因此在层级上普通声明先于原始网页的声明，但是 !important 声明在原始网页的声明之后，允许使用用户样式表来覆盖原始网页的样式。

你可以使用 URL 模式来决定你的脚本和样式表应用于哪些网页。为你的扩展创建一个黑名单或白名单来使用 URL 模式。 黑名单包含你不想注入脚本和样式表网页的 URL 模式。白名单包含你想注入脚本和样式网页的 URL 模式。 想要获得更多细节，请参见 “The Extension Builder Interface.”

如果你想向网页插入脚本，请参见 “Injecting Scripts.”

如果你想向网页应用用户样式表，请参见 “Injecting Styles.”

Plist 文件

Info.plist 文件包含扩展的元数据。它包含扩展的显示名称、作者和版本，以及关于插件如何组织的信息－它是否含有全局 HTML 页面、扩展栏或注入脚本，还有哪个文件被用来干什么。如果你的扩展拥有设置选项，它们也被定义在 plist 文件里－Settings.plist. Settings.plist 是可选的，但 Info.plist 是必须的。当某人谈到插件的 plist 文件时，它一般指的是 Info.plist 文件。

Plist 文件是使用扩展创建器创建的，所以你自己不需要做任事情。但是为了理解插件是任何工作的，你需要知道 plist 文件的存在。你在扩展创建器里填写的所有字段都会被储存在 plist 文件里。

安全

因为扩展拥有允许超出普通脚本的权限，当你写扩展的时候必须拥有安全意识。第一级安全保证有证书提供。证书保证了应用来自一个已知来源（你）并且阻止恶意扩展伪装成你的扩展。无论如何，你有职责阻止你的扩展采用恶意代码。遵循下面章节的指导来阻止安全漏洞。

不要使用 innerHTML 或 document.write 导入文本

使用 innerHTML 属性来显示从网络载入的 HTML 看起来很诱人，但是这么做比较危险。使用 document.write 方法向你的扩展导入文本也是同样危险的。 一个恶意网站可能包含类似这样脚本，当你的扩展加载这些 HTML 的时候，扩展的权限会被获得。而且如果你的扩展使用 HTTP（与 HTTPS 相反）来获取这些载入的 HTML，一个伪造的 DNS 服务器，例如一名 Wi-Fi 黑客，可以插入恶意代码来替换这些请求项目。

如果你要显示载入的文本，请使用 innerText 属性将其插入到一个或多个段落元素中，而非 innerHTML属性或者 document.write 方法。

如果你要显示载入的 HTML内容，在插入 HTML 到你的扩展前请移除任何危险的标签对来过滤代码，例如 HTTP 请求的脚本。使用一个允许标签和属性的白名单，移除任何不在白名单中必配的 HTML。然后使用 如 appendChild 这样只插入安全元素的 DOM 方法将HTML插入到你的插件当中。

不要对重要的文本使用 eval

使用 eval 方法解析插入数据允许将数据作为代码运行，进而使恶意代码通过你的扩展来运行。请使用 JSON.parse 方法替代它。

不要使用 HTTP 来增加 HTML、CSS 或脚本

扩展请包含任何直接使用的脚本、HTML 和 CSS，或者使用 HTTPS 请求从一个可信任的源获取。如果你使用 HTTP 导入项目，一个拥有网络权限的人，例如一名 Wi-Fi 黑客，可以插入恶意代码来替换这些请求项目。

无痕浏览 (Private Browsing)

无痕浏览模式 (Private Browsing mode) 阻止 Safari 储存 cookies、浏览的历史记录、缓存和自动填充信息。在无痕浏览模式中，你的扩展将不会储存关于用户动作的任何信息。

在 Safari 6.0 后续的版本中，你可以通过询问 safari.privateBrowsing.enabled 来检测 Safari 是否处于无痕浏览模式，或者通过监听激活或非激活的事件时候含有 SafariPrivateBrowsing 对象。启动事件完成前，无痕浏览不会被激活，这就允许扩展去做一些重要的清理操作。参见 SafariApplication Class Reference 获取更多信息。

原文链接：https://1992s.com/safari-extensions-development-guide-chinese-version.html
发表时间：osted May 9, 2014 by ReSur

文章TAG：safari  扩展  展开  开发  Safari