الفرق بين المراجعتين ل"Cordova/cordova plugin geolocation"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
سطر 1: سطر 1:
 
<noinclude>{{DISPLAYTITLE:إضافة تحديد الموقع الجغرافي في كوردوفا}}</noinclude>
 
<noinclude>{{DISPLAYTITLE:إضافة تحديد الموقع الجغرافي في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
+
[[تصنيف: Cordova]]
 
[[تصنيف: Plugin]]
 
[[تصنيف: Plugin]]
 
[[تصنيف: cordova-plugin-geolocation]]
 
[[تصنيف: cordova-plugin-geolocation]]
سطر 23: سطر 23:
 
==التثبيت==  
 
==التثبيت==  
  
تتطلب إضافة تحديد الموقع الجغرافي كوردوفا 5.0 أوما بعدها (الإصدار المستقر الحالي 1.0.0)  
+
تتطلب إضافة تحديد الموقع الجغرافي الإصدارَ كوردوفا 5.0 أوما بعده (الإصدار المستقر الحالي 1.0.0)  
 
<syntaxhighlight lang="javascript">cordova plugin add cordova-plugin-geolocation‎</syntaxhighlight>  
 
<syntaxhighlight lang="javascript">cordova plugin add cordova-plugin-geolocation‎</syntaxhighlight>  
  
سطر 37: سطر 37:
 
*ويندوز  
 
*ويندوز  
  
== التوابع ==  
+
== التوابع ==
* navigator.geolocation.getCurrentPosition  
+
===<code>navigator.geolocation.getCurrentPosition</code>===
* navigator.geolocation.watchPosition
 
* navigator.geolocation.clearWatch
 
  
== الكائنات (للقراءة فقط) ==
+
يُعيد هذا التابع الموضع الحالي للجهاز ويمرّره إلى دالة الاستجابة (callback) ‏<code>geolocationSuccess</code> ، مع تمرير الكائن <code>Position</code> كمعامل. إذا كان هناك خطأ، فسيُمرّر الكائن <code>PositionError</code> إلى دالة الاستجابة <code>geolocationError</code>.  
*Position
 
* PositionError
 
*Coordinates
 
 
 
==navigator.geolocation.getCurrentPosition==
 
 
 
يُعيد هذا التابع الموضع الحالي للجهاز إلى دالة الاستجابة (callback) ‏<code>geolocationSuccess</code> مع تمرير الكائن <code>Position</code> كمعامل. إذا كان هناك خطأ، فسيُمرّر لدالة الاستجابة <code>geolocationError</code> الكائن <code>PositionError</code>.  
 
 
<syntaxhighlight lang="javascript">navigator.geolocation.getCurrentPosition(geolocationSuccess,
 
<syntaxhighlight lang="javascript">navigator.geolocation.getCurrentPosition(geolocationSuccess,
 
                                         [geolocationError],
 
                                         [geolocationError],
 
                                         [geolocationOptions]);‎</syntaxhighlight>  
 
                                         [geolocationOptions]);‎</syntaxhighlight>  
===الوسائط===  
+
====المعاملات====  
* '''geolocationSuccess''': دالة الاستجابة (callback) التي سيُمرّر إليها الموضع الحالي.  
+
* <code>geolocationSuccess</code>: دالة الاستجابة (callback) التي سيُمرّر إليها الموقع الحالي.  
* '''geolocationError''': (اختياري) دالة الاستجابة التي ستُنفذ في حالة حدوث خطأ.  
+
* <code>geolocationError</code>: (اختياري) دالة الاستجابة التي ستُنفذ في حالة حدوث خطأ.  
* '''geolocationOptions''': (اختياري) خيارات تحديد الموقع الجغرافي.  
+
* <code>geolocationOptions</code>: (اختياري) خيارات تحديد الموقع الجغرافي.  
=== مثال ===  
+
==== مثال ====  
<syntaxhighlight lang="javascript">// onSuccess Callback
+
<syntaxhighlight lang="javascript">// onSuccess دالة الاستجابة للحدث
     // This method accepts a Position object, which contains the
+
     // والذي يحتوي Position يقبل هذا التابع الكائن
     // current GPS coordinates
+
     // الحالية GPS إحداثيات
 
     //
 
     //
 
     var onSuccess = function(position) {
 
     var onSuccess = function(position) {
سطر 72: سطر 63:
 
               'Timestamp: '        + position.timestamp                + '\n');
 
               'Timestamp: '        + position.timestamp                + '\n');
 
     };
 
     };
     // onError Callback receives a PositionError object
+
     // PositionError الكائن onError تتلقى دالة الاستجابة للحدث
 
     //
 
     //
 
     function onError(error) {
 
     function onError(error) {
سطر 79: سطر 70:
 
     }
 
     }
 
     navigator.geolocation.getCurrentPosition(onSuccess, onError);‎</syntaxhighlight>  
 
     navigator.geolocation.getCurrentPosition(onSuccess, onError);‎</syntaxhighlight>  
== ملاحظات خاصة بمنصة iOS ==  
+
==== ملاحظات خاصة بمنصة iOS ====  
  
