تفاصيل المكان

توفر حزمة تطوير برامج الأماكن لنظام التشغيل Android معلومات وافية لتطبيقك عن الأماكن، بما في ذلك اسم المكان وعنوانه والموقع الجغرافي الموقع المحدد كإحداثيات خطوط الطول/العرض، ونوع المكان (مثل كملهى ليلي ومتجر حيوانات أليفة ومتحف) وأكثر من ذلك. للوصول إلى هذه المعلومات مكان محدد، يمكنك استخدام معرّف المكان، وهو معرّف ثابت تحدد مكانًا.

تفاصيل المكان

تشير رسالة الأشكال البيانية Place يقدم معلومات حول مكان معين. يمكنك الحصول على Place بالطرق التالية:

• اتصل PlacesClient.fetchPlace() – اطّلِع على دليل الحصول على مكان حسب رقم التعريف
• اتصل PlacesClient.findCurrentPlace() – اطّلِع على دليل الحصول على المكان الحالي

عندما تطلب مكانًا، يجب تحديد بيانات المكان التي تريد عرضها. للقيام بذلك، مرر قائمة Place.Field قيمًا تحدد البيانات المراد إرجاعها. تُعد هذه القائمة من الاعتبارات المهمة لأنها تؤثر على والتكلفة لكل طلب.

بما أنّه لا يمكن ترك نتائج بيانات الأماكن فارغة، لا يتم حفظ سوى نتائج الأماكن التي تحتوي على بيانات. (على سبيل المثال، إذا لم يكن للمكان المطلوب أي صور، يتم عرض photos كل حقل موجود في النتيجة).

يجتاز المثال التالي قائمة من ثلاث قيم Place.Field لتحديد البيانات التي يعرضها الطلب:

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
  

الوصول إلى حقول بيانات عناصر "الأماكن"

بعد الحصول على الكائن Place، استخدِم طرق الكائن للوصول إلى حقول البيانات المحددة في الطلب. في حال عدم توفّر هذا الحقل في الكائن Place، فإن الطريقة ذات الصلة تُرجع قيمة خالية. في ما يلي أمثلة على بعض الطرق المتاحة. للحصول على قائمة كاملة بجميع الطرق، يمكنك الاطّلاع على Place مرجع واجهة برمجة التطبيقات.

• getAddress() – عنوان المكان، يمكن لشخص عادي قراءته .
• getAddressComponents() – A List مكونات العنوان لهذا المكان. يتم توفير هذه المكونات استخراج المعلومات المنظَّمة عن عنوان مكان معيّن مثال للعثور على المدينة التي يقع فيها المكان. عدم استخدام هذه ومكونات تنسيق العنوان؛ يُمْكِنُ الِاتِّصَالْ بِـ getAddress() بَدَلًا مِنْ ذَلِكْ. التي توفر عنوانًا منسقًا بما يتناسب مع السوق المحلية.
• getId() – المعرّف النصي للمكان. القراءة مزيد من المعلومات حول معرّفات الأماكن في باقي هذه الصفحة.
• getLatLng() – الموقع الجغرافي للمكان محددة كإحداثيات خطوط الطول والعرض.
• getName() – اسم المكان.

• getOpeningHours() – OpeningHours المكان. يمكنك الاتصال بالرقم OpeningHours.getWeekdayText() لإرجاع قائمة بالسلاسل التي تمثل ساعات الفتح والإغلاق لكل يوم من الأسبوع. يمكنك الاتصال بالرقم OpeningHours.getPeriods() لعرض قائمة period كائنات تحتوي على معلومات أكثر تفصيلاً يعادل البيانات المقدّمة من getWeekdayText().

  يحتوي الكائن Place أيضًا على السمة getCurrentOpeningHours() التي تعرض ساعات عمل المكان خلال الأيام السبعة المقبلة، getSecondaryOpeningHours() التي تعرض ساعات العمل الثانوية للمكان على مدار الأيام السبعة المقبلة.

• isOpen() – قيمة منطقية تشير إلى ما إذا كان المكان مفتوحة حاليًا. إذا لم يتم تحديد وقت، يكون الوقت التلقائي هو الآن. isOpen سيتم إرجاعها فقط في حال استخدام كل من Place.Field.UTC_OFFSET وتتوفر Place.Field.OPENING_HOURS. لضمان دقة النتائج، يمكنك طلب Place.Field.BUSINESS_STATUS حقلان (Place.Field.UTC_OFFSET) في طلب المكان الأصلي وإذا لم يُطلب منك ذلك، سيُفترض أنّ النشاط التجاري جاهز. يمكنك مشاهدة هذا الفيديو لمعرفة كيفية الاستخدام. isOpen مع تفاصيل المكان

