chrome.contextMenus

Deskripsi

Gunakan chrome.contextMenus API untuk menambahkan item ke menu konteks Google Chrome. Anda dapat memilih jenis objek yang akan diterapkan 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 menentukan ikon 16x16 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 dengan URL file:// atau chrome://. Untuk mengontrol dokumen tempat item Anda dapat muncul, tentukan kolom documentUrlPatterns saat Anda memanggil metode create() atau update().

Anda dapat membuat item menu konteks sebanyak yang diperlukan, tetapi jika lebih dari satu item dari ekstensi Anda terlihat sekaligus, Google Chrome akan otomatis menciutkan item tersebut ke dalam satu menu induk.

Contoh

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

Jenis

ContextType

Chrome 44+

Berbagai konteks tempat menu dapat muncul. Menentukan 'all' setara dengan kombinasi semua konteks lainnya kecuali '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 di menu konteks peluncur.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123+

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 dalam satu waktu dalam grup tertentu.

  • konteks

    [ContextType, ...ContextType[]] opsional

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

  • documentUrlPatterns

    string[] opsional

    Membatasi item agar hanya berlaku untuk dokumen atau frame yang URL-nya cocok dengan salah satu pola yang diberikan. Untuk mengetahui detail tentang format pola, lihat Pola Pencocokan.

  • 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 | angka opsional

    ID item menu induk; hal 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.

  • judul

    string opsional

    Teks yang akan ditampilkan di 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 "Terjemahkan '%s' ke Pig Latin" dan pengguna memilih kata "keren", item menu konteks untuk pilihan tersebut adalah "Terjemahkan 'keren' ke Pig Latin".

  • jenis

    ItemType opsional

    Jenis item menu. Default-nya adalah normal.

  • terlihat

    boolean opsional

    Apakah item terlihat di menu.

  • onclick

    void opsional

    Fungsi yang dipanggil kembali saat item menu diklik. Fungsi 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.

    • tab

      Tab

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

ItemType

Chrome 44+

Jenis item menu.

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informasi yang dikirim saat item menu konteks diklik.

Properti

  • dicentang

    boolean opsional

    Flag yang menunjukkan status kotak centang atau item pilihan setelah diklik.

  • dapat diedit

    boolean

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

  • frameId

    number opsional

    Chrome 51+

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

  • frameUrl

    string opsional

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

  • linkUrl

    string opsional

    Jika elemen adalah link, URL yang dituju.

  • mediaType

    string opsional

    Salah satu dari 'image', 'video', atau 'audio' jika menu konteks diaktifkan di 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 yang tidak memiliki halaman saat ini, seperti di menu konteks peluncur.

  • parentMenuItemId

    string | angka 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

    Flag yang menunjukkan status kotak centang atau item pilihan sebelum diklik.

Properti

ACTION_MENU_TOP_LEVEL_LIMIT

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

Nilai

6

Metode

create()

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

Membuat item menu konteks baru. Jika terjadi error selama pembuatan, error tersebut mungkin tidak 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+

    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+

    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 | angka opsional

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

    • targetUrlPatterns

      string[] opsional

    • judul

      string opsional

    • jenis

      ItemType opsional

    • terlihat

      boolean opsional

      Chrome 62+

      Apakah item terlihat di menu.

    • onclick

      void opsional

      Fungsi onclick terlihat seperti: 

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

      • Chrome 44+
      • tab

        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+

    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