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 หนึ่งๆ ในการเข้าชมหนึ่งๆ เช่น หากผู้ใช้เข้าชมหน้าเว็บโดยคลิกลิงก์ในหน้าอื่น ประเภทการเปลี่ยนผ่านจะเป็น "ลิงก์"

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

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

ตัวอย่าง

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

ประเภท

HistoryItem

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

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

• id

  สตริง

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

• lastVisitTime

  number ไม่บังคับ

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

• title

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

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

• typedCount

  number ไม่บังคับ

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

• URL

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

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

• visitCount

  number ไม่บังคับ

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

TransitionType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"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 ขึ้นไป

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

• URL

  สตริง

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

VisitItem

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

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

• id

  สตริง

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

• isLocal

  บูลีน

  Chrome 115 ขึ้นไป

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

• referringVisitId

  สตริง

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

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

  TransitionType

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

• visitId

  สตริง

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

• visitTime

  number ไม่บังคับ

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

เมธอด

addUrl()

Promise

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

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

พารามิเตอร์

• รายละเอียด

  UrlDetails

• callback

  function ไม่บังคับ

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

  () => void

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

• Promise<void>

  Chrome 96 ขึ้นไป

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

deleteAll()

Promise

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

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

พารามิเตอร์

• callback

  function ไม่บังคับ

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

  () => void

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

• Promise<void>

  Chrome 96 ขึ้นไป

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

deleteRange()

Promise

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

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

พารามิเตอร์

• ช่วง

  ออบเจ็กต์

  • endTime

    ตัวเลข

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

  • startTime

    ตัวเลข

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

• callback

  function ไม่บังคับ

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

  () => void

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

• Promise<void>

  Chrome 96 ขึ้นไป

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

deleteUrl()

Promise

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

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

พารามิเตอร์

• รายละเอียด

  UrlDetails

• callback

  function ไม่บังคับ

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

  () => void

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

• Promise<void>

  Chrome 96 ขึ้นไป

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

getVisits()

Promise

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

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

พารามิเตอร์

• รายละเอียด

  UrlDetails

• callback

  function ไม่บังคับ

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

  (results: VisitItem[]) => void

  • ผลลัพธ์

    VisitItem[]

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

• Promise<VisitItem[]>

  Chrome 96 ขึ้นไป

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

search()

Promise

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

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

พารามิเตอร์

• query

  ออบเจ็กต์

  • endTime

    number ไม่บังคับ

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

  • maxResults

    number ไม่บังคับ

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

  • startTime

    number ไม่บังคับ

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

  • ข้อความ

    สตริง

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

• callback

  function ไม่บังคับ

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

  (results: HistoryItem[]) => void

  • ผลลัพธ์

    HistoryItem[]

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

• Promise<HistoryItem[]>

  Chrome 96 ขึ้นไป

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

กิจกรรม

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

      บูลีน

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

    • URL

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