chrome.action

Deskripsi

Ketersediaan

Manifes

Untuk menggunakan chrome.action API, tentukan "manifest_version" 3 dan sertakan kunci "action" dalam file manifes Anda.

{   "name": "Action Extension",   ...   "action": {     "default_icon": {              // optional       "16": "images/icon16.png",   // optional       "24": "images/icon24.png",   // optional       "32": "images/icon32.png"    // optional     },     "default_title": "Click Me",   // optional, shown in tooltip     "default_popup": "popup.html"  // optional   },   ... } 

Kunci "action" (beserta turunannya) bersifat opsional. Jika tidak disertakan, ekstensi Anda tetap ditampilkan di toolbar untuk memberikan akses ke menu ekstensi. Oleh karena itu, sebaiknya Anda selalu menyertakan setidaknya kunci "action" dan "default_icon".

Konsep dan penggunaan

Bagian-bagian UI

Ikon

Ikon adalah gambar utama di toolbar untuk ekstensi Anda, dan ditetapkan oleh kunci "default_icon" di kunci "action" manifes Anda. Ikon harus memiliki lebar dan tinggi 16 piksel independen perangkat (DIP).

Kunci "default_icon" adalah kamus ukuran ke jalur gambar. Chrome menggunakan ikon ini untuk memilih skala gambar yang akan digunakan. Jika kecocokan persis tidak ditemukan, Chrome akan memilih kecocokan terdekat yang tersedia dan menskalakannya agar sesuai dengan gambar, yang dapat memengaruhi kualitas gambar.

Karena perangkat dengan faktor skala yang kurang umum seperti 1,5x atau 1,2x menjadi lebih umum, sebaiknya Anda menyediakan beberapa ukuran untuk ikon Anda. Hal ini juga akan membuat ekstensi Anda siap menghadapi perubahan ukuran tampilan ikon di masa mendatang. Namun, jika hanya memberikan satu ukuran, kunci "default_icon" juga dapat ditetapkan ke string dengan jalur ke satu ikon, bukan kamus.

Anda juga dapat memanggil action.setIcon() untuk menyetel ikon ekstensi Anda secara terprogram dengan menentukan jalur gambar yang berbeda atau memberikan ikon yang dibuat secara dinamis menggunakan elemen canvas HTML, atau, jika menyetel dari pekerja layanan ekstensi, API canvas di luar layar.

const canvas = new OffscreenCanvas(16, 16); const context = canvas.getContext('2d'); context.clearRect(0, 0, 16, 16); context.fillStyle = '#00FF00';  // Green context.fillRect(0, 0, 16, 16); const imageData = context.getImageData(0, 0, 16, 16); chrome.action.setIcon({imageData: imageData}, () => { /* ... */ }); 

Untuk ekstensi yang dikemas (diinstal dari file .crx), gambar dapat menggunakan sebagian besar format yang dapat ditampilkan oleh mesin rendering Blink, termasuk PNG, JPEG, BMP, ICO, dan lainnya. SVG tidak didukung. Ekstensi yang belum di-unzip harus menggunakan gambar PNG.

Tooltip (judul)

Tooltip, atau judul, akan muncul saat pengguna menahan kursor mouse di atas ikon ekstensi di toolbar. Teks ini juga disertakan dalam teks yang dapat diakses yang diucapkan oleh pembaca layar saat tombol mendapatkan fokus.

Tooltip default ditetapkan menggunakan kolom "default_title" dari kunci "action" di manifest.json. Anda juga dapat menyetelnya secara terprogram dengan memanggil action.setTitle().

Badge

Tindakan dapat menampilkan "badge" secara opsional — sedikit teks yang disusun di atas ikon. Hal ini memungkinkan Anda memperbarui tindakan untuk menampilkan sedikit informasi tentang status ekstensi, seperti penghitung. Badge memiliki komponen teks dan warna latar belakang. Karena ruang terbatas, sebaiknya teks badge menggunakan empat karakter atau kurang.

Untuk membuat badge, tetapkan secara terprogram dengan memanggil action.setBadgeBackgroundColor() dan action.setBadgeText(). Tidak ada setelan badge default dalam manifes. Nilai warna badge dapat berupa array empat bilangan bulat antara 0 dan 255 yang membentuk warna RGBA badge atau string dengan nilai warna CSS.

chrome.action.setBadgeBackgroundColor(   {color: [0, 255, 0, 0]},  // Green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: '#00FF00'},  // Also green   () => { /* ... */ }, );  chrome.action.setBadgeBackgroundColor(   {color: 'green'},  // Also, also green   () => { /* ... */ }, ); 

Pop-up

Pop-up tindakan ditampilkan saat pengguna mengklik tombol tindakan ekstensi di toolbar. Pop-up dapat berisi konten HTML apa pun yang Anda inginkan, dan ukurannya akan otomatis disesuaikan agar sesuai dengan kontennya. Ukuran pop-up harus antara 25x25 dan 800x600 piksel.

Pop-up awalnya ditetapkan oleh properti "default_popup" dalam kunci "action" di file manifest.json. Jika ada, properti ini harus mengarah ke jalur relatif dalam direktori ekstensi. Juga dapat diperbarui secara dinamis untuk mengarah ke jalur relatif yang berbeda menggunakan metode action.setPopup().

Kasus penggunaan

Status per tab

Tindakan ekstensi dapat memiliki status yang berbeda untuk setiap tab. Untuk menetapkan nilai untuk setiap tab, gunakan properti tabId di metode setelan action API. Misalnya, untuk menetapkan teks badge untuk tab tertentu, lakukan sesuatu seperti berikut:

function getTabId() { /* ... */} function getTabBadge() { /* ... */}  chrome.action.setBadgeText(   {     text: getTabBadge(tabId),     tabId: getTabId(),   },   () => { ... } ); 

Jika properti tabId tidak disertakan, setelan akan diperlakukan sebagai setelan global. Setelan khusus tab lebih diprioritaskan daripada setelan global.

Status diaktifkan

Secara default, tindakan toolbar diaktifkan (dapat diklik) di setiap tab. Anda dapat mengubah default ini dengan menetapkan properti default_state di kunci action manifes. Jika default_state disetel ke "disabled", tindakan akan dinonaktifkan secara default dan harus diaktifkan secara terprogram agar dapat diklik. Jika default_state ditetapkan ke "enabled" (default), tindakan diaktifkan dan dapat diklik secara default.

Anda dapat mengontrol status secara terprogram menggunakan metode action.enable() dan action.disable(). Hal ini hanya memengaruhi apakah pop-up (jika ada) atau peristiwa action.onClicked dikirim ke ekstensi Anda; hal ini tidak memengaruhi keberadaan tindakan di toolbar.

Contoh

Contoh berikut menunjukkan beberapa cara umum tindakan digunakan dalam ekstensi. Untuk mencoba API ini, instal contoh Action API dari repositori chrome-extension-samples.

Menampilkan pop-up

Ekstensi biasanya menampilkan pop-up saat pengguna mengklik tindakan ekstensi. Untuk menerapkan ini di ekstensi Anda sendiri, deklarasikan pop-up di manifest.json dan tentukan konten yang harus ditampilkan Chrome di pop-up.

// manifest.json {   "name": "Action popup demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to view a popup",     "default_popup": "popup.html"   } } 

<!-- popup.html --> <!DOCTYPE html> <html> <head>   <style>     html {       min-height: 5em;       min-width: 10em;       background: salmon;     }   </style> </head> <body>   <p>Hello, world!</p> </body> </html> 

Menyisipkan skrip konten saat diklik

Pola umum untuk ekstensi adalah mengekspos fitur utamanya menggunakan tindakan ekstensi. Contoh berikut menunjukkan pola ini. Saat pengguna mengklik tindakan, ekstensi menyuntikkan skrip konten ke halaman saat ini. Kemudian, skrip konten menampilkan dialog notifikasi untuk memverifikasi bahwa semuanya berfungsi seperti yang diharapkan.

// manifest.json {   "name": "Action script injection demo",   "version": "1.0",   "manifest_version": 3,   "action": {     "default_title": "Click to show an alert"   },   "permissions": ["activeTab", "scripting"],   "background": {     "service_worker": "background.js"   } } 

// background.js chrome.action.onClicked.addListener((tab) => {   chrome.scripting.executeScript({     target: {tabId: tab.id},     files: ['content.js']   }); }); 

// content.js alert('Hello, world!'); 

Meniru tindakan dengan declarativeContent

Contoh ini menunjukkan cara logika latar belakang ekstensi dapat (a) menonaktifkan tindakan secara default dan (b) menggunakan declarativeContent untuk mengaktifkan tindakan di situs tertentu.

// service-worker.js  // Wrap in an onInstalled callback to avoid unnecessary work // every time the service worker is run chrome.runtime.onInstalled.addListener(() => {   // Page actions are disabled by default and enabled on select tabs   chrome.action.disable();    // Clear all rules to ensure only our expected rules are set   chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {     // Declare a rule to enable the action on example.com pages     let exampleRule = {       conditions: [         new chrome.declarativeContent.PageStateMatcher({           pageUrl: {hostSuffix: '.example.com'},         })       ],       actions: [new chrome.declarativeContent.ShowAction()],     };      // Finally, apply our new array of rules     let rules = [exampleRule];     chrome.declarativeContent.onPageChanged.addRules(rules);   }); }); 

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

chrome.action.onClicked.addListener(
  callback: function,
)

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)