chrome.omnibox

تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex

توضیحات

رابط برنامه‌نویسی کاربردی omnibox به شما امکان می‌دهد یک کلمه کلیدی را در نوار آدرس گوگل کروم ثبت کنید، که به عنوان omnibox نیز شناخته می‌شود.

تصویری از صفحه نمایش که پیشنهادات مربوط به کلمه کلیدی «جستجوی کرومیوم» را نشان می‌دهد

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

این پیشنهادها می‌توانند به روش‌های مختلفی قالب‌بندی شوند. وقتی کاربر پیشنهادی را می‌پذیرد، افزونه شما مطلع می‌شود و می‌تواند اقدام کند.

مانیفست

برای استفاده از رابط برنامه‌نویسی کاربردی omnibox، باید یک فیلد keyword omnibox در مانیفست وارد کنید. همچنین باید یک آیکون 16x16 پیکسلی مشخص کنید که هنگام پیشنهاد ورود به حالت کلمه کلیدی توسط کاربران، در نوار آدرس نمایش داده می‌شود.

برای مثال:

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

مثال‌ها

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

انواع

DefaultSuggestResult

یک نتیجه پیشنهادی.

خواص

  • توضیحات

    رشته

    متنی که در منوی کشویی URL نمایش داده می‌شود. می‌تواند شامل نشانه‌گذاری به سبک XML برای استایل‌دهی باشد. تگ‌های پشتیبانی‌شده عبارتند از 'url' (برای URL تحت‌اللفظی)، 'match' (برای هایلایت کردن متنی که با عبارت جستجوی کاربر مطابقت دارد) و 'dim' (برای متن کمکی کم‌رنگ). استایل‌ها می‌توانند تودرتو باشند، مثلاً dimmed match.

DescriptionStyleType

کروم ۴۴+

نوع سبک.

شمارشی

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

"مطابقت"

"کم نور"

OnInputEnteredDisposition

کروم ۴۴+

حالت پنجره برای کوئری omnibox. این زمینه پیشنهادی برای نمایش نتایج است. برای مثال، اگر دستور omnibox قرار است به یک URL خاص هدایت شود، حالت 'newForegroundTab' به این معنی است که پیمایش باید در یک تب انتخاب شده جدید انجام شود.

شمارشی

"تب فعلی"

"تب پیش‌زمینه جدید"

"تب پس‌زمینه جدید"

SuggestResult

یک نتیجه پیشنهادی.

خواص

  • محتوا

    رشته

    متنی که در نوار آدرس قرار می‌گیرد و وقتی کاربر این ورودی را انتخاب می‌کند، به افزونه ارسال می‌شود.

  • قابل حذف

    بولی اختیاری

    کروم ۶۳+

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

  • توضیحات

    رشته

    متنی که در منوی کشویی URL نمایش داده می‌شود. می‌تواند شامل نشانه‌گذاری به سبک XML برای استایل‌دهی باشد. تگ‌های پشتیبانی‌شده عبارتند از 'url' (برای URL تحت‌اللفظی)، 'match' (برای هایلایت کردن متنی که با عبارت جستجوی کاربر مطابقت دارد) و 'dim' (برای متن کمکی کم‌رنگ). استایل‌ها می‌توانند تودرتو باشند، مثلاً dimmed match. برای نمایش آن‌ها به عنوان متن، باید از پنج موجودیت از پیش تعریف‌شده escape کنید: stackoverflow.com/a/1091953/89484

روش‌ها

setDefaultSuggestion()

وعده
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

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

پارامترها

  • یک شیء SuggestResult ناقص، بدون پارامتر 'content'.

  • تماس برگشتی

    تابع اختیاری

    کروم ۱۰۰+

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

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۱۰۰+

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

رویدادها

onDeleteSuggestion

کروم ۶۳+
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

کاربر یک نتیجه پیشنهادی را حذف کرده است.

پارامترها

  • تماس برگشتی

    تابع

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

    (text: string) => void

    • متن

      رشته

onInputCancelled

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

کاربر جلسه‌ی ورودی کلمه کلیدی را بدون پذیرش ورودی به پایان رسانده است.

پارامترها

  • تماس برگشتی

    تابع

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

    () => void

onInputChanged

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

کاربر آنچه را که در omnibox تایپ می‌شود تغییر داده است.

پارامترها

  • تماس برگشتی

    تابع

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

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

    • متن

      رشته

    • پیشنهاد دادن

      تابع

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

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

کاربر آنچه را که در omnibox تایپ شده است، پذیرفته است.

پارامترها

onInputStarted

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

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

پارامترها

  • تماس برگشتی

    تابع

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

    () => void