browser.history

شرح

از chrome.history API برای تعامل با سابقه صفحه‌های بازدیدشده در مرورگر استفاده کنید. می‌توانید نشانی‌های وب را در سابقه مرورگر اضافه، حذف، و پُرسمان کنید. برای لغو کردن صفحه سابقه با نسخه خودتان، لغو کردن صفحه‌ها را ببینید.

اجازه‌ها

history

برای تعامل با سابقه مرورگر کاربر، از history API استفاده کنید.

برای استفاده از میانای برنامه‌سازی کاربردی سابقه، اجازه "history" را در مانیفست افزونه اعلام کنید. برای مثال:

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

مفاهیم و کاربرد

انواع گذار

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

مثال‌ها

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

انواع

HistoryItem

شیئی که یک نتیجه از پُرسمان سابقه را کپسوله‌سازی می‌کند.

مشخصات

  • id

    رشته

    شناسه یکتای مورد.

  • lastVisitTime

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

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

  • عنوان

    رشته اختیاری

    عنوان صفحه در آخرین باری که بار شده است.

  • typedCount

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

    تعداد دفعاتی که کاربر با تایپ کردن نشانی به این صفحه پیمایش کرده است.

  • نشانی وب

    رشته اختیاری

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

  • visitCount

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

    تعداد دفعاتی که کاربر به این صفحه پیمایش کرده است.

TransitionType

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع انتقال برای این بازدید از ارجاع‌دهنده آن.

شمارشی

«پیوند»
کاربر با کلیک کردن روی پیوندی در صفحه‌ای دیگر به این صفحه رسیده است.

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

«auto_bookmark»
کاربر ازطریق پیشنهادی در میانای کاربر، مثلاً ازطریق گزینه منو، به این صفحه رسیده است.

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

"manual_subframe"
کاربر با انتخاب چیزی در زیرقاب به این صفحه رسیده است.

«تولیدشده»
کاربر با تایپ کردن در نوار نشانی و انتخاب ورودی‌ای که شبیه به نشانی وب نبود (مثل پیشنهاد «جستجوی Google»)، به این صفحه رسیده است. برای مثال، ممکن است یک مورد مطابقت نشانی وب صفحه نتایج «جستجوی Google» را داشته باشد، اما ممکن است برای کاربر به‌صورت «جستجوی Google برای …» نشان داده شود. این موارد با پیمایش‌های تایپ‌شده متفاوت هستند زیرا کاربر نشانی وب مقصد را تایپ نکرده یا ندیده است. این موارد به پیمایش کلیدواژه نیز مربوط می‌شوند.

«auto_toplevel»
صفحه در خط فرمان مشخص شده است یا صفحه شروع است.

«form_submit»
کاربر با تکمیل مقادیر در فرم و ارسال فرم به این صفحه رسیده است. همه فرم‌های ارسال‌شده از این نوع انتقال استفاده نمی‌کنند.

«reload»
کاربر صفحه را با کلیک کردن روی دکمه بار کردن مجدد یا با فشار دادن کلید Enter در نوار نشانی مجدداً بار کرده است. بازیابی جلسه و باز کردن مجدد برگه بسته‌شده نیز از این نوع انتقال استفاده می‌کنند.

«کلیدواژه»
نشانی وب این صفحه از کلیدواژه قابل‌جایگزینی به‌جز ارائه‌دهنده جستجوی پیش‌فرض تولید شده است.

"keyword_generated"
مربوط به بازدیدی است که برای کلیدواژه ایجاد شده است.

UrlDetails

Chrome 88+ browser.* از Chrome 148

مشخصات

  • نشانی وب

    رشته

    نشانی وب برای عملیات. باید در قالبی باشد که از تماس با history.search() برگردانده شده است.

VisitItem

شیئی که یک بازدید از نشانی وب را کپسوله‌سازی می‌کند.

مشخصات

  • id

    رشته

    شناسه یکتای history.HistoryItem مربوطه.

  • isLocal

    بولی

    Chrome نسخه ۱۱۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

    اگر بازدید از این دستگاه شروع شده باشد، مقدار درست است. اگر از دستگاه دیگری همگام‌سازی شده باشد، «نادرست» است.

  • referringVisitId

    رشته

    شناسه بازدید ارجاع‌دهنده.

  • نوع انتقال برای این بازدید از ارجاع‌دهنده آن.

  • visitId

    رشته

    شناسه یکتای این بازدید.

  • visitTime

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

    زمان وقوع این بازدید، که برحسب میلی‌ثانیه از تاریخ نشان داده می‌شود.

روش‌ها

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

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

پارامترها

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

deleteAll()

browser.history.deleteAll(): Promise<void>

همه موارد را از سابقه حذف می‌کند.

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

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

پارامترها

  • بازه مسافت در هر سوخت‌گیری

    شیء

    • endTime

      شماره

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

    • startTime

      شماره

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

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

همه موارد نشانی وب ارائه‌شده را از سابقه برمی‌دارد.

پارامترها

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

اطلاعات مربوط به بازدیدها از نشانی وب را بازیابی می‌کند.

پارامترها

بازگشتی‌ها

  • Promise<VisitItem[]>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸ 
browser.history.search(
  query: object,
): Promise<HistoryItem[]>

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

پارامترها

  • پُرسمان

    شیء

    • endTime

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

      نتایج را به مواردی که قبل‌از این تاریخ بازدید شده‌اند محدود می‌کند، که برحسب میلی‌ثانیه از تاریخ یونیکس نشان داده می‌شود.

    • maxResults

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

      حداکثر تعداد نتایج برای بازیابی. پیش‌فرض ۱۰۰ است.

    • startTime

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

      نتایج را به مواردی که پس‌از این تاریخ بازدید شده‌اند محدود می‌کند، که برحسب میلی‌ثانیه از تاریخ نشان داده می‌شود. اگر ویژگی مشخص نشده باشد، به‌طور پیش‌فرض ۲۴ ساعت خواهد بود.

    • نوشتار

      رشته

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

بازگشتی‌ها

  • Promise<HistoryItem[]>

    Chrome نسخه ۹۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

رویدادها

onVisited

browser.history.onVisited.addListener(
  callback: function,
)

وقتی نشانی وبی بازدید می‌شود، فعال می‌شود و داده‌های HistoryItem را برای آن نشانی وب ارائه می‌دهد. این رویداد قبل‌از بار شدن صفحه فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

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

    (result: HistoryItem) => void

onVisitRemoved

browser.history.onVisitRemoved.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    عملکرد

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

    (removed: object) => void

    • حذف شد

      شیء

      • allHistory

        بولی

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

      • نشانی‌های وب

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