Documentation/แนะนำโปรเจค
v1.0.5GitHub
THAI ADDRESS SELECT DOCUMENTATION

ที่อยู่ไทยครบทุกขั้น
เชื่อมต่อได้ในไม่กี่บรรทัด

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

เริ่มต้นใช้งาน ลองเล่นเดโม
TSเขียนด้วย TypeScriptใช้กับ HTML select เดิมข้อมูลที่อยู่ในแพ็กเกจOpen source · MIT*
INTERACTIVE PLAYGROUND

ลองเลือกที่อยู่ดูสิLive demo

เลือกจังหวัด แล้วให้ dropdown ที่เหลือทำงานต่อให้คุณ

ที่อยู่จัดส่งตัวอย่างฟอร์ม
กำลังเตรียมเดโม...
หรือเริ่มจากที่อยู่ตัวอย่าง
ค่าที่ได้จาก getValue() 
{
  "province": null,
  "district": null,
  "subDistrict": null,
  "zip_code": null
}
รอการเลือกที่อยู่JSON

เดโมนี้ใช้ ThaiAddressSelect จาก source จริง · แสดงค่าที่ยังไม่เลือกเป็น null เพื่อให้อ่านง่าย (API คืน undefined)

77จังหวัด
929อำเภอ / เขต
7,451รายการตำบล / แขวง

นับจากไฟล์ข้อมูลใน repository นี้
ไม่ใช่การยืนยันข้อมูลเขตการปกครองล่าสุด

GETTING STARTED

เพิ่มลงในโปรเจคของคุณ

ติดตั้งแพ็กเกจ แล้วนำเข้าในแอปฝั่ง browser ที่ใช้ bundler เช่น Vite 

npm install thai-address-select
ใช้ bundler เพื่อจัดการ ES modules และ JSON

source นำเข้าฐานข้อมูล JSON โดยตรง และ entry point มี import ที่ไม่ระบุนามสกุล จึงไม่ควรเปิดไฟล์ HTML ผ่าน file:// หรือ import ไฟล์ใน dist ตรง ๆ ใน browser โดยไม่มี bundler

ต้องการรันเว็บเอกสารนี้บนเครื่อง?

ใช้ Node.js 22.12+ หรือ 24+ สำหรับเครื่องมือเว็บเอกสาร จากโฟลเดอร์ repository รัน:

npm run docs:build สร้างเว็บใน docs-dist/ และ npm run docs:preview เปิดดูผล build ส่วน npm run build ยังใช้ build ไลบรารีเหมือนเดิม

YOUR FIRST ADDRESS FORM

จากสามช่องเลือก เป็นหนึ่งที่อยู่

ตัวอย่างนี้ใช้ JavaScript ในโปรเจคที่มี bundler และอ่านค่าทุกครั้งที่ฟอร์มเปลี่ยน

1

เตรียมช่องเลือกใน HTML

ใส่ id ให้แต่ละช่อง และใช้ readonly กับรหัสไปรษณีย์

2

สร้าง instance และเชื่อมกับฟอร์ม

นำเข้าไลบรารีใน main.js แล้วผูก element ทั้งสามเข้าด้วยกัน

3

รับที่อยู่พร้อมใช้ และคืนทรัพยากรเมื่อเลิกใช้

selectChange ส่งข้อมูลเมื่อเลือกครบสามช่อง ส่วนการเปลี่ยนจังหวัดหรืออำเภอจะรีเซ็ตช่องถัดไป จึงต้องอัปเดตรหัสไปรษณีย์จาก event รายช่องด้วย

MAKE IT YOURS

ปรับใช้กับฟอร์มของคุณ

ตั้งค่าเริ่มต้น ปรับข้อความ หรือใช้แค่ฟังก์ชันค้นหาข้อมูลก็ได้

ตั้งค่าผ่านโค้ดแล้ว อย่าลืมอ่านค่าใหม่

