پرش به محتویات

Map

المان Map در Bricks امکان نمایش Google Maps با طیف گسترده‌ای از قابلیت‌ها را می‌دهد — از نمایش یک مکان تکی تا رندر پویای چند نشانگر بر اساس query.

map-without-google-maps-api

برای شروع سریع، یک کلید Google Maps API اضافه کنید. این راهنما را برای راه‌اندازی دنبال کنید: نحوه راه‌اندازی کلید Google Maps API.

بدون کلید API، المان Map همچنان کار می‌کند اما به نمایش یک نشانگر تکی محدود است.

برای اطمینان از نمایش نشانگر، کافی است یک جفت مختصات (latitude و longitude جداشده با کاما) را در فیلد Address وارد کنید.

نمایش چند آدرس

برای دسترسی به ویژگی‌های پیشرفته مانند چند مکان، clustering و Info Box سفارشی، یک کلید Google Maps API معتبر لازم است. پس از اضافه کردن کلید، کنترل‌های بیشتری روی المان خواهید دید.

Bricks از سه حالت ورود آدرس پشتیبانی می‌کند:

۱) استاتیک (Static)

چند مکان را به صورت دستی با استفاده از کنترل Repeater «Addresses» المان Map تعریف کنید. این حالت فقط از Info Box پیش‌فرض Google Maps پشتیبانی می‌کند.

۲) Query loop

از این حالت وقتی می‌خواهید نقشه را با آدرس‌ها/مختصات یک query تغذیه کنید استفاده کنید.

مثلاً اگر Custom post type مثل «Properties» دارید که هر Property آدرسی دارد، فعال‌سازی Query loop امکان نمایش نشانگرهای همه آدرس‌های properties روی نقشه را می‌دهد. (@since 2.0)

همچنین می‌توانید یک Info Box سفارشی با استفاده از popup template تعریف کنید.

در مثال بالا، custom post type property را انتخاب کردیم که هر آدرس در یک فیلد سفارشی (ACF) ذخیره شده. ارائه مختصات latitude و longitude دقیق‌تر از آدرس فیزیکی خواهد بود.

۳) همگام‌سازی با query (Sync with query)

برای موارد استفاده‌ای که نقشه کنار یک query loop پویا مثل دایرکتوری نمایش داده می‌شود ایده‌آل است. Sync with query به نقشه امکان می‌دهد با query به‌صورت زنده هنگام تعامل کاربران از طریق AJAX Pagination، Load More یا Query Filters به‌روز شود.

این حالت نیاز به افزودن المان Map Connector داخل target query loop دارد.

همچنین از Info Box های سفارشی با استفاده از popup template پشتیبانی می‌کند.

مثال: می‌خواهید یک query loop را در همان صفحه نقشه نمایش دهید و هر دو را به هم متصل کنید. اگر این query loop از AJAX Pagination، Query Filters یا Load More استفاده کند، فعال‌سازی Sync with query به نشانگرهای نقشه امکان می‌دهد به‌صورت real-time با تعامل کاربران به‌روز شوند.

نشانگرهای نقشه بر اساس نتایج query به‌روز می‌شوند:

نشانگرها (Markers)

Cluster markers

این گزینه را فعال کنید تا نشانگرهای نزدیک به هم به‌طور خودکار در یک cluster گروه‌بندی شوند. (@since 2.0)

تنظیمات عمومی

Map ID

Google Maps ID خود را (موجود در Google Cloud Console) برای فعال‌سازی آخرین ویژگی‌های Maps وارد کنید. (@since 2.0)

وقتی تنظیم شود:

  • Bricks از Google API مدرن AdvancedMarker استفاده می‌کند.
  • استایل‌های نقشه از طریق Google Console مدیریت می‌شوند (تنظیمات استایل در Bricks غیرفعال می‌شوند).
  • هشدارهای deprecated در console مرورگر از بین می‌روند.

Map Center

نقطه مرکز پیش‌فرض نقشه را تنظیم کنید. مخصوصاً وقتی از Sync with query استفاده می‌کنید مفید است — اگر query همگام‌شده نتیجه‌ای برنگرداند، نقشه به این نقطه مرکز بازنشانی می‌شود. (@since 2.0)

سایر تنظیمات (Others)

Map Connector (element)

المان Map Connector (@since 2.0) هنگام استفاده از Sync with query الزامی‌است.

آن را داخل target query loop که می‌خواهید با نقشه sync کنید قرار دهید. یک node <template> نامرئی حاوی داده مکان تولید می‌کند که نقشه آن را برای رندر پویای نشانگرها می‌خواند.

نکته: به‌شدت توصیه می‌شود وقتی مقادیر latitude و longitude در دسترس هستند آن‌ها را ارائه دهید. اگر فقط به آدرس‌ها متکی باشید و هر بار نشانگرها رندر می‌شوند geocoding لازم باشد، ممکن است از Google Maps Platform Geocoding API هزینه دریافت شود.

