chrome.contextMenus

Mô tả

Dùng API chrome.contextMenus để thêm mục vào trình đơn theo bối cảnh của Google Chrome. Bạn có thể chọn loại đối tượng mà phần bổ sung của trình đơn theo bối cảnh sẽ áp dụng, chẳng hạn như hình ảnh, siêu liên kết và trang.

Quyền

contextMenus

Cách sử dụng

Các mục trong trình đơn ngữ cảnh có thể xuất hiện trong bất kỳ tài liệu nào (hoặc khung trong một tài liệu), ngay cả những tài liệu có file:// hoặc URL chrome://. Để kiểm soát những tài liệu mà mặt hàng của bạn có thể xuất hiện, hãy chỉ định trường documentUrlPatterns khi bạn gọi phương thức create() hoặc update().

Bạn có thể tạo bao nhiêu mục trình đơn ngữ cảnh tuỳ thích, nhưng nếu có nhiều mục từ tiện ích của bạn hiển thị cùng lúc, Google Chrome sẽ tự động thu gọn chúng vào một trình đơn chính.

Tệp kê khai

Bạn phải khai báo các trường "contextMenus" trong tệp kê khai của tiện ích để sử dụng API. Ngoài ra, bạn nên chỉ định biểu tượng có kích thước 16x16 pixel để hiển thị bên cạnh mục trong trình đơn. Ví dụ:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Ví dụ

Để dùng thử API này, hãy cài đặt ví dụ về API contextMenus trong chrome-extension-samples kho lưu trữ.

Loại

ContextType

Chrome 44 trở lên

Các ngữ cảnh khác nhau mà một trình đơn có thể xuất hiện. Chỉ định "tất cả" tương đương với tổ hợp của tất cả các bối cảnh khác, ngoại trừ "trình chạy". "Trình chạy" ngữ cảnh chỉ được các ứng dụng hỗ trợ và được dùng để thêm các mục trong trình đơn vào trình đơn theo bối cảnh xuất hiện khi nhấp vào biểu tượng ứng dụng trong trình chạy/thanh tác vụ/giá đỡ/v.v. Các nền tảng khác nhau có thể đặt giới hạn về những nội dung thực sự được hỗ trợ trong trình đơn theo bối cảnh của trình chạy.

Enum

"tất cả"

"trang"

"khung"

"selection"

"link"

"chỉnh sửa"

"hình ảnh"

"video"

"audio"

"trình chạy"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 trở lên

Thuộc tính của mục trong trình đơn theo bối cảnh mới.

Thuộc tính

  • đã chọn

    boolean không bắt buộc

    Trạng thái ban đầu của hộp đánh dấu hoặc nút chọn: true khi chọn, false khi bỏ chọn. Bạn chỉ có thể chọn một nút chọn trong một nhóm nhất định tại một thời điểm.

  • bối cảnh

    [ContextType, ...ContextType[]] không bắt buộc

    Danh sách các bối cảnh mà mục này trong trình đơn sẽ xuất hiện. Giá trị mặc định là ['page'].

  • documentUrlPatterns

    string[] không bắt buộc

    Giới hạn mục để chỉ áp dụng cho các tài liệu hoặc khung có URL khớp với một trong các mẫu cho trước. Để biết thông tin chi tiết về định dạng mẫu, hãy xem So khớp mẫu.

  • đang bật

    boolean không bắt buộc

    Liệu mục trình đơn theo bối cảnh này đang bật hay tắt. Giá trị mặc định là true.

  • id

    chuỗi không bắt buộc

    Mã nhận dạng duy nhất để gán cho mục này. Bắt buộc đối với các trang sự kiện. Không được giống với một mã khác cho tiện ích này.

  • parentId

    string | số không bắt buộc

    Mã của một mục trong trình đơn gốc; thao tác này sẽ làm cho mục này trở thành phần tử con của mục đã thêm trước đó.

  • targetUrlPatterns

    string[] không bắt buộc

    Tương tự như documentUrlPatterns, các bộ lọc dựa trên thuộc tính src của thẻ img, audiovideo và thuộc tính href của thẻ a.

  • tiêu đề

    chuỗi không bắt buộc

    Văn bản để hiển thị trong mục; đây là bắt buộc trừ khi typeseparator. Khi ngữ cảnh là selection, hãy dùng %s trong chuỗi để hiện văn bản đã chọn. Ví dụ: nếu giá trị của thông số này là "Dịch '%s' thành Pig Latin" và người dùng chọn từ "tuyệt vời", mục trong trình đơn theo bối cảnh để lựa chọn là "Dịch "tuyệt vời" cho Pig Latin".

  • loại

    ItemType không bắt buộc

    Loại mục trong trình đơn. Giá trị mặc định là normal.

  • hiển thị

    boolean không bắt buộc

    Liệu mục có hiển thị trong trình đơn hay không.

  • onclick

    khoảng trống không bắt buộc

    Một hàm được gọi lại khi người dùng nhấp vào một mục trong trình đơn. Tính năng này không có bên trong một trình chạy dịch vụ; thay vào đó, bạn nên đăng ký trình nghe cho contextMenus.onClicked.

    Hàm onclick có dạng như sau:

    (info: OnClickData, tab: Tab) => {...}

    • Thông tin về mặt hàng được nhấp vào và bối cảnh nơi xảy ra lượt nhấp.

    • phím tab

      Thông tin chi tiết về thẻ nơi diễn ra lượt nhấp. Thông số này không áp dụng cho các ứng dụng nền tảng.

