chrome.browserAction

Deskripsi

Gunakan tindakan browser untuk meletakkan ikon di toolbar utama Google Chrome, di sebelah kanan kolom URL. Selain ikon, tindakan browser dapat memiliki tooltip, badge, dan popup.

Ketersediaan

≤ MV2

Pada gambar berikut, kotak warna-warni di sebelah kanan {i>address bar<i} adalah ikon untuk tindakan browser. Pop-up berada di bawah ikon.

Jika Anda ingin membuat ikon yang tidak selalu aktif, gunakan tindakan halaman, bukan browser tindakan.

Manifes

Daftarkan tindakan browser Anda di 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 ukuran terdekat dan menskalakannya ke ukuran yang sesuai untuk mengisi ruang 16 dip. Namun, jika ukuran yang tepat tidak diberikan, penskalaan dapat menyebabkan ikon kehilangan detail atau terlihat kabur.

Karena perangkat dengan faktor skala yang kurang umum seperti 1,5x atau 1,2x menjadi lebih umum, Anda sebaiknya sediakan beberapa ukuran untuk ikon Anda. Ini juga memastikan bahwa jika ukuran tampilan ikon pernah berubah, 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 turunan (piksel yang tidak tergantung perangkat). Lebih besar ikon diubah ukurannya agar sesuai, tetapi untuk hasil terbaik, gunakan ikon persegi 16-dip.

Anda dapat menyetel ikon dengan dua cara: menggunakan gambar statis atau menggunakan elemen kanvas HTML5. Menggunakan gambar statis lebih mudah digunakan untuk aplikasi sederhana, tetapi Anda dapat membuat UI yang lebih dinamis—seperti animasi yang mulus—menggunakan elemen kanvas.

Gambar statis dapat berupa format apa pun yang dapat ditampilkan WebKit, termasuk BMP, GIF, ICO, JPEG, atau PNG. Sebagai ekstensi yang tidak dibuka, gambar harus dalam format PNG.

Untuk menetapkan ikon, gunakan kolom default_icon dari default_icon di manifes, atau panggil metode browserAction.setIcon.

Untuk menampilkan ikon dengan benar saat kepadatan piksel layar (rasio size_in_pixel / size_in_dip) sama berbeda dari 1, ikon bisa didefinisikan sebagai serangkaian gambar dengan ukuran berbeda. Gambar sebenarnya untuk tampilan akan dipilih dari rangkaian yang paling sesuai dengan ukuran piksel 16 dip. Kumpulan ikon dapat berisi spesifikasi ikon ukuran apa pun, dan Chrome akan memilih yang paling sesuai.

Tooltip

Untuk menetapkan tooltip, gunakan kolom default_title dari default_title dalam manifes, atau panggil metode browserAction.setTitle. Anda bisa menetapkan string khusus lokalitas untuk kolom default_title; lihat Internasionalisasi untuk mengetahui detailnya.

Badge

Secara opsional, tindakan browser dapat menampilkan badge—sedikit teks yang menutupi ikon. Lencana memudahkan Anda memperbarui aksi browser untuk menampilkan sejumlah kecil informasi tentang status ekstensi.

Karena badge memiliki ruang terbatas, badge harus memiliki 4 karakter atau kurang.

Menetapkan teks dan warna badge menggunakan browserAction.setBadgeText dan browserAction.setBadgeBackgroundColor.

Jika tindakan browser memiliki pop-up, pop-up tersebut akan muncul saat pengguna mengklik ikon ekstensi. Tujuan dapat berisi konten HTML apa pun yang Anda sukai, dan ukurannya otomatis disesuaikan dengan kontennya. Pop-up tidak boleh lebih kecil dari 25x25 dan tidak boleh lebih besar dari 800x600.

Untuk menambahkan pop-up ke tindakan browser, buat file HTML dengan konten pop-up tersebut. Tentukan File HTML di kolom default_popup default_popup dalam manifes, atau panggil Metode browserAction.setPopup.

Tips

Untuk dampak visual terbaik, ikuti panduan berikut:

  • Gunakan tindakan browser untuk fitur yang tersedia di sebagian besar halaman.
  • Jangan gunakan tindakan browser untuk fitur yang hanya dapat digunakan oleh beberapa halaman. Gunakan halaman tindakan sebagai gantinya.
  • Gunakan ikon besar dan penuh warna yang memaksimalkan ruang celup 16x16. Ikon tindakan browser akan tampak sedikit lebih besar dan lebih berat daripada ikon tindakan halaman.
  • Jangan berupaya meniru ikon menu monokrom Google Chrome. Tidak cocok dengan tema, dan bagaimanapun, ekstensi harus sedikit menonjol.
  • Gunakan transparansi alfa untuk menambahkan tepi yang halus ke ikon Anda. Karena banyak orang menggunakan tema, ikon harus terlihat bagus pada berbagai warna latar belakang.
  • Jangan terus menganimasikan ikon Anda. Menjengkelkan.

