Trang này được dịch bởi Cloud Translation API.

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

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 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 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.

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, audio và video 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 type là separator. 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) => {...}
```
- info
  
  OnClickData
  
  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ẻ
  
  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ị

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

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 được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến 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 được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng loại được truyền đến 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) => {...}
```
  - info
    
    OnClickData
    
    Chrome 44 trở lên
  - phím 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 á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 được hỗ trợ trong Manifest V3 trở lên nhưng lệnh gọi lại được cung cấp cho 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. Chiến lược phát hành đĩa đơn Promise phân giải cùng 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ố

số gọi lại

hàm

Tham số callback sẽ có dạng như sau:
```
(info: OnClickData, tab?: tabs.Tab) => void
```
- info
  
  OnClickData
- phím tab
  
  tabs.Tab không bắt buộc