Các tiện ích Manifest V2 đã bị gỡ khỏi Cửa hàng Chrome trực tuyến vào ngày 31 tháng 8 năm 2026. Hãy di chuyển tiện ích của bạn sang Manifest V3 để người dùng có thể sử dụng lại tiện ích.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

chrome.commands

refresh date: 2026-09-25 robots: noindex

Mô tả

Sử dụng API lệnh để thêm phím tắt kích hoạt các thao tác trong tiện ích, chẳng hạn như thao tác mở thao tác trên trình duyệt hoặc gửi lệnh đến tiện ích.

Tệp kê khai

Bạn phải khai báo các khoá sau trong tệp kê khai để sử dụng API này.

"commands"

Cách sử dụng

Commands API cho phép nhà phát triển tiện ích xác định các lệnh cụ thể và liên kết các lệnh đó với một tổ hợp phím mặc định. Mỗi lệnh mà tiện ích chấp nhận phải được khai báo dưới dạng thuộc tính của đối tượng "commands" trong tệp kê khai của tiện ích.

Khoá thuộc tính được dùng làm tên của lệnh. Đối tượng lệnh có thể có hai thuộc tính.

suggested_key

Một thuộc tính không bắt buộc khai báo phím tắt mặc định cho lệnh. Nếu bạn bỏ qua, lệnh sẽ không được liên kết. Thuộc tính này có thể nhận giá trị chuỗi hoặc giá trị đối tượng.

Giá trị chuỗi chỉ định phím tắt mặc định nên được dùng trên tất cả các nền tảng.
Giá trị đối tượng cho phép nhà phát triển tiện ích tuỳ chỉnh phím tắt cho từng nền tảng. Khi cung cấp phím tắt dành riêng cho nền tảng, các thuộc tính đối tượng hợp lệ là default, chromeos, linux, mac và windows.

Hãy xem phần Yêu cầu về tổ hợp phím để biết thêm thông tin.

description

Một chuỗi dùng để cung cấp cho người dùng nội dung mô tả ngắn gọn về mục đích của lệnh. Chuỗi này xuất hiện trong giao diện người dùng quản lý phím tắt của tiện ích. Nội dung mô tả là bắt buộc đối với các lệnh tiêu chuẩn, nhưng bị bỏ qua đối với Lệnh hành động.

Một tiện ích có thể có nhiều lệnh, nhưng có thể chỉ định tối đa 4 phím tắt được đề xuất. Người dùng có thể thêm các lối tắt khác theo cách thủ công trong hộp thoại chrome://extensions/shortcuts.

Khoá được hỗ trợ

Các phím sau đây là phím tắt lệnh có thể sử dụng. Định nghĩa khoá có phân biệt chữ hoa chữ thường. Nếu bạn cố gắng tải một tiện ích có khoá không đúng kiểu chữ, thì lỗi phân tích cú pháp tệp kê khai sẽ xảy ra tại thời điểm cài đặt.

Phím chữ cái: A … Z
Phím số: 0 … 9
Chuỗi khoá chuẩn: Chung – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete; Các phím mũi tên – Up, Down, Left, Right; Phím điều khiển nội dung nghe nhìn – MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop
Chuỗi phím bổ trợ: Ctrl, Alt (Option trên macOS), Shift, MacCtrl (chỉ trên macOS), Command (chỉ trên macOS), Search (chỉ trên ChromeOS)

Lưu ý: Tab đã bị xoá khỏi danh sách các phím được hỗ trợ trong Chrome 33 vì lý do hỗ trợ tiếp cận.

Yêu cầu về tổ hợp phím

Phím tắt lệnh của tiện ích phải bao gồm Ctrl hoặc Alt.
- Bạn không thể sử dụng phím bổ trợ kết hợp với Phím điều khiển nội dung nghe nhìn.
Trên macOS, Ctrl sẽ tự động được chuyển đổi thành Command.
- Để sử dụng phím Control trên macOS, hãy thay thế Ctrl bằng MacCtrl khi xác định phím tắt "mac".
- Việc sử dụng MacCtrl trong tổ hợp phím cho một nền tảng khác sẽ gây ra lỗi xác thực và ngăn tiện ích cài đặt.
Shift là một đối tượng sửa đổi không bắt buộc trên tất cả các nền tảng.
Search là một đối tượng sửa đổi không bắt buộc dành riêng cho ChromeOS.
Một số phím tắt của hệ điều hành và Chrome (ví dụ: quản lý cửa sổ) luôn được ưu tiên hơn Phím tắt lệnh của tiện ích và không thể ghi đè.

Lưu ý:Không được phép sử dụng các tổ hợp phím có liên quan đến Ctrl+Alt để tránh xung đột với phím AltGr.

Xử lý sự kiện lệnh

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

