在 WebView2 中自訂操作功能表

WebView2 控制項提供預設的操作功能表，您可以在使用 WebView2 控制項時建立自己的操作功能表。 使用 ContextMenuRequested API 自訂 WebView2 應用程式) 的內容功能表 (按滑鼠右鍵功能表。

詳細內容：

簡介

WebView2 控制項提供預設的操作功能表，您可以在使用 WebView2 控制項時建立自己的操作功能表。 使用 ContextMenuRequested API 自訂 WebView2 應用程式) 的內容功能表 (按滑鼠右鍵功能表。

例如，您可以執行下列任何一個動作：

  • 新增自訂操作功能表。

    您的主應用程式可以使用從 WebView2 快顯功能表傳送的資訊，來繪製自己的快顯功能表，而不是使用預設的操作功能表。 您的應用程式會 ContextMenuRequested 處理事件。 您可以使用事件引數中 ContextMenuRequested 提供的資料，來顯示包含您選擇的項目的自訂操作功能表。 在此案例中，您處理事件並要求延遲。

    您可以將預設功能表項目和/或自訂功能表項目新增至自訂操作功能表。

  • 將預設功能表項目新增至自訂操作功能表。

  • 將自訂功能表項目新增至預設操作功能表。

  • 從預設操作功能表移除預設或自訂功能表項目。

  • 停用操作功能表。

術語：

術語 定義
功能表項目 廣義的術語。 包含核取方塊、命令、選項按鈕、分隔符號和子功能表。
命令 一個狹隘的術語。 五種功能表項目之一。
操作功能表 預設操作功能表 (屬於 WebView2 控制項的右鍵功能表) ，或自訂操作功能表 (右鍵功能表) 屬於您的主機應用程式。

新增自訂操作功能表

您的主應用程式可以使用從 WebView2 快顯功能表傳送的資訊，來繪製自己的快顯功能表，而不是使用預設的操作功能表。 您的應用程式會 ContextMenuRequested 處理事件。 您可以使用事件引數中 ContextMenuRequested 提供的資料，來顯示包含您選擇的項目的自訂操作功能表。 在此案例中，您處理事件並要求延遲。

當使用者從自訂操作功能表選取命令時，您的應用程式必須使用 SelectedCommandId 屬性，告知 WebView2 控制項使用者已選取哪個命令。

您可以將預設功能表項目和/或自訂功能表項目新增至自訂操作功能表。

若要顯示包含所需功能表項目的自訂操作功能表，請使用 ContextMenuRequested 事件中CoreWebView2ContextMenuRequestedEventArgsCoreWebView2提供的資料。 在此情況下，您可以指定 Handled 為 true，並要求延遲。

在事件上 CoreWebView2.ContextMenuRequested ，新增具有 的事件接聽程式 CoreWebView2ContextMenuRequestedEventArgs。

的CoreWebView2ContextMenuRequestedEventArgs屬性提供MenuItems以滑鼠右鍵按一下內容的 WebView2 操作功能表項目樹狀結構。 若要在應用程式的操作功能表中包含 WebView2 操作功能表項目，請逐一查看 IList<CoreWebView2ContextMenuItem>，為每個功能表項目新增一個 CoreWebView2ContextMenuItem 。 測試每個功能表項目的 ， .Kind 例如 Command 或 Separator。

範例：新增自訂操作功能表

下列範例以 Win32/WPF 操作功能表格式呈現 WebView2 操作功能表。

webView.CoreWebView2.ContextMenuRequested += delegate (object sender,
                                    CoreWebView2ContextMenuRequestedEventArgs args)
{
    IList<CoreWebView2ContextMenuItem> menuList = args.MenuItems;
    CoreWebView2Deferral deferral = args.GetDeferral();
    args.Handled = true;
    ContextMenu cm = new ContextMenu();
    cm.Closed += (s, ex) => deferral.Complete();
    PopulateContextMenu(args, menuList, cm);
    cm.IsOpen = true;
};
void PopulateContextMenu(CoreWebView2ContextMenuRequestedEventArgs args,
IList<CoreWebView2ContextMenuItem> menuList, ItemsControl cm)
{
    for (int i = 0; i < menuList.Count; i++)
    {
        CoreWebView2ContextMenuItem current = menuList[i];
        if (current.Kind == CoreWebView2ContextMenuItemKind.Separator)
        {
            Separator sep = new Separator();
            cm.Items.Add(sep);
            continue;
        }
        MenuItem newItem = new MenuItem();
        // The accessibility key is the key after the & in the label
        // Replace with '_' so it is underlined in the label
        newItem.Header = current.Label.Replace('&', '_');
        newItem.InputGestureText = current.ShortcutKeyDescription;
        newItem.IsEnabled = current.IsEnabled;
        if (current.Kind == CoreWebView2ContextMenuItemKind.Submenu)
        {
            PopulateContextMenu(args, current.Children, newItem);
        }
        else
        {
            if (current.Kind == CoreWebView2ContextMenuItemKind.CheckBox
            || current.Kind == CoreWebView2ContextMenuItemKind.Radio)
            {
                newItem.IsCheckable = true;
                newItem.IsChecked = current.IsChecked;
            }

            newItem.Click += (s, ex) =>
            {
                args.SelectedCommandId = current.CommandId;
            };
        }
        cm.Items.Add(newItem);
    }
}

新增功能表項目至操作功能表

您可以：

  • 將預設功能表項目新增至自訂操作功能表，如上方的「新增自訂操作功能表」所示。

  • 將自訂功能表項目新增至預設操作功能表，如下方的「新增自訂功能表項目至預設操作功能表」所示。

新增自訂功能表項目至預設操作功能表

若要將自訂功能表項目新增至預設操作功能表，請使用下列 API 項目。

範例：將自訂功能表項目新增至預設操作功能表

下列範例會將 顯示頁面 Uri 命令新增至 WebView2 快顯功能表。

webView.CoreWebView2.ContextMenuRequested += delegate (object sender,
                                    CoreWebView2ContextMenuRequestedEventArgs args)
{
    // add new item to end of collection
    CoreWebView2ContextMenuItem newItem =
                        webView.CoreWebView2.Environment.CreateContextMenuItem(
        "Display Page Uri", null, CoreWebView2ContextMenuItemKind.Command);
        newItem.CustomItemSelected += delegate (object send, Object ex)
        {
            string pageUri = args.ContextMenuTarget.PageUri;
            System.Threading.SynchronizationContext.Current.Post((_) =>
            {
                MessageBox.Show(pageUri, "Page Uri", MessageBoxButton.OK);
            }, null);
        };
    menuList.Insert(menuList.Count, newItem);
};

從預設操作功能表移除功能表項目

您可以從預設操作功能表中移除預設或自訂功能表項目。

範例：從預設操作功能表移除功能表項目

下列範例會從 WebView2 快顯功能表移除 [ 另存影像新檔 ] 命令。

webView.CoreWebView2.ContextMenuRequested += delegate (object sender,
                                    CoreWebView2ContextMenuRequestedEventArgs args)
{
    IList<CoreWebView2ContextMenuItem> menuList = args.MenuItems;
    CoreWebView2ContextMenuTargetKind context = args.ContextMenuTarget.Kind;
    if (context == CoreWebView2ContextMenuTargetKind.Image)
    {
        for (int index = 0; index < menuList.Count; index++)
        {
            if (menuList[index].Name == "saveImageAs")
            {
                menuList.RemoveAt(index);
                break;
            }
        }
    }
};

偵測使用者何時要求操作功能表

本節說明如何偵測使用者要求開啟操作功能表的時機。 這對於自訂或預設操作功能表也是一樣。

當使用者要求開啟操作功能表 (例如以滑鼠右鍵按一下) 時，您的應用程式必須接聽 ContextMenuRequested 事件。

當您的應用程式偵測到此事件時，您的應用程式應該執行下列某些組合：

  • 將自訂功能表項目新增至預設操作功能表。
  • 從預設操作功能表移除自訂功能表項目。
  • 開啟自訂操作功能表。

事件表示 ContextMenuRequested 使用者要求開啟操作功能表。

WebView2 控制項會引發此事件，指出使用者要求在 WebView2 控制項中開啟操作功能表，例如以滑鼠右鍵按一下。

只有在目前網頁允許顯示操作功能表時，也就是AreDefaultContextMenusEnabled屬性為 true時，WebView2 控制項才會ContextMenuRequested引發事件。

CoreWebView2ContextMenuRequestedEventArgs 包含下列資訊：

  • 要填入自訂操作功能表的物件排序 ContextMenuItem 清單。 排序清單包括下列項目：

    • 功能表項目的內部名稱。
    • 在 UI 中向使用者顯示的功能表項目 UI 標籤。
    • 功能表項目的類型。
    • 鍵盤快速鍵 描述，如果有的話，例如 Alt+C。
    • 自訂功能表項目的任何其他屬性。

  • 要求操作功能表的座標，以便您的應用程式可以偵測使用者以滑鼠右鍵按一下的 UI 項目。 座標是根據 WebView2 控制項的左上角來定義。

  • 將包含所選 內容類型和適當操作功能表參數資料的選取物件。

當使用者在操作功能表上選取自訂功能表項目時，WebView2 控制項會 CustomItemSelected 觸發事件。

當您的主應用程式向 WebView2 指出使用者選取了操作功能表上的功能表項目時，WebView2 接著會執行選取的命令。

偵測使用者何時選取自訂功能表項目

您的主應用程式可以處理使用者選取的功能表項目，或者您的應用程式可以將功能表項目傳回 WebView2 控制項，以處理使用者選取的功能表項目。

您的主應用程式應該會接聽 CustomItemSelected 事件，當使用者在預設或自訂操作功能表上選取自訂功能表項目時，就會引發事件。

WebView2 控制項引發此事件，表示使用者已選取您的應用程式新增至操作功能表的自訂功能表項目。

如果使用者選取自訂功能表項目， CustomMenuItemSelected 則會在已選取的操作功能表項目物件上引發事件，在下列情況下：

  • 應用程式會新增自訂功能表項目，但會將操作功能表 UI 延遲到 WebView2 平台。

  • 應用程式會新增自訂功能表項目、顯示自訂 UI，並將屬性設定為 SelectedCommandId 自訂功能表項目的識別碼。

向 WebView2 報告選取的命令功能表項目

當使用者選取 WebView2 操作功能表命令 (自訂操作功能表) 中的預設功能表項目時，主應用程式可以選擇性地向 WebView2 報告該選取項目，以便 WebView2 叫用該命令。

自訂功能表項目

如果您的主應用程式將自訂功能表項目回報為選取的功能表項目，則 CustomMenuItemSelected 會針對該自訂功能表項目觸發事件。

停用操作功能表

屬性控制 AreDefaultContextMenusEnabled 是否可以開啟任何操作功能表。 如果 WebView2 AreDefaultContextMenusEnabled 設定設為 False，會停用操作功能表，且 ContextMenuRequested 事件將不會引發，例如當使用者按右鍵時。

API 參考概觀

另請參閱

  • 上次更新時間：