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 .

  • sessionId

    رشته اختیاری

    شناسه جلسه برای شناسایی منحصربه‌فرد یک پنجره استفاده می‌شود که از 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

    • پنجره

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

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

برمی گرداند

  • وعده< پنجره | تعریف نشده>

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