chrome.windows

توضیحات

از API مربوط به chrome.windows برای تعامل با پنجره‌های مرورگر استفاده کنید. می‌توانید از این API برای ایجاد، تغییر و تنظیم مجدد پنجره‌ها در مرورگر استفاده کنید.

مانیفست

در صورت درخواست، یک windows.Window شامل آرایه‌ای از اشیاء tabs.Tab است. اگر نیاز به دسترسی به ویژگی‌های url ، pendingUrl ، title یا favIconUrl از tabs.Tab دارید، باید مجوز "tabs" را در مانیفست خود اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

پنجره فعلی

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

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

برای مثال، فرض کنید یک افزونه چند تب یا پنجره از یک فایل HTML ایجاد می‌کند و فایل HTML شامل فراخوانی tabs.query() است. پنجره فعلی، پنجره‌ای است که صفحه‌ای که فراخوانی را انجام داده است در آن قرار دارد، صرف نظر از اینکه بالاترین پنجره کدام باشد.

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

مثال‌ها

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

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

انواع

CreateType

کروم ۴۴+

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

شمارشی

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

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

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

QueryOptions

کروم ۸۸+

خواص

  • آباد کردن

    بولی اختیاری

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

  • انواع پنجره

    نوع پنجره [] اختیاری

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

Window

خواص

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

    بولی

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

  • متمرکز

    بولی

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

  • ارتفاع

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

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

  • شناسه

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

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

  • ناشناس

    بولی

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

  • چپ

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

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

  • شناسه جلسه

    رشته اختیاری

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

  • ایالت

    حالت پنجره اختیاری است

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

  • زبانه‌ها

    تب [] اختیاری

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

  • بالا

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

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

  • نوع

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

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

  • عرض

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

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

WindowState

کروم ۴۴+

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

شمارشی

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

"به حداقل رسیده"
حالت پنجره کوچک‌شده.

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

"تمام صفحه"
حالت پنجره تمام صفحه.

WindowType

کروم ۴۴+

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

شمارشی

"عادی"
یک پنجره مرورگر معمولی.

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

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

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

"ابزارهای توسعه"
یک پنجره ابزار توسعه‌دهندگان.

خواص

WINDOW_ID_CURRENT

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

ارزش

-۲

WINDOW_ID_NONE

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

ارزش

-1

روش‌ها

create()

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

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

پارامترها

  • ایجادداده

    شیء اختیاری

    • متمرکز

      بولی اختیاری

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

    • ارتفاع

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

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

    • ناشناس

      بولی اختیاری

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

    • چپ

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

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

    • setSelfAsOpener

      بولی اختیاری

      کروم ۶۴+

      اگر true ، 'window.opener' پنجره‌ی تازه ایجاد شده روی فراخواننده تنظیم می‌شود و در همان واحد زمینه‌های مرور مرتبط با فراخواننده قرار دارد.

    • ایالت

      حالت پنجره اختیاری است

      کروم ۴۴+

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

    • شناسه برگه

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

      شناسه‌ی برگه‌ای که قرار است به پنجره‌ی جدید اضافه شود.

    • بالا

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

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

    • نوع

      نوع ایجاد اختیاری

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

    • آدرس اینترنتی

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

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

    • عرض

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

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (window?: Window) => void

    • پنجره

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

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

بازگشت‌ها

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

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

get()

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

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

پارامترها

  • شناسه پنجره

    شماره

  • گزینه‌های پرس‌وجو

    گزینه‌های پرس‌وجو اختیاری

    کروم ۸۸+
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (window: Window) => void

بازگشت‌ها

  • قول< پنجره >

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getAll()

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

همه پنجره‌ها را می‌گیرد.

پارامترها

  • گزینه‌های پرس‌وجو

    گزینه‌های پرس‌وجو اختیاری

    کروم ۸۸+
  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (windows: Window[]) => void

بازگشت‌ها

  • قول< پنجره []>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getCurrent()

وعده
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

پارامترها

بازگشت‌ها

  • قول< پنجره >

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getLastFocused()

وعده
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

پنجره‌ای را که اخیراً فوکوس روی آن انجام شده است - معمولاً پنجره‌ای که در بالا قرار دارد - برمی‌گرداند.

پارامترها

بازگشت‌ها

  • قول< پنجره >

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

remove()

وعده
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

یک پنجره و تمام تب‌های داخل آن را حذف (می‌بندد).

پارامترها

  • شناسه پنجره

    شماره

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

update()

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

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

پارامترها

  • شناسه پنجره

    شماره

  • اطلاعات به‌روزرسانی

    شیء

    • جلب توجه

      بولی اختیاری

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

    • متمرکز

      بولی اختیاری

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

    • ارتفاع

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

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

    • چپ

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

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

    • ایالت

      حالت پنجره اختیاری است

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

    • بالا

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

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

    • عرض

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

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (window: Window) => void

بازگشت‌ها

  • قول< پنجره >

    کروم ۸۸+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onBoundsChanged

کروم ۸۶+
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (window: Window) => void

onCreated

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

هنگام ایجاد یک پنجره اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

    کروم ۴۶+

    پارامتر callback به شکل زیر است: 

    (window: Window) => void

    • پنجره

      پنجره

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

  • فیلترها

    شیء اختیاری

    • انواع پنجره

      نوع پنجره []

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

onFocusChanged

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

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

پارامترها

  • تماس برگشتی

    تابع

    کروم ۴۶+

    پارامتر callback به شکل زیر است: 

    (windowId: number) => void

    • شناسه پنجره

      شماره

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

  • فیلترها

    شیء اختیاری

    • انواع پنجره

      نوع پنجره []

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

onRemoved

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

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

پارامترها

  • تماس برگشتی

    تابع

    کروم ۴۶+

    پارامتر callback به شکل زیر است: 

    (windowId: number) => void

    • شناسه پنجره

      شماره

      شناسه پنجره حذف شده.

  • فیلترها

    شیء اختیاری

    • انواع پنجره

      نوع پنجره []

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