chrome.omnibox

الوصف

تتيح لك واجهة برمجة التطبيقات المربع المتعدد الاستخدامات تسجيل كلمة رئيسية في شريط عناوين Google Chrome، والذي يُعرف أيضًا باسم المربّع المتعدد الاستخدامات.

لقطة شاشة تعرض اقتراحات ذات صلة بالكلمة الرئيسية "بحث Chromium"

عندما يُدخل المستخدم الكلمة الرئيسية لإضافتك، يبدأ المستخدم في التفاعل معها فقط. يتم إرسال كل ضغطة مفتاح إلى إضافتك، ويمكنك تقديم اقتراحات ردًّا عليها.

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

البيان

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

"omnibox"

يجب تضمين حقل "omnibox.keyword" في البيان لاستخدام واجهة برمجة التطبيقات للمربّع متعدد الاستخدامات. يجب عليك أيضًا تحديد رمز بحجم 16 × 16 بكسل، والذي سيتم عرضه في شريط العناوين عند اقتراح المستخدمين الدخول إلى وضع الكلمات الرئيسية.

مثال:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

أمثلة

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

الأنواع

DefaultSuggestResult

نتيجة مقترَحة.

أماكن إقامة

  • الوصف

    سلسلة

    النص المعروض في القائمة المنسدلة لعنوان URL. يمكن أن تحتوي على ترميز بنمط XML للأنماط. العلامات المسموح بها هي "url" (لعنوان URL الحرفي)، و"match" (لتمييز النص الذي يطابق طلب بحث المستخدم)، و"dim" (لنص مساعد باهت). يمكن دمج الأنماط، على سبيل المثال، مطابقة باهتة.

DescriptionStyleType

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

نوع النمط.

التعداد

"url"

"dim"

OnInputEnteredDisposition

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

ترتيب النافذة لاستعلام المربع المتعدد الاستخدامات. هذا هو السياق المقترَح لعرض النتائج. على سبيل المثال، إذا كان الأمر في المربّع المتعدد الاستخدامات هو الانتقال إلى عنوان URL معيّن، يعني توزيع "newForegroundTab" أن يتم التنقّل في علامة تبويب جديدة ومحددة.

التعداد

"currentTab"

"newForegroundTab"

SuggestResult

نتيجة مقترَحة.

أماكن إقامة

  • بمحتوى

    سلسلة

    تمثّل هذه السمة النص الذي يتمّ وضعه في شريط عنوان URL والذي يتمّ إرساله إلى الإضافة عندما يختار المستخدِم هذا الإدخال.

  • قابل للحذف

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

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

    ما إذا كان بإمكان المستخدم حذف نتيجة الاقتراح.

  • الوصف

    سلسلة

    النص المعروض في القائمة المنسدلة لعنوان URL. يمكن أن تحتوي على ترميز بنمط XML للأنماط. العلامات المسموح بها هي "url" (لعنوان URL الحرفي)، و"match" (لتمييز النص الذي يطابق طلب بحث المستخدم)، و"dim" (لنص مساعد باهت). يمكن دمج الأنماط، على سبيل المثال، مطابقة باهتة. يجب عليك تخطي الكيانات الخمسة المحددة مسبقًا لعرضها كنص: Stoverflow.com/a/1091953/89484.

الطُرق

setDefaultSuggestion()

وعد 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

تُحدِّد الوصف والتصميم للاقتراح التلقائي. الاقتراح التلقائي هو النص الذي يظهر في صف الاقتراح الأول أسفل شريط عنوان URL.

المَعلمات

  • اقتراح

    DefaultSuggestResult

    عنصر ClaimResult جزئي، بدون المعلمة 'content'.

  • معاودة الاتصال

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

    Chrome 100 والإصدارات الأحدث

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

    Chrome 100 والإصدارات الأحدث

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

فعاليات

onDeleteSuggestion

الإصدار 63 من Chrome والإصدارات الأحدث 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

حذف المستخدم نتيجة مقترَحة.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (text: string)=>void

    • text

      سلسلة

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(
  callback: function,
)

أنهى المستخدم جلسة إدخال الكلمات الرئيسية بدون قبول البيانات.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

onInputChanged

chrome.omnibox.onInputChanged.addListener(
  callback: function,
)

غيَّر المستخدم ما تتم كتابته في المربّع المتعدد الاستخدامات.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (text: string,suggest: function)=>void

    • text

      سلسلة

    • اقتراح

      الوظيفة

      تبدو معلَمة suggest على النحو التالي: 

      (suggestResults: SuggestResult[])=>void

      • suggestResults

        SuggestResult[]

        مصفوفة نتائج الاقتراحات

onInputEntered

chrome.omnibox.onInputEntered.addListener(
  callback: function,
)

وافق المستخدم على ما تتم كتابته في المربّع المتعدد الاستخدامات.

المَعلمات

onInputStarted

chrome.omnibox.onInputStarted.addListener(
  callback: function,
)

بدأ المستخدم جلسة إدخال الكلمة الرئيسية عن طريق كتابة الكلمة الرئيسية للإضافة. يمكن ضمان إرسال هذا الحدث مرة واحدة بالضبط لكل جلسة إدخال، وقبل أي أحداث onInputChanged.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    ()=>void