منذ الإصدار iOS 10، صار من الإلزامي تقديم وصف للاستخدام في الملف <code>info.plist</code> إن كنت تريد الوصول إلى بيانات حساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن إذا لم توفر وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. وأيضًا، سترفض Apple التطبيقات التي تصل إلى البيانات الخاصة دون أن تقدم وصفًا للاستخدام.  
+
منذ الإصدار iOS 10، صار من الإلزامي تقديم وصف للاستخدام في الملف <code>info.plist</code> إن كنت تريد الوصول إلى البيانات الحساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن في حال عدم توفير وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. كما سترفض Apple التطبيقات التي تحاول الوصول إلى البيانات الخاصة دون تقديم وصفٍ للاستخدام.  
  
 
تتطلب هذه الإضافات أوصاف الاستخدام التالية:  
 
تتطلب هذه الإضافات أوصاف الاستخدام التالية:  
* <code>NSLocationWhenInUseUsageDescription</code> تصف سبب وصول التطبيق إلى موقع المستخدم.  
+
* <code>NSLocationWhenInUseUsageDescription</code>: تحدد سبب سعي التطبيق للوصول إلى موقع المستخدم.  
  
لإضافة هذه المُدخلة إلى <code>info.plist</code>، يمكنك استخدام الوسم <code>edit-config</code> في الملف <code>config.xml</code> على النحو التالي:  
+
لإضافة هذه المُدخلة إلى <code>info.plist</code>، يمكنك استخدام الوسم <code>edit-config</code> في الملف <code>[[Cordova/config ref|config.xml]]</code> على النحو التالي:  
<syntaxhighlight lang="javascript"><edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
+
<syntaxhighlight lang="xml"><edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
 
     <string>need location access to find things nearby</string>
 
     <string>need location access to find things nearby</string>
 
</edit-config>‎</syntaxhighlight>  
 
</edit-config>‎</syntaxhighlight>  
===ملاحظات خاصة بمنصة أندرويد ===  
+
====ملاحظات خاصة بمنصة أندرويد ====  
  
إذا تم إيقاف تشغيل خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة <code>onError</code> بعد المدة الزمنية <code>timeout</code> (إذا تم تحديدها). في حال عدم تحديد المعامل <code>timeout</code>، فلن يتم استدعاء أي دالة استجابة.  
+
إذا تم إيقاف خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة <code>onError</code> بعد المدة الزمنية <code>timeout</code> (إذا تم تحديدها). وفي حال عدم تحديد المعامل <code>timeout</code>، فلن يتم استدعاء أي دالة استجابة.  
  
==navigator.geolocation.watchPosition==  
+
===<code>navigator.geolocation.watchPosition</code>===  
  
يُعيد هذا التابع الموضع الحالي للجهاز عند رصد أي تغيير في الموضع. عندما يتغير موقع الجهاز، يتم تنفيذ دالة الاستجابة <code>geolocationSuccess</code> مع تمرير الكائن <code>Position</code> إليها كمعامل. إن حدث خطأ، يتم تنفيذ دالة الاستجابة <code>geolocationError</code> مع تمرير الكائن <code>PositionError</code> كمعامل.  
+
يُعيد هذا التابع الموضع الحالي للجهاز عند رصد أي تغيير في الموضع. عندما يتغير موقع الجهاز، يتم تنفيذ دالة الاستجابة <code>geolocationSuccess</code> مع تمرير الكائن <code>Position</code> إليها كمعامل. إن حدث خطأ، تُنفّذ دالة الاستجابة <code>geolocationError</code> مع تمرير الكائن <code>PositionError</code> كمعامل.  
 
<syntaxhighlight lang="javascript">var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
 
<syntaxhighlight lang="javascript">var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
 
                                                   [geolocationError],
 
                                                   [geolocationError],
 
                                                   [geolocationOptions]);‎</syntaxhighlight>  
 
                                                   [geolocationOptions]);‎</syntaxhighlight>  
===الوسائط===  
+
====المعاملات====  
* '''geolocationSuccess''': دالة الاستجابة التي سيُمرّر إليها الموضع الحالي.  
+
* <code>geolocationSuccess</code>: دالة الاستجابة التي سيُمرّر إليها الموقع الحالي.  
* '''geolocationError''': (اختياري) دالة الاستجابة التي ستُنفذ عند حدوث خطأ.  
+
* <code>geolocationError</code>: (اختياري) دالة الاستجابة التي ستُنفذ عند حدوث خطأ.  
* '''geolocationOptions''': (اختياري) خيارات تحديد الموقع الجغرافي.  
+
* <code>geolocationOptions</code>: (اختياري) خيارات تحديد الموقع الجغرافي.  
=== القيمة المعادة ===  
+
==== القيمة المعادة ====
* '''String''': يعاد معرف المراقبة (watch id)، الذي يشير إلى لمجال مراقبة الموضع (watch position interval). يجب استخدام مٌعرّف المراقبة مع <code>navigator.geolocation.clearWatch</code> لإيقاف مراقبة التغييرات في الموضع.  
+
تُعاد سلسلة نصية تحتوي على معرفِ المراقبة (watch id)، الذي يحدد مجال مراقبة الموقع (watch position interval). يجب استخدام مٌعرّف المراقبة مع التابع <code>navigator.geolocation.clearWatch</code> لإيقاف مراقبة تغييرات الموقع الجغرافي.
 +
 
 
