Mendesain antarmuka pengguna

Peringatan: Anda sedang melihat versi Manifes V2 yang tidak digunakan lagi dari artikel ini. Lihat Manifes V3 - Mendesain antarmuka pengguna untuk MV3 yang setara. Chrome Web Store tidak lagi menerima ekstensi Manifes V2. Ikuti Panduan Migrasi Manifes V3 untuk mengonversi ekstensi Anda ke Manifes V3.

Antarmuka pengguna ekstensi harus terarah dan minimal. Sama seperti ekstensi itu sendiri, UI harus menyesuaikan atau meningkatkan pengalaman penjelajahan tanpa mengganggunya.

Panduan ini menguraikan fitur antarmuka pengguna yang wajib dan opsional. Gunakan API ini untuk memahami cara dan waktu menerapkan berbagai elemen UI dalam ekstensi.

Aktifkan ekstensi di semua halaman

Gunakan browser_action ketika fitur ekstensi berfungsi di sebagian besar situasi.

Mendaftarkan tindakan browser

Kolom "browser_action" terdaftar di manifes.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

Mendeklarasikan "browser_action" akan membuat ikon tetap berwarna, yang menunjukkan ekstensi tersedia untuk pengguna.

Tambahkan badge

Badge menampilkan banner berwarna dengan maksimal empat karakter di bagian atas ikon browser. Argumen tersebut hanya dapat digunakan oleh ekstensi yang mendeklarasikan "browser_action" dalam manifesnya.

Gunakan badge untuk menunjukkan status ekstensi. Contoh Peristiwa Air Minum menampilkan badge dengan status "AKTIF" untuk menunjukkan kepada pengguna bahwa mereka berhasil menyetel alarm dan tidak menampilkan apa pun saat ekstensi tidak ada aktivitas.

Tetapkan teks badge dengan memanggil chrome.browserAction.setBadgeText dan warna banner dengan memanggil chrome.browserAction.setBadgeBackgroundColor .

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

Aktifkan ekstensi pada halaman tertentu

Gunakan page_action saat fitur ekstensi hanya tersedia dalam keadaan yang ditentukan.

Mendeklarasikan tindakan halaman

Kolom "page_action" terdaftar di manifes.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

Mendeklarasikan "page_action" akan mewarnai ikon hanya jika ekstensi tersedia untuk pengguna. Jika tidak, ekstensi akan ditampilkan dalam hitam putih.

Tentukan aturan untuk mengaktifkan ekstensi

Tentukan aturan untuk kapan ekstensi dapat digunakan dengan memanggil chrome.declarativeContent di bagian pemroses runtime.onInstalled dalam skrip latar belakang. Ekstensi contoh Tindakan halaman menurut URL menetapkan ketentuan bahwa URL harus menyertakan 'g'. Jika kondisinya terpenuhi, ekstensi akan memanggil declarativeContent.ShowPageAction().

chrome.runtime.onInstalled.addListener(function() {
  // Replace all rules ...
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    // With a new rule ...
    chrome.declarativeContent.onPageChanged.addRules([
      {
        // That fires when a page's URL contains a 'g' ...
        conditions: [
          new chrome.declarativeContent.PageStateMatcher({
            pageUrl: { urlContains: 'g' },
          })
        ],
        // And shows the extension's page action.
        actions: [ new chrome.declarativeContent.ShowPageAction() ]
      }
    ]);
  });
});

Mengaktifkan atau menonaktifkan ekstensi

Ekstensi yang menggunakan "page_action" dapat diaktifkan dan dinonaktifkan secara dinamis dengan memanggil pageAction.show dan pageAction.hide.

Ekstensi contoh Mappy memindai alamat di halaman web dan menampilkan lokasinya pada peta statis di popup. Karena bergantung pada konten halaman, ekstensi tidak dapat mendeklarasikan aturan untuk memprediksi halaman mana yang akan relevan. Sebagai gantinya, jika alamat ditemukan di halaman, alamat akan memanggil pageAction.show untuk mewarnai ikon dan memberi sinyal bahwa ekstensi dapat digunakan di tab tersebut.

