browser.history

คำอธิบาย

ใช้ chrome.history API เพื่อโต้ตอบกับบันทึกหน้าเว็บที่เข้าชมของเบราว์เซอร์ คุณสามารถเพิ่ม นำออก และค้นหา URL ในประวัติของเบราว์เซอร์ได้ หากต้องการลบล้างหน้าประวัติด้วยเวอร์ชันของคุณเอง โปรดดูลบล้างหน้าเว็บ

สิทธิ์

history

หากต้องการโต้ตอบกับประวัติการท่องเว็บของผู้ใช้ ให้ใช้ History API

หากต้องการใช้ History API ให้ประกาศสิทธิ์ "history" ในไฟล์ Manifest ของส่วนขยาย เช่น

{
  "name": "My extension",
  ...
  "permissions": [
    "history"
  ],
  ...
}

แนวคิดและการใช้งาน

ประเภทการเปลี่ยน

API ประวัติการเข้าชมใช้ประเภทการเปลี่ยนเพื่ออธิบายวิธีที่เบราว์เซอร์ไปยัง URL หนึ่งๆ ในการเข้าชมหนึ่งๆ เช่น หากผู้ใช้เข้าชมหน้าเว็บโดยคลิกลิงก์ในหน้าอื่น ประเภทการเปลี่ยนผ่านจะเป็น "ลิงก์" ดูรายการประเภทการเปลี่ยนผ่านได้ในเนื้อหาอ้างอิง

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง API ประวัติจากที่เก็บ chrome-extension-samples

ประเภท

HistoryItem

ออบเจ็กต์ที่รวมผลลัพธ์ 1 รายการของคำค้นหาประวัติไว้

พร็อพเพอร์ตี้

• id

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับรายการ

• lastVisitTime

  number ไม่บังคับ

  เวลาที่โหลดหน้านี้ครั้งล่าสุด โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch

• title

  สตริง ไม่บังคับ

  ชื่อของหน้าเมื่อโหลดครั้งล่าสุด

• typedCount

  number ไม่บังคับ

  จำนวนครั้งที่ผู้ใช้ไปยังหน้านี้โดยการพิมพ์ที่อยู่

• URL

  สตริง ไม่บังคับ

  URL ที่ผู้ใช้ไปยัง

• visitCount

  number ไม่บังคับ

  จำนวนครั้งที่ผู้ใช้ไปยังหน้านี้

TransitionType

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

ประเภทการเปลี่ยนสำหรับการเข้าชมนี้จากผู้แนะนำ

ค่าแจกแจง

"link"
ผู้ใช้มาถึงหน้านี้โดยคลิกลิงก์ในหน้าอื่น

"typed"
ผู้ใช้มาถึงหน้านี้โดยการพิมพ์ URL ในแถบที่อยู่ นอกจากนี้ยังใช้สำหรับการดำเนินการนำทางที่ชัดเจนอื่นๆ ด้วย

"auto_bookmark"
ผู้ใช้มาถึงหน้านี้ผ่านคำแนะนำใน UI เช่น ผ่านรายการเมนู

"auto_subframe"
ผู้ใช้มาถึงหน้านี้ผ่านการนำทางเฟรมย่อยที่ไม่ได้ขอ เช่น ผ่านการโหลดโฆษณาในเฟรมในหน้าก่อนหน้า ซึ่งไม่ได้สร้างรายการการนำทางใหม่ในเมนูย้อนกลับและไปข้างหน้าเสมอไป

"manual_subframe"
ผู้ใช้มาถึงหน้านี้โดยการเลือกบางอย่างในเฟรมย่อย

"generated"
ผู้ใช้มาถึงหน้านี้โดยพิมพ์ในแถบที่อยู่และเลือกรายการที่ไม่เหมือน URL เช่น การแนะนำการค้นหาของ Google Search ตัวอย่างเช่น การจับคู่อาจมี URL ของหน้าผลการค้นหาของ Google แต่ผู้ใช้อาจเห็นเป็น "ค้นหา Google สำหรับ..." ซึ่งแตกต่างจากการไปยังส่วนต่างๆ ด้วยการพิมพ์เนื่องจากผู้ใช้ไม่ได้พิมพ์หรือเห็น URL ปลายทาง และยังเกี่ยวข้องกับการไปยังส่วนต่างๆ ของคีย์เวิร์ดด้วย

"auto_toplevel"
มีการระบุหน้าเว็บในบรรทัดคำสั่งหรือเป็นหน้าเริ่มต้น

"form_submit"
ผู้ใช้มาถึงหน้านี้โดยการกรอกค่าในแบบฟอร์มและส่งแบบฟอร์ม การส่งแบบฟอร์มบางรายการไม่ได้ใช้การเปลี่ยนประเภทนี้

"reload"
ผู้ใช้โหลดหน้าเว็บซ้ำโดยคลิกปุ่มโหลดซ้ำหรือกด Enter ในแถบที่อยู่ การกู้คืนเซสชันและการเปิดแท็บที่ปิดไปแล้วขึ้นมาใหม่ก็ใช้การเปลี่ยนประเภทนี้เช่นกัน

"keyword"
URL ของหน้านี้สร้างขึ้นจากคีย์เวิร์ดที่แทนที่ได้ซึ่งไม่ใช่ผู้ให้บริการการค้นหาเริ่มต้น