ItemType

Chrome 44 trở lên

Loại mục trong trình đơn.

Enum

"normal" (bình thường)

"hộp kiểm"

"radio"

"phân cách"

OnClickData

Thông tin được gửi khi người dùng nhấp vào một mục trong trình đơn theo bối cảnh.

Thuộc tính

  • đã chọn

    boolean không bắt buộc

    Một lá cờ cho biết trạng thái của một hộp đánh dấu hoặc mục radio sau khi người dùng nhấp vào.

  • có thể chỉnh sửa

    boolean

    Một cờ cho biết liệu phần tử có thể chỉnh sửa được hay không (nhập văn bản, vùng văn bản, v.v.).

  • frameId

    số không bắt buộc

    Chrome 51 trở lên

    Mã nhận dạng khung của phần tử nơi trình đơn theo bối cảnh được nhấp vào, nếu nằm trong một khung.

  • frameUrl

    chuỗi không bắt buộc

    URL của khung của phần tử nơi trình đơn theo bối cảnh được nhấp vào, nếu nằm trong một khung.

  • linkUrl

    chuỗi không bắt buộc

    Nếu phần tử là một đường liên kết, thì URL mà phần tử đó trỏ đến.

  • mediaType

    chuỗi không bắt buộc

    Một trong các giá trị "image", "video" hoặc "audio" nếu trình đơn theo bối cảnh đã được kích hoạt trên một trong các loại phần tử này.

  • menuItemId

    string | số

    Mã của mục trong trình đơn được nhấp vào.

  • pageUrl

    chuỗi không bắt buộc

    URL của trang nơi người dùng đã nhấp vào mục trong trình đơn. Thuộc tính này không được đặt nếu lượt nhấp xảy ra trong ngữ cảnh không có trang hiện tại, chẳng hạn như trong trình đơn theo bối cảnh của trình chạy.

  • parentMenuItemId

    string | số không bắt buộc

    Mã gốc (nếu có) của mục được nhấp vào.

  • selectionText

    chuỗi không bắt buộc

    Văn bản để lựa chọn ngữ cảnh, nếu có.

  • srcUrl

    chuỗi không bắt buộc

    Sẽ hiển thị cho các phần tử có "src" URL.

  • wasChecked

    boolean không bắt buộc

    Một cờ cho biết trạng thái của một hộp đánh dấu hoặc mục radio trước khi người dùng nhấp vào.

Thuộc tính

ACTION_MENU_TOP_LEVEL_LIMIT

Số lượng tối đa các mục tiện ích cấp cao nhất có thể được thêm vào trình đơn theo bối cảnh thao tác đối với tiện ích. Mọi mục vượt quá giới hạn này sẽ bị bỏ qua.

Giá trị

6

Phương thức

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

Tạo một mục mới trong trình đơn theo bối cảnh. Nếu xảy ra lỗi trong quá trình tạo, thì lỗi đó có thể không được phát hiện cho đến khi lệnh gọi lại quá trình tạo kích hoạt; thông tin chi tiết sẽ có trong runtime.lastError.

Tham số

  • createProperties
  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau:

    () => void

Giá trị trả về

  • số | chuỗi

    Mã của mục mới tạo.

remove()

Lời hứa
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

Xoá một mục trong trình đơn theo bối cảnh.

Tham số

  • menuItemId

    string | số

    Mã của mục trong trình đơn theo bối cảnh cần xoá.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau:

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 123 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

removeAll()

Lời hứa
chrome.contextMenus.removeAll(
  callback?: function,
)

Xoá tất cả các mục trong trình đơn theo bối cảnh do tiện ích này thêm.

Tham số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau:

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 123 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

update()

Lời hứa
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

Cập nhật một mục trong trình đơn theo bối cảnh đã tạo trước đó.

Tham số

  • id

    string | số

    Mã của mặt hàng cần cập nhật.

  • updateProperties

    đối tượng

    Các thuộc tính cần cập nhật. Chấp nhận các giá trị giống với hàm contextMenus.create.

    • đã chọn

      boolean không bắt buộc

    • bối cảnh

      [ContextType, ...ContextType[]] không bắt buộc

    • documentUrlPatterns

      string[] không bắt buộc

    • đang bật

      boolean không bắt buộc

    • parentId

      string | số không bắt buộc

      Mã của mục được đặt làm mục chính của mục này. Lưu ý: Bạn không thể đặt một mục trở thành phần tử con của chính mục đó.

    • targetUrlPatterns

      string[] không bắt buộc

    • tiêu đề

      chuỗi không bắt buộc

    • loại

      ItemType không bắt buộc

    • hiển thị

      boolean không bắt buộc

      Chrome 62 trở lên

      Liệu mục có hiển thị trong trình đơn hay không.

    • onclick

      khoảng trống không bắt buộc

      Hàm onclick có dạng như sau:

      (info: OnClickData, tab: Tab) => {...}

      • Chrome 44 trở lên
      • phím tab
        Chrome 44 trở lên

        Thông tin chi tiết về thẻ nơi diễn ra lượt nhấp. Thông số này không áp dụng cho các ứng dụng nền tảng.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback sẽ có dạng như sau:

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 123 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

Được kích hoạt khi người dùng nhấp vào một mục trong trình đơn theo bối cảnh.

Tham số