Trong trình chạy dịch vụ, bạn có thể liên kết một trình xử lý với từng lệnh được xác định trong tệp kê khai bằng onCommand.addListener. Ví dụ:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Lệnh hành động

Các lệnh _execute_action (Manifest V3), _execute_browser_action (Manifest V2) và _execute_page_action (Manifest V2) được dành riêng cho hành động kích hoạt hành động, hành động trên trình duyệt hoặc hành động trên trang tương ứng. Các lệnh này không gửi sự kiện command.onCommand như các lệnh tiêu chuẩn.

Nếu bạn cần thực hiện hành động dựa trên việc mở cửa sổ bật lên, hãy cân nhắc việc theo dõi sự kiện DOMContentLoaded bên trong JavaScript của cửa sổ bật lên.

Phạm vi

Theo mặc định, các lệnh được áp dụng cho trình duyệt Chrome. Điều này có nghĩa là khi trình duyệt không được lấy tiêu điểm, các phím tắt lệnh sẽ không hoạt động. Kể từ Chrome 35, nhà phát triển tiện ích có thể tuỳ ý đánh dấu một lệnh là "global" (toàn cục). Các lệnh chung cũng hoạt động khi Chrome không được lấy tiêu điểm.

Đề xuất phím tắt cho các lệnh chung chỉ giới hạn ở Ctrl+Shift+[0..9]. Đây là một biện pháp bảo vệ nhằm giảm thiểu rủi ro ghi đè phím tắt trong các ứng dụng khác, vì nếu cho phép Alt+P làm phím tắt chung, thì phím tắt để mở hộp thoại in có thể không hoạt động trong các ứng dụng khác.

Người dùng cuối có thể tự do ánh xạ lại các lệnh chung cho tổ hợp phím mà họ muốn bằng cách sử dụng giao diện người dùng hiển thị tại chrome://extensions/shortcuts.

Ví dụ:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Ví dụ

Các ví dụ sau đây thể hiện chức năng cốt lõi của Commands API.

Lệnh cơ bản

Lệnh cho phép tiện ích liên kết logic với phím tắt mà người dùng có thể gọi. Ở mức cơ bản nhất, một lệnh chỉ yêu cầu khai báo lệnh trong tệp kê khai của tiện ích và đăng ký trình nghe như trong ví dụ sau.

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Lệnh hành động

Như mô tả trong phần Cách sử dụng, bạn cũng có thể liên kết một lệnh với hành động của tiện ích. Ví dụ sau đây chèn một tập lệnh nội dung cho thấy cảnh báo trên trang hiện tại khi người dùng nhấp vào thao tác của tiện ích hoặc kích hoạt phím tắt.

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

Xác minh các lệnh đã đăng ký

Nếu một tiện ích cố gắng đăng ký một phím tắt đã được một tiện ích khác sử dụng, thì phím tắt của tiện ích thứ hai sẽ không đăng ký như mong đợi. Bạn có thể mang lại trải nghiệm người dùng cuối mạnh mẽ hơn bằng cách dự đoán khả năng này và kiểm tra xung đột tại thời điểm cài đặt.

Lưu ý:_execute_action sẽ không xuất hiện trong danh sách lệnh do commands.getAll() trả về.

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (reason === chrome.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  chrome.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

Loại

Command

Thuộc tính

mô tả

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

Nội dung mô tả lệnh của tiện ích
tên

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

Tên của Lệnh tiện ích
lối tắt

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

Phím tắt đang hoạt động cho lệnh này hoặc để trống nếu không hoạt động.

Phương thức

getAll()

Promise

chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

Trả về tất cả lệnh tiện ích đã đăng ký cho tiện ích này và phím tắt của lệnh (nếu có). Trước phiên bản Chrome 110, lệnh này không trả về _execute_action.

Thông số

callback

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

Tham số callback có dạng như sau:
```
(commands: Command[]) => void
```
- lệnh
  
  Command[]

Giá trị trả về

Lời hứa<Lệnh[]>

Chrome 96 trở lên

Phân giải bằng danh sách các lệnh đã đăng ký.

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

onCommand

chrome.commands.onCommand.addListener(
  callback: function,
)

Được kích hoạt khi một lệnh đã đăng ký được kích hoạt bằng phím tắt.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(command: string, tab?: tabs.Tab) => void
```
- command
  
  chuỗi
- thẻ
  
  tabs.Tab không bắt buộc

chrome.commands Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Tệp kê khai

Cách sử dụng

Khoá được hỗ trợ

Yêu cầu về tổ hợp phím

Xử lý sự kiện lệnh

Lệnh hành động

Phạm vi

Ví dụ

Lệnh cơ bản

Lệnh hành động

Xác minh các lệnh đã đăng ký

Loại

Command

Thuộc tính

Phương thức

getAll()

Thông số

Giá trị trả về

Sự kiện

onCommand

Thông số

chrome.commands