همچنین می‌توانید Info Box (popup template) که هنگام کلیک روی نشانگر نمایش داده می‌شود تعریف کنید. مطمئن شوید popup template انتخاب‌شده گزینه «Info Box (Map)» را در تنظیماتش فعال دارد.

Info Box (Popup template)

در نسخه 2.0 معرفی شد. گزینه Info Box (Map) در تنظیمات Popup template در دسترس است.

  • پس از فعال‌سازی، popup با عرض پیش‌فرض 300px در سازنده نمایش داده می‌شود و backdrop را برای preview حذف می‌کند.
  • می‌توانید طراحی Info Box را در سازنده سفارشی کنید.
  • از Fetch content via AJAX پشتیبانی می‌کند.
  • هنگام بارگذاری پویا از انیمیشن AJAX loader پشتیبانی می‌کند.
  • توصیه می‌شود Populate Content را روی پست یا term در حال loop تنظیم کنید تا داده پویا در سازنده به درستی نمایش داده شود.

تعاملات نقشه

در Bricks 2.0 دو اکشن تعامل نقشه معرفی شده:

  • Open address (Map) — باز کردن آدرس
  • Close address (Map) — بستن آدرس

موارد استفاده:

  • از یک دکمه یا المان داخل query loop برای باز کردن Info Box نشانگر مربوطه استفاده کنید.
  • یک آیکون بستن داخل Info Box popup اضافه کنید تا کاربران بتوانند آن را دستی ببندند.

این تعاملات کنترل و انعطاف بیشتری بر نحوه رفتار Info Box ها در سناریوهای نقشه‌پردازی پویا می‌دهند.

رفع تداخل اسکریپت Google Maps با افزونه‌های دیگر

اگر از افزونه‌ای مانند Fluent Form استفاده می‌کنید که ممکن است اسکریپت Google Maps را در همان صفحه enqueue کند، می‌تواند منجر به تداخل JavaScript شود چون اسکریپت نمی‌تواند دوبار بارگذاری شود.

برای جلوگیری از این مشکل می‌توانید اسکریپت Google Maps بریکس را dequeue کنید و تابع bricksMap() را پس از یک تأخیر کوتاه به‌صورت دستی فراخوانی کنید تا اطمینان حاصل شود اسکریپت نقشه Fluent Forms اول بارگذاری شده:

add_action( 'wp_enqueue_scripts', function() {
  if ( is_page( 1567 ) ) {
    wp_deregister_script( 'bricks-google-maps' );
  }
}, 999 );

add_action( 'wp_footer', function() {
  if ( is_page( 1567 ) ) {
    echo '<script>
      document.addEventListener("DOMContentLoaded", function() {
        setTimeout(function() {
          bricksMap();
        }, 1000); // Adjust delay if needed
      });
    </script>';
  }
}, 999 );

1567 را با ID صفحه واقعی خود جایگزین کنید. تأخیر را به‌گونه‌ای تنظیم کنید که اسکریپت نقشه Fluent Forms قبل از اجرای bricksMap() کاملاً بارگذاری شده باشد.

تنظیمات

Addresses

  • Addresses (repeater) — مکان‌های نقشه را اضافه کنید. هر آدرس شامل:
  • Latitude (text) — مختصات latitude. Placeholder: 52.5164154966524.
  • Longitude (text) — مختصات longitude. Placeholder: 13.377643715349544.
  • Address (text) — آدرس برای geocoding (جایگزین مختصات). Placeholder: Berlin, Germany.
  • Info Box template (select) — قالب برای popup infobox.
  • Title (text) — عنوان infobox.
  • Subtitle (text) — زیرعنوان infobox.
  • Content (textarea) — محتوای infobox.
  • Images (image-gallery) — تصاویر برای infobox.
  • Width (number) — عرض infobox. Placeholder: 300.
  • Label (text) — برچسب screen reader برای دسترسی‌پذیری.
  • Marker: Text (text) — محتوای نشانگر متنی. Placeholder: Marker.
  • Marker: Text (Active) (text) — محتوای نشانگر متنی فعال. Placeholder: Marker.
  • Marker: Image (image) — نشانگر تصویری.
  • Marker: Image (Active) (image) — نشانگر تصویری فعال.

Query loop

  • Has loop (checkbox) — query loop برای آدرس‌های پویا را فعال کنید.
  • Query (query) — پیکربندی کنید کدام پست‌ها نمایش داده شوند.
  • Info Box: Template (select) — قالب popup infobox در query loop.

Sync with query

  • Sync with query (query-list) — به query loop موجود برای نشانگرهای پویا متصل شوید.
  • Text: No results (text) — پیام وقتی مکانی پیدا نشد. Placeholder: No locations found.