chrome.runtime.onMessage.addListener(function(req, sender) {
  chrome.storage.local.set({'address': req.address})
  chrome.pageAction.show(sender.tab.id);
  chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});

Menyediakan ikon ekstensi

Ekstensi memerlukan minimal satu ikon untuk mewakilinya. Berikan ikon dalam format PNG membentuk hasil visual terbaik, meskipun format apa pun yang didukung oleh WebKit termasuk BMP, GIF, ICO, dan JPEG diterima.

Menetapkan ikon {i>toolbar<i}

Ikon khusus untuk toolbar terdaftar di kolom "default_icon" pada browser_action atau page_action dalam manifes. Sebaiknya sertakan beberapa ukuran untuk menskalakan ruang 16 penurunan. Sebaiknya gunakan ukuran minimal 16x16 dan 32x32.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

Semua ikon harus berbentuk persegi atau mungkin terdistorsi. Jika tidak ada ikon yang disediakan, Chrome akan menambahkan ikon umum ke toolbar.

Membuat dan mendaftarkan ikon tambahan

Sertakan ikon tambahan dalam ukuran berikut untuk penggunaan di luar toolbar.

Ukuran Ikon	Penggunaan Ikon
16x16	favicon di halaman ekstensi
32x32	Komputer Windows sering kali memerlukan ukuran ini. Menyediakan opsi ini akan mencegah distorsi ukuran mengecilkan opsi 48x48.
48x48	ditampilkan di halaman pengelolaan ekstensi
128x128	ditampilkan saat penginstalan dan di Chrome Web Store

Daftarkan ikon dalam manifes pada kolom "icons".

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

Fitur UI tambahan

Pop-up

Pop-up adalah file HTML yang ditampilkan di jendela khusus saat pengguna mengklik ikon toolbar. Cara kerja pop-up sangat mirip dengan halaman web; pop-up dapat berisi link ke stylesheet dan tag skrip, tetapi tidak mengizinkan JavaScript inline.

Pop-up contoh Acara Air Minum akan menampilkan opsi timer yang tersedia. Pengguna mengatur alarm dengan mengklik salah satu tombol yang disediakan.

<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>

Pop-up dapat didaftarkan di manifes, di bagian tindakan browser atau tindakan halaman.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

Pop-up juga dapat disetel secara dinamis dengan memanggil browserAction.setPopup atau pageAction.setPopup.

chrome.storage.local.get('signed_in', function(data) {
  if (data.signed_in) {
    chrome.browserAction.setPopup({popup: 'popup.html'});
  } else {
    chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
  }
});

Tooltip

Gunakan tooltip untuk memberikan deskripsi atau petunjuk singkat kepada pengguna saat mengarahkan kursor ke ikon browser.

Tooltip terdaftar di kolom "default_title" browser_action atau page_action dalam manifes.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

Tooltip juga dapat ditetapkan atau diperbarui dengan memanggil browserAction.setTitle dan pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

String lokal khusus diimplementasikan dengan Internasionalisasi. Buat direktori untuk menyimpan pesan khusus bahasa dalam folder bernama _locales, seperti ini:

• _locales/en/messages.json
• _locales/es/messages.json

Memformat pesan di dalam messages.json setiap bahasa.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

Sertakan nama pesan di kolom tooltip, bukan pesan, untuk mengaktifkan pelokalan.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

Omnibox

Pengguna dapat memanggil fungsi ekstensi melalui omnibox. Sertakan kolom "omnibox" dalam manifes dan tentukan kata kunci. Ekstensi contoh Penelusuran Tab Baru Omnibox menggunakan "nt" sebagai kata kunci.

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

Saat pengguna mengetik "nt" di omnibox, ekstensi akan diaktifkan. Untuk menunjukkan hal ini kepada pengguna, ikon tersebut akan menjadi ikon 16x16 yang disediakan berwarna abu-abu dan menyertakannya dalam omnibox di samping nama ekstensi.

