chrome.windows

شرح

از 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 44+

مشخص می کند که چه نوع پنجره مرورگر ایجاد شود. "پانل" منسوخ شده است و فقط برای افزونه های موجود در لیست مجاز در سیستم عامل Chrome در دسترس است.

Enum

"طبیعی"
پنجره را به عنوان یک پنجره استاندارد مشخص می کند.

"پاپ آپ"
پنجره را به عنوان یک پنجره بازشو مشخص می کند.

"پانل"
پنجره را به عنوان یک پنل مشخص می کند.

QueryOptions

Chrome 88+

خواص

• پر جمعیت کردن

  بولی اختیاری

  اگر درست باشد، شی windows.Window دارای یک ویژگی tabs است که حاوی لیستی از اشیاء tabs.Tab است. اشیاء Tab فقط حاوی url , pendingUrl , title , و خصوصیات favIconUrl هستند در صورتی که فایل مانیفست برنامه افزودنی شامل مجوز "tabs" باشد.

• انواع پنجره

  WindowType [] اختیاری است

  اگر تنظیم شود، windows.Window بازگشتی بر اساس نوع آن فیلتر می شود. اگر تنظیم نشود، فیلتر پیش‌فرض روی ['normal', 'popup'] تنظیم می‌شود.

Window

خواص

• همیشه در بالا

  بولی

  اینکه آیا پنجره تنظیم شده است که همیشه در بالا باشد.

• متمرکز شده است

  بولی

  آیا پنجره در حال حاضر پنجره متمرکز است یا خیر.

• ارتفاع

  شماره اختیاری

  ارتفاع پنجره، از جمله قاب، بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره ویژگی height اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions .

• شناسه

  شماره اختیاری

  شناسه پنجره شناسه‌های پنجره در یک جلسه مرورگر منحصربه‌فرد هستند. در برخی شرایط ممکن است به یک پنجره یک ویژگی ID اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو کردن ویندوز با استفاده از sessions API، در این صورت ممکن است شناسه جلسه وجود داشته باشد.

• ناشناس

  بولی

  این که آیا پنجره ناشناس است.

• ترک کرد

  شماره اختیاری

  افست پنجره از لبه سمت چپ صفحه نمایش بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره یک ویژگی left اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions .

• شناسه جلسه

  رشته اختیاری

  شناسه جلسه برای شناسایی منحصربه‌فرد یک پنجره استفاده می‌شود که از sessions API بدست می‌آید.

• حالت

  WindowState اختیاری است

  وضعیت این پنجره مرورگر.

• زبانه ها

  برگه [] اختیاری است

  آرایه ای از اشیاء tabs.Tab که نشان دهنده زبانه های فعلی در پنجره است.

• بالا

  شماره اختیاری

  افست پنجره از لبه بالایی صفحه بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره یک ویژگی top اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions .

• نوع

  WindowType اختیاری است

  نوع پنجره مرورگر این است.

• عرض

  شماره اختیاری

  عرض پنجره، از جمله قاب، بر حسب پیکسل. در برخی شرایط ممکن است به یک پنجره ویژگی width اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions .

WindowState

Chrome 44+

وضعیت این پنجره مرورگر. در برخی شرایط ممکن است به یک پنجره یک ویژگی state اختصاص داده نشود. به عنوان مثال، هنگام پرس و جو پنجره های بسته از API sessions .

Enum

"طبیعی"
حالت نرمال پنجره (حداقل، حداکثر یا تمام صفحه).

"به حداقل رسیده"
به حداقل رساندن حالت پنجره

"به حداکثر رساندن"
حداکثر حالت پنجره

"تمام صفحه"
وضعیت پنجره تمام صفحه

"قفل تمام صفحه"
حالت پنجره تمام صفحه قفل شده. این حالت تمام‌صفحه را نمی‌توان با اقدام کاربر خارج کرد و فقط برای برنامه‌های افزودنی فهرست مجاز در سیستم عامل Chrome در دسترس است.

WindowType

Chrome 44+

نوع پنجره مرورگر این است. در برخی شرایط ممکن است به پنجره خاصیت 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

  • پنجره

    پنجره اختیاری

    حاوی جزئیات مربوط به پنجره ایجاد شده است.

برمی گرداند

• Promise< پنجره |undefined>

  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 86+

chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

هنگامی که اندازه یک پنجره تغییر کرده است فعال می شود. این رویداد تنها زمانی ارسال می شود که محدوده های جدید متعهد شوند، و نه برای تغییرات در حال پیشرفت.

مولفه های

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

  (window: Window)=>void

  • پنجره

    پنجره

onCreated

chrome.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

هنگام ایجاد پنجره فعال می شود.

مولفه های

• پاسخ به تماس

  تابع

  Chrome 46+

  پارامتر callback به نظر می رسد:

  (window: Window)=>void

  • پنجره

    پنجره

    جزئیات پنجره ایجاد شده

• فیلترها

  شی اختیاری

  • انواع پنجره

    نوع پنجره []

    شرایطی که نوع پنجره ایجاد شده باید رعایت شود. به طور پیش فرض ['normal', 'popup'] را برآورده می کند.

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'] را برآورده می کند.