From 218934fa2ed1c702a6d3923d2aa2cc6b43c48684 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:43:23 -0500 Subject: initial commit --- .../user_interface/browser_action/index.html | 50 ++++++++++++ .../user_interface/context_menu_items/index.html | 54 +++++++++++++ .../user_interface/devtools_panels/index.html | 66 +++++++++++++++ .../webextensions/user_interface/index.html | 94 ++++++++++++++++++++++ .../user_interface/sidebars/index.html | 55 +++++++++++++ 5 files changed, 319 insertions(+) create mode 100644 files/zh-tw/mozilla/add-ons/webextensions/user_interface/browser_action/index.html create mode 100644 files/zh-tw/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html create mode 100644 files/zh-tw/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html create mode 100644 files/zh-tw/mozilla/add-ons/webextensions/user_interface/index.html create mode 100644 files/zh-tw/mozilla/add-ons/webextensions/user_interface/sidebars/index.html (limited to 'files/zh-tw/mozilla/add-ons/webextensions/user_interface') diff --git a/files/zh-tw/mozilla/add-ons/webextensions/user_interface/browser_action/index.html b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/browser_action/index.html new file mode 100644 index 0000000000..afdf61f340 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/browser_action/index.html @@ -0,0 +1,50 @@ +--- +title: 工具列按鈕 +slug: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +tags: + - 擴充套件 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Browser_action +--- +
{{AddonSidebar}}
+ +

根據工具列按鈕，這個用戶介面是一個加到瀏覽器工具列的按鈕。用戶透過點擊按鈕來與你的套件互動。
+

+ +

工具列按鈕與網址列按鈕非常相似。關於差別以及何時該使用的指引，詳閱工具列按鈕。

+ +

詳細指定工具列按鈕

+ +

透過在 manifest.json 中使用 browser_action 鍵來定義工具列按鈕的屬性：

+ +
"browser_action": {
+  "default_icon": {
+    "19": "button/geo-19.png",
+    "38": "button/geo-38.png"
+  },
+  "default_title": "我在哪？"
+}
+ +

唯一一個強制的鍵只有 default_icon。

+ +

指定工具列按鈕的方式有兩種： 有彈出視窗跟沒有彈出視窗。如果你不指定彈出視窗，當用戶點擊按鈕事件會被傳送到套件，而套件透過 browserAction.onClicked 監聽：

+ +
browser.browserAction.onClicked.addListener(handleClick);
+ +

如果你指定彈出視窗，點擊事件不會被傳送，取而代之當用戶點擊按鈕時彈出視窗會被展開。用戶可以跟彈出視窗互動且當用戶點擊了彈出視窗外側它會自動關閉。更多建立與管理彈出視窗的細節請查看彈出視窗文章。

+ +

註： 你的套件只能有一個工具列按鈕。

+ +

你可以透過 browserAction API 程式化地更改任何工具列按鈕的屬性。

+ +

圖示

+ +

更多關於建立工具列按鈕使用的圖示，請查看文件光子設計系統裡的圖示學。

+ +

範例

+ +

GitHub上的擴充套件範例程式庫包含兩個建立工具列按鈕的範例：

+ + diff --git a/files/zh-tw/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html new file mode 100644 index 0000000000..949ec58b74 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.html @@ -0,0 +1,54 @@ +--- +title: 快捷選單項 +slug: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +tags: + - 擴充套件 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Context_menu_items +--- +
{{AddonSidebar}}
+ +
+

這個用戶介面添加一個或多個項目到瀏覽器的快捷選單。這是用戶在網頁上點擊右鍵時出現的選單。頁籤也可以透過 browser.menus API 使用快捷選單。

+ +

Example of content menu items added by a WebExtension, from the context-menu-demo example

+ +

你可以用這個介面來顯示一些跟特定瀏覽器或網頁內容相關的功能。舉例來說，當用戶在圖片上按右鍵時提供圖片編輯器的功能或者在反白內容上按右鍵時提供儲存頁面內容的功能。你可以對選單添加普通的選單項目、核取方塊、單選按鈕組以及分隔線。選單項目透過{{WebExtAPIRef("contextMenus.create")}}添加後透過它會顯示在所有瀏覽器頁籤，但是你可以透過{{WebExtAPIRef("contextMenus.remove")}}來移除它。

+ +

指定快捷選單項目

+ +

透過{{WebExtAPIRef("contextMenus")}} API可以程式化地管理快捷選單項目。然而，你必須請求 contextMenus 的權限才能使用這些API的好處。

+ +
"permissions": ["contextMenus"]
+ +

現在你可以在你套件的後端腳本處添加（修改／刪除）選單項目。建立一個選單項目你要指定 id，標題以及它應該隸屬於哪個選單：

+ +
browser.contextMenus.create({
+  id: "log-selection",
+  title: browser.i18n.getMessage("contextMenuItemSelectionLogger"),
+  contexts: ["selection"]
+}, onCreated);
+ +

