diff options
Diffstat (limited to 'files/zh-cn/mozilla/add-ons/webextensions/user_interface')
7 files changed, 863 insertions, 0 deletions
diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html new file mode 100644 index 0000000000..1ec5a5aced --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_action/index.html @@ -0,0 +1,50 @@ +--- +title: Toolbar button +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +<div>{{AddonSidebar}}</div> + +<p>常说的 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">浏览器动作（browser action）</a>, 指通过在工具栏上上添加新按钮，提供用户互动选项，用户可点击按钮与你的扩展进行互动。<br> + <img alt="" src="https://mdn.mozillademos.org/files/15751/browser-action.png" style="display: block; height: 182px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<p>工具栏按钮（browser action）与地址栏按钮（page action）极为相似。区分其不同点及使用，请参看 <a href="/en-US/Add-ons/WebExtensions/user_interface/Page_actions#Page_actions_and_browser_actions">Page actions and browser actions</a>.</p> + +<h2 id="指定浏览器动作">指定浏览器动作</h2> + +<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></code></pre> + +<p>必须定义的键是 <code>default_icon</code>.</p> + +<p>有两种方法来指定浏览器动作：带弹出框（<a href="/en-US/Add-ons/WebExtensions/Popups">popup</a>）和不带弹出框（<a href="/en-US/Add-ons/WebExtensions/Popups">popup</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>如果指定了弹出框，当用户点击按钮时，点击事件将不会被发送，而是显示出弹出框。用户能够通过弹出框进行互动，并且点击框外区域时弹出框会自动关闭。请参看文章 <a href="/en-US/Add-ons/WebExtensions/Popups">Popup </a>来了解更多关于创建和管理弹出框的细节。</p> + +<p>注意一个扩展只能指定一个浏览器动作。</p> + +<p>可通过<code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/browserAction">browserAction</a></code> API在程序里更改你的浏览器动作的属性。</p> + +<h2 id="图标">图标</h2> + +<p>想了解更多关于如何创建浏览器动作图标信息，请参看<a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> 文档里的 <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> 部分.</p> + +<h2 id="范例">范例</h2> + +<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> uses a browser action without a popup.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/beastify">beastify</a> uses a browser action with a popup.</li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html new file mode 100644 index 0000000000..e0647bc543 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/browser_styles/index.html @@ -0,0 +1,466 @@ +--- +title: Browser styles +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +tags: + - Browser style + - WebExtensions + - 扩展程序 + - 指南 + - 浏览器扩展程序 + - 浏览器插件 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_styles +--- +<div>{{AddonSidebar}}</div> + +<p>扩展程序包含的某些UI组件，例如： <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">popups</a>, <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">sidebars</a>, <a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Options_pages">options pages</a> ，实际上可以用如下方式统一定义：</p> + +<ol> + <li>创建一个HTML文件用于描述该UI组件的页面结构</li> + <li>在manifest.json中添加字段 (<code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action">browser_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/page_action">page_action</a></code>, <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code>, 或 <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_ui">options_ui</a></code>) 以指向其对应的页面</li> +</ol> + +<p>这种方式面临的一个挑战是如何使用浏览器自带的样式，以使得组件的UI表现与浏览器的UI风格相符。要解决这个问题，可以在该字段的配置中增加一个可字段 <code>browser_sytle</code> ，如果设置了这个字段并且值为 <code>true</code> , 那么该UI组件的HTML将会被插入一个或多个样式表，样式表会使你的扩展程序的UI表现与浏览器的风格一致 (并且与其它同样应用了这个字段的扩展程序一致)。</p> + +<p>若使用了 <code>browser_style: true</code> , 你需要在不同的浏览器主题中测试你的扩展程序，以确保其UI表现和期望的一致。 </p> + +<div class="blockIndicator note"> +<p><strong>谷歌浏览器Google Chrome</strong> 和 欧朋浏览器 <strong>Opera</strong> 使用字段名 <code>chrome_style</code> 而非<code>browser_style</code>, 因此如果要适配它们，你需要同时添加这两个字段。</p> +</div> + +<p>在火狐浏览器中，这个样式文件可以在 <code>chrome://browser/content/extension.css</code>查看。为Mac OS X系统额外准备的样式文件也可以在 <code>chrome://browser/content/extension-mac.css</code> 查看。</p> + +<p>大多数样式是自动应用的，但是某些元素需要添加非标准的类名 <code style="white-space: nowrap;">browser-style</code> 来获得其样式，如下表所示：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Element</th> + <th scope="col">Example</th> + </tr> + </thead> + <tbody> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/button"><button></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<button class="browser-style">Click me</button></pre> + </td> + </tr> + <tr> + <td> + <p><code><a href="/en-US/docs/Web/HTML/Element/select"><select></a></code></p> + </td> + <td> + <pre class="brush: html no-line-numbers"> +<select class="browser-style" name="select"> + <option value="value1">Value 1</option> + <option value="value2" selected>Value 2</option> + <option value="value3">Value 3</option> +</select></pre> + </td> + </tr> + <tr> + <td><code><a href="/en-US/docs/Web/HTML/Element/textarea"><textarea></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<textarea class="browser-style">Write here</textarea></pre> + </td> + </tr> + <tr> + <td>Parent of an <code><a href="/en-US/docs/Web/HTML/Element/input"><input></a></code></td> + <td> + <pre class="brush: html no-line-numbers"> +<div class="browser-style"> + <input type="radio" id="op1" name="choices" value="op1"/> + <label for="op1">Option 1</label> + + <input type="radio" id="op2" name="choices" value="op2"/> + <label for="op2">Option 2</label> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<div class="blockIndicator note"> +<p>查看 {{bug(1465256)}} 以了解相关修订</p> +</div> + +<h2 id="浏览器兼容性">浏览器兼容性</h2> + +<div class="hidden">兼容列表由结构化文件生成，如果你想要贡献此文件，请通过 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 向我们发送pull request.</div> + +<p>{{Compat("webextensions.browser_style")}}</p> + +<h2 id="火狐面板组件Firefox_Panel_Components">火狐面板组件Firefox Panel Components</h2> + +<div class="blockIndicator nonStandard"> +<p><strong>非标准</strong><br> + 此功能不是通用标准，仅支持在firefox中使用</p> +</div> + +<p><code>chrome://browser/content/extension.css</code> 样式文件中也包含了火狐面板组件的样式</p> + +<p><a href="https://firefoxux.github.io/StyleGuide/#/navigation">legacy Firefox Style Guide</a> 使用示例</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="col">Element</th> + <th scope="col">Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>Header</td> + <td> + <pre class="brush: html"> +<header class="panel-section panel-section-header"> + <div class="icon-section-header"><img src="image.svg"/></div> + <div class="text-section-header">Header</div> +</header></pre> + </td> + </tr> + <tr> + <td>Footer</td> + <td> + <pre class="brush: html"> +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + </td> + </tr> + <tr> + <td>Tabs</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-tabs"> + <button class="panel-section-tabs-button selected">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> + <div class="panel-section-tabs-separator"></div> + <button class="panel-section-tabs-button">Tab</button> +</div></pre> + </td> + </tr> + <tr> + <td>Form</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-formElements"> + <div class="panel-formElements-item"> + <label for="name01">Label:</label> + <input type="text" value="Name" id="name01" /> + </div> + <div class="panel-formElements-item"> + <label for="picker01">Label:</label> + <select id="picker01"> + <option value="value1" selected="true">Dropdown</option> + <option value="value2">List Item</option> + <option value="value3">List Item</option> + </select> + </div> + <div class="panel-formElements-item"> + <label for="placeholder01">Label:</label> + <input type="text" placeholder="Placeholder" id="placeholder01" /> + <button name="expander" class="expander"></button> + </div> +</div></pre> + </td> + </tr> + <tr> + <td>Menu</td> + <td> + <pre class="brush: html"> +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div></pre> + </td> + </tr> + </tbody> +</table> + +<h3 id="Example">Example</h3> + +<h4 id="HTML">HTML</h4> + +<pre class="brush: html"><header class="panel-section panel-section-header"> + <div class="icon-section-header"><!-- An image goes here. --></div> + <div class="text-section-header">Header</div> +</header> + +<div class="panel-section panel-section-list"> + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut">Ctrl-L</div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item disabled"> + <div class="icon"></div> + <div class="text">Disabled List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-section-separator"></div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> + + <div class="panel-list-item"> + <div class="icon"></div> + <div class="text">List Item</div> + <div class="text-shortcut"></div> + </div> +</div> + +<footer class="panel-section panel-section-footer"> + <button class="panel-section-footer-button">Cancel</button> + <div class="panel-section-footer-separator"></div> + <button class="panel-section-footer-button default">Confirm</button> +</footer></pre> + +<div class="hidden"> +<h4 id="CSS">CSS</h4> + +<pre class="brush: css">/* Global */ +html, +body { + background: white; + box-sizing: border-box; + color: #222426; + cursor: default; + display: flex; + flex-direction: column; + font: caption; + margin: 0; + padding: 0; + -moz-user-select: none; +} + +body * { + box-sizing: border-box; + text-align: start; +} + +button.panel-section-footer-button, +button.panel-section-tabs-button { + color: inherit; + background-color: unset; + font: inherit; + text-shadow: inherit; + -webkit-appearance: none; + -moz-appearance: none; + appearance: none; + border: none; +} + +/* Panel Section */ +.panel-section { + display: flex; + flex-direction: row; +} + +.panel-section-separator { + background-color: rgba(0, 0, 0, 0.15); + min-height: 1px; +} + +/* Panel Section - Header */ +.panel-section-header { + border-bottom: 1px solid rgba(0, 0, 0, 0.15); + padding: 16px; +} + +.panel-section-header > .icon-section-header { + background-position: center center; + background-repeat: no-repeat; + height: 32px; + margin-right: 16px; + position: relative; + width: 32px; +} + +.panel-section-header > .text-section-header { + align-self: center; + font-size: 1.385em; + font-weight: lighter; +} + +/* Panel Section - List */ +.panel-section-list { + flex-direction: column; + padding: 4px 0; +} + +.panel-list-item { + align-items: center; + display: flex; + flex-direction: row; + height: 24px; + padding: 0 16px; +} + +.panel-list-item:not(.disabled):hover { + background-color: rgba(0, 0, 0, 0.06); + border-bottom: 1px solid rgba(0, 0, 0, 0.1); + border-top: 1px solid rgba(0, 0, 0, 0.1); +} + +.panel-list-item:not(.disabled):hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-list-item.disabled { + color: #999; +} + +.panel-list-item > .icon { + flex-grow: 0; + flex-shrink: 0; +} + +.panel-list-item > .text { + flex-grow: 10; +} + +.panel-list-item > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; + justify-content: flex-end; +} + +.panel-section-list .panel-section-separator { + margin: 4px 0; +} + +/* Panel Section - Footer */ +.panel-section-footer { + background-color: rgba(0, 0, 0, 0.06); + border-top: 1px solid rgba(0, 0, 0, 0.15); + color: #1a1a1a; + display: flex; + flex-direction: row; + height: 41px; + margin-top: -1px; + padding: 0; +} + +.panel-section-footer-button { + flex: 1 1 auto; + height: 100%; + margin: 0 -1px; + padding: 12px; + text-align: center; +} + +.panel-section-footer-button > .text-shortcut { + color: #808080; + font-family: "Lucida Grande", caption; + font-size: .847em; +} + +.panel-section-footer-button:hover { + background-color: rgba(0, 0, 0, 0.06); +} + +.panel-section-footer-button:hover:active { + background-color: rgba(0, 0, 0, 0.1); +} + +.panel-section-footer-button.default { + background-color: #0996f8; + box-shadow: 0 1px 0 #0670cc inset; + color: #fff; +} + +.panel-section-footer-button.default:hover { + background-color: #0670cc; + box-shadow: 0 1px 0 #005bab inset; +} + +.panel-section-footer-button.default:hover:active { + background-color: #005bab; + box-shadow: 0 1px 0 #004480 inset; +} + +.panel-section-footer-separator { + background-color: rgba(0, 0, 0, 0.1); + width: 1px; + z-index: 99; +}</pre> + +<hr> +<pre class="brush: css">/* Example specific – not part of chrome://browser/content/extension.css */ +body { + background: #fcfcfc; + background-clip: padding-box; + border: 1px solid rgba(24,26,27,.2); + box-shadow: 0 3px 5px rgba(24,26,27,.1),0 0 7px rgba(24,26,27,.1); + box-sizing: content-box; + margin: 2em auto .5em; + width: 384px; +} + +html { + min-height: 100vh; +} + +html > body { + margin: auto; +} + +.icon-section-header { + background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMiIgaGVpZ2h0PSIzMiIgdmlld0JveD0iMCAwIDMyIDMyIj48Y2lyY2xlIGZpbGw9IiMzNjM5NTkiIGN4PSIxNSIgY3k9IjE1IiByPSIxNSIvPjwvc3ZnPg=="); +}</pre> +</div> + +<h4 id="Result若查看失败，请切回英文版查看">Result(若查看失败，请切回英文版查看)</h4> + +<p>{{EmbedLiveSample("Example","640","360")}}</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html new file mode 100644 index 0000000000..2844e7319a --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html @@ -0,0 +1,48 @@ +--- +title: Context menu items +slug: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>This user interface option adds one or more items to a browser context menu. This is the context menu available when a user right-clicks on a web page. Tabs can have context menus also, available through the <a href="/en-US/Add-ons/WebExtensions/API/menus">browser.menus API</a>.</p> + +<p><img alt="Example of content menu items added by a WebExtension, from the context-menu-demo example" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="display: block; height: 587px; margin-left: auto; margin-right: auto; width: 573px;"></p> + +<p>You would use this option to expose features that are relevant to specific browser or web page contexts. For example, you could show features to open a graphic editor when the user clicks on an image or offer a feature to save page content when part of a page is selected. You can add plain menu items, checkbox items, radio button groups, and separators to menus. Once a context menu item has been added using {{WebExtAPIRef("contextMenus.create")}} it's displayed in all browser tabs, but you can hide it by removing it with {{WebExtAPIRef("contextMenus.remove")}}.</p> + +<h2 id="Specifying_context_menu_items">Specifying context menu items</h2> + +<p>You manage context menu items programmatically, using the {{WebExtAPIRef("contextMenus")}} API. However, you need to request the <code>contextMenus</code> permission in your manifest.json to be able to take advantage of the API.</p> + +<pre class="brush: json">"permissions": ["contextMenus"]</pre> + +<p>You can then add (and update or delete) the context menu items in your extension's background script. To create a menu item you specify an id, its title, and the context menus it should appear on:</p> + +<pre class="brush: js">browser.contextMenus.create({ + id: "log-selection", + title: browser.i18n.getMessage("contextMenuItemSelectionLogger"), + contexts: ["selection"] +}, onCreated);</pre> + +<p>Your extension then listens for clicks on the menu items. The passed information about the item clicked, the context where the click happened, and details of the tab where the click took place can then be used to invoke the appropriate extension functionality.</p> + +<pre class="brush: js">browser.contextMenus.onClicked.addListener(function(info, tab) { + switch (info.menuItemId) { + case "log-selection": + console.log(info.selectionText); + break; + ... + } +})</pre> + +<h2 id="Examples">Examples</h2> + +<p>The <a class="external external-icon" href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repo on GitHub, contains several examples of extensions that use context menu items:</p> + +<ul> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/menu-demo">menu-demo</a> adds several items to the browser's context menu.</li> + <li><a href="https://github.com/mdn/webextensions-examples/tree/master/context-menu-copy-link-with-types">context-menu-copy-link-with-types</a> adds a context menu item to links that copies the URL to the clipboard, as plain text and rich HTML.</li> +</ul> +</div> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html new file mode 100644 index 0000000000..8f55647526 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html @@ -0,0 +1,61 @@ +--- +title: devtools panels +slug: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +--- +<div>{{AddonSidebar}}</div> + +<div class="note"> +<p>This feature is available since Firefox 54.</p> +</div> + +<p>When an extension provides tools that are of use to developers, it's possible to add a UI for them to the browser's developer tools as a new panel.</p> + +<p><img alt='Simple example showing the addition of "My panel" to the Developer Tools tabs.' src="https://mdn.mozillademos.org/files/15746/developer_panel_tab.png" style="display: block; height: 112px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<h2 id="Specifying_a_developer_tools_panel">Specifying a developer tools panel</h2> + +<p>A developer tools panel is added using the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.panels">devtools.panels</a></code> API, which in turn needs to be run from a special devtools page.</p> + +<p>Add the devtools page by including the <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/devtools_page">devtools_page</a></code> key in extension's <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> and provide the location of the page's HTML file in the extension:</p> + +<pre class="brush: json line-numbers language-json"><code class="language-json"><span class="key token">"devtools_page":</span> <span class="string token">"devtools-page.html"</span></code></pre> + +<p>From the devtools page, call a script that will add the devtools panel:</p> + +<pre class="brush: html"><body> + <script src="devtools.js"></script> +</body></pre> + +<p>In the script, create the devtools panel by specifying the panel's title, icon, and HTML file that provides the panel's content:</p> + +<pre class="brush: js">function handleShown() { + console.log("panel is being shown"); +} + +function handleHidden() { + console.log("panel is being hidden"); +} + +browser.devtools.panels.create( + "My Panel", // title + "icons/star.png", // icon + "devtools/panel/panel.html" // content +).then((newPanel) => { + newPanel.onShown.addListener(handleShown); + newPanel.onHidden.addListener(handleHidden); +});</pre> + +<p>The extension can now run code in the inspected window using <code><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/devtools.inspectedWindow/eval"><code>devtools</code>.inspectedWindow.eval()</a></code> or by injecting a content script via the background script by passing a message. You can find more details on how to do this in <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">Extending the developer tools.</a></p> + +<h2 id="Developer_panel_design">Developer panel design</h2> + +<p>For details on how to design your developer panel's web page to match the style of Firefox, see the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Icons">Icons</h2> + +<p>For details on how to create icons to use with your developer tools panel, see <a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a> in the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Examples">Examples</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a href="https://github.com/mdn/webextensions-examples/blob/master/devtools-panels/">devtools-panels</a> example which implements a devtools panel.</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..f34e594284 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,92 @@ +--- +title: User interface +slug: Mozilla/Add-ons/WebExtensions/user_interface +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +<div>{{AddonSidebar}}</div> + +<p>为了能给用户提供在不同场景下都具有价值的功能， WebExtensions 提供了许多的用户界面选项。下面是这些选项的摘要，在本章中将会对每个选项做出更详细的说明。</p> + +<div class="note"> +<p>想要使你的扩展能提供良好的用户体验吗? 请查看文章<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/User_experience_best_practices">用户体验的最佳实践</a> .</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">UI 选项</th> + <th scope="col">描述</th> + <th scope="col" style="width: 350px;">实例</th> + </tr> + </thead> + <tbody> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Browser_action">浏览器工具栏按钮</a>(浏览器行为)</td> + <td>工具栏上一个可点击的按钮，点击时将事件派发到附件组件上。默认情况下，这个按钮在栏位中是可见的。</td> + <td><img alt="Example of a WebExtension toolbar button" src="https://mdn.mozillademos.org/files/12966/browser-action.png" style="height: 99px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">带有弹出面板的工具栏按钮</a></td> + <td>当这个在工具栏上的按钮被点击时，它会弹出一个面板。这个面板使用 HTML 文档编写，用于处理与用户的交互行为。</td> + <td><img alt="Example of a WebExtension toolbar button with a popup" src="https://mdn.mozillademos.org/files/14039/popup-shadow.png" style="height: 156px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions">地址栏菜单按钮</a>(页面行为)</td> + <td>这个按钮位于浏览器地址栏菜单条，按钮被点击的时候可以派发一个事件出来。默认情况下，这个按钮在所有tab上都是隐藏的.</td> + <td><img alt="Example showing an address bar button (page action)" src="https://mdn.mozillademos.org/files/15047/address_bar_button.png" style="height: 127px; width: 350px;"></td> + </tr> + <tr> + <td>带有<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Popups">弹出面板</a>的地址栏菜单按钮</td> + <td>地址栏菜单按钮被点击时，会弹出一个面板，这个面板通过HTML文档定义,用于处理用户交互。</td> + <td><img alt="Example of a popup on the address bar button" src="https://mdn.mozillademos.org/files/15053/page_action_popup.png" style="height: 250px; width: 330px;"></td> + </tr> + <tr> + <td><a href="/zh-CN/docs/Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items">上下文菜单项</a></td> + <td>在一个或多个网页上下文菜单中的菜单项,复选框和单选按钮.菜单项也可以通过添加分隔栏进行分组,当一个菜单项被点击时,一个事件将会被派发至附加组件.</td> + <td><img alt="" src="https://mdn.mozillademos.org/files/15051/context_menu_example.png" style="height: 359px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars">侧边栏</a></td> + <td> + <p dir="ltr">一个在网页边显示的HTML文档,每页都有其特定的内容. 每当扩展安装时侧边栏将会打开,但最终还是遵循用户的侧边栏可见性设置. 侧边栏内的用户交互通过HTML文档处理.</p> + </td> + <td><img alt="Example of a WebExtension's sidebar" src="https://mdn.mozillademos.org/files/14825/bookmarks-sidebar.png" style="height: 209px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Options_pages">选项页面</a></td> + <td>一个可以使你定义可以更改的扩展首选项的页面. 用户可以从浏览器的附加组件管理器中访问此页面.</td> + <td><img alt="Example showing the options page content added in the favorite colors example." src="https://mdn.mozillademos.org/files/15055/options_page.png" style="height: 259px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Bundled_web_pages">扩展页面</a></td> + <td> + <p>在单独的窗口或页面中使用扩展提供的页面来提供表单,帮助或其他任何需要的内容.</p> + </td> + <td><img alt="Example of a simple bundled page displayed as a detached panel." src="https://mdn.mozillademos.org/files/15063/bundled_page_as_panel_small.png" style="height: 180px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications">通知</a></td> + <td>通过底层操作系统的通知机制向用户显示的短暂通知. 当用户点击或者通知关闭时(用户关闭或超时关闭)派发事件到扩展程序.</td> + <td><img alt="Example notification from a WebExtension" src="https://mdn.mozillademos.org/files/14043/notify-shadowed.png" style="height: 95px; width: 350px;"></td> + </tr> + <tr> + <td><a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox">地址栏建议</a></td> + <td>当用户输入关键词时提供自定义的地址栏建议.</td> + <td><img alt="Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions." src="https://mdn.mozillademos.org/files/15059/omnibox_example_small.png" style="height: 242px; width: 350px;"></td> + </tr> + <tr> + <td><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels">开发者工具面板</a></td> + <td>在浏览器的开发者工具中显示的一个关联了HTML文档的标签.</td> + <td><img alt="New panel tab in the Developer Tools tab bar" src="https://mdn.mozillademos.org/files/15049/developer_panel_tab.png" style="height: 180px; width: 350px;"></td> + </tr> + </tbody> +</table> + +<p>以下的操作指南提供了一些创建用户界面选项的指导;</p> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Add_a_button_to_the_toolbar">在工具栏中添加一个按钮</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Implement_a_settings_page">实现一个设置页面</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools">扩展开发人员工具</a></li> + <li><a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/user_interface/Browser_styles">浏览器样式</a></li> +</ul> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html new file mode 100644 index 0000000000..fe3901c4a8 --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/page_actions/index.html @@ -0,0 +1,93 @@ +--- +title: 地址栏按钮 +slug: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Page_actions +--- +<div>{{AddonSideBar}}</div> + +<div>通常来说的page action，是添加到浏览器地址栏中的按钮。用户通过点击这个按钮与你的扩展进行交互。</div> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15745/address_bar_button.png" style="display: block; height: 174px; margin-left: auto; margin-right: auto; width: 350px;"></p> + +<h2 id="地址栏按钮（Page_actions）和工具栏按钮（_browser_actions）">地址栏按钮（Page actions）和工具栏按钮（ browser actions）</h2> + +<p>地址栏按钮(或 page action) 与工具栏按钮(或 browser action)非常相似。</p> + +<p>其不同之处为：</p> + +<ul> + <li>位置： + <ul> + <li>地址栏按钮是显示在浏览器的地址栏内；</li> + <li>工具栏按钮不是显示在地址栏内，而是在浏览器的工具栏上。</li> + </ul> + </li> + <li>可见性： + <ul> + <li>地址栏按钮默认是隐藏的（尽管可以通过manifest中“show_matches和hide_matches来改变），而你可以在特定tabs中调用pageAction.show()和pageAction.hide()来显示或隐藏它。</li> + <li>工具栏按钮总是可见的。</li> + </ul> + </li> +</ul> + +<p>当动作（行为）与当前页面关联时，使用地址栏按钮，而当动作（行为）与浏览器相关或与多个页面相关时使用工具栏按钮。例如：</p> + +<table class="fullwidth-table standard-table"> + <thead> + <tr> + <th scope="row">类型</th> + <th scope="col">书签动作</th> + <th scope="col">内容动作</th> + <th scope="col">标签操作</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">page action</th> + <td>将本页面保存到书签</td> + <td>Reddit enhancement</td> + <td>Send tab</td> + </tr> + <tr> + <th scope="row">browser action</th> + <td>显示所有书签</td> + <td>使能ad-blocking</td> + <td>同步所有打开的标签</td> + </tr> + </tbody> +</table> + +<p> </p> + +<h2 id="定义地址栏按钮">定义地址栏按钮</h2> + +<p>你可以在manifest.json中使用page_action键定义地址栏按钮的属性：</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></code></pre> + +<p>仅default_icon是强制（必需）的。</p> + +<p>有两种方式定义地址栏按钮：带popup窗口和无popup窗口。如果你没有指定一个popup，则当用户点击此按钮时，事件被派送到使用<a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction/onClicked">pageAction.onClicked</a>侦听器的扩展：</p> + +<pre class="brush: js line-numbers language-js"><code class="language-js">browser<span class="punctuation token">.</span>pageAction<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>如果你指定了一个popup，则点击事件不被派送，在用户点击按钮时显示popup。用户可以与popup进行交互，并且当用户点击popup以外区域时，popup自动关闭。参见<a href="https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Popups">Popup</a>可获得创建和管理popups更详细内容。</p> + +<p>注意你的扩展只能有一个地址栏按钮。</p> + +<p>通过使用<a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/pageAction">pageAction</a> API，你可以以编程方式修改地址栏按钮的任何属性。</p> + +<h2 id="Icons">Icons</h2> + +<p>如何创建用于地址栏按钮的ICONS的详细内容，请参见<a href="https://design.firefox.com/photon/index.html">Photon Design System</a>文档中的<a href="https://design.firefox.com/photon/visuals/iconography.html">Iconography</a>节。</p> + +<h2 id="示例">示例</h2> + +<p>GitHub上的 <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> 库中包括了实现无popup地址栏按钮的例子 <a href="https://github.com/mdn/webextensions-examples/tree/master/chill-out">chill-out</a> 。</p> diff --git a/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html new file mode 100644 index 0000000000..8d13bfaf2c --- /dev/null +++ b/files/zh-cn/mozilla/add-ons/webextensions/user_interface/侧边栏/index.html @@ -0,0 +1,53 @@ +--- +title: 侧边栏 +slug: Mozilla/Add-ons/WebExtensions/user_interface/侧边栏 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +<div>{{AddonSidebar}}</div> + +<div> +<p>A sidebar is a pane that is displayed at the side of the browser window, next to the web page. The browser provides a UI that enables the user to see the currently available sidebars and to select a sidebar to display. For example, Firefox has a "View > Sidebar" menu. Only one sidebar can be shown at a time, and that sidebar will be displayed for all tabs and all browser windows.</p> + +<p>The browser may include a number of built-in sidebars. For example, Firefox includes a sidebar for interacting with bookmarks:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/15755/bookmarks-sidebar.png" style="display: block; height: 423px; margin-left: auto; margin-right: auto; width: 350px;">Using the <code>sidebar_action</code> manifest.json key, an extension can add its own sidebar to the browser. It will be listed alongside the built-in sidebars, and the user will be able to open it using the same mechanism as for the built-in sidebars.</p> + +<p>就像浏览器的弹出页面，侧边栏也是一个HTML文档。当用户打开侧边栏时，HTML文档载入打开的浏览器窗口。每个窗口有一个该文档的实例。打开一个新窗口时，该窗口获得自己的文档实例</p> + +<p>可以使用函数{{WebExtAPIRef("sidebarAction.setPanel()")}}指定侧边栏仅用于指定的某个标签，使用{{WebExtAPIRef("windows.getCurrent()")}} 侧边栏知道自己属于哪一个标签。</p> + +<pre class="brush: js">// sidebar.js +browser.windows.getCurrent({populate: true}).then((windowInfo) => { + myWindowId = windowInfo.id; +});</pre> + +<p>不同的窗口使用不同的侧边栏是非常有用的，这是一个实例 ，见<a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">"annotate-page" example</a>.</p> + +<p>侧边栏俱有和后台程序以及弹出窗口相同的API权限，在非隐藏模式下，侧边栏使用API {{WebExtAPIRef("runtime.getBackgroundPage()")}} 可以直接访问后台页面，使用 API 如{{WebExtAPIRef("tabs.sendMessage()")}} 与content scripts交互，使用API 如 {{WebExtAPIRef("runtime.sendNativeMessage()")}} 与原生应用交互。</p> + +<p>关闭窗口或关闭侧边栏时，侧边栏文档退出。这意味着和后台页面不同，侧边栏文档不是一直住留，也不像弹出窗口，只要用户与页面交互 ，它就一直存在。</p> + +<p>使用侧边栏的扩展载入时，侧边栏自动打开。这是为了帮助用户知道扩展俱有侧边栏。注意不能通过编程的方式打开侧边栏：侧边栏只能由用户打开。</p> + +<h2 id="声明侧边栏">声明侧边栏</h2> + +<p>声明侧边栏，只需在manifest.json中指 定关键字 <code><a href="/en-US/Add-ons/WebExtensions/manifest.json/sidebar_action">sidebar_action</a></code> 并同时指定title 和 icon:</p> + +<pre class="brush: json">"sidebar_action": { + "default_title": "My sidebar", + "default_panel": "sidebar.html", + "default_icon": "sidebar_icon.png" +}</pre> + +<p>使用API {{WebExtAPIRef("sidebarAction")}} ，你可以用编程的方式修改title panel icon。</p> + +<p>浏览器提供的显示侧边栏的UI中，title和icon显示给用户，如Firefox菜单栏的"View > Sidebar"</p> + +<h2 id="Sidebar_design">Sidebar design</h2> + +<p>For details on how to design your sidebar's web page to match the style of Firefox, see the <a class="grey-90 no-underline hover-no-underline" href="https://design.firefox.com/photon/index.html">Photon Design System</a> documentation.</p> + +<h2 id="Example">Example</h2> + +<p>The <a href="https://github.com/mdn/webextensions-examples">webextensions-examples</a> repository on GitHub includes the <a href="https://github.com/mdn/webextensions-examples/tree/master/annotate-page">annotate-page</a> example which implements a sidebar.</p> +</div> |