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

chrome.commands

Mô tả

Sử dụng API lệnh để thêm phím tắt kích hoạt thao tác trong tiện ích của bạn, ví dụ: 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"

Khái niệm và 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 chúng với một lệnh mặc định tổ hợp phím. Bạn phải khai báo mỗi lệnh mà một tiện ích chấp nhận là 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. Các đối tượng lệnh có thể nhận hai thuộc tính.

suggested_key

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

Giá trị chuỗi chỉ định phím tắt mặc định sẽ được sử dụng trên tất cả các phím tắt 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 mỗi giá trị chủ. Khi cung cấp lối tắt dành riêng cho nền tảng, các thuộc tính đối tượng hợp lệ sẽ là default, chromeos, linux, mac và windows.

Hãy xem mục Yêu cầu đối với tổ hợp phím để biết thêm thông tin chi tiết.

description

Chuỗi được dùng để cung cấp cho người dùng đoạn mô tả ngắ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 tiện ích. Bạn phải nhập nội dung mô tả cho quảng cáo chuẩn nhưng bị bỏ qua đối với các Lệnh thao tác.

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. Chiến lược phát hành đĩa đơn người dùng có thể thêm các lối tắt khác theo cách thủ công qua hộp thoại chrome://extensions/shortcuts.

Phím được hỗ trợ

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

Phím alpha: A... Z
Phím số: 0... 9
Chuỗi phím chuẩn: Chung – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete; Các phím mũi tên – Up, Down, Left, Right; Khoá nội dung đa phương tiện – MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop
Chuỗi phím của đối tượng sửa đổi: Ctrl, Alt (Option trên macOS), Shift, MacCtrl (chỉ dành cho MacOS), Command (chỉ trên MacOS), Search (chỉ dành cho ChromeOS)

Lưu ý: Tab đã bị xoá khỏi danh sách khoá đượ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ể dùng kết hợp đối tượng sửa đổi với Phím nội dung nghe nhìn.
Trên macOS, Ctrl sẽ tự động 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 "mac" lối tắt.
- Việc sử dụng MacCtrl kết hợp cho một nền tảng khác sẽ gây ra lỗi xác thực và khiến tiện ích không được cài đặt.
Shift là đố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 Chrome và hệ điều hành (ví dụ: quản lý cửa sổ) luôn được ưu tiên hơn Các phím tắt của lệnh tiện ích và không được ghi đè.

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

Xử lý các 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 đang sử dụng onCommand.addListener. Ví dụ:

service-worker.js:

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

Lệnh thao tác

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

Nếu bạn cần thực hiện hành động dựa trên mở cửa sổ bật lên, hãy cân nhắc lắng nghe 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 chỉ dành cho trình duyệt Chrome. Điều này có nghĩa là khi trình duyệt không có tiêu điểm, phím tắt lệnh không hoạt động. Kể từ Chrome 35, nhà phát triển tiện ích có thể tùy chọn đánh dấu lệnh là "toàn cầu". Các lệnh chung cũng hoạt động trong khi Chrome không có tiêu điểm.

Các đề xuất phím tắt cho các lệnh chung chỉ được dùng trong Ctrl+Shift+[0..9]. Đây là một biện pháp bảo vệ để giảm thiểu rủi ro ghi đè lối tắt trong các ứng dụng khác vì nếu, ví dụ: Alt+P được cho phép sử dụng chung, là 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ể tuỳ ý ánh xạ lại các lệnh chung với tổ hợp phím họ muốn bằng cách sử dụng giao diện người dùng được hiển thị lúc 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

Các lệnh cho phép tiện ích liên kết logic với các phím tắt mà người dùng có thể gọi. Tại thời điểm cơ bản nhất là 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à 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 thao tác

Như đã mô tả trong phần Khái niệm và cách sử dụng, bạn cũng có thể ánh xạ lệnh đến hành động. Ví dụ sau đây chèn một tập lệnh nội dung hiển thị cảnh báo trên trang hiện tại khi người dùng nhấp vào hành động 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 lối tắt đã được một tiện ích khác sử dụng, thì lối tắt của tiện ích thứ hai sẽ không đăng ký như mong đợi. Bạn có thể cung cấp cho người dùng cuối 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.

service-worker.js:

chrome.runtime.onInstalled.addListener((details) => {
  if (details.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

description

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

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

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

Tên của Lệnh mở rộng
lối tắt

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

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

Phương thức

getAll()

Lời hứa

chrome.commands.getAll(
  callback?: function,
)

Trả về tất cả các lệnh tiện ích mở rộng đã đăng ký cho tiện ích này và lối tắt của chúng (nếu đang hoạt động). Trước Chrome 110, lệnh này không trả về _execute_action.

Tham số

số gọi lại

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

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

Giá trị trả về

Lời hứa<Command[]>

Chrome 96 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

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.

Tham số

số gọi lại

hàm

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