زر مشاركة الموقع الجغرافي في Android هو عنصر في واجهة مستخدم النظام قابل للتخصيص ومصمّم لتبسيط كيفية طلب الوصول إلى الموقع الجغرافي الدقيق على مستوى الجلسة. من خلال بدء طلبات الموقع الجغرافي من خلال إجراء مباشر من المستخدم، يحسّن الزر خصوصية المستخدم ويقلّل من المشاكل الناتجة عن مربّعات حوار الأذونات المتكرّرة التي تظهر عادةً عند منح أذونات مؤقتة "هذه المرة فقط".
إذا كان تطبيقك يستهدف الإصدار 17 من Android (مستوى واجهة برمجة التطبيقات 37) أو الإصدارات الأحدث ولا يحتوي إلا على ميزات تتطلّب الوصول إلى الموقع الجغرافي على مستوى الجلسة لكي تعمل، تفرض عليك سياسة Google Play استخدام زر مشاركة الموقع الجغرافي. لمزيد من التفاصيل، اطّلِع على سياسة زر مشاركة الموقع الجغرافي.
حالات استخدام زر مشاركة الموقع الجغرافي
استخدِم زر مشاركة الموقع الجغرافي للميزات التي تتطلّب الوصول إلى الموقع الجغرافي الدقيق على مستوى الجلسة لفترة قصيرة. ويكون هذا الزر مثاليًا للتطبيقات التي لا تتطلّب الوصول المستمر إلى الموقع الجغرافي وتهدف إلى تقليل طلبات منح الإذن المتكرّرة "هذه المرة فقط".
تشمل حالات الاستخدام الشائعة ما يلي:
- وظائف "البحث بالقرب مني": للعثور على فنادق أو متاجر أو مطاعم قريبة
- مشاركة الموقع الجغرافي: لمشاركة موقعك الجغرافي الحالي مرة واحدة مع الأصدقاء أو العائلة
- وسائل التواصل الاجتماعي: لتسجيل الحضور أو وضع علامة على الموقع الجغرافي
- التجارة الإلكترونية: للملء التلقائي لعنوان توصيل الطلبات
تخصيص واجهة المستخدم
لضمان تطابق الزر مع المظهر الجمالي لتطبيقك مع الحفاظ على سهولة التعرّف عليه، يمكنك تعديل العناصر المرئية التالية:
- نظام ألوان الخلفية والرمز
- شكل وحجم ومظهر الخطوط الخارجية
- التصنيفات النصية من قائمة محدّدة مسبقًا (مثل "استخدام الموقع الجغرافي الدقيق" أو "مشاركة الموقع الجغرافي الدقيق")
تنفيذ زر مشاركة الموقع الجغرافي
لدمج زر مشاركة الموقع الجغرافي، استخدِم مكتبة Jetpack. تسهّل هذه المكتبة عملية الإعداد، وتتعامل مع العرض الآمن على المنصات الأحدث، وتوفّر حلاً بديلاً للتطبيقات التي تستهدف الإصدار 16 من Android والإصدارات الأقدم.
الخطوة 1: الإعلان عن الأذونات في ملف AndroidManifest
يجب الإعلان عن أذونات الموقع الجغرافي العادية بالإضافة إلى إذن USE_LOCATION_BUTTON المخصّص الذي تتطلّبه خدمة العرض عن بُعد في النظام.
<?xml version="1.0" encoding="utf-8"?> <!-- Copyright 2026 The Android Open Source Project Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <manifest xmlns:android="http://schemas.android.com/apk/res/android"> <!-- 1. Standard Coarse and Fine Location Permissions --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <!-- Optional: If your app is only using the location button to access location, you should add the "onlyForLocationButton" flag shown below to your ACCESS_FINE_LOCATION declaration. <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:usesPermissionFlags="onlyForLocationButton"/> Note: Adding this flag restricts your app from accessing the precise location permission via the broader permission, and that users will be required to use the location button in order to share precise location with the app. This is designed to improve user privacy & trust when granting location access. --> <!-- 2. CRITICAL: Required system permission for rendering the LocationButton --> <uses-permission android:name="android.permission.USE_LOCATION_BUTTON" /> <application android:icon="@mipmap/ic_launcher" android:label="LocationButtonSample" android:theme="@style/Theme.PinPoint"> <activity android:name=".MainActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application> </manifest>
الخطوة 2: تنفيذ عنصر Kotlin القابل للإنشاء
في ما يلي مثال على تنفيذ زر مشاركة الموقع الجغرافي، بما في ذلك أمثلة على استخدام خيارات التخصيص المتاحة التي يمكن استخدامها لجعل واجهة المستخدم تتطابق مع بقية التطبيق.
import androidx.compose.foundation.layout.PaddingValues import androidx.compose.foundation.layout.height import androidx.compose.foundation.layout.width import androidx.compose.runtime.Composable import androidx.compose.ui.graphics.Color import androidx.compose.ui.unit.dp import androidx.core.locationbutton.compose.LocationButton import androidx.core.locationbutton.compose.LocationButtonTextType @Composable fun LocationPermissionScreen(onPermissionGranted: () -> Unit, onPermissionDenied: () -> Unit) { // Renders the secure system-trusted Location Button composable LocationButton( // Callback triggered when the user taps the secure button and makes a decision on the permission dialog onPermissionResult = { isGranted -> if (isGranted) { onPermissionGranted() } else { onPermissionDenied() } }, /* ============================================================================ * VISUAL CUSTOMIZATIONS * Un-comment any of the parameters below to customize the button's aesthetics. * If omitted, the button falls back to secure, high-contrast system defaults. * ============================================================================ */ /* // LABEL TEXT TYPE: // Predefined system strings rendered inside the secure process. // Options: PreciseLocation, UsePreciseLocation, SharePreciseLocation, // NearMyPreciseLocation, or None (for an icon-only button). textType = LocationButtonTextType.UsePreciseLocation, // COLOR PALETTE: // Customize the container background, text label, and icon tint colors. backgroundColor = Color(0xFF00796B), // e.g., Material Teal textColor = Color.White, iconTint = Color(0xFFFFC107), // e.g., Amber icon tint // CORNER RADIUS & SHAPE: // Define the resting corner radius and the morphed radius when pressed. cornerRadius = 24.dp, // Rounded capsule shape pressedCornerRadius = 12.dp, // Morphs to sharper corners on tap // OUTLINE STROKE (BORDERS): // Add a contrasting outline stroke around the button bounds. strokeColor = Color(0xFF004D40), strokeWidth = 2.dp, // INTERACTIVE TOUCH PADDING: // Defines the secure clickable touch target boundary. // Coerced securely by the system between 4.dp and 8.dp. clickablePadding = PaddingValues(6.dp) */ ) }
الخطوة 3: التعامل مع التوافق مع الإصدارات السابقة
تتعامل مكتبة Jetpack تلقائيًا مع التوافق مع الإصدارات السابقة على إصدارات Android الأقدم. على الأجهزة التي تعمل بالإصدار 16 من Android أو الإصدارات الأقدم، تعود المكتبة إلى مكوّن يتم عرضه محليًا ويحافظ على التصميم المرئي المخصّص، ولكن يعود إلى عرض طلب منح إذن تحديد الموقع الجغرافي العادي.
باستخدام هذا النهج، يمكنك الاستفادة من مزايا اعتماد زر مشاركة الموقع الجغرافي بدون الحفاظ على حلّ موازٍ للأجهزة التي تعمل بالإصدار 16 من Android أو الإصدارات الأقدم.