chrome.history

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

สิทธิ์

history

ไฟล์ Manifest

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

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

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

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

ตารางต่อไปนี้จะอธิบายการเปลี่ยนฉากแต่ละประเภท

ประเภทการเปลี่ยนผ่านคำอธิบาย
"typed"ผู้ใช้เข้าถึงหน้านี้ได้โดยการพิมพ์ URL ในแถบที่อยู่ นอกจากนี้ยังใช้สำหรับการดำเนินการนำทางที่ชัดเจนอื่นๆ ด้วย ดูสร้างขึ้นด้วย ซึ่งใช้ในกรณีที่ผู้ใช้เลือกตัวเลือกที่ไม่เหมือน URL เลย
"auto_bookmark"ผู้ใช้มาที่หน้านี้ผ่านคำแนะนำใน UI เช่น ผ่านรายการเมนู
"auto_subframe"การไปยังส่วนต่างๆ ของเฟรมย่อย ซึ่งเป็นเนื้อหาที่โหลดโดยอัตโนมัติในเฟรมที่ไม่ใช่ระดับบนสุด เช่น หากหน้าเว็บประกอบด้วยเฟรมหลายเฟรมที่มีโฆษณา URL ของโฆษณาเหล่านั้นจะมีประเภทการเปลี่ยนผ่านนี้ ผู้ใช้อาจไม่ทราบด้วยซ้ำว่าเนื้อหาในหน้าเหล่านี้เป็นเฟรมแยกต่างหาก จึงอาจไม่สนใจ URL (ดู manual_subframe ด้วย)
"manual_subframe"สำหรับการนำทางในเฟรมย่อยที่ผู้ใช้ขออย่างชัดเจนและสร้างรายการการนำทางใหม่ในรายการย้อนกลับ/ไปข้างหน้า เฟรมที่ขออย่างชัดเจนอาจมีความสำคัญมากกว่าเฟรมที่โหลดโดยอัตโนมัติ เนื่องจากผู้ใช้อาจสนใจข้อเท็จจริงที่ว่าเฟรมที่ขอได้รับการโหลดแล้ว
"สร้างขึ้น"ผู้ใช้มาที่หน้านี้โดยพิมพ์ในแถบที่อยู่และเลือกรายการที่ไม่เหมือน URL ตัวอย่างเช่น การจับคู่อาจมี URL ของหน้าผลการค้นหาของ Google แต่ผู้ใช้อาจเห็นเป็น "ค้นหา ... ใน Google" ซึ่งไม่เหมือนกับการไปยังส่วนต่างๆ ที่พิมพ์ เนื่องจากผู้ใช้ไม่ได้พิมพ์หรือเห็น URL ปลายทาง ดูคีย์เวิร์ดด้วย
"auto_toplevel"มีการระบุหน้าในบรรทัดคำสั่งหรือเป็นหน้าเริ่มต้น
"form_submit"ผู้ใช้กรอกค่าในแบบฟอร์มและส่ง โปรดทราบว่าในบางกรณี เช่น เมื่อแบบฟอร์มใช้สคริปต์เพื่อส่งเนื้อหา การส่งแบบฟอร์มจะไม่ทำให้เกิดการเปลี่ยนประเภทนี้
"โหลดซ้ำ"ผู้ใช้โหลดหน้าเว็บซ้ำโดยคลิกปุ่มโหลดซ้ำหรือกด Enter ในแถบที่อยู่ การกู้คืนเซสชันและการเปิดแท็บที่ปิดไปแล้วขึ้นมาใหม่ก็ใช้การเปลี่ยนประเภทนี้ด้วย
"คำหลัก"URL สร้างขึ้นจากคีย์เวิร์ดที่แทนที่ได้ซึ่งไม่ใช่ผู้ให้บริการค้นหาเริ่มต้น ดู keyword_generated ด้วย
"keyword_generated"สอดคล้องกับการเข้าชมที่สร้างขึ้นสําหรับคีย์เวิร์ด ดูคีย์เวิร์ดด้วย

ตัวอย่าง

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

ประเภท

HistoryItem

ออบเจ็กต์ที่แคปซูลผลลัพธ์หนึ่งรายการของการค้นหาประวัติ

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

  • id

    สตริง

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

  • lastVisitTime

    หมายเลข ไม่บังคับ

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

  • title

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

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

  • typedCount

    หมายเลข ไม่บังคับ

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

  • URL

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

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

  • visitCount

    หมายเลข ไม่บังคับ

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

TransitionType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

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

"พิมพ์"
ผู้ใช้มาที่หน้านี้โดยพิมพ์ 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

Chrome 88 ขึ้นไป

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

  • URL

    สตริง

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

VisitItem

ออบเจ็กต์ที่แคปซูลการเข้าชม URL 1 ครั้ง

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

  • id

    สตริง

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

  • isLocal

    บูลีน

    Chrome 115 ขึ้นไป

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

  • referringVisitId

    สตริง

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

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

    TransitionType

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

  • visitId

    สตริง

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

  • visitTime

    หมายเลข ไม่บังคับ

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

เมธอด

addUrl()

Promise 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • callback

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

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

    () =& gt;void

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

  • Promise<void>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

deleteAll()

Promise 
chrome.history.deleteAll(
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • callback

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

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

    () =& gt;void

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

  • Promise<void>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

deleteRange()

Promise 
chrome.history.deleteRange(
  range: object,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • ช่วง

    ออบเจ็กต์

    • endTime

      ตัวเลข

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

    • startTime

      ตัวเลข

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

  • callback

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

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

    () =& gt;void

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

  • Promise<void>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

deleteUrl()

Promise 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • callback

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

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

    () =& gt;void

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

  • Promise<void>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getVisits()

Promise 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
): Promise<VisitItem[]>

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • callback

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

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

    (results: VisitItem[]) =& gt;void

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

  • Promise<VisitItem[]>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

Promise 
chrome.history.search(
  query: object,
  callback?: function,
): Promise<HistoryItem[]>

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

พารามิเตอร์

  • query

    ออบเจ็กต์

    • endTime

      หมายเลข ไม่บังคับ

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

    • maxResults

      หมายเลข ไม่บังคับ

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

    • startTime

      หมายเลข ไม่บังคับ

      จำกัดผลลัพธ์เฉพาะหน้าที่เข้าชมหลังจากวันที่นี้ ซึ่งแสดงเป็นมิลลิวินาทีตั้งแต่ Epoch หากไม่ได้ระบุพร็อพเพอร์ตี้ ค่าเริ่มต้นจะเป็น 24 ชั่วโมง

    • ข้อความ

      สตริง

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

  • callback

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

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

    (results: HistoryItem[]) =& gt;void

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

  • Promise<HistoryItem[]>

    Chrome 96 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

กิจกรรม

onVisited

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (result: HistoryItem) =& gt;void

onVisitRemoved

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (removed: object) =& gt;void

    • ลบแล้ว

      ออบเจ็กต์

      • allHistory

        บูลีน

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

      • URL

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