chrome.windows

refresh date: 2026-09-25 robots: noindex

شرح

از 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() است. پنجره فعلی پنجره‌ای است که حاوی صفحه‌ای است که تماس را برقرار کرده است، صرف‌نظر از اینکه بالاترین پنجره کدام است.

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

مثال‌ها

دو پنجره، هرکدام با یک برگه

برای امتحان کردن این میانای برنامه‌سازی کاربردی، نمونه میانای برنامه‌سازی کاربردی windows را از مخزن chrome-extension-samples نصب کنید.

انواع

CreateType

Chrome نسخه ۴۴ به بالا

نوع پنجره مرورگر را برای ایجاد مشخص می‌کند. ‫'panel' منسوخ شده است و فقط برای افزونه‌های موجود در فهرست مجاز در Chrome OS دردسترس است.

شمارشی

«normal»
پنجره را به‌عنوان پنجره استاندارد مشخص می‌کند.

«popup»
پنجره را به‌عنوان پنجره بالاپر مشخص می‌کند.

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

QueryOptions

Chrome نسخه ۸۸ و بالاتر

مشخصات

  • درج کردن : پر کردن

    بولی اختیاری

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

  • windowTypes

    WindowType[] اختیاری

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

Window

مشخصات

  • alwaysOnTop

    بولی

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

  • متمرکز

    بولی

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

  • ارتفاع

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

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

  • id

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

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

  • ناشناس

    بولی

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

  • چپ

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

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

  • sessionId

    رشته اختیاری

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

  • ایالت

    WindowState اختیاری

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

  • tabs

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

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

  • بالا

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

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

  • نوع

    WindowType اختیاری

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

  • عرض

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

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

WindowState

Chrome نسخه ۴۴ به بالا

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

شمارشی

«normal»
وضعیت پنجره عادی (کوچک‌نشده، بزرگ‌نشده، یا تمام‌صفحه).

"minimized"
وضعیت پنجره کوچک‌شده.

"maximized"
وضعیت پنجره بیشینه شده.

«تمام‌صفحه»
وضعیت پنجره تمام‌صفحه.

WindowType

Chrome نسخه ۴۴ به بالا

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

شمارشی

«normal»
پنجره مرورگر معمولی.

«بالاپر»
بالاپر مرورگر.

«panel»
در این API منسوخ شده است. پنجره‌ای به سبک پانل «برنامه Chrome». افزونه‌ها فقط می‌توانند پنجره‌های پانل خودشان را ببینند.

«برنامه»
در این میانای برنامه‌سازی کاربردی منسوخ شده است. پنجره «برنامه Chrome». افزونه‌ها فقط می‌توانند پنجره‌های برنامه خودشان را ببینند.

«devtools»
پنجره Developer Tools.

مشخصات

WINDOW_ID_CURRENT

مقدار windowId که پنجره فعلی را نشان می‌دهد.

مقدار

-۲

WINDOW_ID_NONE

مقدار windowId که نشان‌دهنده عدم وجود پنجره مرورگر Chrome است.

مقدار

‫-۱

روش‌ها

create()

قول 
chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

پنجره مرورگر جدیدی را با هر اندازه، موقعیت، یا نشانی وب پیش‌فرض اختیاری ارائه‌شده ایجاد (باز) می‌کند.

پارامترها

  • createData

    شیء اختیاری

    • متمرکز

      بولی اختیاری

      اگر true، پنجره فعالی را باز می‌کند. اگر false، پنجره غیرفعالی را باز می‌کند.

    • ارتفاع

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

      ارتفاع پنجره جدید به پیکسل، شامل قاب. اگر مشخص نشده باشد، به‌طور پیش‌فرض روی ارتفاع طبیعی تنظیم می‌شود.

    • ناشناس

      بولی اختیاری

      اینکه پنجره جدید باید پنجره ناشناس باشد یا نه.

    • چپ

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

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

    • setSelfAsOpener

      بولی اختیاری

      Chrome نسخه ۶۴ به بالا

      اگر true، «window.opener» پنجره جدیداً ایجادشده روی تماس‌گیرنده تنظیم می‌شود و در همان واحد زمینه‌های مرور مرتبط تماس‌گیرنده قرار دارد.

    • ایالت

      WindowState اختیاری

      Chrome نسخه ۴۴ به بالا

      وضعیت اولیه پنجره. وضعیت‌های minimized، maximized، و fullscreen را نمی‌توان با left، top، width، یا height ترکیب کرد.

    • tabId

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

      شناسه زبانه برای افزودن به پنجره جدید.

    • بالا

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

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

    • نوع

      CreateType اختیاری

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

    • نشانی وب

      رشته | رشته[] اختیاری

      نشانی وب یا آرایه‌ای از نشانی‌های وب برای باز کردن به‌عنوان برگه در پنجره. نشانی‌های وب کاملاً واجد شرایط باید شامل طرح باشند، مثلاً «http://www.google.com»، نه «www.google.com». نشانی‌های وب کاملاً واجد شرایط در افزونه نسبی درنظر گرفته می‌شوند. به‌طور پیش‌فرض روی «صفحه زبانه جدید» تنظیم شده است.

    • عرض

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

      عرض پنجره جدید به پیکسل، شامل قاب. اگر مشخص نشده باشد، به‌طور پیش‌فرض روی عرض طبیعی تنظیم می‌شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (window?: Window) => void

    • پنجره

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

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

