chrome.contextMenus

Deskripsi

Gunakan chrome.contextMenus API untuk menambahkan item ke menu konteks Google Chrome. Anda dapat memilih jenis objek yang akan diterapkan dengan penambahan menu konteks, seperti gambar, hyperlink, dan halaman.

Izin

contextMenus

Anda harus mendeklarasikan izin "contextMenus" dalam manifes ekstensi untuk menggunakan API. Selain itu, Anda harus menetapkan ikon berukuran 16 x 16 piksel untuk ditampilkan di samping item menu. Contoh:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Konsep dan penggunaan

Item menu konteks dapat muncul di dokumen apa pun (atau bingkai dalam dokumen), bahkan item dengan URL file:// atau chrome://. Untuk mengontrol dokumen mana yang dapat menampilkan item Anda, tentukan kolom documentUrlPatterns saat memanggil metode create() atau update().

Anda dapat membuat item menu konteks sebanyak yang dibutuhkan. Namun, jika lebih dari satu item dari ekstensi Anda terlihat sekaligus, Google Chrome akan otomatis menciutkannya menjadi satu menu induk.

Contoh

Untuk mencoba API ini, instal contoh contextMenus API dari repositori chrome-extension-samples.

Jenis

ContextType

Chrome 44+

Berbagai konteks yang dapat menampilkan menu. Menentukan 'all' setara dengan kombinasi semua konteks lainnya kecuali untuk 'launcher'. Konteks 'peluncur' hanya didukung oleh aplikasi dan digunakan untuk menambahkan item menu ke menu konteks yang muncul saat mengklik ikon aplikasi di peluncur/taskbar/dock/dll. Platform yang berbeda mungkin membatasi apa yang sebenarnya didukung dalam menu konteks peluncur.

Enum

"selection"

"link"

"video"

"audio"

"browser_action"

"page_action"

CreateProperties

Chrome 123 dan yang lebih baru

Properti item menu konteks baru.

Properti

  • dicentang

    boolean opsional

    Status awal kotak centang atau tombol pilihan: true untuk dipilih, false untuk tidak dipilih. Hanya satu tombol pilihan yang dapat dipilih pada satu waktu di grup tertentu.

  • konteks

    [ContextType,...ContextType[]] opsional

    Daftar konteks akan menampilkan item menu ini. Default-nya adalah ['page'].

  • documentUrlPatterns

    string[] opsional

    Membatasi item agar hanya diterapkan pada dokumen atau bingkai yang URL-nya cocok dengan salah satu pola yang ditentukan. Untuk mengetahui detail tentang format pola, lihat Pencocokan Pola.

  • diaktifkan

    boolean opsional

    Apakah item menu konteks ini diaktifkan atau dinonaktifkan. Default-nya adalah true.

  • id

    string opsional

    ID unik yang akan ditetapkan ke item ini. Wajib untuk halaman acara. Tidak boleh sama dengan ID lain untuk ekstensi ini.

  • parentId

    string|number opsional

    ID item menu induk; ini membuat item menjadi turunan dari item yang ditambahkan sebelumnya.

  • targetUrlPatterns

    string[] opsional

    Serupa dengan documentUrlPatterns, filter berdasarkan atribut src dari tag img, audio, dan video serta atribut href dari tag a.

  • title

    string opsional

    Teks yang akan ditampilkan dalam item; ini wajib, kecuali jika type adalah separator. Jika konteksnya adalah selection, gunakan %s dalam string untuk menampilkan teks yang dipilih. Misalnya, jika nilai parameter ini adalah "Translate '%s' to Pig Latin" dan pengguna memilih kata "cool", item menu konteks untuk pilihan tersebut adalah "Translate 'cool' to Pig Latin".

  • tipe

    ItemType opsional

    Jenis item menu. Default-nya adalah normal.

  • terlihat

    boolean opsional

    Apakah item terlihat di menu.

  • onclick

    membatalkan opsional

    Fungsi yang dipanggil kembali saat item menu diklik. Ini tidak tersedia di dalam pekerja layanan; sebagai gantinya, Anda harus mendaftarkan pemroses untuk contextMenus.onClicked.

    Fungsi onclick terlihat seperti: 

    (info: OnClickData,tab: Tab)=> {...}

    • Informasi tentang item yang diklik dan konteks tempat klik terjadi.

    • Subscription

      Tab

      Detail tab tempat klik terjadi. Parameter ini tidak ada untuk aplikasi platform.

