Deskripsi
Gunakan chrome.action
API untuk mengontrol ikon ekstensi di toolbar Google Chrome.
Ketersediaan
Manifes
Untuk menggunakan chrome.action
API, tentukan "manifest_version"
dari 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. Bila ekstensi tidak disertakan, ekstensi Anda akan tetap ditampilkan di toolbar untuk memberikan akses ke menu ekstensi. Karena itu, sebaiknya selalu sertakan 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"
dalam
kunci "action"
manifes Anda. Ikon harus memiliki lebar dan tinggi 16 piksel yang tidak tergantung perangkat (DIP).
Kunci "default_icon"
adalah kamus ukuran untuk jalur gambar. Chrome menggunakan ikon-ikon ini untuk memilih
skala gambar mana yang akan digunakan. Jika pencocokan persis tidak ditemukan, Chrome akan memilih yang terdekat
tersedia dan menskalakannya agar sesuai dengan gambar, yang mungkin memengaruhi kualitas gambar.
Karena perangkat dengan faktor skala yang kurang umum seperti 1,5x atau 1,2x menjadi lebih umum, sebaiknya sediakan beberapa ukuran untuk ikon. Hal ini juga akan membuat ekstensi Anda siap menghadapi masa depan terhadap potensi perubahan ukuran tampilan ikon.
Anda juga dapat memanggil action.setIcon()
untuk menetapkan ikon ekstensi secara terprogram dengan menentukan jalur gambar yang berbeda atau memberikan ikon yang dibuat secara dinamis menggunakan elemen kanvas HTML, atau, jika disetel dari pekerja layanan ekstensi, API kanvas non-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 dipaketkan (diinstal dari file .crx), gambar dapat berupa sebagian besar format yang dapat ditampilkan oleh mesin rendering Blink, termasuk PNG, JPEG, BMP, ICO, dan lainnya. SVG tidak didukung. Ekstensi yang tidak dipaketkan harus menggunakan gambar PNG.
Tooltip (judul)
Tooltip, atau judul, muncul saat pengguna mengarahkan kursor mouse ke ikon ekstensi di toolbar. Hal ini juga disertakan dalam teks yang dapat diakses yang diucapkan oleh pembaca layar saat tombol menjadi fokus.
Tooltip default ditetapkan menggunakan kolom "default_title"
dari kunci "action"
di manifest.json
.
Anda juga dapat menetapkannya secara terprogram dengan memanggil action.setTitle()
.
Badge
Action secara opsional dapat menampilkan "badge" — teks yang berlapis di atas ikon. Hal ini memungkinkan Anda memperbarui tindakan untuk menampilkan sejumlah kecil 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 di 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 sukai, dan akan disesuaikan ukurannya secara otomatis agar sesuai dengan kontennya. Ukuran pop-up harus antara 25x25 dan 800x600 piksel.
Pop-up awalnya ditetapkan oleh properti "default_popup"
di kunci "action"
dalam
file manifest.json
. Jika ada, properti ini harus mengarah ke jalur relatif dalam direktori ekstensi. Kolom ini juga dapat diperbarui secara dinamis agar 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 masing-masing tab, gunakan properti tabId
dalam metode setelan API action
. Misalnya, untuk menetapkan teks badge bagi tab tertentu, lakukan hal seperti berikut:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Jika properti tabId
tidak disertakan, setelan ini 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 mengontrolnya menggunakan
metode action.enable()
dan action.disable()
. Ini hanya memengaruhi apakah peristiwa pop-up (jika ada) atau action.onClicked
dikirim ke ekstensi Anda; tidak memengaruhi kehadiran tindakan di toolbar.
Contoh
Contoh berikut menunjukkan beberapa cara umum penggunaan tindakan dalam ekstensi. Untuk mencoba API ini, instal contoh Action API dari repositori chrome-extension-samples.
Menampilkan pop-up
Sangat umum bagi ekstensi untuk menampilkan pop-up saat pengguna mengklik tindakan ekstensi. Untuk
menerapkannya di ekstensi Anda sendiri, deklarasikan pop-up di manifest.json
dan tentukan
konten yang akan ditampilkan Chrome di pop-up tersebut.
// 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>
Memasukkan skrip konten saat diklik
Pola umum untuk ekstensi adalah mengekspos fitur utamanya menggunakan tindakan ekstensi. Contoh berikut ini menunjukkan pola tersebut. Saat pengguna mengklik tindakan tersebut, ekstensi akan memasukkan skrip konten ke halaman saat ini. Skrip konten kemudian menampilkan pemberitahuan untuk memverifikasi bahwa semuanya bekerja 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!');
Mengemulasi tindakan dengan deklaratifContent
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);
});
});
Jenis
OpenPopupOptions
Properti
-
windowId
nomor opsional
ID jendela untuk membuka pop-up tindakan. Setelan defaultnya adalah jendela yang sedang aktif jika tidak ditentukan.
TabDetails
Properti
-
tabId
nomor opsional
ID tab untuk status kueri. Jika tidak ada tab yang ditentukan, status non-khusus tab akan ditampilkan.
UserSettings
Kumpulan setelan yang ditentukan pengguna yang berkaitan dengan tindakan ekstensi.
Properti
-
isOnToolbar
boolean
Apakah ikon tindakan ekstensi terlihat di toolbar tingkat atas jendela browser (yakni, apakah ekstensi telah 'disematkan' oleh pengguna).
Metode
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
Menonaktifkan tindakan untuk tab.
Parameter
-
tabId
nomor opsional
ID tab yang tindakannya ingin Anda ubah.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Mengaktifkan tindakan untuk tab. Secara default, tindakan diaktifkan.
Parameter
-
tabId
nomor opsional
ID tab yang tindakannya ingin Anda ubah.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Mendapatkan warna latar belakang tindakan.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: ColorArray)=>void
-
hasil
-
Hasil
-
Promise<browserAction.ColorArray>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Mendapatkan teks badge tindakan. Jika tidak ada tab yang ditentukan, teks badge yang tidak khusus tab akan ditampilkan. Jika displayActionCountAsBadgeText diaktifkan, teks placeholder akan ditampilkan kecuali jika izin declarativeNetRequestFeedback ada atau teks badge khusus tab diberikan.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string)=>void
-
hasil
string
-
Hasil
-
Promise<string>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Mendapatkan warna teks tindakan.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: ColorArray)=>void
-
hasil
-
Hasil
-
Promise<browserAction.ColorArray>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Mendapatkan dokumen HTML yang ditetapkan sebagai pop-up untuk tindakan ini.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string)=>void
-
hasil
string
-
Hasil
-
Promise<string>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Mendapatkan judul tindakan.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string)=>void
-
hasil
string
-
Hasil
-
Promise<string>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Menampilkan setelan yang ditentukan pengguna terkait tindakan ekstensi.
Parameter
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(userSettings: UserSettings)=>void
-
userSettings
-
Hasil
-
Promise<UserSettings>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Menunjukkan apakah tindakan ekstensi diaktifkan untuk tab (atau secara global jika tabId
tidak disediakan). Tindakan yang diaktifkan hanya menggunakan declarativeContent
akan selalu menampilkan nilai salah.
Parameter
-
tabId
nomor opsional
ID tab tempat Anda ingin memeriksa status diaktifkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(isEnabled: boolean)=>void
-
isEnabled
boolean
True jika tindakan ekstensi diaktifkan.
-
Hasil
-
Promise<boolean>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Membuka pop-up ekstensi.
Parameter
-
opsi
OpenPopupOptions opsional
Menentukan opsi untuk membuka pop-up.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Menetapkan warna latar belakang untuk badge.
Parameter
-
detail
objek
-
warna
string|ColorArray
Array empat bilangan bulat dalam rentang [0,255] yang membentuk warna RGBA badge. Misalnya, merah buram adalah
[255, 0, 0, 255]
. Bisa juga berupa string dengan nilai CSS, dengan warna merah buram#FF0000
atau#F00
. -
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Menetapkan teks badge untuk tindakan. Badge ditampilkan di bagian atas ikon.
Parameter
-
detail
objek
-
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
teks
string opsional
Berapa pun jumlah karakter dapat diteruskan, tetapi hanya sekitar empat karakter yang dapat dimuat dalam ruang. Jika string kosong (
''
) diteruskan, teks badge akan dihapus. JikatabId
ditentukan dantext
adalah null, teks untuk tab yang ditentukan akan dihapus dan ditetapkan secara default ke teks badge global.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
Menetapkan warna teks untuk badge.
Parameter
-
detail
objek
-
warna
string|ColorArray
Array empat bilangan bulat dalam rentang [0,255] yang membentuk warna RGBA badge. Misalnya, merah buram adalah
[255, 0, 0, 255]
. Bisa juga berupa string dengan nilai CSS, dengan warna merah buram#FF0000
atau#F00
. Tidak menetapkan nilai ini akan menyebabkan warna dipilih secara otomatis yang akan kontras dengan warna latar belakang badge sehingga teks akan terlihat. Warna dengan nilai alfa yang setara dengan 0 tidak akan ditetapkan dan akan menampilkan error. -
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
Menetapkan ikon untuk tindakan. Ikon dapat ditetapkan sebagai jalur ke file gambar atau sebagai data piksel dari elemen kanvas, atau sebagai kamus untuk salah satu dari ikon tersebut. Properti path atau imageData harus ditentukan.
Parameter
-
detail
objek
-
imageData
ImageData|objek opsional
Objek ImageData atau kamus {size -> ImageData} yang mewakili ikon yang akan disetel. Jika ikon ditetapkan sebagai kamus, gambar sebenarnya yang akan digunakan akan dipilih, bergantung pada kepadatan piksel layar. Jika jumlah piksel gambar yang sesuai dengan satu unit ruang layar sama dengan
scale
, maka gambar dengan ukuranscale
* n akan dipilih, dengan n adalah ukuran ikon di UI. Minimal satu gambar harus ditentukan. Perhatikan bahwa 'details.imageData = foo' setara dengan 'details.imageData = {'16': foo}' -
jalur
string|object opsional
Baik jalur gambar relatif atau kamus {size -> relative image path} yang mengarah ke ikon yang akan ditetapkan. Jika ikon ditetapkan sebagai kamus, gambar sebenarnya yang akan digunakan akan dipilih, bergantung pada kepadatan piksel layar. Jika jumlah piksel gambar yang sesuai dengan satu unit ruang layar sama dengan
scale
, maka gambar dengan ukuranscale
* n akan dipilih, dengan n adalah ukuran ikon di UI. Minimal satu gambar harus ditentukan. Perhatikan bahwa 'details.path = foo' setara dengan 'details.path = {'16': foo}' -
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
Menetapkan dokumen HTML yang akan dibuka sebagai pop-up saat pengguna mengklik ikon tindakan.
Parameter
-
detail
objek
-
pop-up
string
Jalur relatif ke file HTML yang akan ditampilkan dalam pop-up. Jika ditetapkan ke string kosong (
''
), tidak ada pop-up yang ditampilkan. -
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Menetapkan judul tindakan. ID ini ditampilkan di tooltip.
Parameter
-
detail
objek
-
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
title
string
String yang akan ditampilkan tindakan saat kursor diarahkan ke string tersebut.
-
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:()=>void
Hasil
-
Promise<void>
Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.