chrome.history

refresh date: 2026-09-25 robots: noindex

شرح

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

اجازه‌ها

history

این اجازه هشداری را فعال می‌کند.

مانیفست

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

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

انواع گذار

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

جدول زیر هر نوع گذار را شرح می‌دهد.

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

مثال‌ها

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

انواع

HistoryItem

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

مشخصات

• id

  رشته

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

• lastVisitTime

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

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

• عنوان

  رشته اختیاری

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

• typedCount

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

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

• نشانی وب

  رشته اختیاری

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

• visitCount

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

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

TransitionType

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

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

شمارشی

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

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

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

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

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

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

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

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

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

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

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

UrlDetails

Chrome نسخه ۸۸ و بالاتر

مشخصات

• نشانی وب

  رشته

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

VisitItem

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

مشخصات

• id

  رشته

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

• isLocal

  بولی

  Chrome نسخه ۱۱۵ و بالاتر

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

• referringVisitId

  رشته

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

• گذر

  TransitionType

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

• visitId

  رشته

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

• visitTime

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

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

روش‌ها

addUrl()

قول

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

پارامترها

• جزئیات

  UrlDetails

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

deleteAll()

قول

chrome.history.deleteAll(
  callback?: function,
): Promise<void>

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

پارامترها

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

deleteRange()

قول

chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

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

پارامترها

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

  شیء

  • endTime

    شماره

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

  • startTime

    شماره

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

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

deleteUrl()

قول

chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

پارامترها

• جزئیات

  UrlDetails

• تماس برگشتی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۹۶ به بالا

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

getVisits()

قول

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

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

پارامترها

• جزئیات

  UrlDetails

• تماس برگشتی

  تابع اختیاری

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

  (results: VisitItem[]) => void

  • نتایج

    VisitItem[]

بازگشتی‌ها

• Promise<VisitItem[]>

  Chrome نسخه ۹۶ به بالا

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

search()

قول

chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

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

پارامترها

• پُرسمان

  شیء

  • endTime

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

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

  • maxResults

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

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

  • startTime

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

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

  • نوشتار

    رشته

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

• تماس برگشتی

  تابع اختیاری

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

  (results: HistoryItem[]) => void

  • نتایج

    HistoryItem[]

بازگشتی‌ها

• Promise<HistoryItem[]>

  Chrome نسخه ۹۶ به بالا

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

رویدادها

onVisited

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

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

پارامترها

• تماس برگشتی

  عملکرد

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

  (result: HistoryItem) => void

  • نتیجه

    HistoryItem

onVisitRemoved

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

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

پارامترها

• تماس برگشتی

  عملکرد

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

  (removed: object) => void

  • حذف شد

    شیء

    • allHistory

      بولی

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

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

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