chrome.windows

الوصف

يمكنك استخدام واجهة برمجة تطبيقات chrome.windows للتفاعل مع نوافذ المتصفِّح. ويمكنك استخدام واجهة برمجة التطبيقات هذه لإنشاء النوافذ وتعديلها وإعادة ترتيبها في المتصفّح.

الأذونات

عند طلب، يحتوي windows.Window على مصفوفة من عناصر tabs.Tab. يجب يُرجى الإفصاح عن إذن ""tabs"" في بيانك إذا كنت بحاجة إلى الوصول إلى url، pendingUrl أو title أو favIconUrl من tabs.Tab. على سبيل المثال:

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

المفاهيم والاستخدام

النافذة الحالية

تستخدم العديد من الدوال في نظام الإضافات وسيطة windowId اختيارية، والتي يتم ضبطها تلقائيًا على النافذة الحالية.

النافذة الحالية هي النافذة التي تتضمّن الرمز البرمجي الذي يتم تنفيذه حاليًا. من المهم إدراك أن هذه النافذة يمكن أن تختلف عن النافذة العلوية أو محل التركيز.

على سبيل المثال، لنفترض أن إحدى الإضافات تنشئ بعض علامات التبويب أو النوافذ من ملف HTML واحد، وأن يحتوي ملف HTML على استدعاء إلى tabs.query(). والنافذة الحالية هي النافذة التي تحتوي على الصفحة التي أجرى الاتصال، بغض النظر عن النافذة العلوية.

في حالة عاملي الخدمة، تعود قيمة النافذة الحالية إلى آخر نشاط. نافذة. في بعض الحالات، قد لا تتوفّر أي نافذة حالية لصفحات الخلفية.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت مثال على واجهة برمجة تطبيقات النوافذ من chrome-extension-samples المستودع.

نافذتان، تحتوي كل منهما على علامة تبويب واحدة
نافذتان، تحتوي كل منهما على علامة تبويب واحدة.

الأنواع

CreateType

الإصدار 44 من Chrome أو الإصدارات الأحدث

تحدِّد هذه السياسة نوع نافذة المتصفّح المطلوب إنشاؤها. "لوحة" متوقفة نهائيًا ولا تتوفّر إلا للإضافات الحالية المُدرَجة في القائمة المسموح بها على نظام التشغيل ChromeOS.

Enum

"normal"
يحدد هذا الإعداد النافذة كنافذة عادية.

"نافذة منبثقة"
يحدِّد هذا العمود النافذة كنافذة منبثقة.

"اللوحة"
يحدّد هذا الخيار النافذة كلوحة.

QueryOptions

الإصدار 88 من Chrome أو الإصدارات الأحدث

أماكن إقامة

  • تعبئة

    قيمة منطقية اختيارية

    إذا كانت القيمة هي true، سيحتوي الكائن windows.Window على السمة tabs التي تحتوي على قائمة بكائنات tabs.Tab. تحتوي كائنات Tab على السمات url وpendingUrl وtitle وfavIconUrl فقط إذا كان ملف بيان الإضافة يتضمّن إذن "tabs".

  • windowTypes

    WindowType[] اختياري

    وفي حال ضبطها، تتم فلترة windows.Window المعروضة بناءً على نوعها. وفي حال ترك هذه السياسة بدون ضبط، يتم ضبط الفلتر التلقائي على ['normal', 'popup'].

Window