نشانگرها (Markers)

  • Cluster: Markers (checkbox) — clustering نشانگر را فعال کنید.
  • Cluster: Background color (color) — رنگ پس‌زمینه cluster.

  • Cluster: Text color (color) — رنگ متن cluster.

  • Marker (separator) — تنظیمات global نشانگر.

  • Type (select) — نوع نشانگر. گزینه‌ها: image، text. پیش‌فرض: image.

Marker: Text

  • Max. width (number with units) — حداکثر عرض نشانگر متنی.
  • Typography (typography) — تنظیمات فونت نشانگر متنی.
  • Background color (color) — پس‌زمینه نشانگر متنی.
  • Border (border) — استایل border نشانگر متنی.
  • Box shadow (box-shadow) — سایه نشانگر متنی.
  • Padding (spacing) — padding نشانگر متنی.

Marker: Text (Active)

  • Typography (typography) — تنظیمات فونت نشانگر متنی فعال.
  • Background color (color) — پس‌زمینه نشانگر متنی فعال.
  • Border (border) — استایل border نشانگر متنی فعال.
  • Box shadow (box-shadow) — سایه نشانگر متنی فعال.
  • Padding (spacing) — padding نشانگر متنی فعال.

Marker: Image

  • Marker (image) — تصویر نشانگر پیش‌فرض.
  • Height (number) — ارتفاع نشانگر به پیکسل. Placeholder: 40.
  • Width (number) — عرض نشانگر به پیکسل. Placeholder: 40.
  • Border (border) — استایل border نشانگر.
  • Box shadow (box-shadow) — سایه نشانگر.

Marker: Image (Active)

  • Marker (Active) (image) — تصویر نشانگر فعال.
  • Height (number) — ارتفاع نشانگر فعال به پیکسل. Placeholder: 40.
  • Width (number) — عرض نشانگر فعال به پیکسل. Placeholder: 40.
  • Border (border) — استایل border نشانگر فعال.
  • Box shadow (box-shadow) — سایه نشانگر فعال.

نقشه (Map)

  • Map ID (text) — Google Maps ID از Cloud Console برای ویژگی‌های پیشرفته.

مرکز نقشه (Map center)

  • Latitude (Center) (text) — latitude مرکز نقشه. Placeholder: 52.5164154966524.
  • Longitude (Center) (text) — longitude مرکز نقشه. Placeholder: 13.377643715349544.
  • Address (Center) (text) — آدرس مرکز نقشه. Placeholder: Berlin, Germany.

تنظیمات عمومی (General settings)

  • Height (number with units) — ارتفاع container نقشه. Placeholder: 300px.
  • Zoom level (number) — سطح زوم اولیه. محدوده: 0-20. Placeholder: 12.
  • Map type (select) — سبک نقشه. گزینه‌ها: roadmap، satellite، hybrid، terrain. پیش‌فرض: roadmap.
  • Map style (select) — استایل‌های از پیش تعریف‌شده. نیاز به نوع roadmap دارد.
  • Custom map style (code) — کد JSON برای استایل‌دهی سفارشی از Snazzy Maps.
  • Apply: Custom map style (apply) — تغییرات استایل سفارشی را اعمال کنید.
  • Fit map on markers change (checkbox) — تنظیم خودکار نمایش هنگام تغییر نشانگرها.
  • Scroll (checkbox) — زوم با چرخ اسکرول. پیش‌فرض: true.
  • Draggable (checkbox) — امکان drag کردن نقشه. پیش‌فرض: true.
  • Fullscreen Control (checkbox) — نمایش دکمه تمام‌صفحه.
  • Map Type Control (checkbox) — نمایش انتخابگر نوع نقشه.
  • Street View Control (checkbox) — نمایش دکمه Street View. پیش‌فرض: true.
  • Disable Default UI (checkbox) — مخفی کردن همه کنترل‌های پیش‌فرض.
  • Disable clickable POI (checkbox) — غیرفعال کردن کلیک روی نقاط مورد علاقه.
  • Zoom Control (checkbox) — نمایش کنترل‌های زوم. پیش‌فرض: true.
  • Zoom level (Min) (number) — حداقل سطح زوم.
  • Zoom level (Max) (number) — حداکثر سطح زوم.

حالت بدون کلید API (No API Key Mode)

وقتی کلید Google Maps API پیکربندی نشده، المان به Google Maps Embed API با قابلیت محدود fallback می‌کند:

  • Address (text) — آدرس تکی برای نقشه embed. Placeholder: Berlin, Germany.
  • Loading (select) — رفتار بارگذاری. گزینه‌ها: eager، lazy. پیش‌فرض: lazy.

مرجع توسعه‌دهنده

برای JSON schema کامل به Map (Google) Schema مراجعه کنید.