Contoh

Anda dapat menemukan contoh sederhana penggunaan tindakan browser di examples/api/browserAction saat ini. Untuk contoh lainnya 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

    angka opsional

    ID tab yang akan dimintakan status. Jika tidak ada tab yang ditentukan, status non-tab tertentu akan ditampilkan.

Metode

disable()

Janji 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Menonaktifkan tindakan browser untuk tab.

Parameter

  • tabId

    angka opsional

    ID tab tempat Anda akan mengubah tindakan browser.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

enable()

Janji 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Mengaktifkan tindakan browser untuk tab. Nilai defaultnya adalah diaktifkan.

Parameter

  • tabId

    angka opsional

    ID tab tempat Anda akan mengubah tindakan browser.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

getBadgeBackgroundColor()

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

Mendapatkan warna latar belakang tindakan browser.

Parameter

Hasil

  • Promise&lt;ColorArray&gt;

    Chrome 88 dan yang lebih baru

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

getBadgeText()

Janji 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

Mendapatkan teks badge tindakan browser. Jika tidak ada tab yang ditentukan, teks badge yang bukan khusus tab akan ditampilkan.

Parameter

  • detail

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (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()

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

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

Parameter

  • detail

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (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()

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

Mendapatkan judul tindakan browser.

Parameter

  • detail

    TabDetails

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (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()

Janji 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Menetapkan warna latar belakang untuk badge.

Parameter

  • detail

    objek

    • warna

      string | ColorArray

      Array berisi empat bilangan bulat dalam rentang 0-255 yang membentuk warna RGBA badge. Dapat juga berupa string dengan nilai warna heksadesimal CSS; misalnya, #FF0000 atau #F00 (merah). Merender warna pada opasitas penuh.

    • tabId

      angka opsional

      Membatasi perubahan saat tab tertentu dipilih. Otomatis direset saat tab ditutup.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

setBadgeText()

Janji 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Menetapkan teks badge untuk tindakan browser. Badge ditampilkan di bagian atas ikon.

Parameter

  • detail

    objek

    • tabId

      angka opsional

      Membatasi perubahan saat tab tertentu dipilih. Otomatis direset saat tab ditutup.

    • teks

      string opsional

      Karakter dalam jumlah berapa pun dapat dimasukkan, tetapi hanya sekitar empat karakter yang dapat masuk ke dalam ruang. Jika string kosong ('') diteruskan, teks badge akan dihapus. Jika tabId ditentukan dan text bernilai null, teks untuk tab yang ditentukan akan dihapus dan defaultnya adalah teks badge global.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

setIcon()

Janji 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

Mengatur ikon untuk tindakan browser. Ikon bisa ditetapkan sebagai jalur ke file gambar, sebagai data piksel dari elemen kanvas, atau sebagai kamus salah satunya. Properti path atau imageData harus ditentukan.

Parameter

  • detail

    objek

    • imageData

      ImageData | objek opsional

      Objek ImageData atau kamus {size -> ImageData} mewakili ikon yang akan ditetapkan. Jika ikon ditetapkan sebagai kamus, gambar yang akan 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' sama dengan 'details.imageData = {'16': foo}'

    • jalur

      string | objek opsional

      Baik jalur gambar relatif maupun kamus {size -> relatif image path} menunjuk ke ikon yang akan diatur. Jika ikon ditetapkan sebagai kamus, gambar yang akan 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' sama dengan 'details.path = {'16': foo}'

    • tabId

      angka opsional

      Membatasi perubahan saat tab tertentu dipilih. Otomatis direset saat tab ditutup.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 116 dan yang lebih baru

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

setPopup()

Janji 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

Menyetel dokumen HTML agar dibuka sebagai pop-up saat pengguna mengklik ikon tindakan browser.

Parameter

  • detail

    objek

    • pop-up

      string

      Jalur relatif ke file HTML yang akan ditampilkan di pop-up. Jika ditetapkan ke string kosong (''), pop-up tidak akan ditampilkan.

    • tabId

      angka opsional

      Membatasi perubahan saat tab tertentu dipilih. Otomatis direset saat tab ditutup.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

setTitle()

Janji 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Menetapkan judul tindakan browser. Judul ini muncul di tooltip.

Parameter

  • detail

    objek

    • tabId

      angka opsional

      Membatasi perubahan saat tab tertentu dipilih. Otomatis direset saat tab ditutup.

    • judul

      string

      String yang harus ditampilkan tindakan browser saat kursor diarahkan ke atasnya.

  • callback

    fungsi opsional

    Chrome 67 dan yang lebih baru

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 88 dan yang lebih baru

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

Acara

onClicked

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

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

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (tab: tabs.Tab) => void