ItemType

Chrome 44+

Jenis item menu.

Enum

"normal"

"radio"

OnClickData

Informasi yang dikirim saat item menu konteks diklik.

Properti

  • dicentang

    boolean opsional

    Tanda yang menunjukkan status kotak centang atau item radio setelah diklik.

  • dapat diedit

    boolean

    Flag yang menunjukkan apakah elemen dapat diedit (text input, textarea, dll.).

  • frameId

    nomor opsional

    Chrome 51+

    ID frame elemen tempat menu konteks diklik, jika berada dalam frame.

  • frameUrl

    string opsional

    URL frame elemen tempat menu konteks diklik, jika berada dalam frame.

  • linkUrl

    string opsional

    Jika elemen adalah link, URL yang dituju oleh elemen tersebut.

  • mediaType

    string opsional

    Salah satu dari 'gambar', 'video', atau 'audio' jika menu konteks diaktifkan pada salah satu jenis elemen ini.

  • menuItemId

    string|number

    ID item menu yang diklik.

  • pageUrl

    string opsional

    URL halaman tempat item menu diklik. Properti ini tidak ditetapkan jika klik terjadi dalam konteks tempat tidak ada halaman saat ini, seperti di menu konteks peluncur.

  • parentMenuItemId

    string|number opsional

    ID induk, jika ada, untuk item yang diklik.

  • selectionText

    string opsional

    Teks untuk pemilihan konteks, jika ada.

  • srcUrl

    string opsional

    Akan ada untuk elemen dengan URL 'src'.

  • wasChecked

    boolean opsional

    Tanda yang menunjukkan status kotak centang atau item radio sebelum diklik.

Properti

ACTION_MENU_TOP_LEVEL_LIMIT

Jumlah maksimum item ekstensi tingkat teratas yang dapat ditambahkan ke menu konteks tindakan ekstensi. Item apa pun yang melebihi batas ini akan diabaikan.

Nilai

6

Metode

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

Membuat item menu konteks baru. Jika terjadi selama pembuatan, error tersebut mungkin tidak akan terdeteksi hingga callback pembuatan diaktifkan. Detailnya akan ada di runtime.lastError.

Parameter

  • createProperties

    CreateProperties

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • number|string

    ID item yang baru dibuat.

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string|number,
  callback?: function,
)

Menghapus item menu konteks.

Parameter

  • menuItemId

    string|number

    ID item menu konteks yang akan dihapus.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 123 dan yang lebih baru

    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.

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
)

Menghapus semua item menu konteks yang ditambahkan oleh ekstensi ini.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 123 dan yang lebih baru

    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.

update()

Promise 
chrome.contextMenus.update(
  id: string|number,
  updateProperties: object,
  callback?: function,
)

Memperbarui item menu konteks yang dibuat sebelumnya.

Parameter

  • id

    string|number

    ID item yang akan diperbarui.

  • updateProperties

    objek

    Properti yang akan diperbarui. Menerima nilai yang sama dengan fungsi contextMenus.create.

    • dicentang

      boolean opsional

    • konteks

      [ContextType,...ContextType[]] opsional

    • documentUrlPatterns

      string[] opsional

    • diaktifkan

      boolean opsional

    • parentId

      string|number opsional

      ID item yang akan dibuat sebagai induk item ini. Catatan: Anda tidak dapat menetapkan item untuk menjadi turunan dari turunannya sendiri.

    • targetUrlPatterns

      string[] opsional

    • title

      string opsional

    • tipe

      ItemType opsional

    • terlihat

      boolean opsional

      Chrome 62 dan yang lebih baru

      Apakah item terlihat di menu.

    • onclick

      membatalkan opsional

      Fungsi onclick terlihat seperti: 

      (info: OnClickData,tab: Tab)=> {...}

      • Chrome 44+
      • Subscription

        Tab

        Chrome 44+

        Detail tab tempat klik terjadi. Parameter ini tidak ada untuk aplikasi platform.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    ()=>void

Hasil

  • Promise<void>

    Chrome 123 dan yang lebih baru

    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.

Acara

onClicked

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

Diaktifkan saat item menu konteks diklik.

Parameter