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
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ẹ.
Tệp kê khai
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 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 contextMenu trong kho lưu trữ chrome-extension-samples.
Loại
ContextType
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
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
chuỗi | số 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ínhsrc
của thẻimg
,audio
,video
và thuộc tínhhref
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) => {...}
-
info
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ô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
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ênMã 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.
-
chuỗi | số
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
chuỗi | số 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
.
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ặt hàng mới tạo.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Xoá một mục trong trình đơn theo bối cảnh.
Tham số
-
chuỗi | 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ề
-
Promise<void>
Chrome 123 trở lênLờ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()
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.
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ề
-
Promise<void>
Chrome 123 trở lênLờ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()
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
chuỗi | số
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
chuỗi | số 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ênLiệ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) => {...}
-
infoChrome 44 trở lên
-
tabChrome 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ênLờ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 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
-
tab
tabs.Tab không bắt buộc
-