chrome.history

คำอธิบาย

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

สิทธิ์

history

หากต้องการโต้ตอบกับประวัติเบราว์เซอร์ของผู้ใช้ ให้ใช้ API ประวัติ

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

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

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

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

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

ตัวอย่าง

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

ประเภท

HistoryItem

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

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

  • id

    สตริง

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

  • lastVisitTime

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

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

  • title

    string ไม่บังคับ

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

  • typedCount

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

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

  • URL

    string ไม่บังคับ

    URL ที่ผู้ใช้นำทางไป

  • visitCount

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

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

TransitionType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"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

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

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

  • URL

    สตริง

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

VisitItem

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

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

  • id

    สตริง

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

  • isLocal

    boolean

    Chrome 115 ขึ้นไป

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

  • referringVisitId

    สตริง

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

  • การเปลี่ยน

    TransitionType

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

  • visitId

    สตริง

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

  • visitTime

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

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

เมธอด

addUrl()

สัญญา 
chrome.history.addUrl(
  details: UrlDetails,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

deleteAll()

สัญญา 
chrome.history.deleteAll(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

deleteRange()

สัญญา 
chrome.history.deleteRange(
  range: object,
  callback?: function,
)

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

พารามิเตอร์

  • ช่วง

    ออบเจ็กต์

    • endTime

      ตัวเลข

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

    • startTime

      ตัวเลข

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

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

deleteUrl()

สัญญา 
chrome.history.deleteUrl(
  details: UrlDetails,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • Callback

    ไม่บังคับ

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 96 ขึ้นไป

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

getVisits()

สัญญา 
chrome.history.getVisits(
  details: UrlDetails,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    UrlDetails

  • Callback

    ไม่บังคับ

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

    (results: VisitItem[]) => void

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

  • Promise&lt;VisitItem[]&gt;

    Chrome 96 ขึ้นไป

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

สัญญา 
chrome.history.search(
  query: object,
  callback?: function,
)

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

พารามิเตอร์

  • query

    ออบเจ็กต์

    • endTime

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

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

    • ผลลัพธ์สูงสุด

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

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

    • startTime

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

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

    • ข้อความ

      สตริง

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

  • Callback

    ไม่บังคับ

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

    (results: HistoryItem[]) => void

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

  • Promise&lt;HistoryItem[]&gt;

    Chrome 96 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง 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[] ไม่บังคับ