=== مثال ===  
 
=== مثال ===  
<syntaxhighlight lang="javascript">// onSuccess Callback
+
<syntaxhighlight lang="javascript">// onSuccess دالة الاستجابة للنجاح
     //   This method accepts a `Position` object, which contains
+
     //والذي يحتوي على Position يقبل هذا التابع كائنا
     //   the current GPS coordinates
+
     // الحالية GPS احداثيات
 
     //
 
     //
 
     function onSuccess(position) {
 
     function onSuccess(position) {
سطر 117: سطر 109:
 
                             '<hr />'      + element.innerHTML;
 
                             '<hr />'      + element.innerHTML;
 
     }
 
     }
     // onError Callback receives a PositionError object
+
     // PositionError  كائنا onError تتلقى دالة الاستجابة للخطأ
 
     //
 
     //
 
     function onError(error) {
 
     function onError(error) {
سطر 123: سطر 115:
 
               'message: ' + error.message + '\n');
 
               'message: ' + error.message + '\n');
 
     }
 
     }
     // Options: throw an error if no update is received every 30 seconds.
+
     // خيارات: إن لم يحدث أي تحديث خلال 30 ثانية، فسيُطلق خطأ
    //
 
 
     var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });‎</syntaxhighlight>  
 
     var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });‎</syntaxhighlight>  
  
==geolocationOptions==  
+
====<code>geolocationOptions</code>====  
  
معاملات اختيارية تُستخدم لتخصيص عملية تحصيل معلومات الموقع الجغرافي <code>Position</code>.  
+
معاملات اختيارية تُستخدم لتخصيص عملية تحصيل معلومات الموقع الجغرافي من الكائن <code>Position</code>.  
 
<syntaxhighlight lang="javascript">{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };‎</syntaxhighlight>  
 
<syntaxhighlight lang="javascript">{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };‎</syntaxhighlight>  
===خيارات===  
+
=====الخيارات=====  
* '''enableHighAccuracy''': يلمح إلى أنّ التطبيق يحتاج إلى الحصول على أدق النتائج الممكنة. بشكل افتراضي، يحاول الجهاز تحصيل <code>Position</code> باستخدام أساليب تستند إلى الشبكة. إن ضبط هذه الخاصية عند القيمة <code>true</code> يخبر إطار العمل بضرورة استخدام أساليب أكثر دقة، مثل تحديد الموقع عبر الأقمار الصناعية. (قيمة منطقية)  
+
* <code>enableHighAccuracy</code>: يُستخدم هذا الخيار عندما يحتاج التطبيق إلى الحصول على أدق النتائج الممكنة. بشكل افتراضي، يحاول الجهاز تحصيل معلومات الموقع الجغرافي (<code>Position</code>) باستخدام أساليب تستند إلى الشبكة. إنّ ضبط هذه الخاصية عند القيمة <code>true</code> يُخطِر إطار العمل بضرورة استخدام أساليب أكثر دقة، مثل تحديد الموقع عبر الأقمار الصناعية. (قيمة منطقية)  
* '''timeout''': االفترة الزمنية القصوى (بالميليثانية) المسموح به بمرورها منذ استدعاء <code>navigator.geolocation.getCurrentPosition</code> أو <code>geolocation.watchPosition</code> وحتى تنفيذ دالة الاستجابة المقابلة <code>geolocationSuccess</code>. إذا لم يتم استدعاء دالة الاستجابة <code>geolocationSuccess</code> خلال هذا الوقت، فسيُمرّر إلى دالة الاستجابة <code>geolocationError</code> كود الخطأ <code>PositionError.TIMEOUT</code>. (لاحظ أنه عند استخدامها مع <code>geolocation.watchPosition</code>، يمكن استدعاء دالة الاستجابة <code>geolocationError</code> على فواصل زمنية كل <code>timeout</code> ميليثانية) (عدد)  
+
* <code>timeout</code>: االفترة الزمنية القصوى (بالميليثانية) المسموح بمرورها منذ لحظة استدعاء التابع <code>navigator.geolocation.getCurrentPosition</code> أو <code>geolocation.watchPosition</code> وحتى تنفيذ دالة الاستجابة المقابلة <code>geolocationSuccess</code>. إذا لم يتم استدعاء دالة الاستجابة <code>geolocationSuccess</code> خلال هذا الوقت، فسيُمرّر إلى دالة الخطأ <code>geolocationError</code> كود الخطأ <code>PositionError.TIMEOUT</code>. (لاحظ أنّه عند استخدامها مع التابع <code>geolocation.watchPosition</code>، يمكن استدعاء دالة الخطأ <code>geolocationError</code> بشكل متكررٍ كل <code>timeout</code> ميليثانية) (عدد)  
* '''maximumAge''': يقبل موضع مخزنا مؤقتًا (cached position)، والذي لا يزيد عمره عن الوقت المحدد بالميليثانية. (عدد)  
+
* <code>maximumAge</code>: يقبل موقعًا مخزّنا مؤقتًا (cached position)، شرط ألا يزيد عمره عن الوقت المحدد بالميليثانية. (عدد)  
===ملاحظات خاصة بمنصة أندرويد ===  
+
====ملاحظات خاصة بمنصة أندرويد ====  
  