أماكن إقامة

  • alwaysOnTop

    منطقي

    ما إذا تم ضبط النافذة لتكون دائمًا في الأعلى.

  • مركَّز

    منطقي

    ما إذا كانت النافذة هي النافذة محل التركيز حاليًا.

  • الطول

    الرقم اختياري

    ارتفاع النافذة، بما في ذلك الإطار، بالبكسل في بعض الحالات، قد لا يتم تخصيص السمة height للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

  • id

    الرقم اختياري

    رقم تعريف النافذة تكون معرّفات الفترات فريدة ضمن جلسة المتصفّح. في بعض الحالات، قد لا يتم تخصيص السمة ID للنافذة. على سبيل المثال، عند إجراء طلبات بحث عن النوافذ باستخدام واجهة برمجة التطبيقات sessions، قد يتوفّر رقم تعريف جلسة في هذه الحالة.

  • وضع التصفُّح المتخفي

    منطقي

    ما إذا كانت النافذة في وضع التصفُّح المتخفِّي

  • اليسرى

    الرقم اختياري

    إزاحة النافذة من الحافة اليسرى للشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص السمة left للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

  • sessionId

    سلسلة اختيارية

    رقم تعريف الجلسة المستخدَم لتحديد فترة بشكلٍ فريد، من خلال واجهة برمجة تطبيقات sessions.

  • الولاية

    WindowState اختياري

    حالة نافذة المتصفح هذه

  • علامات التبويب

    Tab[] اختيارية

    مصفوفة من عناصر tabs.Tab التي تمثّل علامات التبويب الحالية في النافذة

  • العلوية

    الرقم اختياري

    إزاحة النافذة من الحافة العلوية للشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص السمة top للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

  • كتابة

    WindowType اختياري

    نوع نافذة المتصفح هذه.

  • العرض

    الرقم اختياري

    عرض النافذة، بما في ذلك الإطار، بالبكسل. في بعض الحالات، قد لا يتم تخصيص السمة width للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

WindowState

الإصدار 44 من Chrome أو الإصدارات الأحدث

حالة نافذة المتصفح هذه في بعض الحالات، قد لا يتم تخصيص السمة state للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

Enum

"normal"
حالة النافذة العادية (غير مصغَّرة أو مصغَّرة أو بملء الشاشة).

"minimized"
حالة النافذة المصغّرة

"maximized"
حالة النافذة المُكبَّرة.

"ملء الشاشة"
حالة النافذة بملء الشاشة.

"قفل الشاشة بملء الشاشة"
حالة نافذة ملء الشاشة المُقفَلة لا يمكن الخروج من حالة ملء الشاشة هذه من خلال إجراء المستخدم، ولا تتوفّر إلا للإضافات المُدرَجة في القائمة المسموح بها على نظام التشغيل ChromeOS.

WindowType

الإصدار 44 من Chrome أو الإصدارات الأحدث

نوع نافذة المتصفح هذه. في بعض الحالات، قد لا يتم تخصيص السمة type للنافذة. على سبيل المثال، عند الاستعلام عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

Enum

"normal"
نافذة متصفح عادية

"نافذة منبثقة"
نافذة منبثقة في المتصفّح.

"panel"
تم إيقاف العمل بها في واجهة برمجة التطبيقات هذه. نافذة بنمط لوحة تطبيق Chrome يمكن للإضافات الاطّلاع على نوافذ اللوحات الخاصة بها فقط.

"التطبيق"
تم إيقاف العمل به في واجهة برمجة التطبيقات هذه. نافذة تطبيق Chrome يمكن للإضافات الاطّلاع على نوافذ التطبيقات الخاصة بها فقط.

"devtools"
نافذة أدوات المطوّرين.

أماكن إقامة

WINDOW_ID_CURRENT

تمثّل هذه السمة قيمة windowId التي تمثّل النافذة الحالية.

القيمة

-2

WINDOW_ID_NONE

تمثّل هذه السمة قيمة windowId التي تمثّل عدم توفُّر نافذة متصفِّح Chrome.

القيمة

-1

الطُرق

create()

وعود 
chrome.windows.create(
  createData?: object,
  callback?: function,
)

ينشئ (يفتح) نافذة متصفّح جديدة مع توفير أي عنوان URL تلقائي لتغيير الحجم أو موضعه أو تلقائيًا.

