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