接著你的套件會監聽選單項目的點擊。送出有關項目點擊、點擊環境以及發生點擊頁籤的資訊可以用來使用恰當的套件功能。

+ +
browser.contextMenus.onClicked.addListener(function(info, tab) {
+  switch (info.menuItemId) {
+    case "log-selection":
+      console.log(info.selectionText);
+      break;
+    ...
+  }
+})
+ +

圖示

+ +

更多關於建立快捷選單圖示的細節請查看文件光子設計系統的圖示學。

+ +

範例

+ +

GitHub上的webextensions-examples 程式庫包含了兩個建立快捷選單的範例：

+ + +
diff --git a/files/zh-tw/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html new file mode 100644 index 0000000000..fddea1b0e0 --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/devtools_panels/index.html @@ -0,0 +1,66 @@ +--- +title: 開發工具面板 +slug: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +tags: + - 初學者 + - 擴充套件 + - 教學 + - 用戶介面 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels +--- +
{{AddonSidebar}}
+ +
+

Firefox 54 以後可以使用這個功能。

+
+ +

當套件提供開發者使用的工具時，可以以一個瀏覽器開發工具的新面板的形式在開發者工具裡添加一個UI。

+ +

Simple example showing the addition of "My panel" to the Developer Tools tabs.

+ +

指定開發工具面板

+ +

開發工具面板可以透過 devtools.panels API 添加，因此這必須在特別的開發工具頁面執行。

+ +

透過在套件的 manifest.json 添加 devtools_page 鍵並提供HTML檔案來添加開發工具頁面：

+ +
"devtools_page": "devtools-page.html"
+ +

在開發工具頁面，呼叫腳本會添加開發工具面板：

+ +
<body>
+  <script src="devtools.js"></script>
+</body>
+ +

在腳本裡，藉由指定面板標題、圖示、HTML檔案來建立開發工具：

+ +
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);
+});
+ +

套件現在可以在檢測器視窗透過 devtools.inspectedWindow.eval() 或透過後端腳本傳送訊息來插入內容腳本兩種方式執行。你可以在擴充開發者工具找到更多相關訊息。

+ +

開發面板設計

+ +

更多關於如何設計符合 Firefox 風格的開發者面板，請查看文件光子設計系統。

+ +

圖示

+ +

更多關於建立開發者工具面板圖示的細節，請查看文件光子設計系統的圖示學。

+ +

範例

+ +

GitHub上的 webextensions-examples 程式庫包含了建立開發工具面板的 devtools-panels 範例。

diff --git a/files/zh-tw/mozilla/add-ons/webextensions/user_interface/index.html b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/index.html new file mode 100644 index 0000000000..5c8e40bcdd --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/index.html @@ -0,0 +1,94 @@ +--- +title: 用戶介面 +slug: Mozilla/Add-ons/WebExtensions/user_interface +tags: + - 擴充套件 + - 用戶介面 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface +--- +
{{AddonSidebar}}
+ +

套件APIs 提供了幾種介面來完成對用戶的功能。下方是那些介面的概述，每種用戶介面都有更詳細的資訊可以查閱。

+ +
+

爲了使用這些UI元件在套件裡提供優秀的用戶體驗，建議閱讀用戶體驗最佳實踐文章。

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

可用介面

+ 		敘述範例
工具列按鈕一個瀏覽器工具列上的按鈕，被點擊時會送出事件給套件。預設的情況下在所有頁籤都能看到此按鈕。Example showing a toolbar button (browser action).
附帶彈出視窗的工具列按鈕一個按鈕上的彈出視窗，當按鈕被點擊時展開。彈出視窗被一個HTML文件來定義。Example of the pop-up on a toolbar button
網址列按鈕一個網址列上的按鈕，點擊時傳送事件給套件。預設的情況下，在所有的頁籤中此按鈕都會被隱藏。Example showing an address bar button (page action)
附帶彈出視窗的網址列按鈕網址列按鈕上的一個按鈕，當按鈕被點擊時展開，彈出視窗被一個HTML文件來定義。Example of a popup on the address bar button
快捷選單在一個或多個瀏覽器快捷選單中的選單項目、核取方塊、選項按鈕。另外，選單可以透過增加分隔線來組成。當選單項目被點擊時傳送一個事件給套件。Example of content menu items added by a WebExtension, from the context-menu-demo example
側邊欄 +

一個顯示在網頁旁邊的HTML文件，每頁可以顯示獨立的內容。側邊欄會在用戶安裝套件時打開，然後根據用戶對側邊欄的可視選項開關。側邊欄裡的用戶互動由它的HTML文件來控制。

