chrome.commands

Mô tả

Tệp kê khai

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 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ị bỏ qua, lệnh sẽ không được liên kết. Thuộc tính này có thể nhận một chuỗi hoặc một giá trị đối tượng.

• Giá trị chuỗi chỉ định phím tắt mặc định cần sử 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 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 sẽ 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 chỉ được 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 từ hộp thoại chrome://extensions/shortcuts.

Các phím được hỗ trợ

Các phím sau đây là các 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. Việc cố gắng tải một tiện ích có khoá viết hoa 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 điểm cài đặt.

Khoá alpha

A … Z

Phím số

0 … 9

Chuỗi khoá tiêu chuẩn

Chung – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Phím mũi tên –Up, Down, Left, Right

Phím đa phương tiện –MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Chuỗi phím bổ trợ

Ctrl, Alt, Shift, MacCtrl (chỉ dành cho macOS), Command (chỉ dành cho macOS), Search (chỉ dành cho ChromeOS)

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

• Phím tắt lệnh tiện ích phải bao gồm Ctrl hoặc Alt.

  • Bạn không thể sử dụng các đối tượng sửa đổi kết hợp với Phím đa phương tiện.

  • Trên nhiều bàn phím macOS, Alt đề cập đến phím Option.

  • Trên macOS, bạn cũng có thể sử dụng Command hoặc MacCtrl thay cho Ctrl hoặc Alt (xem dấu đầu dòng tiếp theo).

• Trên macOS, Ctrl sẽ tự động chuyển đổi thành Command.

  • Bạn cũng có thể sử dụng Command trong lối tắt "mac" để tham chiếu rõ ràng đến phím Command.

  • Để sử dụng phím Control trên macOS, hãy thay thế Ctrl bằng MacCtrl khi xác định lối tắt "mac".

  • Việc sử dụng MacCtrl trong tổ hợp cho một nền tảng khác sẽ gây ra lỗi xác thực và ngăn việc cài đặt tiện ích.

• 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 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 đè.

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 worker 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 (Tệp kê khai V3), _execute_browser_action (Tệp kê khai V2) và _execute_page_action (Tệp kê khai V2) được dành riêng cho thao tác kích hoạt thao tác, thao tác trình duyệt hoặc thao tác trên trang tương ứng. Các lệnh này không gửi các 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 giới hạn trong 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, 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ể đánh dấu một lệnh là "chung" (không bắt buộc). Các lệnh toàn cục cũng hoạt động khi Chrome không có tiêu điểm.

Đề xuất phím tắt cho các lệnh toàn cục chỉ giới hạn ở Ctrl+Shift+[0..9]. Đây là biện pháp bảo vệ để giảm thiểu nguy cơ ghi đè lối tắt trong các ứng dụng khác vì nếu, ví dụ: Alt+P được cho phép ở chế độ toàn cục, 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 thành 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 API Lệnh.

Lệnh cơ bản

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. Ở cấp độ 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 Khái niệm và cách sử dụng, bạn cũng có thể liên kết một lệnh với thao tác của tiện ích. Ví dụ sau đây sẽ 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 mà 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ư dự kiến. Bạn có thể mang đến 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.

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.
    }
  });
}

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

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