chrome.sidePanel

Açıklama

İçeriği, bir web sayfasının ana içeriğinin yanı sıra tarayıcının yan panelinde barındırmak için chrome.sidePanel API'sini kullanın.

İzinler

sidePanel

Side Panel API'yi kullanmak için uzantı manifest dosyasına "sidePanel" iznini ekleyin:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Kullanılabilirlik

Chrome 114 ve sonraki sürümler MV3+

Kavramlar ve kullanım

Side Panel API, uzantıların yan panelde kendi kullanıcı arayüzünü göstermesine olanak tanıyarak kullanıcının tarama yolculuğunu tamamlayan kalıcı deneyimler sunar.

Yan panel açılır menüsü
Chrome tarayıcı yan panel kullanıcı arayüzü.

Bazı özellikler:

  • Sekmeler arasında gezinirken yan panel açık kalır (bu şekilde ayarlanırsa).
  • Yalnızca belirli web sitelerinde kullanılabilir.
  • Bir uzantı sayfası olarak yan paneller tüm Chrome API'lerine erişebilir.
  • Kullanıcılar, Chrome'un ayarlarında panelin hangi tarafta gösterileceğini belirtebilir.

Kullanım alanları

Aşağıdaki bölümlerde, Side Panel API'ye ilişkin bazı yaygın kullanım alanları gösterilmektedir. Uzantı örneklerinin tamamı için Uzantı örnekleri bölümüne bakın.

Her sitede aynı yan paneli gösterin

Yan panel, her sitede aynı yan paneli görüntülemek için başlangıçta manifestin "side_panel" anahtarındaki "default_path" özelliğinden ayarlanabilir. Bu, uzantı dizini içindeki göreli bir yolu işaret etmelidir.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

Belirli bir sitede yan paneli etkinleştirme

Uzantılar, belirli bir sekmede yan paneli etkinleştirmek için sidepanel.setOptions() simgesini kullanabilir. Bu örnekte, sekmede yapılan güncellemeleri dinlemek için chrome.tabs.onUpdated() kullanılmaktadır. URL'nin www.google.com olup olmadığını kontrol eder ve yan paneli etkinleştirir. Aksi takdirde özellik devre dışı bırakılır.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Bir kullanıcı, yan panelin etkin olmadığı bir sekmeye geçici olarak geçiş yaptığında yan panel gizlenir. Kullanıcı önceden açık olduğu bir sekmeye geçtiğinde bu sekme otomatik olarak tekrar gösterilir.

Kullanıcı, yan panelin etkinleştirilmediği bir siteye gittiğinde yan panel kapanır ve uzantı, yan panel açılır menüsünde gösterilmez.

Tam bir örnek için Sekmeye özel yan panel örneğine bakın.

Araç çubuğu simgesini tıklayarak yan paneli açın

Geliştiriciler, kullanıcıların sidePanel.setPanelBehavior() içeren işlem araç çubuğu simgesini tıkladığında yan paneli açmasına izin verebilir. İlk olarak manifest dosyasında "action" anahtarını tanımlayın:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Şimdi, bu kodu önceki örneğe ekleyin:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Kullanıcı etkileşiminde yan paneli programatik olarak aç

Chrome 116'da sidePanel.open() kullanıma sunuldu. İşlem simgesini tıklama gibi bir uzantı kullanıcı hareketiyle uzantıların yan paneli açmasına olanak tanır. Ya da bir uzantı sayfasındaki veya içerik komut dosyasındaki kullanıcı etkileşimi (ör. bir düğmeyi tıklama). Tam demo için Open Side Panel örnek uzantısına bakın.

Aşağıdaki kod, kullanıcı bir içerik menüsünü tıkladığında geçerli pencerede genel bir yan panelin nasıl açılacağını gösterir. sidePanel.open() kullanılırken, açılması gereken bağlamı seçmeniz gerekir. Genel yan paneli açmak için windowId simgesini kullanın. Alternatif olarak, tabId simgesini, yan paneli yalnızca belirli bir sekmede açacak şekilde ayarlayın.

service-worker.js:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

Farklı bir panele geçme

Uzantılar, mevcut yan paneli almak için sidepanel.getOptions() simgesini kullanabilir. Aşağıdaki örnekte, runtime.onInstalled() için bir karşılama yan paneli ayarlanmaktadır. Ardından, kullanıcı farklı bir sekmeye gittiğinde bu sekmeyi ana yan panelle değiştirir.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
  chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Kodun tamamı için Birden fazla yan panel örneğine bakın.

Yan panel kullanıcı deneyimi

Kullanıcılar ilk olarak Chrome'un yerleşik yan panellerini görür. Her bir yan panelde, yan panel menüsünde uzantının simgesi gösterilir. Herhangi bir simge eklenmezse uzantı adının ilk harfini içeren bir yer tutucu simgesi gösterilir.

Yan paneli aç