المعلمات

  • createData

    الكائن اختياري

    • مركَّز

      قيمة منطقية اختيارية

      في حال true، سيتم فتح نافذة نشطة. في حال false، سيتم فتح نافذة غير نشطة.

    • الطول

      الرقم اختياري

      الارتفاع بالبكسل للنافذة الجديدة، بما في ذلك الإطار. إذا لم يتم تحديده، سيتم ضبطه تلقائيًا على ارتفاع طبيعي.

    • وضع التصفُّح المتخفي

      قيمة منطقية اختيارية

      لتحديد ما إذا كان يجب أن تكون النافذة الجديدة نافذة تصفّح متخفٍ.

    • اليسرى

      الرقم اختياري

      عدد وحدات البكسل المطلوب وضع النافذة الجديدة من الحافة اليسرى للشاشة. إذا لم يتم تحديده، تتم إزاحة النافذة الجديدة بشكل طبيعي من آخر نافذة تم التركيز عليها. يتم تجاهل هذه القيمة في اللوحات.

    • setSelfAsOpener

      قيمة منطقية اختيارية

      الإصدار 64 من Chrome أو الإصدارات الأحدث

      في حال true، سيتم استخدام نافذة "window.opener" للنافذة التي تم إنشاؤها حديثًا. يتم تعيينه للمتصل وفي وحدة سياقات التصفح ذات الصلة نفسها مثل المتصل.

    • الولاية

      WindowState اختياري

      الإصدار 44 من Chrome أو الإصدارات الأحدث

      الحالة الأولية للنافذة. لا يمكن الجمع بين الحالات minimized وmaximized وfullscreen مع left أو top أو width أو height.

    • tabId

      الرقم اختياري

      رقم تعريف علامة التبويب المطلوب إضافتها إلى النافذة الجديدة.

    • العلوية

      الرقم اختياري

      عدد وحدات البكسل المطلوب وضع النافذة الجديدة من الحافة العلوية من الشاشة. إذا لم يتم تحديده، تتم إزاحة النافذة الجديدة بشكل طبيعي من آخر نافذة تم التركيز عليها. يتم تجاهل هذه القيمة في اللوحات.

    • كتابة

      CreateType اختيارية

      تحدِّد هذه السياسة نوع نافذة المتصفّح المطلوب إنشاؤها.

    • url

      string | string[] اختيارية

      عنوان URL أو مصفوفة عناوين URL يتم فتحها كعلامات تبويب في النافذة. يجب أن تحتوي عناوين URL المؤهلة بالكامل على مخطّط، مثل "http://www.google.com" وليس "www.google.com". وتُعتبَر عناوين URL غير المؤهَّلة بالكامل نسبية ضمن الإضافة. يتم ضبط الإعدادات التلقائية على صفحة "علامة تبويب جديدة".

    • العرض

      الرقم اختياري

      عرض النافذة الجديدة بالبكسل، بما في ذلك الإطار. إذا لم يتم تحديده، سيتم ضبطه تلقائيًا على عرض طبيعي.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (window?: Window) => void

    • نافذة

      النافذة اختيارية

      يحتوي على تفاصيل حول النافذة التي تم إنشاؤها.

المرتجعات

  • Promise<Window | غير محددة>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

get()

وعود 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

الحصول على تفاصيل حول نافذة

المعلمات

  • windowId

    الرقم

  • queryOptions

    QueryOptions اختيارية

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getAll()

وعود 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

إتاحة الوصول إلى جميع النوافذ

المعلمات

  • queryOptions

    QueryOptions اختيارية

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (windows: Window[]) => void

المرتجعات

  • Promise<Window[]>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getCurrent()

وعود 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

عرض النافذة الحالية

المعلمات

  • queryOptions

    QueryOptions اختيارية

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getLastFocused()

وعود 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

الحصول على النافذة التي تم التركيز عليها مؤخرًا، وتكون عادةً النافذة "في الأعلى".

المعلمات

  • queryOptions

    QueryOptions اختيارية

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

remove()

وعود 
chrome.windows.remove(
  windowId: number,
  callback?: function,
)

إزالة (إغلاق) نافذة وجميع علامات التبويب بداخلها

المعلمات

  • windowId

    الرقم

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

update()

وعود 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
)

لتعديل خصائص إحدى النوافذ. تحديد السمات التي سيتم تغييرها فقط الخصائص غير المحددة لم تتغير.

