chrome.sidePanel

Açıklama

Tarayıcının yan panelinde, bir web sayfasının ana içeriğinin yanında içerik barındırmak için chrome.sidePanel API'sini kullanın.

İzinler

sidePanel

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

manifest.json:

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

Kullanılabilirlik

Chrome 114 ve üstü sürümler MV3 ve üstü

Kavramlar ve kullanım

Side Panel API'si, uzantıların yan panelde kendi kullanıcı arayüzünü görüntülemesine olanak tanıyarak kullanıcının göz atma yolculuğunu tamamlayan kalıcı deneyimlere olanak tanır.

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

Bazı özellikler şunlardır:

  • Sekmeler arasında gezinirken yan panel açık kalıyor (yapacak şekilde ayarlanmışsa).
  • 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örüntüleneceğini belirtebilir.

Kullanım alanları

Aşağıdaki bölümlerde, Side Panel API ile ilgili 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öster

Yan panel, her sitede aynı yan paneli gösterecek şekilde başlangıçta manifest dosyasının "side_panel" anahtarındaki "default_path" özelliğinden ayarlanabilir. Bu, uzantı dizini içindeki göreli bir yola 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

Bir uzantı, belirli bir sekmede yan paneli etkinleştirmek için sidepanel.setOptions() aracını kullanabilir. Bu örnekte, sekmede yapılan güncellemeleri dinlemek için chrome.tabs.onUpdated() kullanılmıştır. URL'nin www.google.com olup olmadığını kontrol eder ve yan paneli etkinleştirir. Aksi halde 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ı, daha önce açık olduğu bir sekmeye geçiş yaptığında otomatik olarak tekrar gösterilir.

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

Eksiksiz bir örnek için Sekmeye özel yan panel örneğini inceleyin.

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

Geliştiriciler, kullanıcıların sidePanel.setPanelBehavior() ile işlem araç çubuğu simgesini tıkladıkları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 bir ö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. Uzantıların, işlem simgesini tıklama gibi bir uzantı kullanıcı hareketiyle yan paneli açmasına olanak tanır. Uzantı sayfasındaki veya içerik komut dosyasındaki bir kullanıcı etkileşimi de (örneğin, bir düğmeyi tıklama) olabilir. Eksiksiz bir demo için Açık Yan Paneli ö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() uygulamasını kullanırken dosyanın hangi bağlamda açılacağını seçmeniz gerekir. Genel yan paneli açmak için windowId düğmesini kullanın. Alternatif olarak, tabIdyı yan paneli yalnızca belirli bir sekmede açacak şekilde ayarlayabilirsiniz.

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ç

Uzantılar, mevcut yan paneli almak için sidepanel.getOptions() aracını kullanabilir. Aşağıdaki örnekte, runtime.onInstalled() ürününde karşılama yan paneli ayarlanmaktadır. Daha sonra kullanıcı farklı bir sekmeye gittiğinde bu sekme ana yan panelle değiştirilir.

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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Eksiksiz bir örnek için Birden çok yan panel bölümüne bakın.

Yan panel kullanıcı deneyimi

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

Yan paneli aç

Yan panel menüsüne gitme
Kullanıcılar, kullanılabilir yan panelleri yan panel menüsünde bulabilir. Ardından, açılır menüden bir uzantı seçebilir.
Yan panel açılır menüsü
Chrome tarayıcı yan panel kullanıcı arayüzü.
Kullanıcı hareketiyle aç

Yan paneli, sidePanel.open() ve sidePanel.setPanelBehavior() kullanarak kullanıcı etkileşimleri üzerinden açabilirsiniz. Örneğin:

Örnekler

Diğer Side Panel API uzantıları demosu için aşağıdaki uzantılardan birini inceleyin:

Türler

GetPanelOptions

Özellikler

  • tabId

    numara 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ı olmayan sekmeler için kullanılır).

OpenOptions

Chrome 116 ve sonraki sürümler

Özellikler

  • tabId

    numara 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 o anda açık olan sekmeye özgü bir panel olmadan diğer sekmelerde açılır. Bu işlem, ilgili sekmedeki şu anda etkin olan tüm yan panelleri (genel veya sekmeye özgü) geçersiz kılar. Bunun veya windowId özelliklerinden en az biri sağlanmalıdır.

  • windowId

    numara isteğe bağlı

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

PanelBehavior

Özellikler

  • openPanelOnActionClick

    boole isteğe bağlı

    Uzantının simgesi tıklandığında uzantı girişinin yan panelde gösterilip gösterilmeyeceği. Varsayılan olarak false 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, true değeridir.

  • yol

    string isteğe bağlı

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

  • tabId

    numara 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'nin paneli, varsayılan tabId için panelden farklı bir örnek olur.

SidePanel

Özellikler

  • default_path

    dize

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

Yöntemler

getOptions()

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

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

Parametreler

  • seçenekler

    GetPanelOptions

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

  • geri çağırma

    Functions (isteğe bağlı)

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

    (options: PanelOptions)=>void

İlerlemeler

  • Promise<PanelOptions>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

getPanelBehavior()

Söz 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

Parametreler

  • geri çağırma

    Functions (isteğe bağlı)

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

    (behavior: PanelBehavior)=>void

İlerlemeler

  • Promise<PanelBehavior>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, 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 bir kullanıcı işlemine yanıt olarak çağrılabilir.

Parametreler

  • seçenekler

    OpenOptions

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

  • geri çağırma

    Functions (isteğe bağlı)

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

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

setOptions()

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

Yan paneli yapılandırır.

Parametreler

  • seçenekler

    PanelOptions

    Panele uygulanacak yapılandırma seçenekleri.

  • geri çağırma

    Functions (isteğe bağlı)

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

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

setPanelBehavior()

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

Uzantının yan panel davranışını yapılandırır. Bu, daha kapsamlı bir işlemdir.

Parametreler

  • ücretsiz,

    PanelBehavior

    Ayarlanacak yeni davranış.

  • geri çağırma

    Functions (isteğe bağlı)

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

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.