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ó 2 thuộc tính.

suggested_key

Một thuộc tính không bắt buộc, dùng để khai báo các 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 cần 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 tổ hợp phím cho từng nền tảng. Khi cung cấp các 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 Yêu cầu về tổ hợp phím để biết thêm thông tin chi tiết.

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. Bạn phải cung cấp nội dung mô tả cho các lệnh chuẩn, nhưng nội dung mô tả sẽ bị bỏ qua đối với lệnh Hành động.

Tiện ích có thể có nhiều lệnh, nhưng chỉ được phép chỉ định tối đa 4 phím tắt đề 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. Việc cố gắng tải một tiện ích có khoá không đúng cách 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

Các 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 của tiện ích phải có Ctrl hoặc Alt.

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

  • Trên nhiều bàn phím macOS, Alt là phím Option.

  • Trên macOS, bạn cũng có thể 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ể dùng Command trong phím 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 phím 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 không cho tiện ích được 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 chỉ 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 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 cách sử dụ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 của 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 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 lắng nghe 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à "toàn cục" (không bắt buộc). Các lệnh chung cũng hoạt động ngay cả khi Chrome không được chọn làm ứng dụng hoạt động.

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

Lệnh cơ bản

Lệnh cho phép các 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. Ở mức cơ bản nhất, một lệnh chỉ yêu cầu một khai báo lệnh trong tệp kê khai của tiện ích và một hoạt động đă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 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 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 tìm cách đă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ư dự kiến. Bạn có thể mang đến trải nghiệm mạnh mẽ hơn 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.
    }
  });
}

chrome.commands.getAll(): Promise<Command[]>

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