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