في حال إيقاف خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة <code>onError</code> بعد الفاصل الزمني <code>timeout</code> (في حال تحديده). إذا لم يتم تحديد المعامل <code>timeout</code>، فلن يتم استدعاء أي دالة استجابة.  
+
في حال إيقاف خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة <code>onError</code> بعد الفاصل الزمني <code>timeout</code> في حال تحديده. أما في حال عدم تحديده، فلن يتم استدعاء أي دالة استجابة.  
  
==navigator.geolocation.clearWatch==  
+
===<code>navigator.geolocation.clearWatch</code>===  
  
يوقف هذا التابع عملية مراقبة التغييرات في موقع الجهاز، والمشار إليه من قبل المعامل <code>watchID</code>.  
+
يوقف هذا التابع عملية مراقبة التغييرات في موقع الجهاز، والمشار إليها من قبل المعامل <code>watchID</code>.  
 
<syntaxhighlight lang="javascript">navigator.geolocation.clearWatch(watchID);‎</syntaxhighlight>  
 
<syntaxhighlight lang="javascript">navigator.geolocation.clearWatch(watchID);‎</syntaxhighlight>  
===المعاملات===  
+
====المعاملات====  
* '''watchID''': مُعرِّف الفاصل الزمني للتابع <code>watchPosition</code> الذي يُراد حذفه. (سلسلة نصية)  
+
* <code>watchID</code>: مُعرِّف المجال <code>watchPosition</code> المُراد حذفه. (سلسلة نصية)  
=== مثال ===  
+
==== مثال ====  
<syntaxhighlight lang="javascript">// Options: watch for changes in position, and use the most
+
<syntaxhighlight lang="javascript">   // خيارات: مراقبة التغيرات في الموقع الجغرافي، مع استخدام أدق وسائل تحديد الموقع
     // accurate position acquisition method available.
+
     // المُمكنة
 
     //
 
     //
 
     var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });
 
     var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });
     // ...later on...
+
     // ...في وقت لاحق...
     navigator.geolocation.clearWatch(watchID);‎</syntaxhighlight>  
+
     navigator.geolocation.clearWatch(watchID);‎</syntaxhighlight>
 +
 
 +
== الكائنات (للقراءة فقط) ==
  
==Position==  
+
===<code>Position</code>===  
  
يحتوي هذا الكائن على إحداثيات <code>Position</code> وطابعه الزمني، يتم أنشاؤه من قبل الواجهة البرمجية للإضافة.  
+
يحتوي الكائن <code>Position</code> على إحداثيات الموقع الجغرافي وختمه الزمني (timestamp)، يتم انشاؤه من قبل الواجهة البرمجية للإضافة.  
=== خاصيات ===  
+
==== خاصيات ====  
* '''coords''': مجموعة من الإحداثيات الجغرافية. (احداثيات)  
+
* <code>coords</code>: مجموعة من الإحداثيات الجغرافية. (احداثيات)  
* '''timestamp''': الطابع الزمني للإنشاء الخاص بالكائن <code>coords</code>. (DOMTimeStamp)  
+
* <code>timestamp</code>: الختم الزمني الذي يحدد توقيت تسجيل الإحداثيات <code>coords</code>. (<code>DOMTimeStamp</code>)  
  
==Coordinates==  
+
===<code>Coordinates</code>===  
  
تُربط الكائنات <code>Coordinates</code> بكائن <code>Position</code> متوفرٍ لدوال الاستجابة الخاصة بطلبيات الموضع الحالي. يحتوي على مجموعة من الخاصيات التي تصف الإحداثيات الجغرافية للموضع.  
+
يُربط الكائن <code>Coordinates</code> بكائنٍ <code>Position</code> متوفرٍ لدوال الاستجابة الخاصة بطلبيات (requests) الموقع الحالي. يحتوي هذا الكائن على مجموعة من الخاصيات التي تحدد الإحداثيات الجغرافية لموقعٍ ما.  
=== خاصيات ===  
+
==== خاصيات ====  
 
* '''latitude''': خط العرض بالدرجات العشرية. (عدد)  
 
* '''latitude''': خط العرض بالدرجات العشرية. (عدد)  
 
* '''longitude''': خط الطول بالدرجات العشرية. (عدد)  
 
* '''longitude''': خط الطول بالدرجات العشرية. (عدد)  

مراجعة 14:02، 17 ديسمبر 2018

توفر هذه الإضافة معلومات حول الموقع الجغرافي للجهاز، مثل خط العرض وخط الطول.

