Deskripsi
Gunakan tindakan browser untuk menempatkan ikon di toolbar utama Google Chrome, di sebelah kanan kolom URL. Selain ikon, tindakan browser dapat memiliki tooltip, badge, dan pop-up.
Ketersediaan
Dalam gambar berikut, persegi warna-warni di sebelah kanan kolom URL adalah ikon untuk tindakan browser. Pop-up berada di bawah ikon.
Jika Anda ingin membuat ikon yang tidak selalu aktif, gunakan tindakan halaman, bukan tindakan browser.
Manifes
Daftarkan tindakan browser Anda dalam manifes ekstensi seperti ini:
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Anda dapat memberikan ikon ukuran apa pun untuk digunakan di Chrome, dan Chrome akan memilih ikon yang terdekat dan menskalakannya ke ukuran yang sesuai untuk mengisi ruang 16 celup. Namun, jika ukuran yang tepat tidak diberikan, penskalaan ini dapat menyebabkan ikon kehilangan detail atau terlihat tidak jelas.
Karena perangkat dengan faktor skala yang kurang umum seperti 1,5x atau 1,2x menjadi lebih umum, Anda dianjurkan untuk menyediakan beberapa ukuran ikon. Hal ini juga memastikan bahwa jika ukuran tampilan ikon pernah diubah, Anda tidak perlu melakukan pekerjaan lagi untuk menyediakan ikon yang berbeda.
Sintaksis lama untuk mendaftarkan ikon default masih didukung:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
Bagian-bagian UI
Tindakan browser dapat memiliki ikon, tooltip, badge, dan popup.
Ikon
Ikon tindakan browser di Chrome memiliki lebar dan tinggi 16 dip (piksel yang tidak tergantung perangkat). Ikon yang lebih besar diubah ukurannya agar sesuai, tetapi untuk hasil terbaik, gunakan ikon persegi 16 dip.
Anda dapat menetapkan ikon dengan dua cara: menggunakan gambar statis atau menggunakan elemen kanvas HTML5. Menggunakan gambar statis lebih mudah untuk aplikasi sederhana, tetapi Anda dapat membuat UI yang lebih dinamis—seperti animasi yang halus—menggunakan elemen kanvas.
Gambar statis dapat berupa format apa pun yang dapat ditampilkan WebKit, termasuk BMP, GIF, ICO, JPEG, atau PNG. Untuk ekstensi yang belum dipaketkan, gambar harus dalam format PNG.
Untuk menetapkan ikon, gunakan kolom default_icon dari default_icon dalam manifes, atau panggil
metode browserAction.setIcon
.
Untuk menampilkan ikon dengan benar saat kepadatan piksel layar (rasio size_in_pixel / size_in_dip
)
berbeda dari 1, ikon dapat ditentukan sebagai kumpulan gambar dengan ukuran yang berbeda. Gambar sebenarnya yang akan
ditampilkan akan dipilih dari kumpulan agar sesuai dengan ukuran piksel 16 dip. Kumpulan ikon dapat berisi
spesifikasi ikon apa pun, dan Chrome akan memilih ukuran yang paling sesuai.
Tooltip
Untuk menetapkan tooltip, gunakan kolom default_title dari default_title dalam manifes, atau
panggil metode browserAction.setTitle
. Anda dapat menentukan string khusus lokalitas untuk kolom
default_title. Lihat Internasionalisasi untuk mengetahui detailnya.
Badge
Tindakan browser secara opsional dapat menampilkan badge—teks yang berlapis di atas ikon. Badge memudahkan tindakan browser untuk menampilkan sejumlah kecil informasi tentang status ekstensi.
Karena badge memiliki ruang yang terbatas, badge harus terdiri dari 4 karakter atau kurang.
Tetapkan teks dan warna badge menggunakan browserAction.setBadgeText
dan
browserAction.setBadgeBackgroundColor
.
Pop-up
Jika tindakan browser memiliki pop-up, pop-up akan muncul saat pengguna mengklik ikon ekstensi. Jendela pop-up akan berisi konten HTML apa pun yang Anda sukai, dan ukurannya secara otomatis disesuaikan dengan kontennya. Pop-up tidak boleh lebih kecil dari 25x25 dan tidak boleh lebih dari 800x600.
Untuk menambahkan pop-up ke tindakan browser, buat file HTML dengan konten pop-up tersebut. Tentukan
file HTML di kolom default_popup dari default_popup dalam manifes, atau panggil
metode browserAction.setPopup
.
Tips
Untuk memberikan dampak visual terbaik, ikuti panduan berikut:
- Gunakan tindakan browser untuk fitur yang sesuai di sebagian besar halaman.
- Jangan gunakan tindakan browser untuk fitur yang hanya relevan untuk beberapa halaman. Gunakan tindakan halaman sebagai gantinya.
- Gunakan ikon besar penuh warna untuk memaksimalkan ruang penyesuaian 16x16. Ikon tindakan browser akan terlihat sedikit lebih besar dan lebih berat daripada ikon tindakan halaman.
- Jangan berupaya meniru ikon menu monokrom Google Chrome. Itu tidak sesuai dengan tema, dan bagaimanapun juga, ekstensi harus sedikit menonjol.
- Gunakan transparansi alfa untuk menambahkan tepi halus ke ikon Anda. Karena banyak orang menggunakan tema, ikon Anda harus terlihat bagus pada berbagai warna latar belakang.
- Jangan terus-menerus menganimasikan ikon Anda. Merepotkan.
Contoh
Anda dapat menemukan contoh sederhana penggunaan tindakan browser di direktori examples/api/browserAction. Untuk contoh lain dan bantuan dalam melihat kode sumber, lihat Contoh.
Jenis
ColorArray
Jenis
[angka, angka, angka, angka]
ImageDataType
Data piksel untuk gambar. Harus berupa objek ImageData; misalnya, dari elemen canvas
.
Jenis
ImageData
TabDetails
Properti
-
tabId
nomor opsional
ID tab untuk status kueri. Jika tidak ada tab yang ditentukan, status non-khusus tab akan ditampilkan.
Metode
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
Menonaktifkan tindakan browser untuk tab.
Parameter
-
tabId
nomor opsional
ID tab yang akan diubah tindakan browsernya.
-
callback
fungsi opsional
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
Mengaktifkan tindakan browser untuk tab. Setelan defaultnya adalah diaktifkan.
Parameter
-
tabId
nomor opsional
ID tab yang akan diubah tindakan browsernya.
-
callback
fungsi opsional
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Mendapatkan warna latar belakang tindakan browser.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: ColorArray) => void
-
hasil
-
Hasil
-
Promise<ColorArray>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
Mendapatkan teks badge tindakan browser. Jika tidak ada tab yang ditentukan, teks badge yang tidak khusus tab akan ditampilkan.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string) => void
-
hasil
string
-
Hasil
-
Promise<string>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Mendapatkan dokumen HTML yang ditetapkan sebagai pop-up untuk tindakan browser ini.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string) => void
-
hasil
string
-
Hasil
-
Promise<string>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Mendapatkan judul tindakan browser.
Parameter
-
detail
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(result: string) => void
-
hasil
string
-
Hasil
-
Promise<string>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
setBadgeBackgroundColor()
chrome.browserAction.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. Bisa juga berupa string dengan nilai warna heksadesimal CSS; misalnya,
#FF0000
atau#F00
(merah). Merender warna pada opasitas penuh. -
tabId
nomor opsional
Membatasi perubahan pada saat tab tertentu dipilih. Otomatis direset saat tab ditutup.
-
-
callback
fungsi opsional
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
Menetapkan teks badge untuk tindakan browser. 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 ke 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
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
Menetapkan ikon untuk tindakan browser. Ikon dapat ditetapkan sebagai jalur ke file gambar, sebagai data piksel dari elemen kanvas, atau sebagai kamus dari salah satu elemen 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 yang digunakan akan dipilih bergantung pada kepadatan piksel layar. Jika jumlah piksel gambar yang sesuai dengan satu unit ruang layar sama dengan
scale
, 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 | objek opsional
Jalur gambar relatif atau kamus {size -> relative image path} yang mengarah ke ikon yang akan ditetapkan. Jika ikon ditetapkan sebagai kamus, gambar yang digunakan akan dipilih bergantung pada kepadatan piksel layar. Jika jumlah piksel gambar yang sesuai dengan satu unit ruang layar sama dengan
scale
, 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 116 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
Menetapkan dokumen HTML yang akan dibuka sebagai pop-up saat pengguna mengklik ikon tindakan browser.
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
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
Menetapkan judul tindakan browser. Judul ini akan muncul 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 browser saat kursor diarahkan.
-
-
callback
fungsi opsional
Chrome 67 dan yang lebih baruParameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 88 dan yang lebih baruPromise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.