Ekstensi memproses peristiwa omnibox.onInputEntered. Setelah dipicu, ekstensi akan membuka tab baru yang berisi penelusuran Google untuk entri pengguna.

chrome.omnibox.onInputEntered.addListener(function(text) {
  // Encode user input for special characters , / ? : @ & = + $ #
  var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
  chrome.tabs.create({ url: newURL });
});

Menu konteks

Tambahkan opsi menu konteks baru dengan memberikan izin "contextMenus" dalam manifes.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

Ikon 16x16 akan ditampilkan di samping entri menu baru.

Buat menu konteks dengan memanggil contextMenus.create di skrip latar belakang. Tindakan ini harus dilakukan pada peristiwa pemroses runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});

const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

Contoh menu konteks Google Penelusuran Global akan membuat beberapa opsi dari daftar di locales.js . Jika ekstensi berisi lebih dari satu menu konteks, Google Chrome akan otomatis menciutkannya menjadi satu menu induk.

Perintah

Ekstensi dapat menentukan perintah tertentu dan mengikatnya ke kombinasi tombol. Daftarkan satu atau beberapa perintah dalam manifes pada kolom "commands".

{
  "name": "Tab Flipper",
  ...
  "commands": {
    "flip-tabs-forward": {
      "suggested_key": {
        "default": "Ctrl+Shift+Right",
        "mac": "Command+Shift+Right"
      },
      "description": "Flip tabs forward"
    },
    "flip-tabs-backwards": {
      "suggested_key": {
        "default": "Ctrl+Shift+Left",
        "mac": "Command+Shift+Left"
      },
      "description": "Flip tabs backwards"
    }
  }
  ...
}

Perintah dapat digunakan untuk menyediakan pintasan browser baru atau alternatif. Ekstensi contoh Tab Flipper memproses peristiwa commands.onCommand di skrip latar belakang dan menentukan fungsi untuk setiap kombinasi yang terdaftar.

chrome.commands.onCommand.addListener(function(command) {
  chrome.tabs.query({currentWindow: true}, function(tabs) {
    // Sort tabs according to their index in the window.
    tabs.sort((a, b) => { return a.index < b.index; });
    let activeIndex = tabs.findIndex((tab) => { return tab.active; });
    let lastTab = tabs.length - 1;
    let newIndex = -1;
    if (command === 'flip-tabs-forward')
      newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
    else  // 'flip-tabs-backwards'
      newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
    chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
  });
});

Perintah juga dapat membuat binding tombol yang berfungsi secara khusus dengan ekstensinya. Contoh Hello Extensions memberikan perintah untuk membuka pop-up.

{
  "name": "Hello Extensions",
  "description" : "Base Level Extension",
  "version": "1.0",
  "browser_action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  },
  "manifest_version": 2,
  "commands": {
    "_execute_browser_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+F",
        "mac": "MacCtrl+Shift+F"
      },
      "description": "Opens hello.html"
    }
  }
}

Karena ekstensi menentukan browser_action, ekstensi dapat menentukan "execute_browser_action" dalam perintah untuk membuka file pop-up tanpa menyertakan skrip latar belakang. Jika menggunakan page_action, parameter ini dapat diganti dengan "execute_page_action". Perintah browser dan ekstensi dapat digunakan di ekstensi yang sama.

Timpa halaman

Ekstensi dapat menggantikan dan mengganti halaman web Histori, Tab Baru, atau Bookmark dengan file HTML kustom. Seperti popup, pop-up dapat mencakup logika dan gaya khusus, tetapi tidak mengizinkan JavaScript inline. Ekstensi tunggal dibatasi untuk mengganti hanya satu dari tiga kemungkinan halaman.

Daftarkan halaman penggantian dalam manifes pada kolom "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

Kolom "newtab" harus diganti dengan "bookmarks" atau "history" saat mengganti halaman tersebut.

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>