من الطرق الشائعة لتحديد معلومات الموقع الجغرافي، نجد: نظام تحديد المواقع العالمي (GPS)، واستنتاج الموقع من إشارات الشبكة، مثل عنوان IP، وعناوين تحديد الهوية بموجات الراديو (RFID)، واللاسلكي (WiFi)، وعناوين MAC Bluetooth، ومُعرِّفات الخلية GSM/CDMA.

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

تأسست الواجهة البرمجية لهذه الإضافة على مواصفات الواجهة البرمجية لتحديد المواقع الجغرافية من W3C ، ولا تُنفّذ إلا على الأجهزة التي لا توفر تقديما (implementation) جاهزًا سلفًا.

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

تعرّف هذه الإضافة كائنًا عامًّا navigator.geolocation (في المنصات التي لا يكون مُعرّفا فيها).

على الرغم من أن هذا الكائن موجود في النطاق العام (global scope)، إلا أن الميزات التي يوفرها لن تكون متاحة إلا بعد إطلاق الحدث deviceready.

document.addEventListener("deviceready", onDeviceReady, false);
    function onDeviceReady() {
        console.log("navigator.geolocation works well");
    }

التثبيت

تتطلب إضافة تحديد الموقع الجغرافي الإصدارَ كوردوفا 5.0 أوما بعده (الإصدار المستقر الحالي 1.0.0)

cordova plugin add cordova-plugin-geolocation

لا يزال بإمكان الإصدارات القديمة من كوردوفا تثبيت هذه الإضافة عبر المُعرِّف المُتجاوز (الإصدار المستقر 0.3.12)

cordova plugin add org.apache.cordova.geolocation

من الممكن أيضًا تثبيت هذه الإضافة عبر عنوان مستودع git مباشرة (إلا أنه غير مستقر)

cordova plugin add https://github.com/apache/cordova-plugin-geolocation.git‎

المنصات المدعومة

  • أندرويد
  • iOS
  • ويندوز

التوابع

navigator.geolocation.getCurrentPosition

يُعيد هذا التابع الموضع الحالي للجهاز ويمرّره إلى دالة الاستجابة (callback) ‏geolocationSuccess ، مع تمرير الكائن Position كمعامل. إذا كان هناك خطأ، فسيُمرّر الكائن PositionError إلى دالة الاستجابة geolocationError.

navigator.geolocation.getCurrentPosition(geolocationSuccess,
                                         [geolocationError],
                                         [geolocationOptions]);

المعاملات

  • geolocationSuccess: دالة الاستجابة (callback) التي سيُمرّر إليها الموقع الحالي.
  • geolocationError: (اختياري) دالة الاستجابة التي ستُنفذ في حالة حدوث خطأ.
  • geolocationOptions: (اختياري) خيارات تحديد الموقع الجغرافي.

مثال

// onSuccess دالة الاستجابة للحدث
    // والذي يحتوي Position  يقبل هذا التابع الكائن
    // الحالية GPS  إحداثيات
    //
    var onSuccess = function(position) {
        alert('Latitude: '          + position.coords.latitude          + '\n' +
              'Longitude: '         + position.coords.longitude         + '\n' +
              'Altitude: '          + position.coords.altitude          + '\n' +
              'Accuracy: '          + position.coords.accuracy          + '\n' +
              'Altitude Accuracy: ' + position.coords.altitudeAccuracy  + '\n' +
              'Heading: '           + position.coords.heading           + '\n' +
              'Speed: '             + position.coords.speed             + '\n' +
              'Timestamp: '         + position.timestamp                + '\n');
    };
    // PositionError الكائن onError تتلقى دالة الاستجابة للحدث 
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }
    navigator.geolocation.getCurrentPosition(onSuccess, onError);

ملاحظات خاصة بمنصة iOS

منذ الإصدار iOS 10، صار من الإلزامي تقديم وصف للاستخدام في الملف info.plist إن كنت تريد الوصول إلى البيانات الحساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع حوار الاستئذان، ولكن في حال عدم توفير وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. كما سترفض Apple التطبيقات التي تحاول الوصول إلى البيانات الخاصة دون تقديم وصفٍ للاستخدام.

تتطلب هذه الإضافات أوصاف الاستخدام التالية:

  • NSLocationWhenInUseUsageDescription: تحدد سبب سعي التطبيق للوصول إلى موقع المستخدم.

لإضافة هذه المُدخلة إلى info.plist، يمكنك استخدام الوسم edit-config في الملف config.xml على النحو التالي:

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

ملاحظات خاصة بمنصة أندرويد

إذا تم إيقاف خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة onError بعد المدة الزمنية timeout (إذا تم تحديدها). وفي حال عدم تحديد المعامل timeout، فلن يتم استدعاء أي دالة استجابة.

navigator.geolocation.watchPosition

يُعيد هذا التابع الموضع الحالي للجهاز عند رصد أي تغيير في الموضع. عندما يتغير موقع الجهاز، يتم تنفيذ دالة الاستجابة geolocationSuccess مع تمرير الكائن Position إليها كمعامل. إن حدث خطأ، تُنفّذ دالة الاستجابة geolocationError مع تمرير الكائن PositionError كمعامل.

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

