chrome.contextMenus

Nội dung mô tả

Sử 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 những loại đối tượng có thể áp dụng cho trình đơn theo bối cảnh, chẳng hạn như hình ảnh, siêu liên kết và trang.

Quyền

contextMenus

Bạn phải khai báo quyền "contextMenus" trong tệp kê khai của tiện ích để sử dụng API này. Ngoài ra, bạn nên chỉ định biểu tượng 16 x 16 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"
  },
  ...
}

Khái niệm và cách sử dụng

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

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

Ví dụ

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

Loại

ContextType

Chrome 44 trở lên

Các ngữ cảnh khác nhau mà trình đơn có thể xuất hiện. Việc chỉ định "all" tương đương với sự kết hợp của tất cả các bối cảnh khác, ngoại trừ "launcher". Ngữ cảnh "trình chạy" chỉ được ứng dụng hỗ trợ và 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 bạn nhấp vào biểu tượng ứng dụng trong trình chạy/thanh tác vụ/dock/v.v.. Các nền tảng có thể giới hạn 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.

Liệt kê

"selection"

"video"

"launcher"

"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 nếu đã chọn, false nếu không chọn. Mỗi lần, bạn chỉ có thể chọn một nút chọn trong một nhóm nhất định.

  • bối cảnh

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

    Danh sách ngữ cảnh sẽ xuất hiện cho mục này trong trình đơ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. Để biết chi tiết về định dạng mẫu, hãy xem Mẫu so khớp.

  • đ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ã nhận dạng khác cho phần mở rộng này.

  • parentId

    string|number không bắt buộc

    Mã nhận dạng của mục trong trình đơn gốc; mục này làm cho mục này là con của mục đã thêm trước đó.

  • targetUrlPatterns

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

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

  • title

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

    Văn bản cần hiển thị trong mục; đây là văn bản bắt buộc trừ phi type là separator. Khi ngữ cảnh là selection, hãy sử dụng %s trong chuỗi để hiện văn bản đã chọn. Ví dụ: nếu giá trị của tham số này là "Translate '%s' to Pig Latin" và người dùng chọn từ "cool", mục trình đơn theo bối cảnh cho lựa chọn sẽ là "Dịch "ngon" sang Tiếng 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

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

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

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

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

    • tab

      Thẻ

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

ItemType

Chrome 44 trở lên

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

Liệt kê

"radio"

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

    Cờ cho biết trạng thái của hộp đánh dấu hoặc mục radio sau khi được 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ử mà trình đơn theo bối cảnh được nhấp vào, nếu mã này nằm trong một khung.

  • frameUrl

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

    URL của khung của phần tử mà trình đơn theo bối cảnh được nhấp vào, nếu URL này 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 thuộc tính "hình ảnh", "video" hoặc "âm thanh" nếu trình đơn theo bối cảnh được kích hoạt trên một trong những loại phần tử này.

  • menuItemId

    string|number

    Mã của món trong thực đơn được nhấp vào.

  • pageUrl

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

    URL của trang đã 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 mà không có trang hiện tại, chẳng hạn như trong menu ngữ cảnh của trình chạy.

  • parentMenuItemId

    string|number không bắt buộc

    Mã nhận dạng chính (nếu có) của mặt hàng đượ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ẽ xuất hiện cho các phần tử có URL "src".

  • wasChecked

    boolean không bắt buộc

    Cờ cho biết trạng thái của hộp đánh dấu hoặc mục chọn 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 của 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 trên 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 của quá trình tạo được kích hoạt. Thông tin chi tiết sẽ có trong runtime.lastError.

Thông số

  • createProperties

    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ề

  • number|string

    Mã của mặt hàng mới tạo.

remove()

Cam kết 
chrome.contextMenus.remove(
  menuItemId: string|number,
  callback?: function,
)

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

Thông số

  • menuItemId

    string|number

    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ề

  • Promise<void>

    Chrome 123 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

removeAll()

Cam kết 
chrome.contextMenus.removeAll(
  callback?: function,
)

Xoá tất cả các mục trong trình đơn theo bối cảnh mà phần mở rộng này thêm vào.

Thông 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ề

  • Promise<void>

    Chrome 123 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

update()

Cam kết 
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 đó.

Thông số

  • id

    string|number

    Mã của mục 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ị tương tự như 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|number không bắt buộc

      Mã của mục sẽ được đặt thành mục gốc 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 thành phần con cháu của mục đó.

    • targetUrlPatterns

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

    • title

      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 sẽ có dạng như sau: 

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

      • Chrome 44 trở lên
      • tab

        Thẻ

        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 có 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ề

  • Promise<void>

    Chrome 123 trở lên

    Lời hứa được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp để có khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ được phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

Sự kiện

onClicked

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

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

Thông số