Açıklama
İçeriği, web sayfasının ana içeriğiyle birlikte tarayıcının yan panelinde barındırmak için chrome.sidePanel API'yi kullanın.
İzinler
sidePanelSide Panel API'yi kullanmak için uzantı manifest dosyasına "sidePanel" iznini ekleyin:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Kullanılabilirlik
Kavramlar ve kullanım
Side Panel API, uzantıların kendi kullanıcı arayüzlerini yan panelde göstermesine olanak tanır. Böylece, kullanıcının göz atma yolculuğunu tamamlayan kalıcı deneyimler sunulabilir.
Bazı özellikler şunlardır:
- Sekmeler arasında gezinirken yan panel açık kalır (böyle ayarlanmışsa).
- Yalnızca belirli web sitelerinde kullanılabilir.
- 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'nin bazı yaygın kullanım alanları gösterilmektedir. Eksiksiz uzantı örnekleri için Uzantı örnekleri bölümüne bakın.
Her sitede aynı yan paneli gösterme
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 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 panel etkinleştirmek için sidepanel.setOptions() kullanabilir. Bu örnekte, sekmede yapılan güncellemeleri dinlemek için browser.tabs.onUpdated() kullanılır. URL'nin www.google.com olup olmadığını kontrol eder ve yan paneli etkinleştirir. Aksi takdirde devre dışı bırakır.
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
browser.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 browser.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await browser.sidePanel.setOptions({
tabId,
enabled: false
});
}
});
Kullanıcı geçici olarak yan panelin etkinleştirilmediği bir sekmeye geçtiğinde yan panel gizlenir. Kullanıcı daha önce açık olduğu bir sekmeye geçtiğinde 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() ile işlem araç çubuğu simgesini tıkladıklarında yan paneli açmalarına izin verebilir. Öncelikle 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
browser.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
Kullanıcı etkileşimi olduğunda yan paneli programatik olarak açma
Chrome 116, sidePanel.open()'i kullanıma sunuyor. Uzantıların, işlem simgesini tıklama gibi bir uzantı kullanıcı hareketiyle yan paneli açmasına olanak tanır. Uzantı sayfasında veya içerik komut dosyasında bir düğmeyi tıklama gibi kullanıcı etkileşimleri de olabilir. Tam bir demo için Yan Paneli Aç örnek uzantısına bakın.
Aşağıdaki kod, kullanıcı bir bağlam menüsünü tıkladığında geçerli pencerede genel bir yan panelin nasıl açılacağını gösterir. sidePanel.open() kullanırken açılacağı bağlamı seçmeniz gerekir. Genel bir yan panel açmak için windowId kısayolunu kullanın. Alternatif olarak, yan paneli yalnızca belirli bir sekmede açılacak şekilde tabId ayarlayabilirsiniz.
service-worker.js:
browser.runtime.onInstalled.addListener(() => {
browser.contextMenus.create({
id: 'openSidePanel',
title: 'Open side panel',
contexts: ['all']
});
});
browser.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'openSidePanel') {
// This will open the panel in all the pages on the current window.
browser.sidePanel.open({ windowId: tab.windowId });
}
});
Farklı bir panele geçme
Uzantılar, mevcut yan paneli almak için sidepanel.getOptions() yöntemini kullanabilir. Aşağıdaki örnekte, runtime.onInstalled() üzerinde bir karşılama yan paneli ayarlanmaktadır. Kullanıcı farklı bir sekmeye gittiğinde ise bu panelin yerini ana yan panel alır.
service-worker.js:
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
browser.runtime.onInstalled.addListener(() => {
browser.sidePanel.setOptions({ path: welcomePage });
browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
browser.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await browser.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
browser.sidePanel.setOptions({ path: mainPage });
}
});
Kodun tamamı için Birden çok yan panel örneğine bakın.
Yan panel kullanıcı deneyimi
Kullanıcılar önce Chrome'un yerleşik yan panellerini görür. Her yan panel, yan panel menüsünde uzantının simgesini gösterir. Simge eklenmezse uzantı adının ilk harfini içeren bir yer tutucu simge gösterilir.
Yan paneli açma
Kullanıcıların yan paneli açmasına izin vermek için sidePanel.setPanelBehavior() ile birlikte bir işlem simgesi kullanın. Alternatif olarak, kullanıcı etkileşiminden sonra sidePanel.open() yöntemini çağırabilirsiniz. Örneğin:
- İşlem tıklaması
- Klavye kısayolu
- Bağlam menüsü
- Uzantı sayfasında veya içerik komut dosyasında kullanıcı hareketi.
Yan paneli sabitleme
Yan paneliniz açıkken yan panel araç çubuğunda bir sabitleme simgesi gösterilir. Simgeyi tıkladığınızda uzantınızın işlem simgesi sabitlenir. İşlem simgesi sabitlendikten sonra tıklandığında işlem simgeniz için varsayılan işlem gerçekleştirilir ve yalnızca açıkça yapılandırılmışsa yan panel açılır.
Örnekler
Daha fazla Side Panel API uzantısı demosu için aşağıdaki uzantılardan herhangi birini inceleyin:
- Sözlük yan paneli.
- Global yan panel.
- Birden fazla yan panel.
- Yan paneli açın.
- Siteye özel yan panel.
Türler
CloseOptions
Özellikler
-
tabId
number isteğe bağlı
Yan panelin kapatılacağı sekme. Belirtilen sekmede sekmeye özel bir yan panel açıksa bu panel ilgili sekme için kapatılır. Yalnızca genel yan panel açıksa
close()çağrısı tarafından döndürülen promise bir hatayla reddedilir. Bu davranış Chrome 145'te değiştirildi. Önceki sürümlerde ise genel panel kapatılıyordu. Bu veyawindowIdözelliklerinden en az biri sağlanmalıdır. -
windowId
number isteğe bağlı
Yan panelin kapatılacağı pencere. Belirtilen pencerede genel bir yan panel açıksa sekmeye özel panelin etkin olmadığı tüm sekmeler için kapatılır. Bu veya
tabIdözelliklerinden en az biri sağlanmalıdır.
GetPanelOptions
Özellikler
-
tabId
number isteğe bağlı
Belirtilirse, ilgili sekmenin yan panel seçenekleri döndürülür. Aksi takdirde, varsayılan yan panel seçeneklerini döndürür (belirli ayarları olmayan tüm sekmeler için kullanılır).
OpenOptions
Özellikler
-
tabId
number isteğe bağlı
Yan panelin açılacağı sekme. İlgili sekmenin sekmeye özel bir yan paneli varsa panel yalnızca o sekme için açılır. Sekmeye özel bir panel yoksa genel panel, belirtilen sekmede ve şu anda açık olan sekmeye özel paneli olmayan diğer sekmelerde açılır. Bu işlem, ilgili sekmede etkin olan tüm yan panelleri (genel veya sekmeye özel) geçersiz kılar. Bu veya
windowIdözelliklerinden en az biri sağlanmalıdır. -
windowId
number isteğe bağlı
Yan panelin açılacağı pencere. Bu, yalnızca uzantının genel (sekmeye özel olmayan) bir yan paneli varsa veya
tabIdda belirtilmişse geçerlidir. Bu işlem, kullanıcının ilgili pencerede açık olan ve şu anda etkin durumdaki genel yan panelini geçersiz kılar. Bu veyatabIdözelliklerinden en az biri sağlanmalıdır.
PanelBehavior
Özellikler
-
openPanelOnActionClick
boole isteğe bağlı
Uzantının simgesi tıklandığında uzantının girişinin yan panelde gösterilip gösterilmeyeceğini belirler. Varsayılan olarak "false" (yanlış) değerine ayarlıdır.
PanelClosedInfo
Özellikler
-
yol
dize
İçeriği panelde gösterilen uzantı paketindeki yerel kaynağın yolu.
-
tabId
number isteğe bağlı
Yan panelin kapatıldığı sekmenin isteğe bağlı kimliği. Bu, yalnızca panel sekmeye özgü olduğunda sağlanır.
-
windowId
sayı
Yan panelin kapatıldığı pencerenin kimliği. Bu özellik hem genel hem de sekmeye özel paneller için kullanılabilir.
PanelLayout
Özellikler
-
side
PanelOpenedInfo
Özellikler
-
yol
dize
İçeriği panelde gösterilen uzantı paketindeki yerel kaynağın yolu.
-
tabId
number isteğe bağlı
Yan panelin açıldığı sekmenin isteğe bağlı kimliği. Bu, yalnızca panel sekmeye özgü olduğunda sağlanır.
-
windowId
sayı
Yan panelin açıldığı pencerenin kimliği. Bu özellik hem genel hem de sekmeye özel paneller için kullanılabilir.
PanelOptions
Özellikler
-
etkin
boole isteğe bağlı
Yan panelin etkinleştirilip etkinleştirilmeyeceğini belirler. Bu işlem isteğe bağlıdır. Varsayılan değer "true"dur.
-
yol
string isteğe bağlı
Kullanılacak yan panel HTML dosyasının yolu. Bu, uzantı paketindeki yerel bir kaynak olmalıdır.
-
tabId
number 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ışı ayarlar (belirli ayarları olmayan tüm 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'nin panelinden farklı bir örnek olur.
Side
Tarayıcı kullanıcı arayüzündeki yan panel için olası hizalamayı tanımlar.
Enum
"left"
"right"
SidePanel
Özellikler
-
default_path
dize
Geliştirici, yan panel görünümü için yol belirtti.
Yöntemler
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
Uzantının yan panelini kapatır. Panel zaten kapalıysa bu işlem yapılmaz.
Parametreler
-
seçenekler
Yan panelin kapatılacağı bağlamı belirtir.
İadeler
-
Promise<void>
Yan panel kapatıldığında çözümlenen bir Promise döndürür.
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
Yan panelin mevcut düzenini döndürür.
İadeler
-
Promise<PanelLayout>
PanelLayoutile çözümlenen bir Promise döndürür.
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
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.
İadeler
-
Promise<PanelOptions>
Etkin panel yapılandırmasıyla çözümlenen bir Promise döndürür.
getPanelBehavior()
browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
Uzantının mevcut yan panel davranışını döndürür.
İadeler
-
Promise<PanelBehavior>
Uzantının yan panel davranışıyla çözümlenen bir Promise döndürür.
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
Uzantının yan panelini açar. Bu yalnızca bir kullanıcı işlemine yanıt olarak çağrılabilir.
Parametreler
-
seçenekler
Yan panelin açılacağı bağlamı belirtir.
İadeler
-
Promise<void>
Yan panel açıldığında çözümlenen bir Promise döndürür.
setOptions()
browser.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
Yan paneli yapılandırır.
Parametreler
-
seçenekler
Panele uygulanacak yapılandırma seçenekleri.
İadeler
-
Promise<void>
Seçenekler ayarlandığında çözümlenen bir Promise döndürür.
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
Uzantının yan panel davranışını yapılandırır. Bu bir güncelleme ve ekleme işlemidir.
Parametreler
-
ücretsiz,
Ayarlanacak yeni davranış.
İadeler
-
Promise<void>
Yeni davranış ayarlandığında çözümlenen bir Promise döndürür.
Etkinlikler
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
Uzantının yan paneli kapatıldığında tetiklenir.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(info: PanelClosedInfo) => void
-
bilgi
-
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
Uzantının yan paneli açıldığında tetiklenir.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(info: PanelOpenedInfo) => void
-
bilgi
-