chrome.contextMenus

Deskripsi

Gunakan chrome.contextMenus API untuk menambahkan item ke menu konteks Google Chrome. Anda dapat memilih jenis objek yang akan diterapkan pada 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 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 mana pun (atau frame dalam dokumen), bahkan yang memiliki 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 Anda butuhkan, tetapi 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 API contextMenus dari repositori chrome-extension-samples.

Jenis

ContextType

Chrome 44+

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

"halaman"

"frame"

"selection"

"link"

"dapat diedit"

"image"

"video"

"audio"

"peluncur"

"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 | number opsional

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

  • targetUrlPatterns

    string[] opsional

    Mirip 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 dalam item; ini wajib diisi 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 dalam bahasa Pig Latin" dan pengguna memilih kata "cool", item menu konteks untuk pilihan tersebut adalah "Terjemahkan 'cool' ke dalam bahasa 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. Hal ini tidak tersedia di dalam pekerja layanan; sebagai gantinya, Anda harus mendaftarkan pemroses untuk contextMenus.onClicked.

    Fungsi onclick akan 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 item kotak centang atau pilihan setelah diklik.

  • dapat diedit

    boolean

    Tanda yang menunjukkan apakah elemen dapat diedit (input teks, 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 ditujunya.

  • mediaType

    string opsional

    Salah satu dari 'image', '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 yang tidak memiliki 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 pilihan konteks, jika ada.

  • srcUrl

    string opsional

    Akan ada untuk elemen dengan URL 'src'.

  • wasChecked

    boolean opsional

    Tanda yang menunjukkan status item kotak centang atau tombol 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,
): number | string

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

  • angka | string

    ID item yang baru dibuat.

remove()

chrome.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

Menghapus item menu konteks.

Parameter

  • menuItemId

    string | number

    ID item menu konteks yang akan dihapus.

Hasil

  • Promise<void>

    Chrome 123+

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

Menghapus semua item menu konteks yang ditambahkan oleh ekstensi ini.

Hasil

  • Promise<void>

    Chrome 123+

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

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 dijadikan induk item ini. Catatan: Anda tidak dapat menetapkan item 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 akan terlihat seperti: 

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

      • Chrome 44+
      • tab

        Tab

        Chrome 44+

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

Hasil

  • Promise<void>

    Chrome 123+

Acara

onClicked

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

Diaktifkan saat item menu konteks diklik.

Parameter