initialValue และ setValue() ไม่ส่ง event ให้เรียก getValue() เพื่ออัปเดต UI เอง และใช้ชื่อให้ตรงกับ dataset เช่น เขตบางรัก

THE REFERENCE

API ที่ใช้บ่อย อยู่ตรงนี้ครบ

ชื่อและพฤติกรรมอ้างอิงจาก source ใน repository เวอร์ชัน v1.0.5

Constructor new ThaiAddressSelect(options)

Option Type การใช้งาน
provinceElrequired HTMLSelectElement ช่องเลือกจังหวัด
districtElrequired HTMLSelectElement ช่องเลือกอำเภอ / เขต
subDistrictElrequired HTMLSelectElement ช่องเลือกตำบล / แขวง
placeholder object · optional ข้อความ province, district, subDistrict ปรับแยกได้ ค่าเริ่มต้นคือ “เลือกจังหวัด”, “เลือกอำเภอ/เขต”, “เลือกตำบล/แขวง”
initialValue ThaiAddressValue · optional ชื่อจังหวัด อำเภอ และตำบลสำหรับค่าเริ่มต้น

Methods

getValue()

คืน { province?, district?, subDistrict?, zip_code? } เป็น string หรือ undefined รหัสไปรษณีย์ได้เมื่อเลือกครบและพบในข้อมูล

setValue(value)

เติมค่าตาม ThaiAddressValue โดยไม่ส่ง event ใช้ setValue({}) เพื่อล้างทั้งฟอร์ม ไม่ใช่การ merge ค่าเดิม

destroy()

ถอด listener ของไลบรารีออกจาก select ทั้งสามช่อง ไม่ลบ DOM และไม่ถอด listener ที่คุณเพิ่มเองบน instance

Events · CustomEvent.detail

Event ส่งเมื่อ detail
provinceChange ผู้ใช้เปลี่ยนจังหวัด { province }
districtChange ผู้ใช้เปลี่ยนอำเภอ { province, district }
subDistrictChange ผู้ใช้เปลี่ยนตำบล { province, district, subDistrict }
selectChange เลือกครบสามช่อง { province, district, subDistrict, zip_code }

Utility functions

นำเข้าจาก thai-address-select หรือ thai-address-select/utils โดยไม่ต้องสร้าง dropdown

Function ผลลัพธ์และพฤติกรรม
loadData() Promise<void> — ปัจจุบันข้อมูลโหลดผ่าน import แล้ว ฟังก์ชันนี้ resolve ทันที
getProvinces() string[] — ชื่อจังหวัดไม่ซ้ำ เรียงตามภาษาไทย
getDistricts(province) string[] — อำเภอในจังหวัด เรียงตามภาษาไทย ไม่พบคืน []
getSubDistricts(province, district) string[] — ตำบลในอำเภอ เรียงตามภาษาไทย ไม่พบคืน []
getzip_code(province, district, subDistrict) string | undefined — ชื่อฟังก์ชันใช้ตัว z เล็กตาม source
findProvinceByName(query) string[] — trim แล้วค้นหาข้อความที่อยู่ในชื่อด้วย includes ไม่ใช่ fuzzy matching; "" คืน [] แต่ช่องว่างล้วนคืนทุกจังหวัด

Types ที่ export: ThaiAddressSelectOptions และ ThaiAddressValue (ตัวหลังมีเฉพาะชื่อที่อยู่สามช่อง; return type ของ getValue() เพิ่ม zip_code)

UNDER THE HOOD

เล็กพอที่จะอ่านโค้ดตามได้

หน้าที่หลักแบ่งเป็นสามส่วน: ข้อมูล → ฟังก์ชันกรอง → ตัวควบคุม dropdown

JSONฐานข้อมูลที่อยู่thai-address.json
→
TSค้นหาและกรองfilterAddress.ts
→
DOMเชื่อม dropdownThaiAddressSelect.ts

