توضیحات
از chrome.windows
API برای تعامل با پنجره های مرورگر استفاده کنید. شما می توانید از این API برای ایجاد، اصلاح و تنظیم مجدد پنجره ها در مرورگر استفاده کنید.
مجوزها
در صورت درخواست، یک windows.Window
حاوی آرایه ای از اشیاء tabs.Tab
است. در صورت نیاز به دسترسی به url
، pendingUrl
، title
یا ویژگیهای favIconUrl
tabs.Tab
، باید مجوز "tabs"
در مانیفست خود اعلام کنید. به عنوان مثال:
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
مفاهیم و کاربرد
پنجره فعلی
بسیاری از توابع در سیستم برنامه افزودنی یک آرگومان اختیاری windowId
می گیرند که به طور پیش فرض روی پنجره فعلی است.
پنجره فعلی پنجره ای است که حاوی کدی است که در حال اجراست. توجه به این نکته مهم است که این می تواند با بالاترین پنجره یا پنجره متمرکز متفاوت باشد.
به عنوان مثال، فرض کنید یک برنامه افزودنی چند برگه یا پنجره از یک فایل HTML ایجاد می کند و فایل HTML حاوی یک فراخوانی به tabs.query()
است. پنجره فعلی پنجره ای است که حاوی صفحه ای است که تماس برقرار کرده است، مهم نیست که بالاترین پنجره کدام باشد.
در مورد کارگران خدمات ، مقدار پنجره فعلی به آخرین پنجره فعال باز می گردد. تحت برخی شرایط، ممکن است هیچ پنجره فعلی برای صفحات پس زمینه وجود نداشته باشد.
نمونه ها
برای امتحان این API، نمونه Windows API را از مخزن chrome-extension-samples نصب کنید.
انواع
CreateType
مشخص می کند که چه نوع پنجره مرورگر ایجاد شود. "پانل" منسوخ شده است و فقط برای افزونه های موجود در لیست مجاز در سیستم عامل Chrome در دسترس است.
Enum
"عادی" "پاپ آپ" "پانل"
پنجره را به عنوان یک پنجره استاندارد مشخص می کند.
پنجره را به عنوان یک پنجره بازشو مشخص می کند.
پنجره را به عنوان یک پنل مشخص می کند.
QueryOptions
خواص
- پر جمعیت کردن
بولی اختیاری
اگر درست باشد، شی
windows.Window
دارای یک ویژگیtabs
است که حاوی لیستی از اشیاءtabs.Tab
است. اشیاءTab
فقط حاویurl
،pendingUrl
،title
، و خصوصیاتfavIconUrl
هستند در صورتی که فایل مانیفست برنامه افزودنی شامل مجوز"tabs"
باشد. - انواع پنجره
WindowType [] اختیاری است
اگر تنظیم شود،
windows.Window
بازگشتی بر اساس نوع آن فیلتر می شود. اگر تنظیم نشود، فیلتر پیشفرض روی['normal', 'popup']
تنظیم میشود.
Window
خواص
- همیشه در بالا
بولی
اینکه آیا پنجره تنظیم شده است که همیشه در بالا باشد.
- متمرکز شده است
بولی
آیا پنجره در حال حاضر پنجره متمرکز است یا خیر.
- ارتفاع
شماره اختیاری
ارتفاع پنجره، از جمله قاب، بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره ویژگی
height
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از APIsessions
. - شناسه
شماره اختیاری
شناسه پنجره شناسههای پنجره در یک جلسه مرورگر منحصربهفرد هستند. در برخی شرایط ممکن است به یک پنجره یک ویژگی
ID
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو کردن ویندوز با استفاده ازsessions
API، در این صورت ممکن است شناسه جلسه وجود داشته باشد. - ناشناس
بولی
این که آیا پنجره ناشناس است.
- سمت چپ
شماره اختیاری
افست پنجره از لبه سمت چپ صفحه نمایش بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره یک ویژگی
left
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از APIsessions
. - sessionId
رشته اختیاری
شناسه جلسه برای شناسایی منحصربهفرد یک پنجره استفاده میشود که از
sessions
API بدست میآید. - دولت
WindowState اختیاری است
وضعیت این پنجره مرورگر.
- زبانه ها
برگه [] اختیاری است
آرایه ای از اشیاء
tabs.Tab
که نشان دهنده زبانه های فعلی در پنجره است. - بالا
شماره اختیاری
افست پنجره از لبه بالایی صفحه بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره یک ویژگی
top
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از APIsessions
. - نوع
WindowType اختیاری است
نوع پنجره مرورگر این است.
- عرض
شماره اختیاری
عرض پنجره، از جمله قاب، بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره ویژگی
width
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از APIsessions
.
WindowState
وضعیت این پنجره مرورگر. در برخی شرایط ممکن است به یک پنجره یک ویژگی state
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions
.
Enum
"عادی" "به حداقل رسیده" "به حداکثر رساندن" "تمام صفحه" "قفل تمام صفحه"
حالت نرمال پنجره (حداقل، حداکثر یا تمام صفحه).
به حداقل رساندن حالت پنجره
حداکثر حالت پنجره
وضعیت پنجره تمام صفحه
حالت پنجره تمام صفحه قفل شده. این حالت تمامصفحه را نمیتوان با اقدام کاربر خارج کرد و فقط برای برنامههای افزودنی فهرست مجاز در سیستم عامل Chrome در دسترس است.
WindowType
نوع پنجره مرورگر این است. در برخی شرایط ممکن است به پنجره خاصیت type
اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions
.
Enum
"عادی" "پاپ آپ" "پانل" "برنامه" "ابزارهای توسعه"
یک پنجره معمولی مرورگر
یک پنجره بازشو مرورگر
در این API منسوخ شده است. یک پنجره به سبک پانل برنامه Chrome. برنامههای افزودنی فقط میتوانند پنجرههای پانل خودشان را ببینند.
در این API منسوخ شده است. یک پنجره برنامه Chrome. برنامه های افزودنی فقط می توانند پنجره های برنامه خود را ببینند.
یک پنجره Developer Tools.
خواص
WINDOW_ID_CURRENT
مقدار windowId که نمایانگر پنجره فعلی است.
ارزش
-2
WINDOW_ID_NONE
مقدار windowId که نشان دهنده عدم وجود پنجره مرورگر کروم است.
ارزش
-1
روش ها
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
یک پنجره مرورگر جدید با هر اندازه اختیاری، موقعیت یا URL پیش فرض ارائه شده ایجاد می کند (باز می کند).
پارامترها
- ایجاد داده
شی اختیاری
- متمرکز شده است
بولی اختیاری
اگر
true
، یک پنجره فعال باز می شود. اگرfalse
، یک پنجره غیر فعال باز می شود. - ارتفاع
شماره اختیاری
ارتفاع بر حسب پیکسل پنجره جدید، از جمله قاب. اگر مشخص نشده باشد، به طور پیش فرض روی ارتفاع طبیعی قرار می گیرد.
- ناشناس
بولی اختیاری
آیا پنجره جدید باید یک پنجره ناشناس باشد.
- سمت چپ
شماره اختیاری
تعداد پیکسل ها برای قرار دادن پنجره جدید از لبه سمت چپ صفحه. اگر مشخص نشده باشد، پنجره جدید به طور طبیعی از آخرین پنجره متمرکز خارج می شود. این مقدار برای پانل ها نادیده گرفته می شود.
- setSelfAsOpener
بولی اختیاری
Chrome 64+اگر
true
، "window.opener" پنجره تازه ایجاد شده روی تماس گیرنده تنظیم می شود و در همان واحد زمینه های مرور مرتبط با تماس گیرنده قرار دارد. - دولت
WindowState اختیاری است
Chrome 44+حالت اولیه پنجره حالت های
minimized
,maximized
وfullscreen
را نمی توان باleft
,top
,width
یاheight
ترکیب کرد . - tabId
شماره اختیاری
شناسه برگه برای افزودن به پنجره جدید.
- بالا
شماره اختیاری
تعداد پیکسل ها برای قرار دادن پنجره جدید از لبه بالایی صفحه. اگر مشخص نشده باشد، پنجره جدید به طور طبیعی از آخرین پنجره متمرکز خارج می شود. این مقدار برای پانل ها نادیده گرفته می شود.
- نوع
CreateType اختیاری است
مشخص می کند که چه نوع پنجره مرورگر ایجاد شود.
- آدرس اینترنتی
رشته | رشته[] اختیاری است
URL یا آرایه ای از URL ها برای باز کردن به عنوان برگه در پنجره. نشانیهای وب کاملاً واجد شرایط باید شامل یک طرح باشد، به عنوان مثال، «http://www.google.com»، نه «www.google.com». نشانیهای وب غیر کاملاً واجد شرایط در برنامه افزودنی نسبی در نظر گرفته میشوند. پیشفرض صفحه برگه جدید است.
- عرض
شماره اختیاری
عرض بر حسب پیکسل پنجره جدید، از جمله قاب. اگر مشخص نشده باشد، به طور پیشفرض روی عرض طبیعی تنظیم میشود.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(window?: Window) => void
- پنجره
پنجره اختیاری
حاوی جزئیات مربوط به پنجره ایجاد شده است.
برمی گرداند
وعده< پنجره | تعریف نشده>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
جزئیات یک پنجره را دریافت می کند.
پارامترها
- شناسه پنجره
شماره
- queryOptions
QueryOptions اختیاری است
Chrome 88+ - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(window: Window) => void
- پنجره
برمی گرداند
وعده< پنجره >
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
تمام ویندوزها را دریافت می کند.
پارامترها
- queryOptions
QueryOptions اختیاری است
Chrome 88+ - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(windows: Window[]) => void
- پنجره ها
پنجره []
برمی گرداند
وعده< پنجره []>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
پنجره فعلی را دریافت می کند.
پارامترها
- queryOptions
QueryOptions اختیاری است
Chrome 88+ - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(window: Window) => void
- پنجره
برمی گرداند
وعده< پنجره >
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
پنجره ای را دریافت می کند که اخیراً متمرکز شده است - معمولاً پنجره "در بالا".
پارامترها
- queryOptions
QueryOptions اختیاری است
Chrome 88+ - پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(window: Window) => void
- پنجره
برمی گرداند
وعده< پنجره >
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
یک پنجره و تمام برگه های داخل آن را حذف (بسته) می کند.
پارامترها
- شناسه پنجره
شماره
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
ویژگی های یک پنجره را به روز می کند. فقط خصوصیاتی را که باید تغییر کنند مشخص کنید. ویژگی های نامشخص بدون تغییر هستند.
پارامترها
- شناسه پنجره
شماره
- updateInfo
شی
- جلب توجه
بولی اختیاری
اگر
true
، باعث می شود که پنجره به گونه ای نمایش داده شود که توجه کاربر را به پنجره جلب کند، بدون اینکه پنجره متمرکز شده را تغییر دهد. این افکت تا زمانی که کاربر فوکوس را به پنجره تغییر دهد ادامه دارد. اگر پنجره از قبل فوکوس داشته باشد، این گزینه تاثیری ندارد. برای لغو درخواستdrawAttention
قبلی، رویfalse
تنظیم کنید. - متمرکز شده است
بولی اختیاری
اگر
true
، پنجره را به جلو می آورد. را نمی توان با حالت "به حداقل رسانده" ترکیب کرد. اگرfalse
، پنجره بعدی به ترتیب z را به جلو می آورد. نمی توان با حالت "تمام صفحه" یا "حداکثر" ترکیب کرد. - ارتفاع
شماره اختیاری
ارتفاع برای تغییر اندازه پنجره به پیکسل. این مقدار برای پانل ها نادیده گرفته می شود.
- سمت چپ
شماره اختیاری
افست از لبه سمت چپ صفحه برای انتقال پنجره به پیکسل. این مقدار برای پانل ها نادیده گرفته می شود.
- دولت
WindowState اختیاری است
وضعیت جدید پنجره. حالت های «حداقل»، «حداکثر» و «تمام صفحه» را نمی توان با «چپ»، «بالا»، «عرض» یا «ارتفاع» ترکیب کرد.
- بالا
شماره اختیاری
جابجایی از لبه بالایی صفحه برای انتقال پنجره به پیکسل. این مقدار برای پانل ها نادیده گرفته می شود.
- عرض
شماره اختیاری
عرض تغییر اندازه پنجره به پیکسل. این مقدار برای پانل ها نادیده گرفته می شود.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(window: Window) => void
- پنجره
برمی گرداند
وعده< پنجره >
Chrome 88+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
رویدادها
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
هنگامی که اندازه یک پنجره تغییر کرده است فعال می شود. این رویداد تنها زمانی ارسال می شود که محدوده های جدید متعهد شوند، و نه برای تغییرات در حال پیشرفت.
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
هنگام ایجاد پنجره فعال می شود.
پارامترها
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
هنگامی که پنجره متمرکز فعلی تغییر می کند فعال می شود. اگر تمام پنجرههای Chrome تمرکز خود را از دست داده باشند، chrome.windows.WINDOW_ID_NONE
را برمیگرداند. توجه: در برخی از مدیران پنجره لینوکس، WINDOW_ID_NONE
همیشه بلافاصله قبل از تغییر از یک پنجره Chrome به پنجره دیگر ارسال میشود.
پارامترها
- پاسخ به تماس
تابع
Chrome 46+پارامتر
callback
به نظر می رسد:(windowId: number) => void
- شناسه پنجره
شماره
شناسه پنجره تازه متمرکز شده.
- فیلترها
شی اختیاری
- انواع پنجره
نوع پنجره []
شرایطی که نوع پنجره در حال حذف باید رعایت شود. به طور پیش فرض
['normal', 'popup']
را برآورده می کند.
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
هنگام برداشتن پنجره (بسته) شلیک می شود.
پارامترها
- پاسخ به تماس
تابع
Chrome 46+پارامتر
callback
به نظر می رسد:(windowId: number) => void
- شناسه پنجره
شماره
شناسه پنجره حذف شده
- فیلترها
شی اختیاری
- انواع پنجره
نوع پنجره []
شرایطی که نوع پنجره در حال حذف باید رعایت شود. به طور پیش فرض
['normal', 'popup']
را برآورده می کند.