"keyword_generated"
สอดคล้องกับการเข้าชมที่สร้างขึ้นสำหรับคีย์เวิร์ด

UrlDetails

Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

พร็อพเพอร์ตี้

• URL

  สตริง

  URL สำหรับการดำเนินการ โดยต้องอยู่ในรูปแบบที่แสดงผลจากการเรียกใช้ history.search()

VisitItem

ออบเจ็กต์ที่รวมการเข้าชม URL 1 ครั้ง

พร็อพเพอร์ตี้

• id

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับ history.HistoryItem ที่เกี่ยวข้อง

• isLocal

  บูลีน

  Chrome 115 ขึ้นไป browser.* ตั้งแต่ Chrome 148

  "จริง" หากการเข้าชมเริ่มต้นในอุปกรณ์นี้ False หากซิงค์จากอุปกรณ์อื่น

• referringVisitId

  สตริง

  รหัสการเข้าชมของ URL ที่มา

• การเปลี่ยนผ่าน

  TransitionType

  ประเภทการเปลี่ยนสำหรับการเข้าชมนี้จากผู้แนะนำ

• visitId

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับการเข้าชมนี้

• visitTime

  number ไม่บังคับ

  เวลาที่เกิดการเข้าชมนี้ โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch

เมธอด

addUrl()

browser.history.addUrl(
  details: UrlDetails,
): Promise<void>

เพิ่ม URL ลงในประวัติ ณ เวลาปัจจุบันด้วยประเภทการเปลี่ยนเป็น "ลิงก์"

พารามิเตอร์

• รายละเอียด

  UrlDetails

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

deleteAll()

browser.history.deleteAll(): Promise<void>

ลบรายการทั้งหมดออกจากประวัติ

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

deleteRange()

browser.history.deleteRange(
  range: object,
): Promise<void>

นำรายการทั้งหมดในช่วงวันที่ที่ระบุออกจากประวัติ ระบบจะไม่นำหน้าเว็บออกจากประวัติ เว้นแต่การเข้าชมทั้งหมดจะอยู่ในช่วงเวลาดังกล่าว

พารามิเตอร์

• ช่วง

  ออบเจ็กต์

  • endTime

    ตัวเลข

    รายการที่เพิ่มลงในประวัติก่อนวันที่นี้ โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch

  • startTime

    ตัวเลข

    รายการที่เพิ่มลงในประวัติหลังจากวันที่นี้ โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

deleteUrl()

browser.history.deleteUrl(
  details: UrlDetails,
): Promise<void>

นำ URL ที่ระบุทั้งหมดออกจากประวัติ

พารามิเตอร์

• รายละเอียด

  UrlDetails

การคืนสินค้า

• Promise<void>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getVisits()

browser.history.getVisits(
  details: UrlDetails,
): Promise<VisitItem[]>

เรียกดูข้อมูลเกี่ยวกับการเข้าชม URL

พารามิเตอร์

• รายละเอียด

  UrlDetails

การคืนสินค้า

• Promise<VisitItem[]>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

search()

browser.history.search(
  query: object,
): Promise<HistoryItem[]>

ค้นหาประวัติการเข้าชมครั้งล่าสุดของแต่ละหน้าที่ตรงกับคำค้นหา

พารามิเตอร์

• query

  ออบเจ็กต์

  • endTime

    number ไม่บังคับ

    จำกัดผลลัพธ์เฉพาะผู้ที่เข้าชมก่อนวันที่นี้ โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่ Epoch

  • maxResults

    number ไม่บังคับ

    จำนวนผลลัพธ์สูงสุดที่จะดึงข้อมูล ค่าเริ่มต้นคือ 100

  • startTime

    number ไม่บังคับ

    จำกัดผลลัพธ์เฉพาะผู้ที่เข้าชมหลังจากวันที่นี้ โดยแสดงเป็นมิลลิวินาทีนับตั้งแต่วันที่ 1 มกราคม ค.ศ. 1970 หากไม่ได้ระบุพร็อพเพอร์ตี้ ระบบจะใช้ค่าเริ่มต้นเป็น 24 ชั่วโมง

  • ข้อความ

    สตริง

    การค้นหาข้อความอิสระในบริการประวัติการเข้าชม ปล่อยช่องนี้ว่างไว้เพื่อดึงข้อมูลหน้าเว็บทั้งหมด

การคืนสินค้า

• Promise<HistoryItem[]>

  Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กิจกรรม

onVisited

browser.history.onVisited.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการเข้าชม URL โดยให้ข้อมูล HistoryItem สำหรับ URL นั้น เหตุการณ์นี้จะเริ่มทำงานก่อนที่หน้าเว็บจะโหลด

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (result: HistoryItem) => void

  • ผลลัพธ์

    HistoryItem

onVisitRemoved

browser.history.onVisitRemoved.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการนำ URL อย่างน้อย 1 รายการออกจากประวัติ เมื่อนำการเข้าชมทั้งหมดออกแล้ว ระบบจะล้าง URL ออกจากประวัติการเข้าชม

พารามิเตอร์

• callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (removed: object) => void

  • ลบแล้ว

    ออบเจ็กต์

    • allHistory

      บูลีน

      เป็นจริงหากนำประวัติทั้งหมดออกแล้ว หากเป็นจริง URL จะว่างเปล่า

    • URL

      string[] ไม่บังคับ