跳至主要內容

類別：MenuItem

類別：MenuItem​

將項目新增至原生應用程式選單和關聯式選單。

程序：主

請參閱 Menu 以取得範例。

new MenuItem(options)​

  • options 物件
    • click 函式 (選用) - 在選單項目被點擊時，會以 click(menuItem, window, event) 呼叫。
      • menuItem MenuItem
      • window BaseWindow | undefined - 如果沒有開啟任何視窗，則不會定義。
      • event KeyboardEvent
    • role 字串 (選用) - 可以是 undo、redo、cut、copy、paste、pasteAndMatchStyle、delete、selectAll、reload、forceReload、toggleDevTools、resetZoom、zoomIn、zoomOut、toggleSpellChecker、togglefullscreen、window、minimize、close、help、about、services、hide、hideOthers、unhide、quit、showSubstitutions、toggleSmartQuotes、toggleSmartDashes、toggleTextReplacement、startSpeaking、stopSpeaking、zoom、front、appMenu、fileMenu、editMenu、viewMenu、shareMenu、recentDocuments、toggleTabBar、selectNextTab、selectPreviousTab、showAllTabs、mergeAllWindows、clearRecentDocuments、moveTabToNewWindow 或 windowMenu - 定義選單項目的動作，指定時會忽略 click 屬性。請參閱角色。
    • type 字串 (選用) - 可以是 normal、separator、submenu、checkbox 或 radio。
    • label 字串 (選用)
    • sublabel 字串 (選用)
    • toolTip 字串 (選用) macOS - 這個選單項目的懸停文字。
    • accelerator Accelerator (選用)
    • icon (NativeImage | 字串) (選用)
    • enabled 布林值 (選用) - 如果為 false，選單項目會呈現灰色且無法點擊。
    • acceleratorWorksWhenHidden 布林值 (選用) macOS - 預設值為 true，當為 false 時，如果項目不可見，則會阻止加速器觸發該項目。
    • visible 布林值 (選用) - 如果為 false，選單項目會完全隱藏。
    • checked 布林值 (選用) - 應僅針對 checkbox 或 radio 類型的選單項目指定。
    • registerAccelerator 布林值 (選用) Linux Windows - 如果為 false，加速器將不會在系統中註冊，但仍會顯示。預設為 true。
    • sharingItem SharingItem (選用) macOS - 當 role 為 shareMenu 時，要分享的項目。
    • submenu (MenuItemConstructorOptions[] | Menu) (選用) - 應針對 submenu 類型的選單項目指定。如果指定了 submenu，則可以省略 type: 'submenu'。如果值不是 Menu，則會使用 Menu.buildFromTemplate 自動轉換為一個。
    • id 字串 (選用) - 在單一選單中是唯一的。如果已定義，則可以使用它作為此項目的位置屬性參考。
    • before 字串[] (選用) - 將此項目插入在具有指定 ID 的項目之前。如果參考的項目不存在，則該項目將插入選單的末尾。也表示相關的選單項目應與該項目放置在相同的「群組」中。
    • after 字串[] (選用) - 將此項目插入在具有指定 ID 的項目之後。如果參考的項目不存在，則該項目將插入選單的末尾。
    • beforeGroupContaining 字串[] (選用) - 提供單一關聯式選單的方式，以在其包含群組之前宣告其包含群組的位置，該包含群組具有指定 ID 的項目。
    • afterGroupContaining 字串[] (選用) - 提供單一關聯式選單的方式，以在其包含群組之後宣告其包含群組的位置，該包含群組具有指定 ID 的項目。

注意： acceleratorWorksWhenHidden 被指定為僅限 macOS，因為在 Windows 和 Linux 上，當項目隱藏時，加速器始終有效。向使用者公開此選項是為了讓他們選擇關閉它，因為這在原生 macOS 開發中是可能的。

角色​

角色允許選單項目具有預先定義的行為。

最好為任何符合標準角色的選單項目指定 role，而不是嘗試在 click 函式中手動實作行為。內建的 role 行為將提供最佳的原生體驗。

當使用 role 時，label 和 accelerator 值是選用的，並且會預設為每個平台的適當值。

每個選單項目都必須具有 role、label 或在分隔符號的情況下具有 type。

role 屬性可以具有下列值

  • undo
  • about - 觸發原生關於面板 (Windows 上的自訂訊息方塊，它不提供自己的面板)。
  • redo
  • cut
  • copy
  • paste
  • pasteAndMatchStyle
  • selectAll
  • delete
  • minimize - 最小化目前的視窗。
  • close - 關閉目前的視窗。
  • quit - 結束應用程式。
  • reload - 重新載入目前的視窗。
  • forceReload - 重新載入目前的視窗，忽略快取。
  • toggleDevTools - 在目前的視窗中切換開發人員工具。
  • togglefullscreen - 在目前的視窗上切換全螢幕模式。
  • resetZoom - 將焦點頁面的縮放層級重設為原始大小。
  • zoomIn - 將焦點頁面放大 10%。
  • zoomOut - 將焦點頁面縮小 10%。
  • toggleSpellChecker - 啟用/停用內建拼字檢查器。
  • fileMenu - 整個預設「檔案」選單（關閉/結束）。
  • editMenu - 整個預設「編輯」選單（復原、複製等）。
  • viewMenu - 整個預設「檢視」選單（重新載入、切換開發人員工具等）。
  • windowMenu - 整個預設「視窗」選單（最小化、縮放等）。

