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

  • نتایج

    VisitItem []

برمی گرداند

• Promise< VisitItem []>

  Chrome 96+

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

search()

وعده

chrome.history.search(
  query: object,
  callback?: function,
)

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

مولفه های

• پرس و جو

  هدف - شی

  • زمان پایان

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

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

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

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

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

  • زمان شروع

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

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

  • متن

    رشته

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

• پاسخ به تماس

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

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

  (results: HistoryItem[])=>void

  • نتایج

    History Item []

برمی گرداند

• Promise< HistoryItem []>

  Chrome 96+

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

مناسبت ها

onVisited

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

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

مولفه های

• پاسخ به تماس

  تابع

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

  (result: HistoryItem)=>void

  • نتیجه

    History Item

onVisitRemoved

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

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

مولفه های

• پاسخ به تماس

  تابع

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

  (removed: object)=>void

  • حذف شده

    هدف - شی

    • تمام تاریخ

      بولی

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

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

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