chrome.history

توضیحات

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

مجوزها

history

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

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

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

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

انواع انتقال

تاریخچه API از انواع انتقال برای توصیف نحوه پیمایش مرورگر به یک URL خاص در یک بازدید خاص استفاده می کند. به عنوان مثال، اگر کاربر با کلیک بر روی پیوندی در صفحه دیگر از صفحه ای بازدید کند، نوع انتقال "لینک" است. برای فهرستی از انواع انتقال به محتوای مرجع مراجعه کنید.

نمونه ها

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

انواع

HistoryItem

یک شی که یک نتیجه از یک پرس و جو تاریخچه را کپسوله می کند.

خواص

  • شناسه

    رشته

    شناسه منحصر به فرد مورد.

  • lastVisitTime

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

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

  • عنوان

    رشته اختیاری

    عنوان صفحه آخرین بارگذاری آن.

  • typedCount

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

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

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

    رشته اختیاری

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

  • تعداد بازدید

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

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

TransitionType

Chrome 44+

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

Enum

"پیوند"
کاربر با کلیک کردن روی پیوندی در صفحه دیگر به این صفحه رسید.

"تایپ شده"
کاربر با تایپ URL در نوار آدرس به این صفحه رسید. این همچنین برای سایر اقدامات ناوبری صریح استفاده می شود.

"auto_bookmark"
کاربر از طریق یک پیشنهاد در UI، به عنوان مثال، از طریق یک آیتم منو به این صفحه رسید.

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

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

"تولید شده"
کاربر با تایپ کردن در نوار آدرس و انتخاب ورودی که شبیه URL نیست، مانند پیشنهاد جستجوی Google، به این صفحه رسید. برای مثال، یک مسابقه ممکن است نشانی اینترنتی یک صفحه نتیجه جستجوی Google را داشته باشد، اما ممکن است برای کاربر به عنوان "جستجوی گوگل برای ..." ظاهر شود. این‌ها با پیمایش‌های تایپ‌شده متفاوت هستند، زیرا کاربر URL مقصد را تایپ نکرده یا ندیده است. آنها همچنین با ناوبری کلمات کلیدی مرتبط هستند.

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

"form_submit"
کاربر با پر کردن مقادیر در یک فرم و ارسال فرم به این صفحه رسید. همه فرم های ارسالی از این نوع انتقال استفاده نمی کنند.

"بارگذاری مجدد"
کاربر صفحه را بارگیری مجدد کرد، یا با کلیک بر روی دکمه بارگیری مجدد یا با فشار دادن Enter در نوار آدرس. بازیابی جلسه و باز کردن مجدد برگه بسته نیز از این نوع انتقال استفاده می کنند.

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

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

UrlDetails

Chrome 88+

خواص

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

    رشته

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

VisitItem

یک شی که یک بار بازدید از یک URL را محصور می کند.

خواص

  • شناسه

    رشته

    شناسه منحصر به فرد برای history.HistoryItem مربوطه.

  • محلی است

    بولی

    Chrome 115+

    درست است اگر بازدید از این دستگاه انجام شده باشد. اگر از دستگاه دیگری همگام‌سازی شده باشد، نادرست است.

  • referringVisitId

    رشته

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

  • انتقال

    نوع انتقال

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

  • visitId

    رشته

    شناسه منحصر به فرد برای این بازدید.

  • visitTime

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

    زمانی که این بازدید رخ داد، در میلی ثانیه از آن دوران نشان داده شد.

روش ها

addUrl()

قول بده
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

یک URL به تاریخچه در زمان فعلی با نوع انتقال "پیوند" اضافه می کند.

پارامترها

  • جزئیات

    UrlDetails

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

deleteAll()

قول بده
chrome.history.deleteAll(
  callback?: function,
)

تمام موارد را از تاریخچه حذف می کند.

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

deleteRange()

قول بده
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

تمام موارد در محدوده تاریخ مشخص شده را از تاریخچه حذف می کند. صفحات از تاریخچه حذف نمی شوند مگر اینکه همه بازدیدها در محدوده قرار بگیرند.

پارامترها

  • محدوده

    شی

    • پایان زمان

      شماره

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

    • زمان شروع

      شماره

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

deleteUrl()

قول بده
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

تمام رخدادهای URL داده شده را از تاریخچه حذف می کند.

پارامترها

  • جزئیات

    UrlDetails

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getVisits()

قول بده
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

پارامترها

  • جزئیات

    UrlDetails

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: VisitItem[]) => void

برمی گرداند

  • Promise< VisitItem []>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

قول بده
chrome.history.search(
  query: object,
  callback?: function,
)

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

پارامترها

  • پرس و جو

    شی

    • پایان زمان

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

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

    • حداکثر نتایج

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

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

    • زمان شروع

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

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

    • متن

      رشته

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (results: HistoryItem[]) => void

برمی گرداند

  • Promise< HistoryItem []>

    Chrome 96+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onVisited

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

هنگام بازدید از یک URL فعال می شود و داده HistoryItem را برای آن URL فراهم می کند. این رویداد قبل از بارگیری صفحه فعال می شود.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (result: HistoryItem) => void

onVisitRemoved

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

زمانی فعال می شود که یک یا چند URL از تاریخچه حذف شود. وقتی همه بازدیدها حذف شدند URL از تاریخچه پاک می شود.

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (removed: object) => void

    • حذف شده است

      شی

      • تمام تاریخ

        بولی

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

      • آدرس های اینترنتی

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