下列額外角色可在 macOS 上使用

  • appMenu - 整個預設「應用程式」選單（關於、服務等）。
  • hide - 對應至 hide 動作。
  • hideOthers - 對應至 hideOtherApplications 動作。
  • unhide - 對應至 unhideAllApplications 動作。
  • showSubstitutions - 對應至 orderFrontSubstitutionsPanel 動作。
  • toggleSmartQuotes - 對應至 toggleAutomaticQuoteSubstitution 動作。
  • toggleSmartDashes - 對應至 toggleAutomaticDashSubstitution 動作。
  • toggleTextReplacement - 對應至 toggleAutomaticTextReplacement 動作。
  • startSpeaking - 對應至 startSpeaking 動作。
  • stopSpeaking - 對應至 stopSpeaking 動作。
  • front - 對應至 arrangeInFront 動作。
  • zoom - 對應至 performZoom 動作。
  • toggleTabBar - 對應至 toggleTabBar 動作。
  • selectNextTab - 對應至 selectNextTab 動作。
  • selectPreviousTab - 對應到 selectPreviousTab 動作。
  • showAllTabs - 對應到 showAllTabs 動作。
  • mergeAllWindows - 對應到 mergeAllWindows 動作。
  • moveTabToNewWindow - 對應到 moveTabToNewWindow 動作。
  • window - 子選單為「視窗」選單。
  • help - 子選單為「說明」選單。
  • services - 子選單為 「服務」選單。這僅適用於應用程式選單，且與 macOS 應用程式內容選單中使用的「服務」子選單不同，後者在 Electron 中未實作。
  • recentDocuments - 子選單為「開啟最近使用的檔案」選單。
  • clearRecentDocuments - 對應到 clearRecentDocuments 動作。
  • shareMenu - 子選單為分享選單。必須同時設定 sharingItem 屬性，以指示要分享的項目。

在 macOS 上指定 role 時，只有 label 和 accelerator 選項會影響選單項目。所有其他選項都會被忽略。仍然支援小寫的 role，例如 toggledevtools。

注意： enabled 和 visibility 屬性在 macOS 上不適用於系統匣中的頂層選單項目。

實例屬性​

以下屬性可於 MenuItem 實例上使用

一個 string，指示項目的唯一 ID，此屬性可動態變更。

一個 string，指示項目可見的標籤。

一個 Function，當 MenuItem 收到點擊事件時觸發。可使用 menuItem.click(event, focusedWindow, focusedWebContents) 呼叫。

一個 Menu（選用），包含選單項目的子選單（如果有的話）。

一個 string，指示項目的類型。可以是 normal、separator、submenu、checkbox 或 radio。

一個 string（選用），指示項目的角色（如果已設定）。可以是 undo、redo、cut、copy、paste、pasteAndMatchStyle、delete、selectAll、reload、forceReload、toggleDevTools、resetZoom、zoomIn、zoomOut、toggleSpellChecker、togglefullscreen、window、minimize、close、help、about、services、hide、hideOthers、unhide、quit、startSpeaking、stopSpeaking、zoom、front、appMenu、fileMenu、editMenu、viewMenu、shareMenu、recentDocuments、toggleTabBar、selectNextTab、selectPreviousTab、showAllTabs、mergeAllWindows、clearRecentDocuments、moveTabToNewWindow 或 windowMenu

一個 Accelerator（選用），指示項目的加速鍵（如果已設定）。

一個 Accelerator | null，指示選單項目的使用者指定的加速鍵。

注意： 此屬性僅在 MenuItem 加入 Menu 後初始化。透過 Menu.buildFromTemplate 或 Menu.append()/insert()。在初始化之前存取只會傳回 null。

一個 NativeImage | string（選用），指示項目的圖示（如果已設定）。

一個 string，指示項目的子標籤。

一個 string，指示項目的懸停文字。

一個 boolean，指示項目是否啟用，此屬性可動態變更。

一個 boolean，指示項目是否可見，此屬性可動態變更。

一個 boolean，指示項目是否已勾選，此屬性可動態變更。

當選取 checkbox 選單項目時，會切換 checked 屬性的開關狀態。

當點擊 radio 選單項目時，會開啟其 checked 屬性，並關閉同一選單中所有相鄰項目的該屬性。

您可以新增一個 click 函數以取得額外行為。

一個 boolean，指示加速鍵應向系統註冊還是僅顯示。

此屬性可動態變更。

當 role 為 shareMenu 時，一個 SharingItem 指示要分享的項目。

此屬性可動態變更。

一個 number，指示項目的循序唯一 ID。

一個 Menu，該項目是其一部分。