คำอธิบาย
ใช้ chrome.history API เพื่อโต้ตอบกับบันทึกหน้าเว็บที่เข้าชมของเบราว์เซอร์ คุณสามารถเพิ่ม นำออก และค้นหา URL ในประวัติของเบราว์เซอร์ได้ หากต้องการลบล้างหน้าประวัติด้วยเวอร์ชันของคุณเอง โปรดดูลบล้างหน้า
สิทธิ์
historyหากต้องการโต้ตอบกับประวัติเบราว์เซอร์ของผู้ใช้ ให้ใช้ History API
หากต้องการใช้ History API ให้ประกาศสิทธิ์ "history" ใน ไฟล์ Manifest ของส่วนขยาย เช่น
{
"name": "My extension",
...
"permissions": [
"history"
],
...
}
แนวคิดและการใช้งาน
ประเภทการเปลี่ยน
History API ใช้ประเภทการเปลี่ยนเส้นทางเพื่ออธิบายวิธีที่เบราว์เซอร์ไปยัง URL หนึ่งๆ ในการเข้าชมครั้งหนึ่งๆ เช่น หากผู้ใช้เข้าชมหน้าเว็บโดยคลิกลิงก์ในหน้าเว็บอื่น ประเภทการเปลี่ยนหน้าจะเป็น "ลิงก์" ดูรายการประเภทการเปลี่ยนฉากได้ในเนื้อหาอ้างอิง
ตัวอย่าง
หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง History API จากที่เก็บchrome-extension-samples
ประเภท
HistoryItem
ออบเจ็กต์ที่แคปซูลผลลัพธ์หนึ่งรายการของการค้นหาประวัติ
พร็อพเพอร์ตี้
-
id
สตริง
ตัวระบุที่ไม่ซ้ำกันสำหรับสินค้า
-
lastVisitTime
หมายเลข ไม่บังคับ
เวลาที่โหลดหน้านี้ครั้งล่าสุด ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch
-
title
สตริง ไม่บังคับ
ชื่อของหน้าเว็บเมื่อโหลดครั้งล่าสุด
-
typedCount
หมายเลข ไม่บังคับ
จำนวนครั้งที่ผู้ใช้ไปยังหน้านี้โดยการพิมพ์ที่อยู่
-
URL
สตริง ไม่บังคับ
URL ที่ผู้ใช้เข้าชม
-
visitCount
หมายเลข ไม่บังคับ
จำนวนครั้งที่ผู้ใช้ไปยังหน้าเว็บนี้
ค่าแจกแจง
"ลิงก์"
ผู้ใช้มาที่หน้านี้โดยคลิกลิงก์ในหน้าอื่น
"พิมพ์"
ผู้ใช้มาที่หน้านี้โดยพิมพ์ URL ในแถบที่อยู่ นอกจากนี้ ยังใช้สำหรับการดำเนินการนำทางอื่นๆ ที่ชัดเจนด้วย
"auto_bookmark"
ผู้ใช้มาที่หน้านี้ผ่านคำแนะนำใน UI เช่น ผ่านรายการเมนู
"auto_subframe"
ผู้ใช้มาที่หน้านี้ผ่านการนำทางในเฟรมย่อยที่ไม่ได้ขอ เช่น ผ่านโฆษณาที่โหลดในเฟรมในหน้าก่อนหน้า แต่ไม่ได้สร้างรายการการนำทางใหม่ในเมนูย้อนกลับและไปข้างหน้าเสมอไป
"manual_subframe"
ผู้ใช้มาที่หน้านี้โดยเลือกบางอย่างในเฟรมย่อย
"สร้างขึ้น"
ผู้ใช้มาที่หน้านี้โดยพิมพ์ในแถบที่อยู่และเลือกรายการที่ดูไม่เหมือน URL เช่น คำแนะนำของ Google Search ตัวอย่างเช่น การจับคู่อาจมี URL ของหน้าผลการค้นหาของ Google Search แต่ผู้ใช้อาจเห็นเป็น "ค้นหา ... ใน Google" ซึ่งแตกต่างจากการนำทางที่พิมพ์เนื่องจากผู้ใช้ไม่ได้พิมพ์หรือเห็น URL ปลายทาง นอกจากนี้ยังเกี่ยวข้องกับการไปยังส่วนต่างๆ ด้วยคีย์เวิร์ดด้วย
"auto_toplevel"
มีการระบุหน้าในบรรทัดคำสั่งหรือเป็นหน้าเริ่มต้น
"form_submit"
ผู้ใช้มาที่หน้านี้โดยกรอกค่าในแบบฟอร์มและส่งแบบฟอร์ม การส่งแบบฟอร์มบางรายการไม่ได้ใช้การเปลี่ยนประเภทนี้
"โหลดซ้ำ"
ผู้ใช้โหลดหน้าเว็บซ้ำโดยคลิกปุ่มโหลดซ้ำหรือกด Enter ในแถบที่อยู่ การกู้คืนเซสชันและการเปิดแท็บที่ปิดไปแล้วขึ้นมาใหม่จะใช้การเปลี่ยนประเภทนี้ด้วย
"คีย์เวิร์ด"
URL ของหน้านี้สร้างขึ้นจากคีย์เวิร์ดที่แทนที่ได้ซึ่งไม่ใช่ผู้ให้บริการค้นหาเริ่มต้น
"keyword_generated"
สอดคล้องกับการเข้าชมที่สร้างขึ้นสําหรับคีย์เวิร์ด
UrlDetails
พร็อพเพอร์ตี้
-
URL
สตริง
URL ของการดำเนินการ ต้องอยู่ในรูปแบบที่แสดงผลจากการเรียกใช้
history.search()
VisitItem
ออบเจ็กต์ที่แคปซูลการเข้าชม URL ครั้งเดียว
พร็อพเพอร์ตี้
-
id
สตริง
ตัวระบุที่ไม่ซ้ำกันสำหรับ
history.HistoryItemที่เกี่ยวข้อง -
isLocal
บูลีน
Chrome 115 ขึ้นไปจริง หากการเข้าชมเริ่มต้นในอุปกรณ์นี้ เป็นเท็จหากซิงค์จากอุปกรณ์อื่น
-
referringVisitId
สตริง
รหัสการเข้าชมของผู้เข้าชมที่มาจากแหล่งที่มา
-
การเปลี่ยน
ประเภทการเปลี่ยนเส้นทางสำหรับการเข้าชมนี้จากผู้แนะนำ
-
visitId
สตริง
ตัวระบุที่ไม่ซ้ำกันสำหรับการเข้าชมนี้
-
visitTime
หมายเลข ไม่บังคับ
เวลาที่เกิดการเข้าชมนี้ ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch
เมธอด
addUrl()
chrome.history.addUrl(
details: UrlDetails,
): Promise<void>
เพิ่ม URL ลงในประวัติ ณ เวลาปัจจุบันโดยมีประเภทการเปลี่ยนเส้นทางเป็น "ลิงก์"
พารามิเตอร์
-
รายละเอียด
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไป
deleteAll()
chrome.history.deleteAll(): Promise<void>
ลบรายการทั้งหมดออกจากประวัติ
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไป
deleteRange()
chrome.history.deleteRange(
range: object,
): Promise<void>
นำรายการทั้งหมดในช่วงวันที่ที่ระบุออกจากประวัติ ระบบจะไม่นำหน้าเว็บออกจากประวัติการเข้าชม เว้นแต่การเข้าชมทั้งหมดจะอยู่ในช่วงดังกล่าว
พารามิเตอร์
-
ช่วง
ออบเจ็กต์
-
endTime
ตัวเลข
รายการที่เพิ่มลงในประวัติก่อนวันที่นี้ ซึ่งแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch
-
startTime
ตัวเลข
รายการที่เพิ่มลงในประวัติหลังจากวันที่นี้ ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch
-
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไป
deleteUrl()
chrome.history.deleteUrl(
details: UrlDetails,
): Promise<void>
นำ URL ที่ระบุทั้งหมดออกจากประวัติการเข้าชม
พารามิเตอร์
-
รายละเอียด
การคืนสินค้า
-
Promise<void>
Chrome 96 ขึ้นไป
getVisits()
chrome.history.getVisits(
details: UrlDetails,
): Promise<VisitItem[]>
ดึงข้อมูลเกี่ยวกับการเข้าชม URL
พารามิเตอร์
-
รายละเอียด
การคืนสินค้า
-
Promise<VisitItem[]>
Chrome 96 ขึ้นไป
search()
chrome.history.search(
query: object,
): Promise<HistoryItem[]>
ค้นหาประวัติเวลาเข้าชมล่าสุดของแต่ละหน้าที่ตรงกับคำค้นหา
พารามิเตอร์
-
query
ออบเจ็กต์
-
endTime
หมายเลข ไม่บังคับ
จำกัดผลลัพธ์เฉพาะรายการที่เข้าชมก่อนวันที่นี้ ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch
-
maxResults
หมายเลข ไม่บังคับ
จำนวนผลลัพธ์สูงสุดที่จะดึงข้อมูล ค่าเริ่มต้นคือ 100
-
startTime
หมายเลข ไม่บังคับ
จำกัดผลลัพธ์เฉพาะหน้าที่เข้าชมหลังจากวันที่นี้ ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch หากไม่ได้ระบุพร็อพเพอร์ตี้ ค่าเริ่มต้นจะเป็น 24 ชั่วโมง
-
ข้อความ
สตริง
คำค้นหาที่พิมพ์อย่างไรก็ได้ไปยังบริการประวัติ ปล่อยให้ว่างไว้เพื่อดึงข้อมูลหน้าเว็บทั้งหมด
-
การคืนสินค้า
-
Promise<HistoryItem[]>
Chrome 96 ขึ้นไป
กิจกรรม
onVisited
chrome.history.onVisited.addListener(
callback: function,
)
เริ่มทำงานเมื่อมีการเข้าชม URL โดยจะให้HistoryItemข้อมูลสำหรับ URL นั้น เหตุการณ์นี้จะทริกเกอร์ก่อนที่หน้าเว็บจะโหลด
พารามิเตอร์
-
callback
ฟังก์ชัน
พารามิเตอร์
callbackมีลักษณะดังนี้(result: HistoryItem) => void
-
ผลลัพธ์
-
onVisitRemoved
chrome.history.onVisitRemoved.addListener(
callback: function,
)
เริ่มทำงานเมื่อมีการนำ URL อย่างน้อย 1 รายการออกจากประวัติ เมื่อนำการเข้าชมทั้งหมดออกแล้ว ระบบจะล้าง URL ออกจากประวัติการเข้าชม
พารามิเตอร์
-
callback
ฟังก์ชัน
พารามิเตอร์
callbackมีลักษณะดังนี้(removed: object) => void
-
ลบแล้ว
ออบเจ็กต์
-
allHistory
บูลีน
เป็นจริงหากนำประวัติทั้งหมดออกแล้ว หากเป็นจริง URL จะว่างเปล่า
-
URL
string[] ไม่บังคับ
-
-