تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex
توضیحات
از API chrome.history برای تعامل با سابقه صفحات بازدید شده مرورگر استفاده کنید. می‌توانید URLها را در تاریخچه مرورگر اضافه، حذف و جستجو کنید. برای لغو صفحه تاریخچه با نسخه خودتان، به بخش لغو صفحات مراجعه کنید.
مجوزها
historyمانیفست
برای استفاده از API تاریخچه، باید مجوز "history" را در مانیفست افزونه اعلام کنید. برای مثال:
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
انواع گذار
رابط برنامه‌نویسی کاربردی تاریخچه (history API) از یک نوع انتقال (transition type ) برای توصیف نحوه پیمایش مرورگر به یک URL خاص در یک بازدید خاص استفاده می‌کند. برای مثال، اگر کاربری با کلیک روی یک لینک در صفحه دیگری از یک صفحه بازدید کند، نوع انتقال "link" خواهد بود.
جدول زیر هر نوع انتقال را شرح می‌دهد.
| نوع انتقال | توضیحات |
|---|---|
| «پیوند» | کاربر با کلیک روی لینکی در صفحه دیگری به این صفحه رسیده است. |
| "تایپ شده" | کاربر با تایپ کردن URL در نوار آدرس، این صفحه را دریافت کرده است. همچنین برای سایر اقدامات ناوبری صریح نیز استفاده می‌شود. همچنین به generate مراجعه کنید، که برای مواردی استفاده می‌شود که کاربر گزینه‌ای را انتخاب کرده که اصلاً شبیه URL نیست. |
| "نشانه‌گذاری خودکار" | کاربر از طریق یک پیشنهاد در رابط کاربری - مثلاً از طریق یک آیتم منو - به این صفحه رسیده است. |
| "زیرفریم خودکار" | ناوبری زیرفریم. این هر محتوایی است که به طور خودکار در یک فریم غیر سطح بالا بارگذاری می‌شود. برای مثال، اگر صفحه‌ای شامل چندین فریم حاوی تبلیغات باشد، آن URLهای تبلیغاتی این نوع انتقال را دارند. کاربر ممکن است حتی متوجه نشود که محتوای این صفحات یک فریم جداگانه است و بنابراین ممکن است به URL اهمیتی ندهد (همچنین به manual_subframe مراجعه کنید). |
| "زیرفریم_دستی" | برای پیمایش‌های زیرفریم که صریحاً توسط کاربر درخواست می‌شوند و ورودی‌های پیمایش جدیدی را در لیست عقب/جلو ایجاد می‌کنند. یک فریم که صریحاً درخواست شده باشد، احتمالاً از یک فریم که به طور خودکار بارگذاری شده است، مهم‌تر است، زیرا کاربر احتمالاً به این واقعیت که فریم درخواست شده بارگذاری شده است، اهمیت می‌دهد. |
| "تولید شده" | کاربر با تایپ کردن در نوار آدرس و انتخاب ورودی که شبیه URL نیست، به این صفحه رسیده است. برای مثال، یک مورد منطبق ممکن است URL یک صفحه نتیجه جستجوی گوگل را داشته باشد، اما ممکن است برای کاربر به صورت "جستجو در گوگل برای ..." ظاهر شود. اینها کاملاً مشابه پیمایش‌های تایپی نیستند زیرا کاربر URL مقصد را تایپ نکرده یا ندیده است. همچنین به کلمه کلیدی مراجعه کنید. |
| "سطح_بالای_خودکار" | صفحه در خط فرمان مشخص شده است یا صفحه شروع است. |
| "فرم_ارسال" | کاربر مقادیری را در یک فرم پر کرده و آن را ارسال کرده است. توجه داشته باشید که در برخی شرایط - مانند زمانی که یک فرم از اسکریپت برای ارسال محتوا استفاده می‌کند - ارسال فرم منجر به این نوع انتقال نمی‌شود. |
| "بارگیری مجدد" | کاربر صفحه را یا با کلیک روی دکمه بارگذاری مجدد یا با فشار دادن Enter در نوار آدرس، دوباره بارگذاری کرده است. بازیابی جلسه و باز کردن مجدد تب بسته نیز از این نوع انتقال استفاده می‌کنند. |
| «کلمه کلیدی» | این نشانی اینترنتی (URL) از یک کلمه کلیدی قابل تعویض غیر از ارائه دهنده جستجوی پیش‌فرض ایجاد شده است. همچنین به keyword_generated مراجعه کنید. |
| "کلمه کلیدی_تولید شده" | مربوط به بازدیدی است که برای یک کلمه کلیدی ایجاد شده است. همچنین به کلمه کلیدی مراجعه کنید. |
مثال‌ها
برای امتحان کردن این API، نمونه‌ی history API را از مخزن chrome-extension-samples نصب کنید.
انواع
HistoryItem
شیء‌ای که یک نتیجه از یک کوئری تاریخچه را در خود جای داده است.
خواص
- شناسه
رشته
شناسه منحصر به فرد برای کالا.
- آخرین زمان بازدید
شماره اختیاری
آخرین باری که این صفحه بارگذاری شده است، بر حسب میلی‌ثانیه از زمان شروع نمایش داده می‌شود.
- عنوان
رشته اختیاری
عنوان صفحه در آخرین باری که بارگذاری شده است.
- typedCount
شماره اختیاری
تعداد دفعاتی که کاربر با تایپ آدرس به این صفحه هدایت شده است.
- آدرس اینترنتی
رشته اختیاری
آدرس اینترنتی (URL) که کاربر به آن هدایت شده است.
- تعداد بازدید
شماره اختیاری
تعداد دفعاتی که کاربر به این صفحه مراجعه کرده است.
شمارشی
«پیوند» "تایپ شده" "نشانه‌گذاری خودکار" "زیرفریم خودکار" "زیرفریم_دستی" "تولید شده" "سطح_بالای_خودکار" "فرم_ارسال" "بارگیری مجدد" «کلمه کلیدی» "کلمه کلیدی_تولید شده"
کاربر با کلیک روی لینکی در صفحه دیگری به این صفحه رسیده است.
کاربر با تایپ کردن URL در نوار آدرس به این صفحه رسیده است. این همچنین برای سایر اقدامات ناوبری صریح استفاده می‌شود.
کاربر از طریق یک پیشنهاد در رابط کاربری، مثلاً از طریق یک آیتم منو، به این صفحه رسیده است.
کاربر از طریق ناوبری زیرفریمی که درخواست نکرده بود، مانند بارگذاری یک تبلیغ در یک فریم در صفحه قبل، به این صفحه رسیده است. این موارد همیشه ورودی‌های ناوبری جدید را در منوهای عقب و جلو ایجاد نمی‌کنند.
کاربر با انتخاب چیزی در یک زیرفریم به این صفحه رسیده است.
کاربر با تایپ کردن در نوار آدرس و انتخاب ورودی که شبیه URL نیست، مانند پیشنهاد جستجوی گوگل، به این صفحه رسیده است. برای مثال، یک مورد منطبق ممکن است URL یک صفحه نتیجه جستجوی گوگل را داشته باشد، اما ممکن است برای کاربر به صورت "جستجو در گوگل برای ..." ظاهر شود. این موارد با پیمایش‌های تایپی متفاوت هستند زیرا کاربر URL مقصد را تایپ نکرده یا ندیده است. آنها همچنین به پیمایش‌های کلمات کلیدی مرتبط هستند.
صفحه در خط فرمان مشخص شده است یا صفحه شروع است.
کاربر با پر کردن مقادیر در یک فرم و ارسال فرم به این صفحه رسیده است. همه ارسال‌های فرم از این نوع انتقال استفاده نمی‌کنند.
کاربر صفحه را یا با کلیک روی دکمه بارگذاری مجدد یا با فشار دادن Enter در نوار آدرس، دوباره بارگذاری کرده است. بازیابی جلسه و باز کردن مجدد تب بسته نیز از این نوع انتقال استفاده می‌کنند.
نشانی اینترنتی این صفحه از یک کلمه کلیدی قابل تعویض غیر از ارائه دهنده جستجوی پیش‌فرض ایجاد شده است.
مربوط به بازدیدی است که برای یک کلمه کلیدی ایجاد شده است.
UrlDetails
خواص
- آدرس اینترنتی
رشته
آدرس اینترنتی (URL) عملیات. این آدرس باید به فرمتی باشد که از فراخوانی تابع
history.search()برگردانده شده است.
VisitItem
یک شیء که یک بازدید از یک URL را در خود جای می‌دهد.
خواص
- شناسه
رشته
شناسه منحصر به فرد برای
history.HistoryItemمربوطه. - محلی
بولی
کروم ۱۱۵+اگر بازدید از این دستگاه انجام شده باشد، درست است. اگر از دستگاه دیگری همگام‌سازی شده باشد، نادرست است.
- ارجاع‌دهنده‌ی شناسه‌ی بازدید
رشته
شناسه بازدید معرف.
- گذار
نوع انتقال برای این بازدید از ارجاع‌دهنده‌اش.
- شناسه بازدید
رشته
شناسه منحصر به فرد برای این بازدید.
- ویزیت تایم
شماره اختیاری
زمان وقوع این بازدید، که بر حسب میلی‌ثانیه از زمان آغاز نمایش داده می‌شود.
روش‌ها
addUrl()
chrome.history.addUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
یک URL را در زمان فعلی به تاریخچه اضافه می‌کند که نوع انتقال آن "link" است.
پارامترها
- جزئیات
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
بازگشت‌ها
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
deleteAll()
chrome.history.deleteAll(
callback?: function,
): Promise<void>
تمام موارد را از تاریخچه حذف می‌کند.
پارامترها
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
بازگشت‌ها
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
deleteRange()
chrome.history.deleteRange(
range: object,
callback?: function,
): Promise<void>
تمام موارد موجود در محدوده تاریخ مشخص شده را از تاریخچه حذف می‌کند. صفحات از تاریخچه حذف نمی‌شوند مگر اینکه همه بازدیدها در این محدوده قرار گیرند.
پارامترها
- محدوده
شیء
- پایان زمان
شماره
مواردی که قبل از این تاریخ به تاریخچه اضافه شده‌اند، بر حسب میلی‌ثانیه از آن دوره زمانی نمایش داده می‌شوند.
- زمان شروع
شماره
مواردی که پس از این تاریخ به تاریخچه اضافه شده‌اند، بر حسب میلی‌ثانیه از آن دوره زمانی نمایش داده می‌شوند.
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
بازگشت‌ها
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
callback?: function,
): Promise<void>
تمام موارد تکرار شده‌ی URL داده شده را از تاریخچه حذف می‌کند.
پارامترها
- جزئیات
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
بازگشت‌ها
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
getVisits()
chrome.history.getVisits(
details: UrlDetails,
callback?: function,
): Promise<VisitItem[]>
اطلاعات مربوط به بازدیدهای انجام شده از یک URL را بازیابی می‌کند.
پارامترها
- جزئیات
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:(results: VisitItem[]) => void
- نتایج
بازگشت‌ها
قول< بازدید از آیتم []>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
search()
chrome.history.search(
query: object,
callback?: function,
): Promise<HistoryItem[]>
تاریخچه آخرین زمان بازدید هر صفحه مطابق با عبارت جستجو شده را جستجو می‌کند.
پارامترها
- پرس و جو
شیء
- پایان زمان
شماره اختیاری
نتایج را به مواردی که قبل از این تاریخ بازدید شده‌اند، محدود کنید، که از زمان شروع، بر حسب میلی‌ثانیه نمایش داده می‌شوند.
- نتایج حداکثر
شماره اختیاری
حداکثر تعداد نتایج برای بازیابی. پیش‌فرض ۱۰۰.
- زمان شروع
شماره اختیاری
نتایج را به مواردی که پس از این تاریخ بازدید شده‌اند، محدود کنید، که از زمان شروع بر حسب میلی‌ثانیه نمایش داده می‌شوند. اگر ویژگی مشخص نشده باشد، به طور پیش‌فرض روی ۲۴ ساعت تنظیم می‌شود.
- متن
رشته
یک پرس‌وجوی متن آزاد به سرویس تاریخچه. برای بازیابی همه صفحات، این قسمت را خالی بگذارید.
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:(results: HistoryItem[]) => void
- نتایج
تاریخچه []
بازگشت‌ها
قول< تاریخچه مورد []>
کروم ۹۶+Promiseها فقط برای 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
- حذف شده
شیء
- همهتاریخچه
بولی
اگر تمام تاریخچه حذف شده باشد، درست است. اگر درست باشد، آدرس‌ها خالی خواهند بود.
- آدرس‌های اینترنتی
رشته[] اختیاری