المعاملات

  • geolocationSuccess: دالة الاستجابة التي سيُمرّر إليها الموقع الحالي.
  • geolocationError: (اختياري) دالة الاستجابة التي ستُنفذ عند حدوث خطأ.
  • geolocationOptions: (اختياري) خيارات تحديد الموقع الجغرافي.

القيمة المعادة

تُعاد سلسلة نصية تحتوي على معرفِ المراقبة (watch id)، الذي يحدد مجال مراقبة الموقع (watch position interval). يجب استخدام مٌعرّف المراقبة مع التابع navigator.geolocation.clearWatch لإيقاف مراقبة تغييرات الموقع الجغرافي.

مثال

// onSuccess دالة الاستجابة للنجاح
    //والذي يحتوي على Position يقبل هذا التابع كائنا 
    // الحالية GPS احداثيات 
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                            'Longitude: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }
    // PositionError  كائنا onError تتلقى دالة الاستجابة للخطأ 
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }
    // خيارات: إن لم يحدث أي تحديث خلال 30 ثانية، فسيُطلق خطأ
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 });

geolocationOptions

معاملات اختيارية تُستخدم لتخصيص عملية تحصيل معلومات الموقع الجغرافي من الكائن Position.

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
الخيارات
  • enableHighAccuracy: يُستخدم هذا الخيار عندما يحتاج التطبيق إلى الحصول على أدق النتائج الممكنة. بشكل افتراضي، يحاول الجهاز تحصيل معلومات الموقع الجغرافي (Position) باستخدام أساليب تستند إلى الشبكة. إنّ ضبط هذه الخاصية عند القيمة true يُخطِر إطار العمل بضرورة استخدام أساليب أكثر دقة، مثل تحديد الموقع عبر الأقمار الصناعية. (قيمة منطقية)
  • timeout: االفترة الزمنية القصوى (بالميليثانية) المسموح بمرورها منذ لحظة استدعاء التابع navigator.geolocation.getCurrentPosition أو geolocation.watchPosition وحتى تنفيذ دالة الاستجابة المقابلة geolocationSuccess. إذا لم يتم استدعاء دالة الاستجابة geolocationSuccess خلال هذا الوقت، فسيُمرّر إلى دالة الخطأ geolocationError كود الخطأ PositionError.TIMEOUT. (لاحظ أنّه عند استخدامها مع التابع geolocation.watchPosition، يمكن استدعاء دالة الخطأ geolocationError بشكل متكررٍ كل timeout ميليثانية) (عدد)
  • maximumAge: يقبل موقعًا مخزّنا مؤقتًا (cached position)، شرط ألا يزيد عمره عن الوقت المحدد بالميليثانية. (عدد)

ملاحظات خاصة بمنصة أندرويد

في حال إيقاف خدمة تحديد الموقع الجغرافي، فستُستدعى دالة الاستجابة onError بعد الفاصل الزمني timeout في حال تحديده. أما في حال عدم تحديده، فلن يتم استدعاء أي دالة استجابة.

navigator.geolocation.clearWatch

يوقف هذا التابع عملية مراقبة التغييرات في موقع الجهاز، والمشار إليها من قبل المعامل watchID.

navigator.geolocation.clearWatch(watchID);

المعاملات

  • watchID: مُعرِّف المجال watchPosition المُراد حذفه. (سلسلة نصية)

مثال

    // خيارات: مراقبة التغيرات في الموقع الجغرافي، مع استخدام أدق وسائل تحديد الموقع 
    // المُمكنة 
    //
    var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true });
    // ...في وقت لاحق...
    navigator.geolocation.clearWatch(watchID);

الكائنات (للقراءة فقط)

Position

يحتوي الكائن Position على إحداثيات الموقع الجغرافي وختمه الزمني (timestamp)، يتم انشاؤه من قبل الواجهة البرمجية للإضافة.

خاصيات

  • coords: مجموعة من الإحداثيات الجغرافية. (احداثيات)
  • timestamp: الختم الزمني الذي يحدد توقيت تسجيل الإحداثيات coords. ‏(DOMTimeStamp)

Coordinates

يُربط الكائن Coordinates بكائنٍ Position متوفرٍ لدوال الاستجابة الخاصة بطلبيات (requests) الموقع الحالي. يحتوي هذا الكائن على مجموعة من الخاصيات التي تحدد الإحداثيات الجغرافية لموقعٍ ما.

خاصيات

  • latitude: خط العرض بالدرجات العشرية. (عدد)
  • longitude: خط الطول بالدرجات العشرية. (عدد)
  • altitude: ارتفاع الموقع بالأمتار فوق الإهليليج (ellipsoid). (عدد)
  • accuracy: مستوى الدقة لإحداثيات الطول والعرض بالأمتار. (عدد)
  • altitudeAccuracy: مستوى دقة إحداثيات الإرتفاع بالأمتار. (عدد)
  • heading: اتجاه السفر، محدد بعدد الدرجات في اتجاه عقارب الساعة نسبةً إلى الشمال الحقيقي. (عدد)
  • speed: السرعة الأرضية الحالية للجهاز، تُحدد بعدد الأمتار المقطوعة في الثانية. (عدد)