بازگشتی‌ها

  • Promise<Window | undefined>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

get()

قول 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

جزئیات مربوط به پنجره را دریافت می‌کند.

پارامترها

  • windowId

    شماره

  • queryOptions

    QueryOptions اختیاری

    Chrome نسخه ۸۸ و بالاتر
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

بازگشتی‌ها

  • Promise<Window>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getAll()

قول 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

همه پنجره‌ها را دریافت می‌کند.

پارامترها

  • queryOptions

    QueryOptions اختیاری

    Chrome نسخه ۸۸ و بالاتر
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (windows: Window[]) => void

بازگشتی‌ها

  • Promise<Window[]>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getCurrent()

قول 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

پنجره کنونی را دریافت می‌کند.

پارامترها

  • queryOptions

    QueryOptions اختیاری

    Chrome نسخه ۸۸ و بالاتر
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

بازگشتی‌ها

  • Promise<Window>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getLastFocused()

قول 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

پنجره‌ای را که اخیراً روی آن تمرکز شده است دریافت می‌کند — معمولاً پنجره «در بالا».

پارامترها

  • queryOptions

    QueryOptions اختیاری

    Chrome نسخه ۸۸ و بالاتر
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

بازگشتی‌ها

  • Promise<Window>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

remove()

قول 
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

پنجره و همه برگه‌های داخل آن را برمی‌دارد (می‌بندد).

پارامترها

  • windowId

    شماره

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

update()

قول 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

ویژگی‌های پنجره را به‌روز می‌کند. فقط ویژگی‌هایی را که باید تغییر کنند مشخص کنید؛ ویژگی‌های نامشخص تغییر نمی‌کنند.

پارامترها

  • windowId

    شماره

  • updateInfo

    شیء

    • drawAttention

      بولی اختیاری

      اگر true، باعث می‌شود پنجره به‌گونه‌ای نمایش داده شود که توجه کاربر را به پنجره جلب کند، بدون اینکه پنجره کانونی تغییر کند. این جلوه تا زمانی که کاربر تمرکز را به پنجره تغییر دهد ادامه دارد. اگر پنجره ازقبل در کانون توجه باشد، این گزینه تأثیری ندارد. برای لغو درخواست drawAttention قبلی، روی false تنظیم کنید.

    • متمرکز

      بولی اختیاری

      اگر true، پنجره را به جلو می‌آورد؛ نمی‌تواند با وضعیت «کوچک‌شده» ترکیب شود. اگر false، پنجره بعدی را در ترتیب z به جلو می‌آورد؛ نمی‌تواند با حالت «تمام‌صفحه» یا «بیشینه‌شده» ترکیب شود.

    • ارتفاع

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

      ارتفاعی که اندازه پنجره باید به آن تغییر کند (به پیکسل). این مقدار برای پانل‌ها نادیده گرفته می‌شود.

    • چپ

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

      فاصله از لبه چپ صفحه برای انتقال پنجره به آنجا (برحسب پیکسل). این مقدار برای پانل‌ها نادیده گرفته می‌شود.

    • ایالت

      WindowState اختیاری

      وضعیت جدید پنجره. حالت‌های «کوچک‌شده»، «بزرگ‌شده»، و «تمام‌صفحه» را نمی‌توان با «چپ»، «بالا»، «عرض»، یا «ارتفاع» ترکیب کرد.

    • بالا

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

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

    • عرض

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

      عرضی که اندازه پنجره باید به آن تغییر کند (به پیکسل). این مقدار برای پانل‌ها نادیده گرفته می‌شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

بازگشتی‌ها

  • Promise<Window>

    Chrome نسخه ۸۸ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onBoundsChanged

Chrome نسخه ۸۶ و بالاتر 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

onCreated

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

وقتی پنجره‌ای ایجاد می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    Chrome نسخه ۴۶ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    (window: Window) => void

    • پنجره

      پنجره

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

  • فیلترها

    شیء اختیاری

    • windowTypes

      WindowType[]

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

onFocusChanged

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

وقتی پنجره‌ای که درحال‌حاضر روی آن تمرکز شده است تغییر می‌کند، فعال می‌شود. اگر همه پنجره‌های Chrome از کانون خارج شده باشند، chrome.windows.WINDOW_ID_NONE را برمی‌گرداند. توجه: در برخی‌از مدیران پنجره Linux،‏ WINDOW_ID_NONE همیشه بلافاصله قبل‌از جابه‌جایی از یک پنجره Chrome به پنجره دیگر ارسال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    Chrome نسخه ۴۶ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    (windowId: number) => void

    • windowId

      شماره

      شناسه پنجره‌ای که به‌تازگی روی آن تمرکز شده است.

  • فیلترها

    شیء اختیاری

    • windowTypes

      WindowType[]

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

onRemoved

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

وقتی پنجره‌ای برداشته (بسته) می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    Chrome نسخه ۴۶ و بالاتر

    پارامتر callback به‌صورت زیر است: 

    (windowId: number) => void

    • windowId

      شماره

      شناسه پنجره برداشته‌شده.

  • فیلترها

    شیء اختیاری

    • windowTypes

      WindowType[]

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