chrome.omnibox

refresh date: 2026-09-25 robots: noindex

شرح

omnibox API به شما امکان می‌دهد کلیدواژه‌ای را در نوار نشانی Google Chrome (که omnibox نیز نامیده می‌شود) ثبت کنید.

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

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

مانیفست

برای استفاده از omnibox API، باید فیلد omnibox keyword را در مانیفست اضافه کنید. همچنین باید نمادی ۱۶×۱۶ پیکسلی مشخص کنید که هنگام پیشنهاد دادن به کاربران برای ورود به حالت کلیدواژه در نوار نشانی نمایش داده می‌شود.

برای مثال:

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

توجه: Chrome به‌طور خودکار نسخه خاکستری نماد ۱۶×۱۶ پیکسلی شما را ایجاد می‌کند. باید نسخه تمام‌رنگی ارائه دهید تا بتوان از آن در موقعیت‌های دیگری که به رنگ نیاز دارند نیز استفاده کرد. برای مثال، میانای برنامه‌سازی کاربردی منوهای زمینه‌ای نیز از نماد ۱۶×۱۶ پیکسلی استفاده می‌کند، اما به‌صورت رنگی نمایش داده می‌شود.

مثال‌ها

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

انواع

DefaultSuggestResult

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

مشخصات

• description

  رشته

  نوشتاری که در منو کرکره‌ای نشانی وب نمایش داده می‌شود. می‌تواند حاوی نشانه‌گذاری XML-style برای سبک‌بندی باشد. برچسب‌های پشتیبانی‌شده عبارت‌اند از: «url» (برای نشانی وب تحت‌اللفظی)، «match» (برای برجسته کردن نوشتاری که با پُرسمان کاربر مطابقت دارد)، و «dim» (برای نوشتار راهنمای کم‌نور). سبک‌ها می‌توانند تودرتو باشند، مثلاً مطابقت کم‌نور.

DescriptionStyleType

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

نوع سبک.

شمارشی

«url»

«مطابقت»

«dim»

OnInputEnteredDisposition

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

وضعیت پنجره برای پُرسمان omnibox. این بافت توصیه‌شده برای نمایش نتایج است. برای مثال، اگر فرمان کادر چندمنظوره پیمایش به نشانی وب خاصی باشد، ترتیب «newForegroundTab» به این معنی است که پیمایش باید در برگه انتخاب‌شده جدیدی انجام شود.

شمارشی

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

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

مشخصات

• محتوا

  رشته

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

• قابل‌حذف

  بولی اختیاری

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

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

• description

  رشته

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

روش‌ها

setDefaultSuggestion()

قول

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

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

پارامترها

• پیشنهاد

  DefaultSuggestResult

  یک شیء SuggestResult جزئی، بدون پارامتر «محتوا».

• تماس برگشتی

  تابع اختیاری

  Chrome نسخه ۱۰۰ به بالا

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۱۰۰ به بالا

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

رویدادها

onDeleteSuggestion

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

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,
)

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

پارامترها

• تماس برگشتی

  عملکرد

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

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

  • نوشتار

    رشته

  • پیشنهاد

    عملکرد

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

    (suggestResults: SuggestResult[]) => void

    • suggestResults

      SuggestResult[]

      آرایه نتایج پیشنهاد

onInputEntered

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

کاربر آنچه را در همه‌جانبه‌باکس تایپ شده است پذیرفته است.

پارامترها

• تماس برگشتی

  عملکرد

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

  (text: string, disposition: OnInputEnteredDisposition) => void

  • نوشتار

    رشته

  • disposition

    OnInputEnteredDisposition

onInputStarted

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

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

پارامترها

• تماس برگشتی

  عملکرد

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

  () => void