ملاحظات خاصة بمنصة أندرويد

altitudeAccuracy: غير مدعومة في أجهزة أندرويد، تعيد null.

PositionError

يُمرّر الكائن PositionError إلى دالة الاستجابة geolocationError عند حدوث خطأ في navigator.geolocation.

خاصيات

  • code: أحد رموز الخطأ المحددة مسبقًا المدرجة أدناه.
  • message: رسالة خطأ تصف تفاصيل الخطأ الذي وقع.

ثوابت

  • PositionError.PERMISSION_DENIED
  • تُعاد هذه الثابتة عندما يرفض المستخدمون السماح للتطبيق بالوصول إلى معلومات الموقع الجغرافي. يعتمد هذا على المنصة المُستخدمة.
  • PositionError.POSITION_UNAVAILABLE
  • تُعاد عندما يعجز الجهاز عن الحصول على الموقع الجغرافي. بشكل عام، هذا يعني أنّ الجهاز ليس متصلًا بأي بشبكة، أو لا يمكنه الوصول إلى القمر الصناعي.
  • PositionError.TIMEOUT
  • تُعاد عندما يتعذر على الجهاز الحصول الموقع الجغرافي خلال الوقت المحدد بواسطة timeout المتضمَّن في geolocationOptions. عند استخدامها مع التابع navigator.geolocation.watchPosition، يمكن تمرير هذا الخطأ مراراً وتكراراً إلى دالة الاستجابة geolocationError كل timeout ميليثانية.

عينة: الحصول على الطقس، والعثور على المتاجر، ومشاهدة الصور للأشياء القريبة مع تحديد الموقع الجغرافي

يمكن أن استخدام هذه الإضافة لمساعدة المستخدمين على العثور على المواقع أو الأحداث القريبة منهم، مثل عروض Grouponأ والمنازل المعروضة للبيعأ والأفلام المعروضة حاليًا، والأحداث الرياضية والترفيهية وغير ذلك.

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

  • [#coords Get your coordinates].
  • [#weather Get the weather forecast].
  • [#receive Receive updated weather forecasts as you drive around].
  • [#see See where you are on a map].
  • [#find Find stores near you].
  • [#see See pictures of things around you].

الحصول على إحداثيات موقعك الجغرافي

function getWeatherLocation() {
    navigator.geolocation.getCurrentPosition
    (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true });
}

الحصول على توقعات الطقس

// Success callback for get geo coordinates
var onWeatherSuccess = function (position) {
    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;
    getWeather(Latitude, Longitude);
}
// Get weather by using coordinates
function getWeather(latitude, longitude) {
    // Get a free key at http://openweathermap.org/. Replace the "Your_Key_Here" string with that key.
    var OpenWeatherAppKey = "Your_Key_Here";
    var queryString =
      'http://api.openweathermap.org/data/2.5/weather?lat='
      + latitude + '&lon=' + longitude + '&appid=' + OpenWeatherAppKey + '&units=imperial';
    $.getJSON(queryString, function (results) {
        if (results.weather.length) {
            $.getJSON(queryString, function (results) {
                if (results.weather.length) {
                    $('#description').text(results.name);
                    $('#temp').text(results.main.temp);
                    $('#wind').text(results.wind.speed);
                    $('#humidity').text(results.main.humidity);
                    $('#visibility').text(results.weather[0].main);
                    var sunriseDate = new Date(results.sys.sunrise);
                    $('#sunrise').text(sunriseDate.toLocaleTimeString());
                    var sunsetDate = new Date(results.sys.sunrise);
                    $('#sunset').text(sunsetDate.toLocaleTimeString());
                }
            });
        }
    }).fail(function () {
        console.log("error getting location");
    });
}
// Error callback
function onWeatherError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

تلقي تحديثات توقعات الطقس أثناء القيادة

// Watch your changing position
function watchWeatherPosition() {
    return navigator.geolocation.watchPosition
    (onWeatherWatchSuccess, onWeatherError, { enableHighAccuracy: true });
}
// Success callback for watching your changing position
var onWeatherWatchSuccess = function (position) {
    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;
    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
        Latitude = updatedLatitude;
        Longitude = updatedLongitude;
        // Calls function we defined earlier.
        getWeather(updatedLatitude, updatedLongitude);
    }
}

التعرف على موقعك على الخريطة

يُوفر كلٌّ من Bing و Google خدمات الخرائط. سنستخدم جوجل. ستحتاج إلى مفتاح، وهو مجاني إن كنت تحاول تجربة الخدمة.

قم بإضافة مرجع إلى الخدمة maps.

<script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script>‎

ثم أضف الشيفرة التالية لاستخدامها.

var Latitude = undefined;
var Longitude = undefined;
// Get geo coordinates
function getMapLocation() {
    navigator.geolocation.getCurrentPosition
    (onMapSuccess, onMapError, { enableHighAccuracy: true });
}
// Success callback for get geo coordinates
var onMapSuccess = function (position) {
    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;
    getMap(Latitude, Longitude);
}
// Get map by using coordinates
function getMap(latitude, longitude) {
    var mapOptions = {
        center: new google.maps.LatLng(0, 0),
        zoom: 1,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };
    map = new google.maps.Map
    (document.getElementById("map"), mapOptions);
    var latLong = new google.maps.LatLng(latitude, longitude);
    var marker = new google.maps.Marker({
        position: latLong
    });
    marker.setMap(map);
    map.setZoom(15);
    map.setCenter(marker.getPosition());
}
// Success callback for watching your changing position
var onMapWatchSuccess = function (position) {
    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;
    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
        Latitude = updatedLatitude;
        Longitude = updatedLongitude;
        getMap(updatedLatitude, updatedLongitude);
    }
}
// Error callback
function onMapError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}
// Watch your changing position
function watchMapPosition() {
    return navigator.geolocation.watchPosition
    (onMapWatchSuccess, onMapError, { enableHighAccuracy: true });
}

البحث عن متجر قريب

يمكنك استخدام نفس مفتاح جوجل لأجل هذا.

أضف مرجعًا إلى الخدمة places.

<script src=
"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places">
</script>‎

ثم أضف الشيفرة التالية لاستخدامها.

var Map;
var Infowindow;
var Latitude = undefined;
var Longitude = undefined;
// Get geo coordinates
function getPlacesLocation() {
    navigator.geolocation.getCurrentPosition
    (onPlacesSuccess, onPlacesError, { enableHighAccuracy: true });
}
// Success callback for get geo coordinates
var onPlacesSuccess = function (position) {
    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;
    getPlaces(Latitude, Longitude);
}
// Get places by using coordinates
function getPlaces(latitude, longitude) {
    var latLong = new google.maps.LatLng(latitude, longitude);
    var mapOptions = {
        center: new google.maps.LatLng(latitude, longitude),
        zoom: 15,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };
    Map = new google.maps.Map(document.getElementById("places"), mapOptions);
    Infowindow = new google.maps.InfoWindow();
    var service = new google.maps.places.PlacesService(Map);
    service.nearbySearch({
        location: latLong,
        radius: 500,
        type: ['store']
    }, foundStoresCallback);
}
// Success callback for watching your changing position
var onPlacesWatchSuccess = function (position) {
    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;
    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
        Latitude = updatedLatitude;
        Longitude = updatedLongitude;
        getPlaces(updatedLatitude, updatedLongitude);
    }
}
// Success callback for locating stores in the area
function foundStoresCallback(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
        for (var i = 0; i < results.length; i++) {
            createMarker(results[i]);
        }
    }
}
// Place a pin for each store on the map
function createMarker(place) {
    var placeLoc = place.geometry.location;
    var marker = new google.maps.Marker({
        map: Map,
        position: place.geometry.location
    });
    google.maps.event.addListener(marker, 'click', function () {
        Infowindow.setContent(place.name);
        Infowindow.open(Map, this);
    });
}
// Error callback
function onPlacesError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}
// Watch your changing position
function watchPlacesPosition() {
    return navigator.geolocation.watchPosition
    (onPlacesWatchSuccess, onPlacesError, { enableHighAccuracy: true });
}

