thai-address-select
Dropdown ที่อยู่ไทย
thai-address-select คือไลบรารี JavaScript/TypeScript สำหรับเลือก จังหวัด → อำเภอ/เขต → ตำบล/แขวง แบบเชื่อมโยง พร้อมค้นหารหัสไปรษณีย์จากข้อมูลในแพ็กเกจ ใช้กับ HTML select และ React ผ่าน bundler เช่น Vite
แพ็กเกจ v1.0.7 บน npm ↗ ผู้ดูแล rratchapol ตรวจเอกสารกับ source
เหมาะกับฟอร์มจัดส่งสินค้า สมัครสมาชิก และข้อมูลลูกค้าที่ต้องเลือกที่อยู่ไทยแบบเป็นลำดับ ใช้ข้อมูลในแพ็กเกจโดยไม่ต้องมี API key; ไม่มีแผนที่ geocoding หรือช่อง autocomplete ในตัว
ลองเลือกที่อยู่ดูสิLive demo
เลือกจังหวัด แล้วให้ dropdown ที่เหลือทำงานต่อให้คุณ
{
"province": null,
"district": null,
"subDistrict": null,
"zip_code": null
}
เดโมนี้ใช้ ThaiAddressSelect จาก source จริง ·
แสดงค่าที่ยังไม่เลือกเป็น null เพื่อให้อ่านง่าย (API
คืน undefined)
นับจากไฟล์ข้อมูลใน repository นี้
ไม่ใช่การยืนยันข้อมูลเขตการปกครองล่าสุด
ติดตั้ง thai-address-select ด้วย npm
ติดตั้งแพ็กเกจ แล้วนำเข้าในแอปฝั่ง browser ที่ใช้ bundler เช่น Vite
npm install thai-address-select
source นำเข้าฐานข้อมูล JSON โดยตรง และ entry point มี import
ที่ไม่ระบุนามสกุล จึงไม่ควรเปิดไฟล์ HTML ผ่าน
file:// หรือ import ไฟล์ใน dist ตรง ๆ
ใน browser โดยไม่มี bundler
ต้องการรันเว็บเอกสารนี้บนเครื่อง?
ใช้ Node.js 22.12+ หรือ 24+ สำหรับเครื่องมือเว็บเอกสาร จากโฟลเดอร์ repository รัน:
npm install
npm run docs:dev
# สร้างเว็บสำหรับนำไป host แบบ static
npm run docs:build
npm run docs:preview
npm run docs:build สร้างเว็บใน
docs-dist/ และ
npm run docs:preview เปิดดูผล build ส่วน
npm run build ยังใช้ build ไลบรารีเหมือนเดิม
วิธีสร้าง Dropdown ที่อยู่ไทยด้วย JavaScript
ตัวอย่างนี้ใช้ JavaScript ในโปรเจคที่มี bundler และอ่านค่าทุกครั้งที่ฟอร์มเปลี่ยน
เตรียมช่องเลือกใน HTML
ใส่ id ให้แต่ละช่อง และใช้
readonly กับรหัสไปรษณีย์
<label for="province">จังหวัด</label>
<select id="province"></select>
<label for="district">อำเภอ / เขต</label>
<select id="district"></select>
<label for="subDistrict">ตำบล / แขวง</label>
<select id="subDistrict"></select>
<label for="zipCode">รหัสไปรษณีย์</label>
<input id="zipCode" readonly />
<script type="module" src="/main.js"></script>สร้าง instance และเชื่อมกับฟอร์ม
นำเข้าไลบรารีใน main.js แล้วผูก element
ทั้งสามเข้าด้วยกัน
import { ThaiAddressSelect, loadData } from "thai-address-select";
// ปัจจุบันข้อมูลพร้อมจาก import แล้ว
await loadData();
const address = new ThaiAddressSelect({
provinceEl: document.getElementById("province"),
districtEl: document.getElementById("district"),
subDistrictEl: document.getElementById("subDistrict"),
});
const zipCode = document.getElementById("zipCode");
const updateZipCode = () => {
zipCode.value = address.getValue().zip_code ?? "";
};
const events = [
"provinceChange", "districtChange", "subDistrictChange"
];
events.forEach((event) => {
address.addEventListener(event, updateZipCode);
});
updateZipCode();รับที่อยู่พร้อมใช้ และคืนทรัพยากรเมื่อเลิกใช้
selectChange ส่งข้อมูลเมื่อเลือกครบสามช่อง
ส่วนการเปลี่ยนจังหวัดหรืออำเภอจะรีเซ็ตช่องถัดไป
จึงต้องอัปเดตรหัสไปรษณีย์จาก event รายช่องด้วย
const onComplete = (event) => {
console.log(event.detail);
// { province: "กรุงเทพมหานคร", district: "เขตบางรัก",
// subDistrict: "สีลม", zip_code: "10500" }
};
address.addEventListener("selectChange", onComplete);
// เรียกเมื่อถอดฟอร์มหรือเปลี่ยนหน้าในแอปของคุณ
function cleanupAddressForm() {
events.forEach((event) => {
address.removeEventListener(event, updateZipCode);
});
address.removeEventListener("selectChange", onComplete);
address.destroy();
}ตัวอย่าง React, Next.js และการปรับแต่งฟอร์ม
ตั้งค่าเริ่มต้น ปรับข้อความ หรือใช้แค่ฟังก์ชันค้นหาข้อมูลก็ได้
ปรับแต่งฟอร์ม
ใช้แทน main.js เดิมเพื่อกำหนด placeholder และที่อยู่เริ่มต้น พร้อมอัปเดตรหัสไปรษณีย์เมื่อผู้ใช้เปลี่ยนค่า
import { ThaiAddressSelect } from "thai-address-select";
const address = new ThaiAddressSelect({
provinceEl: document.getElementById("province"),
districtEl: document.getElementById("district"),
subDistrictEl: document.getElementById("subDistrict"),
placeholder: {
province: "จังหวัดที่จัดส่ง",
district: "เลือกอำเภอ / เขต",
subDistrict: "เลือกตำบล / แขวง",
},
initialValue: {
province: "กรุงเทพมหานคร",
district: "เขตบางรัก",
subDistrict: "สีลม",
},
});
const sync = () => {
document.getElementById("zipCode").value =
address.getValue().zip_code ?? "";
};
const events = [
"provinceChange", "districtChange", "subDistrictChange"
];
events.forEach((event) => address.addEventListener(event, sync));
sync(); // initialValue ไม่ส่ง event
function resetAddress() {
address.setValue({});
sync(); // setValue() ไม่ส่ง event เช่นกัน
}
function cleanupAddressForm() {
events.forEach((event) => address.removeEventListener(event, sync));
address.destroy();
}React / Next.js
สร้าง instance หลัง mount บน client พร้อม cleanup และป้องกัน async initialization หลัง unmount ใช้ใน React หรือ Next.js Client Component
"use client";
import { useEffect, useRef, useState } from "react";
export default function AddressForm() {
const provinceRef = useRef<HTMLSelectElement>(null);
const districtRef = useRef<HTMLSelectElement>(null);
const subDistrictRef = useRef<HTMLSelectElement>(null);
const [zipCode, setZipCode] = useState("");
const [ready, setReady] = useState(false);
const [error, setError] = useState("");
useEffect(() => {
let cancelled = false;
let dispose = () => {};
async function init() {
try {
const { ThaiAddressSelect, loadData } =
await import("thai-address-select");
await loadData();
if (cancelled) return;
const provinceEl = provinceRef.current;
const districtEl = districtRef.current;
const subDistrictEl = subDistrictRef.current;
if (!provinceEl || !districtEl || !subDistrictEl) return;
const address = new ThaiAddressSelect({
provinceEl, districtEl, subDistrictEl,
});
const sync = () => {
setZipCode(address.getValue().zip_code ?? "");
};
const events = [
"provinceChange", "districtChange", "subDistrictChange"
];
events.forEach((event) => address.addEventListener(event, sync));
dispose = () => {
events.forEach((event) => {
address.removeEventListener(event, sync);
});
address.destroy();
};
sync();
setReady(true);
} catch {
if (!cancelled) setError("โหลดข้อมูลไม่สำเร็จ กรุณาโหลดหน้าใหม่");
}
}
void init();
return () => {
cancelled = true;
dispose();
};
}, []);
return (
<fieldset disabled={!ready}>
<legend>ที่อยู่จัดส่ง</legend>
<label>จังหวัด <select ref={provinceRef} /></label>
<label>อำเภอ / เขต <select ref={districtRef} /></label>
<label>ตำบล / แขวง <select ref={subDistrictRef} /></label>
<label>รหัสไปรษณีย์ <input value={zipCode} readOnly /></label>
{error && <p role="alert">{error}</p>}
</fieldset>
);
}Utility functions
ใช้ข้อมูลกับ UI ของคุณเอง โดยไม่ต้องสร้าง ThaiAddressSelect ค่า string ต้องตรงกับชื่อใน dataset
import {
loadData,
getProvinces,
getDistricts,
getSubDistricts,
getzip_code,
findProvinceByName,
} from "thai-address-select/utils";
await loadData();
const provinces = getProvinces(); // string[] เรียงตามภาษาไทย
const districts = getDistricts("กรุงเทพมหานคร");
const subDistricts = getSubDistricts("กรุงเทพมหานคร", "เขตบางรัก");
const zipCode = getzip_code("กรุงเทพมหานคร", "เขตบางรัก", "สีลม");
console.log(zipCode); // "10500" (string)
console.log(findProvinceByName("เชียง"));
// ["เชียงราย", "เชียงใหม่"]
console.log(getDistricts("ไม่มีจังหวัดนี้")); // []
console.log(getzip_code("ไม่มีจังหวัดนี้", "", "")); // undefined
initialValue และ setValue() ไม่ส่ง
event ให้เรียก getValue() เพื่ออัปเดต UI เอง
และใช้ชื่อให้ตรงกับ dataset เช่น เขตบางรัก
ThaiAddressSelect API: options, methods และ events
ชื่อและพฤติกรรมอ้างอิงจาก source ใน repository เวอร์ชัน v1.0.7
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)
เล็กพอที่จะอ่านโค้ดตามได้
หน้าที่หลักแบ่งเป็นสามส่วน: ข้อมูล → ฟังก์ชันกรอง → ตัวควบคุม dropdown
thai-address.json
filterAddress.ts
ThaiAddressSelect.ts
src/
├── index.ts # public exports และ types
├── components/
│ └── ThaiAddressSelect.ts # DOM, state และ events
├── utils/
│ └── filterAddress.ts # ฟังก์ชันค้นหาข้อมูล
└── data/
└── thai-address.json # จังหวัด → อำเภอ → ตำบล
dist/ # ผล build ไลบรารี (tsc)
docs/ # style, interaction และตัวอย่าง
index.html # เว็บเอกสารนี้
vite.config.mjs # config สำหรับเว็บเอกสาร
docs-dist/ # ผล build เว็บ (ไม่ commit)
test.ts # ตัวอย่างทดลอง DOM ไม่ใช่ test runnerสิ่งที่ควรรู้จากการอ่านโปรเจค
- ข้อมูลอยู่ใน 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 จากเว็บเอกสารนี้ - ขอบเขตของข้อมูล: จำนวนบนหน้านี้นับรายการจากไฟล์จริงใน repository ไม่ใช่ข้อมูลเขตการปกครองล่าสุดที่ยืนยันโดยหน่วยงานภายนอก
แหล่งอ้างอิงของเอกสารและข้อมูล
พฤติกรรม API ตรวจจากโค้ดโดยตรง คุณตรวจสอบหรือแจ้งข้อมูลที่ควรแก้ได้จากแหล่งต่อไปนี้:
- แพ็กเกจ thai-address-select บน npm — เวอร์ชันที่เผยแพร่และคำสั่งติดตั้ง
- ThaiAddressSelect.ts — การเลือกที่อยู่ ค่าเริ่มต้น และ events
- filterAddress.ts — ฟังก์ชันค้นหาจังหวัด อำเภอ ตำบล และรหัสไปรษณีย์
- thai-address.json — snapshot ที่ใช้คำนวณจำนวนรายการบนหน้านี้
- แจ้งปัญหาหรือเสนอแก้ไขเอกสาร
คำถามที่พบบ่อยเกี่ยวกับ thai-address-select
ค้นหารหัสไปรษณีย์ไทยโดยไม่สร้าง dropdown ได้ไหม?
ได้ ใช้
getzip_code(province, district, subDistrict) จาก
thai-address-select/utils เช่น
getzip_code("กรุงเทพมหานคร", "เขตบางรัก", "สีลม") ได้
"10500" หากชื่อไม่ตรงกับข้อมูลจะได้
undefined ดู
ตัวอย่างฟังก์ชันข้อมูลที่อยู่
เป็นช่องพิมพ์ค้นหาที่อยู่แบบ autocomplete หรือไม่?
thai-address-select เป็น dropdown แบบเชื่อมโยงสามช่อง ไม่มีช่อง
autocomplete ในตัว หากต้องการทำช่องค้นหาของตัวเอง ใช้ utility
functions ดึงรายการไปสร้าง UI ได้ โดย
findProvinceByName()
ค้นหาชื่อจังหวัดที่มีข้อความตรงกัน ไม่ใช่ fuzzy search
หรือการตรวจสอบที่อยู่จัดส่ง
ต้องใช้ API ภายนอกเพื่อค้นหารหัสไปรษณีย์ไหม?
ไม่ต้องเรียก API ที่อยู่ภายนอกตอนเลือกฟอร์ม เพราะ thai-address-select นำเข้าข้อมูลจังหวัด อำเภอ ตำบล และรหัสไปรษณีย์จาก JSON ในแพ็กเกจ ผ่าน bundler ของแอป ข้อมูลนี้ไม่ sync อัตโนมัติ
เปลี่ยนจังหวัดแล้วรหัสไปรษณีย์เก่ายังแสดงอยู่?
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 ในแพ็กเกจที่ติดตั้ง ควรตรวจสอบความเหมาะสมและความถูกต้องสำหรับงานของคุณก่อนใช้งานจริง
ให้ฟอร์มถัดไป เลือกที่อยู่ได้ง่ายขึ้น
เริ่มด้วยสาม select แล้วต่อยอดในแบบของคุณ