ACF Persian Fields
مجموعهای کامل از ۱۰ فیلد تخصصی و هوشمند ایرانی برای ACF PRO — فیلدهایی که میدانند یک کدملی، شماره شبا، موبایل یا کدپستی ایرانی چطور باید باشد.
چرا این افزونه ساخته شد؟
اگر تا به حال برای گرفتن یک کدملی معتبر، شماره کارت بانکی که الگوریتمش درست باشد، یا یک تاریخ جلالی واقعی مجبور بودید چند فیلد متنی ساده بسازید و بعد با کد و افزونهی اعتبارسنجی آنها را دستی کنترل کنید — این افزونه دقیقاً برای همین ساخته شده است.
ACF Persian Fields ده فیلد آماده و هوشمند را در قالب یک دستهی جدید به ACF PRO اضافه میکند. این فیلدها فقط شکل ظاهری ندارند؛ هرکدام الگوریتم اعتبارسنجی واقعی، نرمالسازی هوشمند ورودی و چند قالب خروجی آمادهی استفاده در قالب را در خود دارند. ارقام فارسی و عربی بهصورت خودکار مدیریت میشوند، پیشوندهای موبایل نرمال میشوند و مقادیر همیشه بهصورت کانونیکال و استاندارد در دیتابیس ذخیره میشوند — حتی اگر کاربر با کیبورد عربی یا با کپیپیست مقدار وارد کرده باشد.
- اعتبارسنجی سمت سرور و کلاینت (غیرقابل دور زدن)
- تبدیل خودکار ارقام فارسی و عربی به لاتین
- ذخیرهسازی کانونیکال و سازگار با WP_Query و REST
- چند قالب خروجی برای هر فیلد (Return Format)
- هفت صفحهی تنظیمات بومی در پیشخوان وردپرس
- معماری Service Locator با هوکهای قابل توسعه
- پشتیبانی کامل از WPML و Polylang
- هیچ وابستگی خارجی اجباری ندارد
قبل از این افزونه، چه میکردید؟
روش رایج برای گرفتن مثلاً یک کدملی این بود: یک فیلد متنی (Text) بسازید، نوع ورودی را عددی بگذارید و طول آن را ۱۰ محدود کنید. این روش ظاهر درست دارد، اما در عمل با مشکلات جدی روبهرو میشود:
0000000000 یا 1234567890 از نظر طول درستاند، اما کدملی واقعی نیستند. هیچ بررسی الگوریتمی وجود ندارد.۰۰۴۱۱۱۶۶۵۹)، ذخیره و پردازش ارزشی مختل میشود.09...، +989... و 00989... در دیتابیس پراکنده و ناسازگار ذخیره میشوند.00411-16659 یا +98912... باید خودتان کد بنویسید و قالببندی را دستی پیاده کنید.ACF Persian Fields همهی این مشکلات را با فیلدهای تخصصی حل میکند. در ادامه میبینیم هر فیلد چه فرقی با فیلد معمولی دارد.
۱۰ فیلد در یک نگاه
افزونه همهی فیلدها را زیر یک دستهی جدید بهنام «Persian Fields» در مودال افزودن فیلد ACF قرار میدهد. هر فیلد در چند ثانیه قابل افزودن است و بلافاصله با الگوریتمهای اختصاصی کار میکند.
انتخابگر تاریخ جلالی
تقویم شمسی RTL اختصاصی با ذخیرهسازی استاندارد میلادی. سازگار با WP_Query، REST API و JSON-LD.
acfpf_jalali_date
انتخابگر تاریخ و ساعت
همان تقویم هوشمند جلالی، همراه با انتخاب ساعت. مناسب برای رویدادها، رزرو و گزارشهای زماندار.
acfpf_jalali_datetime
کدملی
۱۰ رقم با اعتبارسنجی الگوریتم چکسام استاندارد ایرانی. ارقام فارسی و عربی بهطور خودکار تبدیل میشوند.
acfpf_national_id
موبایل
نرمالسازی خودکار +98/0098 و اعتبارسنجی پیششمارهی اپراتورهای ایرانی.
acfpf_mobile
کدپستی
قواعد ایرانپست شامل ۱۰ رقم، غیر یکنواخت بودن و عدم امکان صفر در رقم پنجم. سیاست در سطح کل سایت.
acfpf_postal_code
حساب بانکی (کارت/شبا)
کارت ۱۶ رقمی با الگوریتم Luhn یا شبای IR... با ISO 13616. تشخیص خودکار بانک صادرکننده.
acfpf_bank_account
انتخاب بانک
لیست کشویی ۲۸ بانک ایرانی با لوگوی SVG. بدون نیاز به ورود دستی، با بهروزرسانی فوری منبع داده.
acfpf_banks_select
استان و شهر
دو لیست آبشاری هماهنگ (۳۱ استان و ۴۷۲ شهر) با بارگذاری AJAX و اعتبارسنجی سازگاری زوجها.
acfpf_province_city
نقشهی نشان
نقشهی Leaflet/Neshan با مارکر، موقعیتیابی، تمامصفحه و ۵ استایل مختلف. بدون محدودیت گوگل.
acfpf_neshan_map
امبد آپارات
پذیرش URL، iframe یا script و نرمالسازی به یک ویدیوی شناساییشده با پیشنمایش زندهی AJAX.
acfpf_aparat
جدول کامل فیلدها
جدول زیر نمای کاملی از دستهبندی، نام نمایشی، کلید فیلد (برای استفاده در کد) و عملکرد هر فیلد ارائه میدهد.
| دسته | فیلد | کلید فیلد | چه کاری انجام میدهد |
|---|---|---|---|
| تقویم جلالی | انتخابگر تاریخ جلالی | acfpf_jalali_date |
تاریخ شمسی با تقویم RTL، ذخیرهی استاندارد میلادی |
| انتخابگر تاریخ و ساعت جلالی | acfpf_jalali_datetime |
مانند بالا، همراه با ساعت | |
| هویت | کدملی | acfpf_national_id |
۱۰ رقم با اعتبارسنجی الگوریتم چکسام ایرانی |
| موبایل | acfpf_mobile |
نرمالسازی +98/0098 و اعتبارسنجی پیششمارهی اپراتور |
|
| کدپستی | acfpf_postal_code |
قواعد ایرانپست (رقم پنجم ≠ صفر و ...) | |
| بانکی | حساب بانکی (کارت/شبا) | acfpf_bank_account |
کارت ۱۶ رقمی (Luhn) یا شبای IR... (ISO 13616) |
| انتخاب بانک | acfpf_banks_select |
لیست کشویی ۲۸ بانک با لوگوی SVG | |
| موقعیت | استان و شهر | acfpf_province_city |
دو لیست آبشاری (۳۱ استان، ۴۷۲ شهر) با بارگذاری AJAX |
| نقشهی نشان | acfpf_neshan_map |
نقشهی Leaflet/Neshan با مارکر، موقعیتیابی و تمامصفحه | |
| رسانه | امبد آپارات | acfpf_aparat |
پذیرش URL/iframe/script و نرمالسازی به یک ویدیوی شناساییشده |
چه چیزی این افزونه را متمایز میکند؟
این افزونه فقط «چند فیلد اضافه» نیست؛ تفاوت اصلی در هوشمندی داخلی هر فیلد است. پنج ستون اصلی این متمایز بودن را شکل میدهند:
۱ اعتبارسنجی واقعی الگوریتمی
فیلدها فقط طول یا نوع ورودی را بررسی نمیکنند؛ صحت خودِ الگوریتم را تأیید میکنند:
- کدملی — چکسام استاندارد ایرانی (مجموع وزنی ارقام با ضریب
10−i، سپس مقایسه با رقم کنترل). - کارت بانکی — الگوریتم بینالمللی Luhn روی ۱۶ رقم.
- شبا — اعتبارسنجی ISO 13616 (mod-97) روی
IR+ ۲۴ رقم. - کدپستی — قواعد ایرانپست (۱۰ رقم، غیر یکنواخت، رقم پنجم نمیتواند صفر باشد).
- موبایل — علاوه بر الگوی
09xxxxxxxxx، حالت دقیق که پیششمارهی اپراتور (همراه اول، ایرانسل، رایتل، شاتل) را تأیید میکند.
هرکدام هم در مرورگر (AJAX) و هم در سرور اجرا میشوند، پس دور زدن سمت کلاینت ممکن نیست.
۲ تبدیل و نرمالسازی هوشمند ورودی
کاربر فارسیزبان اغلب با کیبورد فارسی تایپ میکند یا مقدار را از جای دیگری کپی میکند. افزونه این موارد را پیش از ذخیره خودکار اصلاح میکند:
- تبدیل ارقام فارسی (
۰۱۲۳...) و عربی (٠١٢٣...) به لاتین. - نرمالسازی پیشوندهای موبایل:
+989...،00989...و989...همگی به09xxxxxxxxx. - بزرگنویسی حروف، حذف فاصلهها و اطمینان از وجود یک
IRدر ابتدای شبا. - حذف جداکنندهها و نگهداشتن فقط ارقام کارت، کدملی و کدپستی.
نتیجه: مقدار ذخیرهشده همیشه یک شکل استاندارد و تمیز است، حتی اگر کاربر با کیبورد عربی یا با کپیپیست مقدار وارد کرده باشد.
۳ چند قالب خروجی برای هر فیلد
هر فیلد در تنظیماتش یک گزینهی «Return Format» دارد که تعیین میکند get_field() چه چیزی برگرداند. مثلاً موبایل میتواند سه شکل بدهد:
09123456789— کانونیکال+989123456789— بینالمللی0912-345-6789— گروهبندیشده
و کارت بانکی میتواند آرایهای برگرداند که نام بانک صادرکننده را هم در خود دارد (تشخیص از روی پیشوند IIN). این یعنی در قالب نیازی به منطق تبدیل دستی نیست.
۴ رابط مدیریت بومی و کامل
هفت صفحهی تنظیمات زیر یک منوی سطحبالای «Persian Fields» در پیشخوان وردپرس:
- عمومی — فعال/غیرفعال کردن ماژولها (جلالی، هویت، بانکی، موقعیت، رسانه).
- بومیسازی — RTL اجباری، تقویم فارسی/انگلیسی.
- پیشفرضهای جلالی — قالب نمایش و خروجی، شروع هفته، بازه.
- نقشهها — کلید API نشان، مرکز و زوم پیشفرض.
- داراییها — بارگذاری خودکار اسکریپتها.
- اعتبارسنجی — سختگیری کدپستی و موبایل در سطح کل سایت.
- توسعهدهنده — ابزارهای دیباگ.
همهی اینها با فیلدهای بومی ACF ساخته شدهاند، یعنی هیچ صفحهی تنظیمات سفارشی و سنگینی ندارید.
۵ معماری تمیز و قابل توسعه
- الگوی Service Locator (
ACFPF()) با سرویسها و helperهای آماده برای استفادهی مستقل در کد. - Providerهای قابل تعویض برای دادههای بانک، موقعیت، نقشه و ویدیو — هرکدام با یک فیلتر قابل جایگزینی است.
- هوکها برای توسعهی هر بخش (اضافه کردن بانک، پیششمارهی اپراتور، تغییر منبع داده).
- فایل زبان فارسی کامل (
fa_IR) با پشتیبانی ازfa_AFو انگلیسی.
کجا به کار میآید؟
هرجا که سایت شما اطلاعات هویتی، بانکی، موقعیتی یا رسانهای کاربران ایرانی را جمعآوری میکند، این افزونه وقت شما را حفظ میکند و کیفیت دادهها را تضمین میکند.
فرم تسویهحساب با کدملی، موبایل، کدپستی و استانشهر معتبر — کیفیت دادهی سفارشها تضمین میشود.
گرفتن شماره کارت یا شبا با اعتبارسنجی الگوریتمی واقعی و تشخیص خودکار بانک صادرکننده.
انتخاب تاریخ شمسی در فرم و نمایش آن در قالب، با ذخیرهی میلادی استاندارد برای کوئری.
نقشهی نشان با موقعیتیابی، مارکر و ۵ استایل — بدون محدودیت نقشهی گوگل در ایران.
امبد آپارات با پیشنمایش زنده، بدون نگرانی از فرمت ورودی URL یا iframe.
فرم پروفایل با همهی فیلدهای هویتی و بانکی، با نرمالسازی خودکار و خروجی تمیز.
معماری در یک نگاه
افزونه بر پایهی الگوی Service Locator ساخته شده است؛ همهی سرویسها از طریق یک تابع واحد در دسترساند و در عین حال کاملاً مستقل و قابل استفادهی مجدد هستند.
- پیشنیاز: ACF PRO فعال باشد. اگر نباشد، افزونه بیاثر میماند و فقط یک هشدار نشان میدهد (هیچ خطایی نمیدهد).
- همزیستی: فیلدها بهصورت یک دستهی جداگانه اضافه میشوند و با فیلدهای پیشفرض ACF هیچ تداخلی ندارند.
- ذخیرهسازی: مقادیر همیشه بهصورت استاندارد و کانونیکال ذخیره میشوند (تاریخ میلادی، کدملی فقط ارقام لاتین و ...) تا با کوئریهای WP، REST و خروجیهای دیگر سازگار بمانند.
- امنیت AJAX: نقشهی استانشهر و پیشنمایش آپارات با nonce مختص هر فیلد محافظت میشوند؛ حتی در فرمهای سمت کاربر (با
acf_form) هم امن هستند.
هفت صفحهی تنظیمات بومی
زیر منوی سطحبالای «Persian Fields» در پیشخوان، هفت صفحهی تنظیمات وجود دارد. همهی اینها با فیلدهای بومی ACF ساخته شدهاند — بدون صفحهی سفارشی سنگین.
دوستدار توسعهدهنده
افزونه طوری طراحی شده که هم برای کاربر نهایی ساده باشد و هم برای توسعهدهنده انعطافپذیر. چهار روش فراخوانی هر فیلد در قالب وجود دارد:
- توابع استاندارد ACF:
get_field()وthe_field() - توابع اختصاصی:
acfpf_get_*وacfpf_the_* - Service Locator:
ACFPF()->date()،->bank()و ... - شورتکد داخلی:
[acfpf_single_fields] - پشتیبانی کامل از Repeater، Group و Options Page
- اعتبارسنجی مستقل از فیلد برای فرمهای سفارشی و REST
- هوکهای متعدد برای جایگزینی Providerها
- helperهای آمادهی تبدیل تاریخ و ارقام
پشتیبانی از زبان
افزونه سه زبان را پشتیبانی میکند و تنظیمات بومیسازی (مثل شروع هفته و قالب تاریخ) بهصورت خودکار با زبان سایت تطبیق پیدا میکنند.
افزونه با WPML و Polylang سازگار است چون از متادیتای استاندارد ACF استفاده میکند. فایل زبان فارسی بهصورت کامل ارائه شده است.
آمادهی افزودن فیلدهای واقعاً ایرانی به سایتتان هستید؟
ده فیلد هوشمند، اعتبارسنجی الگوریتمی، نرمالسازی خودکار و معماری قابل توسعه — همه در یک افزونه. دیگر نیازی به کدنویسی دستی برای کدملی، موبایل، شبا، تقویم جلالی یا نقشهی ایرانی نیست.