مطالعة صور الأشياء المحيطة بك

يمكن أن تحتوي الصور الرقمية على إحداثيات جغرافية تحدد مكان التقاط الصورة.

استخدم الواجهة البرمجية لموقع Flickr للعثور على الصور التي التُقِطت بالقرب من مكان تواجدك. مثل خدمات جوجل، ستحتاج إلى مفتاح، ولكنه مجاني إن كنت ترغب في التجربة وحسب.

var Latitude = undefined;
var Longitude = undefined;
// Get geo coordinates
function getPicturesLocation() {
    navigator.geolocation.getCurrentPosition
    (onPicturesSuccess, onPicturesError, { enableHighAccuracy: true });
}
// Success callback for get geo coordinates
var onPicturesSuccess = function (position) {
    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;
    getPictures(Latitude, Longitude);
}
// Get pictures by using coordinates
function getPictures(latitude, longitude) {
    $('#pictures').empty();
    var queryString =
    "https://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=Your_API_Key&lat="
    + latitude + "&lon=" + longitude + "&format=json&jsoncallback=?";
    $.getJSON(queryString, function (results) {
        $.each(results.photos.photo, function (index, item) {
            var photoURL = "http://farm" + item.farm + ".static.flickr.com/" +
                item.server + "/" + item.id + "_" + item.secret + "_m.jpg";
            $('#pictures').append($("<img />").attr("src", photoURL));
           });
        }
    );
}
// Success callback for watching your changing position
var onPicturesWatchSuccess = function (position) {
    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;
    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {
        Latitude = updatedLatitude;
        Longitude = updatedLongitude;
        getPictures(updatedLatitude, updatedLongitude);
    }
}
// Error callback
function onPicturesError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}
// Watch your changing position
function watchPicturePosition() {
    return navigator.geolocation.watchPosition
    (onPicturesWatchSuccess, onPicturesError, { enableHighAccuracy: true });
}

مصادر