chrome.browserAction

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

≤ MV2

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.

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

Chrome 88 dan yang lebih baru

Properti

  • tabId

    nomor opsional

    ID tab untuk status kueri. Jika tidak ada tab yang ditentukan, status non-khusus tab akan ditampilkan.

Metode

disable()

Promise 
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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

enable()

Promise 
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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Mendapatkan warna latar belakang tindakan browser.

Parameter

Hasil

  • Promise<ColorArray>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

getBadgeText()

Promise 
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

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: string)=>void

    • hasil

      string

Hasil

  • Promise<string>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Mendapatkan dokumen HTML yang ditetapkan sebagai pop-up untuk tindakan browser ini.

Parameter

  • detail

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: string)=>void

    • hasil

      string

Hasil

  • Promise<string>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Mendapatkan judul tindakan browser.

Parameter

  • detail

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (result: string)=>void

    • hasil

      string

Hasil

  • Promise<string>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

setBadgeBackgroundColor()

Promise 
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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

setBadgeText()

Promise 
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. Jika tabId ditentukan dan text 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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

setIcon()

Promise 
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 ukuran scale * 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

      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 ukuran scale * 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 baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

setPopup()

Promise 
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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

setTitle()

Promise 
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 baru

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 88 dan yang lebih baru

    Promise hanya didukung untuk Manifes V3 dan yang lebih baru, platform lain perlu menggunakan callback.

Peristiwa

onClicked

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

Diaktifkan saat ikon tindakan browser diklik. Tidak aktif jika tindakan browser memiliki pop-up.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (tab: tabs.Tab)=>void