+ 		Example of a sidebar
選項頁面一個使你可以定義用戶能修改的偏好設定的頁面。用戶可以透過瀏覽器的套件管理畫面進到這裡。Example showing the options page content added in the favorite colors example.
套件頁面透過套件裡的網頁來在視窗或頁籤內提供表單、幫助訊息或任何需要的內容。Example of a simple bundled page displayed as a detached panel.
通知透過作業系統的機制顯示的短暫的通知。當用戶點擊通知或通知關閉時（不論自動關閉或用戶手動關閉）時傳送事件給套件。Example of an extension triggered system notification
網址列建議當用戶輸入關鍵字時提供自訂的網址列建議。Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.
開發者工具面板一個包含相關HTML文件的頁籤顯示在瀏覽器的開發者工具裡。Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.
+ +

下面是一些關於建立這些用戶介面的詳細教學：

+ + diff --git a/files/zh-tw/mozilla/add-ons/webextensions/user_interface/sidebars/index.html b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/sidebars/index.html new file mode 100644 index 0000000000..923cd9d14f --- /dev/null +++ b/files/zh-tw/mozilla/add-ons/webextensions/user_interface/sidebars/index.html @@ -0,0 +1,55 @@ +--- +title: 側邊欄 +slug: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +tags: + - 擴充套件 +translation_of: Mozilla/Add-ons/WebExtensions/user_interface/Sidebars +--- +
{{AddonSidebar}}
+ +
+

側邊欄是一個顯示在瀏覽器視窗上、網頁旁邊的面板。瀏覽器提供能讓用戶看見目前可用的側邊欄並且擇一顯示的UI。例如，Firefox 有一個 "檢視 > 側邊欄" 的選單。一次只能有一個側邊欄顯示，而那個側邊欄會顯示在所有的頁籤以及瀏覽器視窗。

+ +

瀏覽器可能包含了一些內建的側邊欄。例如，Firefox 包含了一個可以跟書籤互動的側邊欄：

+ +

在 manifest.json 裡用 sidebar_action 鍵可以替瀏覽器添加側邊欄。它會被列在內建的側邊欄旁邊，而用戶可以透過與內建側邊欄一模一樣的機制來打開它。

+ +

就像工具列按鈕一樣，你藉由HTML文件指定側邊欄的內容。當用戶打開側邊欄，側邊欄的文件會被讀取到每個開著的瀏覽器視窗。每個視窗都各自獲取文件的實例，當新的視窗被開啓，他們也會獲取自己的側邊欄實例。

+ +

你可以用{{WebExtAPIRef("sidebarAction.setPanel()")}}函數設置某個頁籤專屬的文件。側邊欄會透過{{WebExtAPIRef("windows.getCurrent()")}} API找出它隸屬的視窗 :

+ +
// sidebar.js
+browser.windows.getCurrent({populate: true}).then((windowInfo) => {
+  myWindowId = windowInfo.id;
+});
+ +

如果側邊欄要在不同的視窗顯示不同內容這會很有用。範例請看 "annotate-page" 範例。

+ +

側邊欄文件與後端腳本以及彈出視窗享有一樣的權限。他們可以透過{{WebExtAPIRef("runtime.getBackgroundPage()")}}直接讀取後端頁面（只要側邊欄隸屬於隱私模式的視窗），並且可以透過一些 messaging APIs 與內容腳本或原生應用互動，像是{{WebExtAPIRef("tabs.sendMessage()")}}與{{WebExtAPIRef("runtime.sendNativeMessage()")}}。

+ +

側邊欄文件會在瀏覽器視窗關閉或用戶關閉側邊欄時被卸載。這代表不像後端腳本，側邊欄文件並不總是保持讀入的狀態。但是不像工具列按鈕，他們可以在用戶與網頁互動時保持讀入。

+ +

當定義著側邊欄的套件被首次安裝時，側邊欄2會自動開啓。這是爲了幫助用戶瞭解這個套件包含了一個側邊欄。註：套件無法程式化地開啓側邊欄，側邊欄只能由用戶開啓。

+ +

指定側邊欄

+ +

要指定側邊欄，在 manifest.json 裡透過 sidebar_action 鍵定義文件、標題以及圖示：

+ +
"sidebar_action": {
+  "default_title": "My sidebar",
+  "default_panel": "sidebar.html",
+  "default_icon": "sidebar_icon.png"
+}
+ +

你可以透過{{WebExtAPIRef("sidebarAction")}} API程式化地更改標題、面板以及圖示。

+ +

標題與圖示會在任一個瀏覽器提供的UI中顯示，像是 Firefox 裡的 "檢視 > 側邊欄" 選單。

+ +

側邊欄設計

+ +

更多如何設計符合 Firefox 風格的側邊欄網頁細節，請查看文件光子設計系統。

+ +

範例

+ +

GitHub上的 webextensions-examples 程式庫包含了建立側邊欄的 annotate-page 範例。

+
-- cgit v1.2.3-54-g00ecf