Title: VietAddr – Vietnam 2-Level Address for WooCommerce
Author: vnwooplugins
Published: <strong>2026 年 10 月 7 日</strong>
Last modified: 2026 年 10 月 7 日

---

搜尋外掛

![](https://ps.w.org/vietaddr/assets/banner-772x250.png?rev=3731764)

![](https://ps.w.org/vietaddr/assets/icon-256x256.png?rev=3731796)

# VietAddr – Vietnam 2-Level Address for WooCommerce

 由 [vnwooplugins](https://profiles.wordpress.org/vnwooplugins/) 開發

[下載](https://downloads.wordpress.org/plugin/vietaddr.0.2.0.zip)

 * [詳細資料](https://tw.wordpress.org/plugins/vietaddr/#description)
 * [使用者評論](https://tw.wordpress.org/plugins/vietaddr/#reviews)
 *  [安裝方式](https://tw.wordpress.org/plugins/vietaddr/#installation)
 * [開發資訊](https://tw.wordpress.org/plugins/vietaddr/#developers)

 [技術支援](https://wordpress.org/support/plugin/vietaddr/)

## 外掛說明

Since 1 July 2025 Vietnam uses a 2-level administrative system: 34 provinces/cities
and 3,321 wards/communes/special zones. VietAddr turns the WooCommerce address form
into two dependent dropdowns for Vietnamese addresses:

 * **Province** (Tỉnh/Thành phố) uses the core `state` field: 34 entries.
 * **Ward** (Xã/Phường/Đặc khu) uses the core `city` field, filtered by the selected
   province. The ward name is stored, so addresses stay readable in emails, exports
   and other plugins.
 * Postcode is hidden for Vietnam.
 * Phone numbers must have 10 digits starting with 0 or +84 (03/05/07/08/09); they
   are saved as `0xxxxxxxxx`.

Works with:

 * the Checkout block and the classic `[woocommerce_checkout]` shortcode,
 * My Account > Addresses,
 * the admin order screen (ward dropdown filtered by province),
 * High-Performance Order Storage (HPOS).

**Migrating from “Vietnam Checkout for WooCommerce”** (woo-vietnam-checkout): Tools
> “VietAddr: chuyển địa chỉ” converts saved customer addresses (old 3-level province/
district/ward codes, or that plugin’s 2-level codes) to the new format. It has a
dry-run mode, backs up old values to the user meta `_vnck_legacy_address`, and lists
the addresses that need a manual fix (for example, an old ward split between several
new wards). WP-CLI: `wp vnck migrate-legacy [--apply]`.

Tiếng Việt: Plugin thay ô địa chỉ của WooCommerce bằng 2 ô chọn Tỉnh/Thành phố  
Xã/Phường/Đặc khu (34 tỉnh, 3.321 xã theo đơn vị hành chính từ 01/07/2025), ẩn mã
bưu chính, kiểm số điện thoại Việt Nam. Dùng được với Checkout Block, checkout cổ
điển, Tài khoản > Địa chỉ, màn sửa đơn trong admin, HPOS.

#### Data

Administrative units are bundled in `data/vn-units.json` (source: provinces.open-
api.vn API v2, see `data/SOURCE.md`). The plugin makes no external requests: the
browser loads the JSON file from your own site.

#### Credits and data sources

 * Administrative units (34 provinces/cities, 3,321 wards/communes/special zones,
   per the 2025 merger resolutions): source is the Vietnam National Statistics Office(
   Cục Thống kê, https://danhmuchanhchinh.nso.gov.vn/), downloaded through the API
   https://provinces.open-api.vn/ by Nguyễn Hồng Quân (https://github.com/hongquan/
   vn-open-api-provinces), licensed GPL-3.0-or-later. Download date and SHA-256 
   are in `data/SOURCE.md`.
 * The old-to-new ward conversion table (`data/legacy-map.json`) also uses data 
   from the plugin “Vietnam Checkout for WooCommerce” (woo-vietnam-checkout) 2.1.6(
   GPL), and the old-ward mapping of the same API.
 * This plugin is licensed GPL-3.0-or-later; the full text is in the `LICENSE` file.

## 螢幕擷圖

[⌊Checkout block: province and ward dropdowns.⌉⌊Checkout block: province and ward
dropdowns.⌉[

Checkout block: province and ward dropdowns.

[⌊Order received page with ward and province names.⌉⌊Order received page with ward
and province names.⌉[

Order received page with ward and province names.

[⌊Admin order screen: ward dropdown filtered by province.⌉⌊Admin order screen: ward
dropdown filtered by province.⌉[

Admin order screen: ward dropdown filtered by province.

## 安裝方式

 1. Upload the `vietaddr` folder to `/wp-content/plugins/` or install the zip from 
    Plugins > Add New.
 2. Activate the plugin. WooCommerce 8.0 or newer is required.
 3. Set the store country to Vietnam if needed. No settings page is required.

## 常見問題集

### Does it replace the city/state fields in the Checkout block?

The block keeps the core fields. Province is the core state dropdown. For the ward,
a small script places a dropdown over the core city field and writes the value through
the WooCommerce Blocks data store. The server checks again when the order is placed,
so an invalid ward or phone is rejected even without JavaScript.

### Can I change the phone rule?

Yes, with the `vnck_phone_pattern` filter (PHP regular expression applied to the
normalized number).

### What happens to addresses saved by version 0.1.0?

Version 0.1.0 stored ward codes. They are still accepted and shown as ward names;
the migration tool converts them to names.

### What is removed when I delete the plugin?

The plugin creates no options or transients. Deleting it from Plugins (uninstall)
removes only the user meta `_vnck_legacy_address`, the backup written by the migration
tool. Customer and order addresses (WooCommerce billing/shipping fields) are kept.
Deactivating the plugin removes nothing.

## 使用者評論

這個外掛目前沒有任何使用者評論。

## 參與者及開發者

以下人員參與了開源軟體〈VietAddr – Vietnam 2-Level Address for WooCommerce〉的開發
相關工作。

參與者

 *   [ vnwooplugins ](https://profiles.wordpress.org/vnwooplugins/)

[將〈VietAddr – Vietnam 2-Level Address for WooCommerce〉外掛本地化為台灣繁體中文版](https://translate.wordpress.org/projects/wp-plugins/vietaddr)

### 對開發相關資訊感興趣？

任何人均可[瀏覽程式碼](https://plugins.trac.wordpress.org/browser/vietaddr/)、查看
[SVN 存放庫](https://plugins.svn.wordpress.org/vietaddr/)，或透過 [RSS](https://plugins.trac.wordpress.org/log/vietaddr/?limit=100&mode=stop_on_copy&format=rss)
訂閱[開發記錄](https://plugins.trac.wordpress.org/log/vietaddr/)。

## 變更記錄

#### 0.2.0

 * Renamed from “VN Checkout” to VietAddr (slug `vietaddr`).
 * Checkout block support (ward dropdown, server-side validation through the Store
   API).
 * Ward name is stored in the city field (ward codes from 0.1.0 still accepted).
 * Admin order screen: ward dropdown.
 * Migration tool and WP-CLI command for “Vietnam Checkout for WooCommerce” addresses.
 * Text domain `vietaddr`, translation template `languages/vietaddr.pot`.
 * Uninstall removes the migration backup meta `_vnck_legacy_address`.
 * License changed to GPL-3.0-or-later; data credits added.

#### 0.1.0

 * Classic checkout and My Account: province/ward dropdowns, Vietnamese phone validation,
   HPOS compatibility.

## 中繼資料

 *  版本 **0.2.0**
 *  最後更新 **2 天前**
 *  啟用安裝數 **少於 10 次**
 *  WordPress 版本需求 ** 6.0 或更新版本 **
 *  已測試相容的 WordPress 版本 **7.1.3**
 *  PHP 版本需求 ** 7.4 或更新版本 **
 *  語言
 * [English (US)](https://wordpress.org/plugins/vietaddr/)
 * 標籤:
 * [address](https://tw.wordpress.org/plugins/tags/address/)[checkout](https://tw.wordpress.org/plugins/tags/checkout/)
   [phone](https://tw.wordpress.org/plugins/tags/phone/)[vietnam](https://tw.wordpress.org/plugins/tags/vietnam/)
   [woocommerce](https://tw.wordpress.org/plugins/tags/woocommerce/)
 *  [進階檢視](https://tw.wordpress.org/plugins/vietaddr/advanced/)

## 評分

這個項目尚無任何評論記錄。

[撰寫評分](https://wordpress.org/support/plugin/vietaddr/reviews/#new-post)

[查看全部使用者評論](https://wordpress.org/support/plugin/vietaddr/reviews/)

## 參與者

 *   [ vnwooplugins ](https://profiles.wordpress.org/vnwooplugins/)

## 技術支援

使用者可在技術支援論壇提出意見反應或使用問題。

 [檢視技術支援論壇](https://wordpress.org/support/plugin/vietaddr/)