Kullanıcıların yan paneli açmasına izin vermek için birlikte bir işlem simgesi kullanın sidePanel.setPanelBehavior() ile. Alternatif olarak, aşağıdakiler gibi bir kullanıcı etkileşiminden sonra sidePanel.open() numarasına çağrı yapabilirsiniz:

Yan paneli sabitleme

Yan panel kullanıcı arayüzündeki raptiye simgesi.
Yan panel kullanıcı arayüzündeki raptiye simgesi.

Yan panel araç çubuğu, yan paneliniz açıkken bir raptiye simgesi gösterir. Simgeyi tıkladığınızda uzantınızın işlem simgesi sabitlenir. İşlem simgesini sabitlendiğinde işlem simgeniz için varsayılan işlemi gerçekleştirir ve yalnızca açıkça yapılandırılmışsa yan paneli açın.

Örnekler

Daha fazla Yan Panel API uzantısı demosu için aşağıdaki uzantılardan herhangi birini keşfedin:

Türler

GetPanelOptions

Özellikler

  • tabId

    sayı isteğe bağlı

    Belirtilirse belirtilen sekme için yan panel seçenekleri döndürülür. Aksi takdirde, varsayılan yan panel seçeneklerini döndürür (belirli ayarların olmadığı sekmeler için kullanılır).

OpenOptions

Chrome 116 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • tabId

    sayı isteğe bağlı

    Yan panelin açılacağı sekme. İlgili sekmede sekmeye özel bir yan panel varsa panel yalnızca o sekme için açılır. Sekmeye özel bir panel yoksa genel panel, belirtilen sekmede ve sekmeye özel bir panel içermeyen diğer tüm sekmelerde açılır. Bu, ilgili sekmede o anda etkin olan tüm yan panelleri (genel veya sekmeye özgü) geçersiz kılar. Bundan veya windowId özelliklerinden en az biri sağlanmalıdır.

  • windowId

    sayı isteğe bağlı

    Yan panelin açılacağı pencere. Bu yalnızca uzantıda genel (sekmeye özgü olmayan) bir yan panel varsa veya tabId belirtilmişse geçerlidir. Bu, kullanıcının belirtilen pencerede açık olan, şu anda etkin olan genel yan panelleri geçersiz kılar. Bundan veya tabId özelliklerinden en az biri sağlanmalıdır.

PanelBehavior

Özellikler

  • openPanelOnActionClick

    boole isteğe bağlı

    Uzantının simgesini tıkladığınızda, uzantı girişinin yan panelde gösterilip gösterilmeyeceğini belirler. Varsayılan olarak yanlış değerine ayarlanır.

PanelOptions

Özellikler

  • etkin

    boole isteğe bağlı

    Yan panelin etkinleştirilip etkinleştirilmeyeceği. Bu işlem isteğe bağlıdır. Varsayılan değer, doğru değeridir.

  • yol

    dize isteğe bağlı

    Kullanılacak yan panel HTML dosyasının yolu. Bu, uzantı paketi içinde yer alan yerel bir kaynak olmalıdır.

  • tabId

    sayı isteğe bağlı

    Belirtilirse yan panel seçenekleri yalnızca bu kimliğe sahip sekme için geçerli olur. Atlanırsa bu seçenekler varsayılan davranışı belirler (belirli ayarları olmayan sekmeler için kullanılır). Not: Bu tabId ve varsayılan tabId için aynı yol ayarlanırsa bu tabId öğesine ait panel, varsayılan tabId parametresinden farklı bir örnek olacaktır.

SidePanel

Özellikler

  • default_path

    dize

    Yan panel ekranı için geliştirici tarafından belirtilen yol.

Yöntemler

getOptions()

Söz 'nı inceleyin.
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Etkin panel yapılandırmasını döndürür.

Parametreler

  • seçenekler

    Yapılandırmanın döndürüleceği bağlamı belirtir.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür:

    (options: PanelOptions) => void

İadeler

  • Promise&lt;PanelOptions&gt;

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

getPanelBehavior()

Söz 'nı inceleyin.
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Uzantının mevcut yan panel davranışını döndürür.

Parametreler

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür:

    (behavior: PanelBehavior) => void

İadeler

  • Promise&lt;PanelBehavior&gt;

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

open()

Söz Chrome 116 ve sonraki sürümler
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Uzantının yan panelini açar. Bu, yalnızca kullanıcı işlemine yanıt olarak çağrılabilir.

Parametreler

  • seçenekler

    Yan panelin açılacağı bağlamı belirtir.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür:

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

setOptions()

Söz 'nı inceleyin.
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Yan paneli yapılandırır.

Parametreler

  • seçenekler

    Panele uygulanacak yapılandırma seçenekleri.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür:

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

setPanelBehavior()

Söz 'nı inceleyin.
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Uzantının yan panel davranışını yapılandırır. Bu bir düzeltme işlemidir.

Parametreler

  • ücretsiz,

    Ayarlanacak yeni davranış.

  • geri çağırma

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür:

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.