المعلمات

  • windowId

    الرقم

  • updateInfo

    كائن

    • drawAttention

      قيمة منطقية اختيارية

      إذا كان true، يؤدي إلى عرض النافذة بطريقة تلفت انتباه المستخدم إلى النافذة، بدون تغيير النافذة التي يتم التركيز عليها. يستمر التأثير حتى يغيّر المستخدم التركيز إلى النافذة. لن يكون لهذا الخيار أي تأثير إذا كانت النافذة مُركَّزة عليها مسبقًا. يُرجى ضبط القيمة على false لإلغاء طلب drawAttention سابق.

    • مركَّز

      قيمة منطقية اختيارية

      إذا كانت true، سيتم إحضار النافذة إلى الأمام. لا يمكن الجمع بينه وبين الحالة " مصغر". إذا كانت false، سيتم عرض النافذة التالية بالترتيب z إلى المقدمة. لا يمكن دمجه مع الحالة "ملء الشاشة" أو "مكبَّر".

    • الطول

      الرقم اختياري

      الارتفاع المطلوب تغيير حجم النافذة إليه بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

    • اليسرى

      الرقم اختياري

      الإزاحة من الحافة اليسرى للشاشة لنقل النافذة بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

    • الولاية

      WindowState اختياري

      الحالة الجديدة للنافذة. "ميني" و"مكبس" و"ملء الشاشة" لا يمكن دمج الحالات مع "left" أو "top" أو "width" أو "height".

    • العلوية

      الرقم اختياري

      الإزاحة من الحافة العلوية للشاشة لنقل النافذة بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

    • العرض

      الرقم اختياري

      العرض المطلوب تغيير حجم النافذة إليه بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise&lt;Window&gt;

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

فعاليات

onBoundsChanged

الإصدار 86 من Chrome أو الإصدارات الأحدث 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

يتم تنشيطها عند تغيير حجم النافذة. لا يتم إرسال هذا الحدث إلا عند الالتزام بالحدود الجديدة، وليس للتغييرات الجارية.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

onCreated

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

يتم تنشيطها عند إنشاء نافذة.

المعلمات

  • رد الاتصال

    دالة

    الإصدار 46 من Chrome أو الإصدارات الأحدث

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

    • نافذة

      نافذة

      تفاصيل النافذة التي تم إنشاؤها

  • الفلاتر

    الكائن اختياري

    • windowTypes

      WindowType[]

      الشروط التي يجب أن يستوفيها نوع النافذة التي يتم إنشاؤها. يتوافق مع "['normal', 'popup']" تلقائيًا.

onFocusChanged

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

يتم إطلاقه عند تغيير النافذة التي يتم التركيز عليها حاليًا. عرض chrome.windows.WINDOW_ID_NONE في حال فقدان التركيز على جميع نوافذ Chrome. ملاحظة: في بعض مدراء النوافذ في نظام التشغيل Linux، يتم دائمًا إرسال WINDOW_ID_NONE مباشرةً قبل التبديل من نافذة Chrome إلى نافذة أخرى.

المعلمات

  • رد الاتصال

    دالة

    الإصدار 46 من Chrome أو الإصدارات الأحدث

    تظهر المَعلمة callback على النحو التالي: 

    (windowId: number) => void

    • windowId

      الرقم

      رقم تعريف النافذة التي تم التركيز عليها حديثًا.

  • الفلاتر

    الكائن اختياري

    • windowTypes

      WindowType[]

      يجب أن يستوفي الشروط التي يجب أن تستوفيها نوع النافذة التي تتم إزالتها. يتوافق مع "['normal', 'popup']" تلقائيًا.

onRemoved

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

يتم الإطلاق عند إزالة نافذة (إغلاقها).

المعلمات

  • رد الاتصال

    دالة

    الإصدار 46 من Chrome أو الإصدارات الأحدث

    تظهر المَعلمة callback على النحو التالي: 

    (windowId: number) => void

    • windowId

      الرقم

      رقم تعريف النافذة التي تمت إزالتها

  • الفلاتر

    الكائن اختياري

    • windowTypes

      WindowType[]

      يجب أن يستوفي الشروط التي يجب أن تستوفيها نوع النافذة التي تتم إزالتها. يتوافق مع "['normal', 'popup']" تلقائيًا.