chrome.contextMenus

Deskripsi

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

Izin

contextMenus

Anda harus mendeklarasikan izin "contextMenus" dalam manifes ekstensi Anda untuk menggunakan API. Selain itu, Anda harus menentukan ikon berukuran 16 x 16 piksel untuk tampilan di sebelah 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 dalam dokumen (atau bingkai dalam dokumen), bahkan dengan file:// atau URL chrome://. Untuk mengontrol dokumen tempat item Anda dapat ditampilkan, tentukan Kolom documentUrlPatterns saat Anda memanggil metode create() atau update().

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

Contoh

Untuk mencoba API ini, instal contohcontextMenus API dari chrome-extension-samples repositori resource.

Jenis

ContextType

Chrome 44 dan yang lebih baru

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

Enum

"semua"

"halaman"

"bingkai"

"selection"

"link"

"editable"

"gambar"

"video"

"audio"

"peluncur"

"browser_action"

"page_action"

"tindakan"

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 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 diterapkan pada dokumen atau bingkai yang URL-nya cocok dengan salah satu pola yang diberikan. 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 | angka opsional

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

  • targetUrlPatterns

    string[] opsional

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

  • judul

    string opsional

    Teks yang akan ditampilkan dalam item; ini wajib kecuali 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 "cool", item menu konteks untuk pilihan ini adalah "Terjemahkan 'cool' menjadi Pig Latin".

  • jenis

    ItemType opsional

    Jenis item menu. Default-nya adalah normal.

  • terlihat

    boolean opsional

    Apakah item terlihat di menu.

  • onclick

    batal 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 akan terlihat seperti ini: 

    (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 dan yang lebih baru

Jenis item menu.

Enum

"normal"

"kotak centang"

"radio"

"pemisah"

OnClickData

Informasi yang dikirim saat item menu konteks diklik.

Properti

  • dicentang

    boolean opsional

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

  • dapat diedit

    boolean

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

  • frameId

    angka opsional

    Chrome 51 dan yang lebih baru

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

  • frameUrl

    string opsional

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

  • linkUrl

    string opsional

    Jika elemennya adalah link, URL yang ditujunya.

  • mediaType

    string opsional

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

  • menuItemId

    string | angka

    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 mendukung 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 'src' .

  • wasChecked

    boolean opsional

    Tanda yang menunjukkan status kotak centang atau item pilihan 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 error selama pembuatan, error tersebut mungkin tidak akan terdeteksi hingga callback pembuatan diaktifkan; detailnya akan tersedia dalam runtime.lastError.

Parameter

  • createProperties

    CreateProperties

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • angka | {i>string<i}

    ID item yang baru dibuat.

remove()

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

Menghapus item menu konteks.

Parameter

  • menuItemId

    string | angka

    ID item menu konteks yang akan dihapus.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

removeAll()

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

Menghapus semua item menu konteks yang ditambahkan oleh ekstensi ini.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

update()

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

Memperbarui item menu konteks yang dibuat sebelumnya.

Parameter

  • id

    string | angka

    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 dan yang lebih baru

      Apakah item terlihat di menu.

    • onclick

      batal opsional

      Fungsi onclick akan terlihat seperti ini: 

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

      • Chrome 44 dan yang lebih baru
      • tab

        Tab

        Chrome 44 dan yang lebih baru

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

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onClicked

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

Diaktifkan saat item menu konteks diklik.

Parameter