في ما يلي بعض الأمثلة البسيطة:

val name = place.name
val address = place.address
val location = place.latLng

      

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

الحصول على مكان باستخدام رقم التعريف

رقم تعريف المكان هو معرّف نصي يُعرِّف المكان بشكل فريد. ضِمن حزمة تطوير برامج الأماكن لأجهزة Android، يمكنك استرداد معرّف المكان من خلال Place.getId() تشير رسالة الأشكال البيانية خدمة الإكمال التلقائي للأماكن معرّف مكان لكل مكان يطابق طلب البحث المقدم والتصفية. يمكنك تخزين معرّف المكان واستخدامه لاسترداد Place مرة أخرى لاحقًا.

للوصول إلى مكان باستخدام رقم التعريف، اتصل PlacesClient.fetchPlace()، اجتياز FetchPlaceRequest.

تعرض واجهة برمجة التطبيقات FetchPlaceResponse في Task تشير رسالة الأشكال البيانية FetchPlaceResponse يحتوي على Place يطابق رقم تعريف المكان الذي تم توفيره.

يوضّح مثال الرمز التالي طلب fetchPlace() إلى الحصول على تفاصيل عن المكان المحدد.

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

معرفة الحالة "مفتوح"

PlacesClient.isOpen(IsOpenRequest request) تؤدي إلى إرجاع كائن IsOpenResponse يشير إلى ما إذا كان المكان مفتوح حاليًا بناءً على الوقت المحدد في المكالمة.

تستخدم هذه الطريقة وسيطة واحدة من النوع IsOpenRequest تحتوي على:

• Place أو سلسلة تحدد معرف مكان.
• قيمة زمنية اختيارية تحدد الوقت بالمللي ثانية من 1970-01-01T00:00:00Z. إذا لم يتم تحديد وقت، يكون الوقت التلقائي هو الآن.

تتطلّب هذه الطريقة توفّر الحقول التالية في الكائن Place:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

في حال عدم توفير هذه الحقول في عنصر Place أو ضبط رقم تعريف مكان، عليك تستخدم الطريقة PlacesClient.fetchPlace() لجلبها. لمزيد من المعلومات حول إنشاء كائن المكان باستخدام الحقول اللازمة، راجِع تفاصيل المكان.

يحدد المثال التالي ما إذا كان المكان مفتوحًا حاليًا أم لا. في هذا المثال، أنت تجتاز فقط رقم تعريف المكان إلى isOpen():

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

يوضّح المثال التالي استدعاء isOpen() حيث تمرر عنصر Place. يجب أن يحتوي العنصر Place على رقم تعريف مكان صالح:

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

عرض عمليات تحديد المصدر في تطبيقك

عندما يعرض تطبيقك معلومات عن بعض الأماكن، بما في ذلك المراجعات المتعلقة بها، يجب أن يعرض التطبيق أيضًا معلومات عن الأماكن. أي مراجع. لمزيد من المعلومات، يُرجى مراجعة الإحالة.

مزيد من المعلومات عن أرقام تعريف الأماكن

رقم تعريف المكان المُستخدَم في حزمة تطوير برامج الأماكن لنظام التشغيل Android هو المعرّف نفسه. كما هي مُستخدَمة في Places API. يمكن أن يشير كلّ رقم تعريف مكان إلى مكان واحد فقط، ولكن يمكن أن يتضمّن مكان واحد أكثر. معرّف مكان واحد هناك ظروف أخرى قد تتسبب في الحصول على معرّف مكان جديد. على سبيل المثال، قد يحدث هذا إذا انتقل نشاط تجاري إلى غرفة الموقع.

عند طلب مكان من خلال تحديد معرّف مكان، يمكنك أن تكون واثقًا من أن ستتلقى دائمًا نفس المكان في الرد (إذا كان المكان لا يزال موجود). ومع ذلك، لاحظ أن الرد قد يحتوي على معرّف مكان مختلفة عن تلك المدرجة في طلبك.

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان.