قابلیت استان‌ها و شهرهای ایران، فرایند ثبت نشانی در فروشگاه را برای مشتریان ایرانی ساده‌تر و دقیق‌تر می‌کند. با فعال‌سازی آن، نام استان‌های ایران به‌صورت فارسی نمایش داده می‌شود و مشتری به‌جای تایپ دستی نام شهر، آن را از فهرست شهرهای همان استان انتخاب می‌کند.
نسخه بررسی‌شده جم پک شامل اطلاعات ۳۱ استان و ۱۵۶۶ شهر ایران است. استان‌ها و شهرها بر اساس ترتیب الفبای فارسی مرتب می‌شوند تا پیداکردن مقصد سریع‌تر باشد. با تغییر استان، فهرست شهرها بدون بارگذاری دوباره صفحه تازه می‌شود.
نشانی‌ها با ساختار معمول ووکامرس ذخیره می‌شوند: کد استان در billing_state یا shipping_state و نام شهر در billing_city یا shipping_city. برای راه‌اندازی این قابلیت، لازم نیست نشانی‌های قبلی را تبدیل کنید یا فیلد تازه‌ای بسازید.
این قابلیت چه چیزی را تغییر می‌دهد؟
ماژول آدرس ایرانی دو کار مستقل انجام می‌دهد:
- نام استان‌های ایران را به‌جای برچسب دوزبانه ووکامرس، فقط به فارسی نمایش می‌دهد؛
- فیلد متنی شهر را برای استان‌های دارای داده به یک فهرست انتخابی تبدیل می‌کند.
برای نمونه، برچسب استان ممکن است از حالت زیر:
Tehran (تهران)به این حالت تبدیل شود:
تهراناین تغییر فقط مربوط به برچسب قابل مشاهده است. کد استاندارد استان تهران همچنان THR باقی می‌ماند و آدرس‌های قبلی، مناطق حمل‌ونقل و قواعدی که بر اساس این کد ساخته شده‌اند از کار نمی‌افتند.
ورود به تنظیمات استان‌ها و شهرها
برای دسترسی به تنظیمات:
- وارد پیشخوان وردپرس شوید.
- از منوی جم پک، «حمل‌ونقل و نشانی‌ها» را انتخاب کنید.
- زیرتب «استان‌ها و شهرها» را باز کنید.
پیوند مستقیم این بخش:
/wp-admin/admin.php?page=gempack#locations/addressesدر این زیرتب، تعداد استان‌ها و شهرهای موجود در نسخه نصب‌شده را هم می‌بینید. این مجموعه شامل ۳۱ استان و ۱۵۶۶ شهر است.
گزینه‌های استان‌ها و شهرهای ایران
فعال‌سازی قابلیت استان و شهر
این گزینه، قابلیت استان و شهر را روشن یا خاموش می‌کند. وقتی خاموش است، جم پک فیلدهای نشانی ووکامرس را تغییر نمی‌دهد.
برای استفاده از دو گزینه بعدی ابتدا باید این سوییچ را فعال کنید.
نمایش نام استان‌ها فقط به فارسی
با فعال‌کردن این گزینه، بخش انگلیسی برچسب استان‌های ایران حذف و فقط نام فارسی نمایش داده می‌شود. نام‌ها از فهرست خود ووکامرس خوانده می‌شوند و جم پک کد تازه‌ای برای استان‌ها ایجاد نمی‌کند.
فعال‌سازی این گزینه:
- کد استان ذخیره‌شده در سفارش را تغییر نمی‌دهد؛
- مناطق حمل‌ونقل فعلی را بازنویسی نمی‌کند؛
- نشانی مشتریان قبلی را ویرایش نمی‌کند؛
- روی استان‌ها و ایالت‌های کشورهای دیگر اثری ندارد؛
- فقط ترتیب و برچسب قابل مشاهده استان‌های ایران را بومی می‌کند.
تبدیل فیلد شهر به فهرست انتخابی
با فعال‌کردن این گزینه، فیلد شهر در آدرس صورتحساب و ارسال از ورودی متنی به یک فهرست قابل جست‌وجو تبدیل می‌شود. شهرهای نمایش‌داده‌شده به استان انتخابی وابسته‌اند.
رفتار فهرست شهر به این صورت است:
- با انتخاب استان، فقط شهرهای همان استان نمایش داده می‌شوند؛
- با تغییر استان، فهرست شهر بدون بارگذاری کامل صفحه تازه می‌شود؛
- شهرها با ترتیب الفبای فارسی مرتب‌اند؛
- مقدار ذخیره‌شده همان نام شهر است؛
- فهرست با ظاهر انتخابگرهای استاندارد ووکامرس هماهنگ می‌شود؛
- اگر برای یک استان داده‌ای وجود نداشته باشد، فیلد متنی معمولی باقی می‌ماند؛
- اگر جاوااسکریپت در دسترس نباشد، امکان تایپ شهر از بین نمی‌رود.
این فهرست، نام شهرها را نشان می‌دهد. نام شهرستان‌ها که محدوده اداری گسترده‌تری دارند، در آن قرار نگرفته است.
تنظیم پیشنهادی برای فروشگاه‌های ایرانی
| گزینه | مقدار پیشنهادی | دلیل |
|---|---|---|
| فعال‌سازی قابلیت استان و شهر | فعال | راه‌اندازی ماژول آدرس ایرانی |
| نمایش نام استان‌ها فقط به فارسی | فعال | حذف برچسب‌های دوزبانه از فرم فارسی |
| تبدیل فیلد شهر به فهرست انتخابی | فعال | کاهش غلط تایپی و یکدست‌شدن نام شهرها |
اگر افزونه دیگری در حال تبدیل شهر به فهرست است، گزینه سوم را هم‌زمان فعال نکنید. در بخش «جلوگیری از تداخل» روش بررسی این موضوع توضیح داده شده است.
فعال‌سازی مرحله‌به‌مرحله
- وارد «جم پک ← حمل‌ونقل و نشانی‌ها» شوید.
- زیرتب «استان‌ها و شهرها» را باز کنید.
- گزینه اصلی فعال‌سازی استان و شهر را روشن کنید.
- گزینه نمایش نام استان‌ها فقط به فارسی را فعال کنید.
- گزینه تبدیل فیلد شهر به فهرست انتخابی را روشن کنید.
- تنظیمات را ذخیره کنید.
- صفحه تسویه‌حساب یا ویرایش نشانی حساب کاربری را در یک پنجره جدید باز کنید.
- کشور را روی ایران قرار دهید.
- یک استان و سپس یک شهر را انتخاب کنید.
- استان را تغییر دهید و تازه‌شدن فهرست شهرها را بررسی کنید.
پس از فعال‌سازی، فقط ظاهر تنظیمات را بررسی نکنید. یک نشانی آزمایشی را ذخیره و نتیجه را در سفارش یا حساب کاربری کنترل کنید.
آزمایش در صفحه تسویه‌حساب
برای آزمایش فرایند خرید:
- یک محصول آزمایشی به سبد خرید اضافه کنید.
- وارد صفحه تسویه‌حساب شوید.
- کشور صورتحساب را «ایران» انتخاب کنید.
- یک استان مانند تهران را انتخاب کنید.
- فهرست شهر را باز و یکی از شهرها را انتخاب کنید.
- استان را به استان دیگری تغییر دهید.
- مطمئن شوید شهر قبلی حذف و فهرست شهرهای استان جدید نمایش داده می‌شود.
- سفارش آزمایشی را ثبت کنید.
- نشانی صورتحساب و ارسال سفارش را در پیشخوان بررسی کنید.
اگر مشتری برای ارسال کالا نشانی جداگانه‌ای وارد کند، همین رفتار باید در فیلدهای نشانی ارسال نیز آزمایش شود.
تغییر استان می‌تواند باعث اجرای دوباره محاسبه روش و هزینه ارسال شود. این رفتار متعلق به ووکامرس است و به فروشگاه کمک می‌کند نرخ مناسب مقصد جدید را نمایش دهد.
آزمایش در حساب کاربری مشتری
فهرست شهر در صفحه ویرایش نشانی حساب کاربری نیز استفاده می‌شود. برای بررسی:
- با یک حساب مشتری آزمایشی وارد شوید.
- به «حساب کاربری ← آدرس‌ها» بروید.
- نشانی صورتحساب یا ارسال را ویرایش کنید.
- کشور را ایران و استان را انتخاب کنید.
- شهر را از فهرست انتخاب و نشانی را ذخیره کنید.
- صفحه را دوباره باز و حفظ‌شدن استان و شهر را بررسی کنید.
اگر یک نشانی قدیمی شهری داشته باشد که در فهرست فعلی وجود ندارد، جم پک هنگام ویرایش آن مقدار را نگه می‌دارد تا ذخیره دوباره نشانی باعث حذف ناخواسته شهر نشود.
رفتار آدرس‌های قبلی
با فعال‌کردن قابلیت، سفارش‌ها و نشانی‌های قبلی تغییر نمی‌کنند. هنگام نمایش و ویرایش آن‌ها:
- کد استان‌های قبلی بدون تغییر باقی می‌ماند؛
- نام شهر ذخیره‌شده همچنان از همان فیلد ووکامرس خوانده می‌شود؛
- شهر قدیمیِ خارج از فهرست هنگام ویرایش نشانی حفظ می‌شود؛
- با تغییر استان، شهر قبلیِ نامرتبط با استان جدید کنار گذاشته می‌شود؛
- خاموش‌کردن ماژول دوباره همان فیلد متنی شهر ووکامرس را نمایش می‌دهد.
برای اطمینان، بهتر است پیش از استفاده عمومی یک سفارش قدیمی و یک حساب مشتری قدیمی را باز و بدون تغییر غیرضروری بررسی کنید.
داده‌ها چگونه در ووکامرس ذخیره می‌شوند؟
جم پک جدول یا متافیلد جداگانه‌ای برای استان و شهر ایجاد نمی‌کند. ساختار ذخیره‌سازی همان ساختار استاندارد ووکامرس است:
| نوع داده | فیلد استاندارد | مقدار ذخیره‌شده |
|---|---|---|
| استان صورتحساب | billing_state | کد استاندارد ووکامرس، مانند THR |
| شهر صورتحساب | billing_city | نام شهر، مانند تهران |
| استان ارسال | shipping_state | کد استاندارد ووکامرس، مانند ESF |
| شهر ارسال | shipping_city | نام شهر، مانند اصفهان |
ثابت‌ماندن این فیلدها باعث می‌شود بخش‌های دیگری که اطلاعات نشانی را می‌خوانند همچنان کار کنند؛ از جمله:
- سفارش‌ها و حساب مشتری؛
- فاکتورهای ووکامرس؛
- متغیرهای شهر در پیامک‌ها؛
- گزارش‌ها و خروجی‌های فروشگاه؛
- مناطق و روش‌های حمل‌ونقل؛
- اپلیکیشن موبایل و اتصال‌های مبتنی بر اطلاعات استاندارد آدرس.
تأثیر بر مناطق و روش‌های حمل‌ونقل
مناطق حمل‌ونقل ووکامرس استان را بر اساس کد استاندارد آن تشخیص می‌دهند. چون این ماژول کد استان را تغییر نمی‌دهد:
- مناطق حمل‌ونقل موجود حذف یا بازنویسی نمی‌شوند؛
- شرط‌های مبتنی بر استان همچنان قابل استفاده‌اند؛
- روش‌های ارسال می‌توانند مقصد را با همان کد استان تشخیص دهند؛
- فعال یا غیرفعال‌کردن نمایش فارسی نام استان، منطق منطقه را عوض نمی‌کند.
انتخاب دقیق شهر می‌تواند برای روش‌های حمل‌ونقلی که نرخ را بر اساس استان و شهر تعیین می‌کنند مفید باشد. تنظیم خود روش‌ها و نرخ‌های ایرانی در مستند جداگانه توضیح داده می‌شود.
سازگاری با صفحه تسویه‌حساب کلاسیک و بلوکی
فهرست شهر برای فرم‌های نشانی کلاسیک ووکامرس پیاده‌سازی شده است؛ از جمله تسویه‌حساب کلاسیک، ویرایش نشانی حساب کاربری و فرم‌های استاندارد مبتنی بر woocommerce_form_field.
اگر صفحه تسویه‌حساب شما با Checkout Block جدید ووکامرس ساخته شده است، پیش از اتکا به فهرست شهر آن را جداگانه آزمایش کنید. بلوک تسویه‌حساب از فرم و API مخصوص خود استفاده می‌کند و ممکن است فهرست شهر این نسخه در آن نمایش داده نشود.
برای تشخیص نوع صفحه تسویه‌حساب:
- اگر محتوای صفحه شامل شورت‌کد
[woocommerce_checkout]است، از ساختار کلاسیک استفاده می‌کنید؛ - اگر در ویرایشگر، بلوک Checkout ووکامرس قرار دارد، صفحه بلوکی است.
تا زمانی که سازگاری اختصاصی Checkout Block تأیید نشده، برای استفاده قطعی از فهرست وابسته شهر می‌توانید صفحه تسویه‌حساب کلاسیک را نگه دارید. این محدودیت به فارسی‌شدن نام استان در سایر بخش‌های استاندارد ووکامرس تعمیم داده نمی‌شود و هر بخش باید جداگانه آزمایش شود.
رفتار برای کشورهای دیگر
فهرست شهر برای ایران آماده شده است. با انتخاب کشور دیگر، فیلد شهر را ووکامرس یا افزونه مربوط به آن کشور مدیریت می‌کند.
این رفتار برای فروشگاه‌های بین‌المللی مهم است؛ فعال‌سازی آدرس ایرانی نباید مشتری کشورهای دیگر را مجبور به انتخاب شهر از فهرست ایران کند.
جلوگیری از تداخل با افزونه‌های شهر و استان
فعال‌بودن دو افزونه که هم‌زمان فیلد شهر را به فهرست تبدیل می‌کنند می‌تواند باعث موارد زیر شود:
- نمایش دو انتخابگر روی یک فیلد؛
- پاک‌شدن شهر هنگام تغییر استان؛
- حلقه تازه‌سازی در صفحه تسویه‌حساب؛
- ناهماهنگی گزینه‌های شهر؛
- ثبت‌نشدن صحیح نشانی.
جم پک وجود بعضی پیاده‌سازی‌های شناخته‌شده مبتنی بر کلاس‌های WC_City_Select و RY_WC_City_Select را تشخیص می‌دهد. اگر یکی از آن‌ها فعال باشد، برای جلوگیری از درگیری، تبدیل شهر را کنار می‌گذارد و در صفحه تنظیمات هشدار نمایش می‌دهد.
برای رفع تداخل:
- افزونه‌ها یا کدهای مربوط به استان و شهر را شناسایی کنید.
- فقط یک افزونه را مسئول فهرست شهر قرار دهید.
- کش سایت و مرورگر را پاک کنید.
- صفحه تسویه‌حساب را در حالت ناشناس باز کنید.
- نشانی صورتحساب و ارسال را دوباره آزمایش کنید.
اگر افزونه دیگری فقط داده شهر را از طریق استاندارد رایج wc_city_select_cities توسعه می‌دهد و خودش فیلد را بازنویسی نمی‌کند، داده آن می‌تواند با ساختار ماژول هماهنگ باشد. تداخل اصلی زمانی رخ می‌دهد که دو ابزار هم‌زمان کنترل رابط شهر را بر عهده بگیرند.
توسعه یا اصلاح فهرست شهرها
توسعه‌دهندگان می‌توانند داده استان و شهر را با فیلترهای وردپرس تغییر دهند. فیلتر اختصاصی استان‌ها:
aio_wc_iran_provincesفیلتر اختصاصی داده شهرها:
aio_wc_iran_citiesماژول همچنین از فیلتر رایج اکوسیستم انتخاب شهر ووکامرس استفاده می‌کند:
wc_city_select_citiesدر سفارشی‌سازی استان‌ها، کلید هر استان باید همان کد استاندارد ووکامرس باقی بماند. تغییر کدهایی مانند THR می‌تواند ارتباط نشانی‌ها و مناطق حمل‌ونقل را مختل کند.
کد سفارشی را مستقیماً داخل فایل‌های جم پک قرار ندهید، زیرا با به‌روزرسانی افزونه از بین می‌رود. از افزونه اختصاصی سایت یا محل امنی برای اسنیپت‌های وردپرس استفاده کنید و تغییرات را ابتدا در محیط آزمایشی بسنجید.
استفاده در اپلیکیشن موبایل
وقتی سوییچ اصلی استان‌ها و شهرها فعال باشد، دو مسیر فقط‌خواندنی برای دریافت همان داده‌های سایت ثبت می‌شوند. این مسیرها به ورود کاربر نیاز ندارند، زیرا فقط اطلاعات عمومی مرجع را برمی‌گردانند.
دریافت استان‌ها:
GET /wp-json/aio/v1/locations/provincesدریافت شهرهای یک استان:
GET /wp-json/aio/v1/locations/cities?province=THRخروجی استان‌ها شامل کد و نام فارسی است. برای ذخیره نشانی بهتر است اپلیکیشن کد استان را ارسال کند، اما نام فارسی یا برچسب شناخته‌شده استان نیز می‌تواند به کد استاندارد تبدیل شود.
این مسیرها به اپلیکیشن کمک می‌کنند فهرستی همسان با وب‌سایت نمایش دهد. اگر داده شهرها با فیلترهای توسعه‌دهنده تغییر کند، خروجی API نیز از همان مجموعه به‌روزشده استفاده می‌کند.
غیرفعال‌کردن استان‌ها و شهرها
برای بازگرداندن رفتار معمول ووکامرس:
- وارد «جم پک ← حمل‌ونقل و نشانی‌ها» شوید.
- زیرتب «استان‌ها و شهرها» را باز کنید.
- سوییچ اصلی قابلیت را خاموش کنید.
- تنظیمات را ذخیره کنید.
- صفحه تسویه‌حساب و ویرایش نشانی را تازه‌سازی کنید.
غیرفعال‌کردن قابلیت:
- آدرس‌های قبلی را حذف نمی‌کند؛
- نام شهرهای ذخیره‌شده را تغییر نمی‌دهد؛
- کد استان سفارش‌ها را بازنویسی نمی‌کند؛
- مناطق حمل‌ونقل را حذف نمی‌کند؛
- فقط فیلترها و رابط انتخاب شهر جم پک را کنار می‌گذارد.
اگر تنها یکی از رفتارها را نمی‌خواهید، می‌توانید سوییچ نام فارسی استان یا فهرست شهر را جداگانه خاموش و سوییچ اصلی را فعال نگه دارید.
چک‌لیست آزمایش پس از فعال‌سازی
- هر ۳۱ استان ایران در فهرست استان قابل انتخاب باشد؛
- نام استان‌ها فقط به فارسی نمایش داده شود؛
- شهرهای انتخابگر با استان فعلی مطابقت داشته باشند؛
- تغییر استان باعث تازه‌شدن فهرست شهر شود؛
- شهر قبلی متعلق به استان دیگر باقی نماند؛
- نشانی صورتحساب با موفقیت ذخیره شود؛
- نشانی ارسال جداگانه نیز با موفقیت ذخیره شود؛
- سفارش آزمایشی نام شهر و کد استان صحیح داشته باشد؛
- ویرایش یک نشانی قدیمی مقدار شهر آن را حذف نکند؛
- منطقه و هزینه حمل‌ونقل مناسب مقصد نمایش داده شود؛
- انتخاب کشور غیر از ایران فرم معمول خودش را حفظ کند؛
- نسخه موبایل و دسکتاپ صفحه تسویه‌حساب بررسی شود؛
- نوع کلاسیک یا بلوکی‌بودن Checkout مشخص و سازگاری آن آزمایش شود؛
- افزونه دیگری هم‌زمان فیلد شهر را بازنویسی نکند.
خطاهای رایج
گزینه‌های استان و شهر غیرفعال‌اند
- مطمئن شوید ووکامرس فعال است.
- صفحه تنظیمات جم پک را دوباره بارگذاری کنید.
- سطح دسترسی حساب مدیر را بررسی کنید.
- سوییچ اصلی استان و شهر را پیش از گزینه‌های وابسته فعال کنید.
فیلد شهر هنوز متنی است
- فعال‌بودن سوییچ اصلی و گزینه فهرست شهر را بررسی کنید.
- کشور نشانی باید ایران باشد.
- ابتدا یک استان دارای داده انتخاب کنید.
- صفحه را پس از ذخیره تنظیمات کاملاً تازه‌سازی کنید.
- وجود هشدار تداخل با افزونه انتخاب شهر دیگر را بررسی کنید.
- مطمئن شوید صفحه تسویه‌حساب از ساختار کلاسیک پشتیبانی‌شده استفاده می‌کند.
- خطاهای جاوااسکریپت یا بهینه‌سازی فایل‌های صفحه Checkout را بررسی کنید.
اگر برای استان انتخابی داده‌ای در دسترس نباشد یا جاوااسکریپت اجرا نشود، بازگشت به فیلد متنی رفتاری عمدی است تا ثبت نشانی غیرممکن نشود.
با تغییر استان، شهر قبلی پاک می‌شود
این رفتار در صورتی که شهر قبلی متعلق به استان پیشین باشد صحیح است. نگه‌داشتن آن، نشانی ناسازگار ایجاد می‌کند. پس از انتخاب استان جدید باید شهری از فهرست همان استان انتخاب شود.
شهر قدیمی در فهرست وجود ندارد
هنگام بازکردن نشانی ذخیره‌شده، شهر قدیمی باید به‌عنوان مقدار انتخاب‌شده حفظ شود تا از بین نرود. می‌توانید همان مقدار را نگه دارید یا یک شهر جدید از فهرست انتخاب کنید.
اگر استان را تغییر دهید، شهر قدیمی به استان جدید منتقل نمی‌شود؛ زیرا دیگر مقصد معتبری برای آن استان نیست.
نام استان هنوز دوزبانه است
- گزینه نمایش نام استان فقط به فارسی را فعال کنید.
- تنظیمات را ذخیره و صفحه را دوباره بارگذاری کنید.
- کش سایت و مرورگر را پاک کنید.
- افزونه یا قالبی را که فهرست استان‌های ووکامرس را بعد از جم پک بازنویسی می‌کند بررسی کنید.
فهرست شهر در Checkout Block نمایش داده نمی‌شود
نسخه فعلی ماژول برای ساختار فرم آدرس کلاسیک ووکامرس پیاده شده است. صفحه را از نظر استفاده از بلوک Checkout بررسی کنید. اگر فهرست شهر در صفحه بلوکی شما نمایش داده نمی‌شود، می‌توانید از تسویه‌حساب کلاسیک استفاده کنید یا فعلاً شهر را به‌صورت متنی دریافت کنید.
صفحه تسویه‌حساب پیوسته تازه می‌شود
- افزونه‌های دیگر استان، شهر، تسویه‌حساب و شخصی‌سازی فیلدها را بررسی کنید.
- ادغام یا تأخیر اجرای جاوااسکریپت Checkout را موقتاً غیرفعال کنید.
- کش را پاک و صفحه را بدون بهینه‌سازی آزمایش کنید.
- فقط یک ابزار را مسئول تبدیل فیلد شهر قرار دهید.
هزینه ارسال اشتباه نمایش داده می‌شود
این ماژول خودش نرخ ارسال تعیین نمی‌کند. موارد زیر را بررسی کنید:
- کد استان ذخیره‌شده در نشانی؛
- منطقه حمل‌ونقل متناظر در تنظیمات ووکامرس؛
- ترتیب مناطق حمل‌ونقل؛
- روش ارسال فعال در آن منطقه؛
- قواعد استان و شهر در روش حمل‌ونقل موردنظر.
بعضی شهرها تکراری یا با املای متفاوت‌اند
داده‌ها میان شکل‌های رایج نام شهرها تفاوت قائل می‌شوند و ممکن است داده اضافه‌شده توسط افزونه یا اسنیپت دیگری نیز وارد مجموعه شده باشد. فیلترهای aio_wc_iran_cities و wc_city_select_cities و افزونه‌های تأمین‌کننده داده را بررسی کنید.
مسیر شهرهای API خطای استان ناشناخته می‌دهد
پارامتر province باید کد یا نام شناخته‌شده استان باشد. نمونه معتبر:
/wp-json/aio/v1/locations/cities?province=THRاگر نام فارسی را در URL می‌فرستید، از رمزگذاری صحیح آن مطمئن شوید. استفاده از کد استان روش پیشنهادی و پایدارتر است.