QuickAddress — nhúng 1 dòng, tự điền form

Bảy form dưới đây giả lập 7 website viết theo các kiểu khác nhau, không sửa gì cả, chỉ thêm <script src="quick-address.js" defer></script>. Bấm một nút "Dán thử" rồi bấm Nhập trong ô cam, sau đó bấm "Gửi" để xem dữ liệu form nhận được.

Thử ngay

Website A — form mới (Tỉnh → Phường/Xã)

Có <label for>, select Phường/Xã tải bằng AJAX sau khi chọn tỉnh, radio loại địa chỉ, ô ghi chú.

Dán thử:

Website B — kiểu WooCommerce, địa giới cũ (Tỉnh → Quận → Phường)

Có first/last name, email (phải bỏ qua), ghi chú đơn hàng, 3 select phụ thuộc nhau.

Dán thử:

Tên

Họ

Điện thoại

Tỉnh / Thành phố

Quận / Huyện

Xã / Phường

Địa chỉ

Ghi chú đơn hàng

Website D — form đăng ký tư vấn

Radio xưng hô, checkbox dịch vụ, select ngân sách theo khoảng, radio thanh toán, checkbox điều khoản (không được tự tick).

Dán thử:

Website G — đăng ký địa điểm (tên địa điểm, thương hiệu, hotline, mạng xã hội)

Không có ô họ tên, địa chỉ; ô Website/Facebook là type="url". Khách gõ liền một câu, không dấu phẩy.

Dán thử:

Website E — ô chọn tự vẽ, gõ để tìm (kiểu Ant Design / React-Select)

Không có <select> thật: ô là input role="combobox", danh sách gợi ý vẽ bằng div ở cuối trang; phường tải sau khi chọn tỉnh.

Dán thử:

Website F — bảng chọn kiểu Shopee (Tỉnh → Phường trong một ô)

Một ô duy nhất "Tỉnh/Thành phố, Phường/Xã"; bấm vào mở bảng chọn, chọn tỉnh xong bảng tự chuyển sang danh sách phường.

Dán thử:

Website C — form liên hệ đặt hàng, địa chỉ chỉ 1 ô

Không label, chỉ placeholder; tỉnh/phường được ghép vào chung ô địa chỉ.

Dán thử:

Hướng dẫn sử dụng

1. Gắn vào website (cho người làm web)

Đưa file lên host. Up quick-address.js (file mồi, không cần sửa) và quick-address.core.js (code thật) lên cùng một thư mục. Up kèm quick-address.php. Sau này chỉ sửa quick-address.core.js: mọi site dùng bản mới ngay lần tải trang kế tiếp, không cần đổi link.
Nhúng 1 dòng vào cuối trang có form, trước </body>:
```
<script src="https://cdn.cua-ban.vn/quick-address.js" defer></script>
```
Script tự tìm form và chèn ô "Dán và nhập nhanh" lên đầu form.
Kiểm tra khi gắn site mới. Tạm thêm data-debug:
```
<script src="https://cdn.cua-ban.vn/quick-address.js" data-debug defer></script>
```
Ô dò được có viền đỏ nét đứt, rê chuột để xem vai trò; mở Console (F12) có bảng liệt kê. Kiểm tra xong thì bỏ data-debug.

Dò sai thì sửa ngay trên form của site:

Tình huống	Cách sửa
Ô bị nhận sai vai trò	`data-qa-field="phone"` (name, firstName, lastName, phone, province, district, ward, street, note, budget)
Ô không muốn script đụng vào	`data-qa-field="none"`
Checkbox/radio khách hay gọi tên khác	`data-qa-keywords="vat, hoá đơn đỏ"`
Ô chọn tự vẽ không được nhận ra	`data-qa-field="province"` trên ô đó; ô chọn Tỉnh → Phường trong một bảng thì dùng `data-qa-field="area"` và nhãn có chữ "Tỉnh … Phường"
Muốn ô dán nằm chỗ khác	Đặt `<div data-quick-address></div>` trong form

Tuỳ chỉnh thêm trên thẻ script:

Thuộc tính	Tác dụng
`data-color="#0a7cff"`	Đổi màu theo brand của site
`data-selector="#form-dat-hang"`	Chỉ gắn vào form này
`data-confirm="false"`	Không hỏi trước khi ghi đè ô người dùng đã sửa
`data-confirm-submit="false"`	Không hỏi lại khi bấm Gửi mà còn ô viền cam
`data-auto="false"`	Tắt tự quét, tự gọi `QuickAddress.attach('#form')`
`data-api="https://..."`	Đổi nguồn dữ liệu tỉnh/phường

2. Cách dùng (cho người nhập liệu)

Copy thông tin khách (Zalo, Messenger…) và dán vào ô Dán và nhập nhanh. Không cần đúng thứ tự.
Bấm Nhập (hoặc Ctrl/Cmd + Enter).
Xem kết quả:
- Viền xanh đã điền, khá chắc chắn.
- Viền cam + ⚠ cần xem lại: chỉ có tên chưa có họ, SĐT sai đầu số, chưa thấy số nhà, phường cũ bị chia… Sửa ô đó thì nhắc tự tắt.
- Khung xám dưới ô dán là thông tin thêm, ví dụ "Phường Lộc Thọ là tên cũ → nay là Phường Nha Trang".
Bấm Gửi. Còn ô viền cam thì form hỏi lại: Kiểm tra lại (nhảy tới ô đó) hoặc Vẫn gửi.
Đã sửa tay mà dán lại nội dung khác thì form hỏi trước khi ghi đè.

3. Tự điền những gì

Trong nội dung dán	Điền vào
Họ tên, "anh/chị/ông/bà …"	Ô họ tên (bỏ xưng hô); radio/select Xưng hô – Giới tính
SĐT `0909…`, `+84…`, có chấm/cách	Ô SĐT; số thứ 2 trở đi đưa vào Ghi chú
Email `ten@congty.vn`	Ô Email (form bắt buộc email mà nội dung không có thì viền cam)
"Công ty …", "Cty …", "TNHH …", "Hộ kinh doanh …"	Ô Tên công ty / Đơn vị
Tỉnh, phường (mới hoặc cũ), quận cũ	Ô/select tỉnh, quận, phường (kể cả select tải bằng AJAX)
`Ghi chú: …`, `(gọi trước khi giao)`, "giao giờ hành chính", "cần tư vấn …"	Ô Ghi chú / Nội dung / Lời nhắn
`5tr`, `500k`, `8-10 triệu`, `ngân sách 1,5 tỷ`	Select/radio ngân sách (chọn đúng khoảng), hoặc ô số
Từ trùng nhãn lựa chọn: "chuyển khoản", "chữ ký số", "văn phòng"…	Tick radio/checkbox, chọn option tương ứng

Checkbox đồng ý điều khoản, chính sách, nhận tin, đặt làm mặc định không bao giờ được tự tick.

4. Cần lưu ý

Ô chọn tỉnh/phường tự vẽ bằng div (Ant Design, Element, React-Select, vue-select, MUI, bảng chọn kiểu Shopee) được điền bằng cách làm như người dùng: bấm mở, gõ tên để lọc, bấm đúng lựa chọn (xem Website E, F). Script nhận ra ô qua role="combobox", aria-haspopup hoặc class của các thư viện phổ biến. Ô tự vẽ không theo chuẩn nào thì thêm data-qa-field="province" (hoặc ward, district, area cho ô chọn nhiều cấp) vào chính ô đó.
Danh sách chỉ vẽ một phần và không có ô tìm kiếm (cuộn mới hiện thêm) thì có thể không tìm thấy lựa chọn; ô đó sẽ viền cam để người dùng tự chọn.
Form không dùng thẻ <form> hoặc chia nhiều bước (ô thông tin ẩn ở bước sau) vẫn chạy: script tự gắn khi bước đó hiện ra, và hỏi lại khi bấm các nút như "Tiếp tục", "Đăng ký", "Gửi", "Đặt lịch" mà còn ô viền cam.
Dữ liệu tỉnh/phường lấy từ API miễn phí provinces.open-api.vn. Trang phải mở qua http/https (không mở thẳng file trên máy).