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 88 و نسخه‌های بالاتر

مشخصات

• نشانی وب

  رشته

  نشانی وب برای عملیات. باید در قالبی باشد که از تماس با 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 نسخه ۹۶ و بالاتر

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

deleteRange()

قول

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

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

پارامترها

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

  شیء

  • endTime

    شماره

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

  • startTime

    شماره

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

• بازخوانی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

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

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

deleteUrl()

Promise

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

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

پارامترها

• جزئیات

  UrlDetails

• بازخوانی

  تابع اختیاری

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

  () => void

بازگشتی‌ها

• Promise<void>

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

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

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 نسخه ۹۶ و بالاتر

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

رویدادها

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

      بولی

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

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

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