สิ่งที่ควรรู้จากการอ่านโปรเจค

  • ข้อมูลอยู่ใน bundle: JSON ต้นฉบับมีขนาดประมาณ 3.43 MB ก่อน minify และบีบอัด ไม่มีการเรียก API ที่อยู่ภายนอกตอนเลือก dropdown
  • จัดการ DOM โดยตรง: ใช้ document, EventTarget และ CustomEvent จึงควรสร้าง instance หลัง mount บน client
  • แยก build เว็บกับไลบรารี: tsc สร้าง JavaScript และ declarations ใน dist/; Vite bundle เว็บเอกสารไปที่ docs-dist/
  • ตรวจ packaging ก่อนนำไปเผยแพร่: package.json ยังระบุ dependency ชื่อเดียวกับแพ็กเกจตัวเอง และชี้ require ไปไฟล์ ESM จึงไม่รับรองการใช้ผ่าน CommonJS จากเว็บเอกสารนี้
  • ขอบเขตของข้อมูล: จำนวนบนหน้านี้นับรายการจากไฟล์จริง ต่างจากตัวเลขเดิมใน README และยังไม่มีการยืนยันแหล่งข้อมูลหรือความสดใหม่จากหน่วยงานภายนอก
A FEW USEFUL ANSWERS

ติดตรงไหน ลองเริ่มจากตรงนี้

เปลี่ยนจังหวัดแล้วรหัสไปรษณีย์เก่ายังแสดงอยู่?

selectChange จะไม่ส่งเมื่อเลือกไม่ครบ ให้ฟัง provinceChange และ districtChange แล้วอ่าน getValue().zip_code ?? "" ใหม่ตามตัวอย่างเริ่มต้น

ทำไมเปิด index.html ตรง ๆ แล้วเดโมไม่ทำงาน?

เว็บนี้ต้องผ่าน Vite เพื่อแปลง TypeScript และ JSON ให้รัน npm install แล้ว npm run docs:dev จาก repository และเปิด URL ที่ terminal แสดง

ใช้กับ React หรือ Next.js ได้อย่างไร?

สร้าง instance ใน useEffect หลัง DOM พร้อม ใช้ dynamic import บน client และถอด listener พร้อมเรียก destroy() ตอน unmount ตัวอย่างในแท็บ React จัดการกรณี component ถูกถอดระหว่างโหลดด้วย

ตั้งค่าเริ่มต้นแล้วเลือกอำเภอหรือตำบลไม่ติด?

ชื่อต้องตรงกับข้อมูลและสัมพันธ์กันทั้งสามระดับ เรียก getDistricts(province) และ getSubDistricts(province, district) เพื่อดูชื่อจริง เช่นใช้ เขตบางรัก แทน บางรัก สำหรับอำเภอ

ปรับหน้าตาและปิดช่องที่ยังเลือกไม่ได้อย่างไร?

ไลบรารีใช้ select ของคุณ จึงแต่งด้วย CSS ได้ตามปกติ ส่วน disabled ต้องจัดการเองจากค่าปัจจุบัน เหมือนเดโมหน้านี้ที่เปิดช่องอำเภอหลังเลือกจังหวัด และเปิดช่องตำบลหลังเลือกอำเภอ

ข้อมูลจะอัปเดตให้อัตโนมัติไหม?

ไม่มีการ sync ข้อมูลภายนอก ข้อมูลผูกกับ JSON ในแพ็กเกจที่ติดตั้ง ควรตรวจสอบความเหมาะสมและความถูกต้องสำหรับงานของคุณก่อนใช้งานจริง

READY WHEN YOU ARE

ให้ฟอร์มถัดไป เลือกที่อยู่ได้ง่ายขึ้น

เริ่มด้วยสาม select แล้วต่อยอดในแบบของคุณ

สร้างฟอร์มแรก

ค้นหาเอกสาร

Tab เพื่อเลือกผลลัพธ์ · Enter เพื่อเปิด · Esc เพื่อปิด