chrome.history

คำอธิบาย

ใช้ 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

  ตัวเลข ไม่บังคับ

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

TransitionType

Chrome 44 ขึ้นไป

ประเภทการเปลี่ยนสําหรับการเข้าชมนี้จาก URL ที่มา

ค่าแจกแจง

"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

Chrome เวอร์ชัน 88 ขึ้นไป

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

• url

  string

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

VisitItem

ออบเจ็กต์สรุปการเข้าชม 1 ครั้งไปยัง URL

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

• id

  string

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

• isLocal

  boolean

  Chrome 115 ขึ้นไป

  เป็นจริงหากการเข้าชมเกิดขึ้นในอุปกรณ์นี้ เป็นเท็จ หากซิงค์จากอุปกรณ์อื่น

• referringVisitId

  string

  รหัสการเข้าชมของผู้บอกต่อ

• การเปลี่ยน

  TransitionType

  ประเภทการเปลี่ยนสําหรับการเข้าชมนี้จาก URL ที่มา

• visitId

  string

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

• visitTime

  ตัวเลข ไม่บังคับ

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

วิธีการ

addUrl()

สัญญา

chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

พารามิเตอร์

• รายละเอียด

  UrlDetails

• 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 ที่ระบุทั้งหมดออกจากประวัติ

พารามิเตอร์

• รายละเอียด

  UrlDetails

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  ()=>void

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

• Promise<void>

  Chrome 96 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getVisits()

สัญญา

chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

พารามิเตอร์

• รายละเอียด

  UrlDetails

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  (results: VisitItem[])=>void

  • ผลการแข่งขัน

    VisitItem[]

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

• 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

  • ผลการแข่งขัน

    HistoryItem[]

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

• Promise<HistoryItem[]>

  Chrome 96 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onVisited

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

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

พารามิเตอร์

• Callback

  ฟังก์ชัน

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

  (result: HistoryItem)=>void

  • ผลลัพธ์

    HistoryItem

onVisitRemoved

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

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

พารามิเตอร์

• Callback

  ฟังก์ชัน

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

  (removed: object)=>void

  • ถูกลบทิ้ง

    ออบเจ็กต์

    • allHistory

      boolean

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

    • urls

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