1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
---
title: 用户界面元素
slug: Mozilla/Add-ons/WebExtensions/用户界面元素
translation_of: Mozilla/Add-ons/WebExtensions/user_interface
translation_of_original: Mozilla/Add-ons/WebExtensions/User_interface_components
---
<div>{{AddonSidebar}}</div>
<p>该主题概括了所有你能用来创建你扩展的用户界面的组件。</p>
<h2 id="浏览器行为">浏览器行为</h2>
<p>浏览器行为是一个你能添加至浏览器工具栏的按钮，用户可以点击该按钮来与你的扩展交互。</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="display: block; height: 387px; margin-left: auto; margin-right: auto; width: 782px;"></p>
<p>有两种方式定义一个浏览器行为: 有一个 <a href="#Popups">弹出菜单</a>, 或者没有弹出菜单。</p>
<p>当你没有定义一个弹出菜单时，用户点击按钮会导致一个消息被分发至扩展，而你可以使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/BrowserAction/onClicked" title="Fired when a browser action icon is clicked. This event will not fire if the browser action has a popup."><code>browserAction.onClicked</code></a> 来监听它:</p>
<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>browserAction<span class="punctuation token">.</span>onClicked<span class="punctuation token">.</span><span class="function token">addListener</span><span class="punctuation token">(</span>handleClick<span class="punctuation token">)</span><span class="punctuation token">;</span></code></pre>
<p>如果你定义了弹出菜单，点击事件就不会被分发取而代之的是弹出菜单会显示出来。用户可以跟弹出菜单交互而当用户点击菜单外的区域时它会自动关闭。</p>
<p>值得注意的是你的扩展只能拥有一个浏览器行为。</p>
<h3 id="定义浏览器行为">定义浏览器行为</h3>
<p>你通过使用在manifest.json 文件中使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 关键字定义浏览器行为的属性 - 图标, 标题, 弹出菜单 :</p>
<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"browser_action":</span> <span class="punctuation token">{</span>
<span class="key token">"default_icon":</span> <span class="punctuation token">{</span>
<span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span>
<span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span>
<span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span><span class="punctuation token">,</span>
<span class="key token">"default_popup":</span> <span class="string token">"popup/geo.html"</span>
<span class="punctuation token">}</span></code></pre>
<p>唯一必要的关键字是 <code>default_icon</code>.你可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API 修改任何属性.</p>
<h3 id="例子">例子</h3>
<p>在GITHUB上的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> 资源包含了以下使用浏览行为的例子:</p>
<ul>
<li><a href="https://github.com/mdn/webextensions-examples/blob/master/bookmark-it/">bookmark-it</a> 使用了没有弹出菜单的浏览器行为</li>
<li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> 使用了由弹出菜单的浏览器行为</li>
</ul>
<h2 id="页面行为">页面行为</h2>
<p>页面行为在很多方面类似于 <a href="#Browser_actions">browser actions</a> , 除了:</p>
<ul>
<li>浏览器行为按钮会一直显现，并且一直可用。</li>
<li>页面行为只会在几个页面并且该页面处于活动标签时显示。</li>
</ul>
<p>为了强调页面行为只跟部分页面有联系，他们将其显示在地址栏内而不是工具栏:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/12960/page-action.png" style="display: block; height: 262px; margin-left: auto; margin-right: auto; width: 850px;"></p>
<p>不像浏览器行为，页面行为默认是关闭的, 调用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/show" title="Shows the page action for a given tab. The page action is shown whenever the given tab is the active tab."><code>pageAction.show()</code></a> 和<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/PageAction/hide" title="Hides the page action for a given tab."><code>pageAction.hide()</code></a> 可以显示或隐藏页面行为。</p>
<h3 id="定义页面行为">定义页面行为</h3>
<p>通过在manifest.json中使用<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code> 关键字来定义页面行为的属性 —— 图标, 标题, 弹出菜单:</p>
<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"page_action":</span> <span class="punctuation token">{</span>
<span class="key token">"browser_style":</span> <span class="keyword token">true</span><span class="punctuation token">,</span>
<span class="key token">"default_icon":</span> <span class="punctuation token">{</span>
<span class="key token">"19":</span> <span class="string token">"button/geo-19.png"</span><span class="punctuation token">,</span>
<span class="key token">"38":</span> <span class="string token">"button/geo-38.png"</span>
<span class="punctuation token">}</span><span class="punctuation token">,</span>
<span class="key token">"default_title":</span> <span class="string token">"Whereami?"</span><span class="punctuation token">,</span>
<span class="key token">"default_popup":</span> <span class="string token">"popup/geo.html"</span>
<span class="punctuation token">}</span></code></pre>
<p><code>default_icon 是唯一强制要求的关键字</code>. 你可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">pageAction</a></code> API 修改所有的属性或现实或隐藏页面行为。</p>
<h3 id="例子_2">例子</h3>
<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a> 例子使用了一个页面行为。</p>
<h2 id="弹出菜单">弹出菜单</h2>
<p>一个弹出菜单是一个绑定至 <a href="#Browser_actions">browser action</a> 或者 <a href="#Page_actions">page action</a> 的对话框。</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="display: block; height: 545px; margin-left: auto; margin-right: auto; width: 700px;"></p>
<p>当用户点击按钮弹出菜单显示，当用户点击弹出菜单外的任何区域弹出菜单关闭。可以使用 <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/close">window.close()</a></code> 来关闭弹出菜单。</p>
<p>你可以使用专门的在manifest.json中使用"_execute_browser_action" 和 "_execute_page_action" 来定义一个快捷键打开浏览器行为或页面行为. 详情请看 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands">commands</a></code> manifest.json 关键字。不过你不能在你的扩展脚本中通过编程打开弹出菜单 : 他只能通过用户的行为的被打开。</p>
<p>弹出菜单像普通网页一样通过HTML文件被定义，你当然也可以在里面包含CSS 和 javascript文件。 而且不像普通网页, 其包含的javascript可以使用所有的已经通过<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a>获取了使用权限的 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> 。</p>
<p>你可以要求浏览器在你的弹出菜单中包含一个样式表以使其看起来与浏览器UI一致。为了达成这一目的，在你的 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code> 或 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a> 关键字中包含<code> "browser_style": true</code> 。</p>
<p>弹出菜单存在一个限制其可以加载资源的源地址的安全机制， 同时不允许类似 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> 的做法的使用 查看 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> 获取更多细节。</p>
<p>你可以使用Add-on Debugger来调试弹出菜单标记和脚本，但是你需要一些技巧来设置让弹出菜单不在自动关闭。<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Debugging#Debugging_popups"> 阅读关于调试弹出菜单</a>。</p>
<h3 id="弹出菜单尺寸重新计算">弹出菜单尺寸重新计算</h3>
<p>弹出菜单自动根据其内容调整尺寸。其适应算法可能因浏览器而不同。</p>
<p>在火狐, 尺寸只再弹出菜单显示前被计算，而且在内容变化后至多进行每秒十次的计算。严格来说， 尺寸受 <code><a href="/en-US/docs/Web/HTML/Element/body"><body></a></code> 元素放置尺寸决定。 一种怪异的说法是, 他由 <code><a href="/en-US/docs/Web/HTML/Element/html"><html></a></code> 决定， Firefox 计算该元素的推荐宽度, 重新调整弹出菜单至其宽度， 然后完成尺寸调整所以这里没有上下滚动。 如果适应用户的屏幕他可能会增长到800X600px的尺寸。 如果用户 <a href="https://support.mozilla.org/en-US/kb/customize-firefox-controls-buttons-and-toolbars#w_customize-the-menu-or-the-toolbar">移动弹出菜单对应按钮到菜单面板</a> ，而后弹出菜单会在菜单栏内显示并具有合适的尺寸。</p>
<h2 id="设置页面">设置页面</h2>
<p>设置页面允许你定义你的扩展可以被用户修改的选项。 用户从浏览器扩展管理器中访问设置页面:</p>
<p>{{EmbedYouTube("02oXAcbUv-s")}}</p>
<p>每个浏览器访问该页面的方法存在区别。</p>
<ul>
</ul>
<p>你可以通过调用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Runtime/openOptionsPage" title="If your add-on does not have an options page, or the browser failed to create one for some other reason, runtime.lastError will be set."><code>runtime.openOptionsPage()</code></a> 打开设置页面</p>
<p>设置页面存在一个限制其可以加载资源的源地址的安全机制， 同时不允许类似 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code> 的做法的使用 查看 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">Content Security Policy</a> 获取更多细节。</p>
<h3 id="定义一个设置页面：">定义一个设置页面：</h3>
<p>创建一个设置页面有以下流程：</p>
<ul>
<li>写一个HTML文件定义页面。该文件像普通网页一样可以包含CSS和Javascript 文件而且可以使用所有 <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API">WebExtension APIs</a> ，特别的你可以使用 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Storage" title="Enables WebExtensions to store and retrieve data, and listen for changes to stored items."><code>storage</code></a> API 来保存设置。</li>
<li>将这些文件打包至你的扩展。</li>
<li>在manifest.json 文件包含 <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code> 关键字， 并给予设置页面的URL。</li>
</ul>
<h3 id="例子_3">例子</h3>
<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/favourite-colour">favourite-colour</a> 使用了设置页面。</p>
<h2 id="上下文菜单项">上下文菜单项</h2>
<p>使用 {{WebExtAPIRef("contextMenus")}} API, 你可以按你指定的情况向浏览器上下文菜单添加项目, 比如，你可以只在用户点击图片时显示一项，或者在一个可编辑的元素上，或者被选择的页面的一部份。</p>
<h3 id="指定一个上下文菜单项">指定一个上下文菜单项</h3>
<p>您可以使用{{WebExtAPIRef("contextMenus")}} API来 程序化地管理上下文菜单项。</p>
<h3 id="例子_4">例子</h3>
<p> <a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-demo">context-menu-demo</a> 创建了几种不同的上下文菜单项。</p>
<h2 id="通知">通知</h2>
<p>使用 {{WebExtAPIRef("notifications")}} API，你通过使用操作系统的通知系统可以创建短时通知:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="display: block; height: 334px; margin-left: auto; margin-right: auto; width: 700px;"></p>
<h3 id="定义一个通知">定义一个通知</h3>
<p>使用{{WebExtAPIRef("notifications")}} API 可以程序化地管理通知。</p>
<h3 id="Examples">Examples</h3>
<p><a href="https://github.com/mdn/webextensions-examples/tree/master/notify-link-clicks-i18n">notify-link-clicks-i18n</a> 创建了通知。</p>
|
