chrome.contextMenus

Mô tả

Sử dụng API chrome.contextMenus để thêm các 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à các mục bổ sung trong trình đơn theo bối cảnh áp dụng, chẳng hạn như hình ảnh, đường liên kết siêu 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. Ngoài ra, bạn nên chỉ định một biểu tượng 16x16 pixel để hiển thị bên cạnh mục 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 bất kỳ tài liệu nào (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 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 bạn 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ỳ ý, nhưng nếu nhiều mục trong tiện ích của bạn xuất hiện 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 contextMenus từ kho lưu trữ chrome-extension-samples.

Loại

ContextType

Chrome 44 trở lên

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

"page"

"khung"

"selection"

"đường liên kết"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 trở lên

Thuộc tính của mục trình đơn ngữ 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 cho trạng thái đã chọn, false cho trạng thái chưa 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.

  • ngữ cảnh

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

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

  • documentUrlPatterns

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

    Hạn chế 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 thông tin chi tiết về định dạng mẫu, hãy xem phần Mẫu 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 có được 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 để chỉ định cho mục này. Bắt buộc đối với trang sự kiện. Không được trùng với mã nhận dạng khác của tiện ích này.

  • parentId

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

    Mã của một mục trình đơn mẹ; điều này khiến mục này trở thành mục con của một 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, audio và video cũng như thuộc tính href của thẻ a.

  • tiêu đề

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

    Văn bản cần hiển thị trong mục; đây là thông tin 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 thị văn bản đã chọn. Ví dụ: nếu giá trị của thông số này là "Dịch "%s" sang tiếng La Tinh" và người dùng chọn từ "cool", thì mục trình đơn theo bối cảnh cho lựa chọn này sẽ là "Dịch "cool" sang tiếng La Tinh".

  • 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ó xuất hiện trong trình đơn hay không.

  • onclick

    void không bắt buộc

    Hàm được gọi lại khi người dùng nhấp vào mục trong trình đơn. Bạn không thể sử dụng tính năng này bên trong 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ục được nhấp và bối cảnh xảy ra lượt nhấp.

    • phím tab

      Tab

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

ItemType

Chrome 44 trở lên

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

Enum

"bình thường"

"checkbox"

"radio"

"separator"

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 chọn sau khi người dùng nhấp vào hộp đánh dấu hoặc mục chọn đó.

  • có thể chỉnh sửa

    boolean

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

  • frameId

    số không bắt buộc

    Chrome 51 trở lên

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

  • frameUrl

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

    URL của khung của phần tử mà bạn đã nhấp vào trình đơn theo bối cảnh, nếu phần tử đó nằm trong 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à đường liên kết đó trỏ đến.

  • mediaType

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

    Một trong các giá trị "image" (hình ảnh), "video" (video) hoặc "audio" (âm thanh) 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

    chuỗi | số

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

  • pageUrl

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

    URL của trang mà 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

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

    Mã nhận dạng của phần tử mẹ (nếu có) cho mục đã nhấp.

  • selectionText

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

    Văn bản cho lựa chọn theo 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 được 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 hành động 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 trình đơn theo ngữ cảnh mới. Nếu xảy ra lỗi trong quá trình tạo, lỗi đó có thể không được phát hiện cho đến khi lệnh gọi lại tạo được kích hoạt; thông tin chi tiết sẽ có trong runtime.lastError.

Tham số

  • createProperties

    CreateProperties

  • lệnh gọi lại

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

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

    () => void

Giá trị trả về

  • số | chuỗi

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

remove()

Promise 
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

    chuỗi | số

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

  • lệnh gọi lại

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

    Tham số callback 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

Tham số

  • lệnh gọi lại

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

    Tham số callback 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

update()

Promise 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

Tham số

  • id

    chuỗi | 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 như hàm contextMenus.create.

    • đã chọn

      boolean không bắt buộc

    • ngữ 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

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

      Mã của mục sẽ được đặt làm mục mẹ của mục này. Lưu ý: Bạn không thể đặt một mục thành phần 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

      void 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

        Tab

        Chrome 44 trở lên

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

  • lệnh gọi lại

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

    Tham số callback 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 Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo 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ẽ 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 người dùng nhấp vào một mục trong trình đơn theo bối cảnh.

Tham số