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
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.
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, tabId
yı 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.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 çok 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 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ç
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, bir kullanıcı etkileşiminden sonra sidePanel.open()
numaralı telefonu arayın. Örneğin:
- İşlem tıklaması
- Klavye kısayolu
- İçerik menüsü
- Bir uzantı sayfasındaki veya içerik komut dosyasındaki kullanıcı hareketi.
Yan paneli sabitleme
Yan paneliniz açıkken yan panel araç çubuğunda bir raptiye simgesi görüntülenir. Simgeyi tıkladığınızda uzantınızın işlem simgesi sabitlenir. Sabitledikten sonra işlem simgesini tıkladığınızda işlem simgeniz için varsayılan işlem gerçekleştirilir ve yalnızca açık bir şekilde yapılandırılmışsa yan panel açılır.
Ö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
Ö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 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ı 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()
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
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(options: PanelOptions) => void
-
seçenekler
-
İ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()
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
-
ücretsiz,
-
İ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()
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
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()
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
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()
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,
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.