chrome.history

توضیحات

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

مجوزها

history

آشکار

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

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

انواع انتقال

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

جدول زیر هر نوع انتقال را توضیح می دهد.

نوع انتقال توضیحات
"تایپ شده" کاربر این صفحه را با تایپ URL در نوار آدرس دریافت کرد. همچنین برای سایر اقدامات ناوبری صریح استفاده می شود. همچنین تولید شده را ببینید، که برای مواردی استفاده می‌شود که کاربر گزینه‌ای را انتخاب کرده است که اصلاً شبیه URL نیست.
"auto_bookmark" کاربر از طریق یک پیشنهاد در UI - به عنوان مثال، از طریق یک آیتم منو به این صفحه رسید.
"auto_subframe" ناوبری زیر فریم. این هر محتوایی است که به طور خودکار در یک قاب غیر سطح بالا بارگذاری می شود. به عنوان مثال، اگر یک صفحه از چندین فریم حاوی تبلیغات تشکیل شده باشد، آن URL های تبلیغاتی دارای این نوع انتقال هستند. کاربر ممکن است حتی متوجه نشود که محتوای این صفحات یک قاب جداگانه است و بنابراین ممکن است به URL اهمیتی ندهد (همچنین به manual_subframe مراجعه کنید).
"subframe_manual" برای پیمایش‌های فریم فرعی که به صراحت توسط کاربر درخواست شده و ورودی‌های ناوبری جدید را در فهرست عقب/ جلو ایجاد می‌کنند. یک فریم صریحاً درخواست شده احتمالاً مهمتر از فریمی است که به طور خودکار بارگذاری می شود زیرا کاربر احتمالاً به این واقعیت اهمیت می دهد که فریم درخواستی بارگذاری شده است.
"تولید شده" کاربر با تایپ در نوار آدرس و انتخاب ورودی که شبیه URL نیست به این صفحه رسید. به عنوان مثال، یک مسابقه ممکن است URL یک صفحه نتیجه جستجوی Google را داشته باشد، اما ممکن است برای کاربر به عنوان "جستجوی گوگل برای ..." ظاهر شود. اینها کاملاً مشابه پیمایش های تایپ شده نیستند زیرا کاربر URL مقصد را تایپ نکرده یا ندیده است. کلمه کلیدی را نیز ببینید.
"auto_toplevel" صفحه در خط فرمان مشخص شده است یا صفحه شروع است.
"form_submit" کاربر مقادیر را در فرمی پر کرده و ارسال کرده است. توجه داشته باشید که در برخی شرایط - مانند زمانی که یک فرم از اسکریپت برای ارسال محتوا استفاده می کند - ارسال یک فرم منجر به این نوع انتقال نمی شود.
"بارگذاری مجدد" کاربر صفحه را بارگیری مجدد کرد، یا با کلیک بر روی دکمه بارگیری مجدد یا با فشار دادن Enter در نوار آدرس. بازیابی جلسه و باز کردن مجدد برگه بسته نیز از این نوع انتقال استفاده می کنند.
"کلید واژه" URL از یک کلمه کلیدی قابل جایگزینی غیر از ارائه دهنده جستجوی پیش فرض ایجاد شده است. همچنین keyword_generated را ببینید.
"keyword_generated" مربوط به بازدید ایجاد شده برای یک کلمه کلیدی است. کلمه کلیدی را نیز ببینید.

نمونه ها

برای امتحان این 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 و نسخه های جدیدتر پشتیبانی می شود، پلتفرم های دیگر نیاز به استفاده از callback دارند.

deleteAll()

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

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

پارامترها

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

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

deleteRange()

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

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

پارامترها

  • محدوده

    شی

    • پایان زمان

      شماره

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

    • زمان شروع

      شماره

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

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

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

deleteUrl()

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

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

پارامترها

  • جزئیات

    UrlDetails

  • پاسخ به تماس

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

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

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 96+

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

getVisits()

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

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

پارامترها

  • جزئیات

    UrlDetails

  • پاسخ به تماس

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

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

    (results: VisitItem[]) => void

برمی گرداند

  • Promise< VisitItem []>

    Chrome 96+

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

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

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

پارامترها

  • پرس و جو

    شی

    • پایان زمان

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

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

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

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

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

    • زمان شروع

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

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

    • متن

      رشته

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

  • پاسخ به تماس

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

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

    (results: HistoryItem[]) => void

برمی گرداند

  • Promise< HistoryItem []>

    Chrome 96+

    Promises فقط برای Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، پلتفرم های دیگر نیاز به استفاده از 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

    • حذف شده است

      شی

      • تمام تاریخ

        بولی

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

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

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