الفرق بين المراجعتين لصفحة: «Cordova/cordova plugin media capture»

من موسوعة حسوب
لا ملخص تعديل
لا ملخص تعديل
سطر 4: سطر 4:
تمكّن إضافة الوصول إلى الوسائط المتعددة (<code>cordova-plugin-media-capture</code>) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز.
تمكّن إضافة الوصول إلى الوسائط المتعددة (<code>cordova-plugin-media-capture</code>) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز.


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


تعرّف هذه الإضافة كائنًا عامًّا <code>navigator.device.capture</code>. وعلى الرغم من أن هذا الكائن موجودٌ في النطاق العام (global scope)، إلا أنّه لن يكون متوفرًا إلا بعد إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code>. <syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
تعرّف هذه الإضافة كائنًا عامًّا <code>navigator.device.capture</code>. وعلى الرغم من أن هذا الكائن موجودٌ في النطاق العام (global scope)، إلا أنّه لن يكون متوفرًا إلا بعد إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code>. <syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
سطر 40: سطر 40:
* <code>supportedAudioModes</code>: تمثل هذه الخاصية تنسيقات (formats) التسجيل الصوتي التي يدعمها الجهاز. (<code>ConfigurationData[]‎</code>)  
* <code>supportedAudioModes</code>: تمثل هذه الخاصية تنسيقات (formats) التسجيل الصوتي التي يدعمها الجهاز. (<code>ConfigurationData[]‎</code>)  
* <code>supportedImageModes</code>: أحجام وتنسيقات الصور المسجلة التي يدعمها الجهاز. (<code>ConfigurationData []</code>‎)  
* <code>supportedImageModes</code>: أحجام وتنسيقات الصور المسجلة التي يدعمها الجهاز. (<code>ConfigurationData []</code>‎)  
* <code>supportedVideoModes</code>: دقة (resolution) الفيديوهات المُسجلة وتنسيقاتها التي يدعمها الجهاز. (<code>ConfigurationData []</code>‎)  
* <code>supportedVideoModes</code>: دقة (resolution) الفيديوهات المُسجلة وتنسيقاتها المدعومة في الجهاز. (<code>ConfigurationData []</code>‎)  


==<code>capture.captureAudio</code>==  
==<code>capture.captureAudio</code>==  
سطر 46: سطر 46:
<syntaxhighlight lang="javascript">navigator.device.capture.captureAudio(
<syntaxhighlight lang="javascript">navigator.device.capture.captureAudio(
     CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
     CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);‎</syntaxhighlight>يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل المقطوعات الصوتية باستخدام تطبيق التسجيل الصوتي الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة.
);‎</syntaxhighlight>


تنتهي عملية الالتقاط عند خروج المستخدم من تطبيق التسجيل الصوتي، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل <code>CaptureAudioOptions.limit</code>. في حال عدم تمرير المعامل <code>limit</code>، فسيأخذ القيمة الافتراضية (<code>1</code>)، وستُنهى عملية الالتقاط بعد تسجيل المستخدم لمقطعٍ صوتي واحد.  
=== الوصف ===
يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل المقطوعات الصوتية باستخدام تطبيق التسجيل الصوتي الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة.  


عند انتهاء عملية الالتقاط، يُنفّذ رد النداء <code>CaptureCallback</code>، مع تمرير مصفوفة إليه تضم كائناتٍ <code>MediaFile</code> تحتوي معلومات وصفية لكل الملفات الصوتيةالمُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي مقطعٍ صوتي، سيُنفّذ رد النداء <code>CaptureErrorCallback</code> مع تمرير كائنٍ <code>CaptureError</code> إليه، والذي سيتضمن رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.  
تنتهي عملية التسجيل عند خروج المستخدم من تطبيق التسجيل الصوتي، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل <code>CaptureAudioOptions.limit</code>. في حال عدم تمرير المعامل <code>limit</code>، فسيأخذ القيمة الافتراضية (<code>1</code>)، وستُنهى عملية الالتقاط بعد تسجيل المستخدم لمقطعٍ صوتي واحد.
 
عند انتهاء عملية التسجيل، يُنفّذ رد النداء <code>CaptureCallback</code>، مع تمرير مصفوفة إليه تضم كائنات <code>MediaFile</code> تحتوي معلومات وصفية لكل الملفات الصوتية المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي مقطعٍ صوتي، سيُنفّذ رد النداء <code>CaptureErrorCallback</code> مع تمرير كائنٍ <code>CaptureError</code> إليه، والذي سيتضمن رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.  
=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
*أندرويد  
*أندرويد  
سطر 82: سطر 85:
===الوصف===  
===الوصف===  


ٍيبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط أكثر من صورة واحدة في جلسة واحدة.  
ٍيبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط عدة صورٍ في جلسة واحدة.  


تنتهي عملية الالتقاط عندما يغلق المستخدم تطبيق الكاميرا، أو عند بلوغ الحد الأقصى لعدد التسجيلات المحدد بواسطة المعامل <code>CaptureImageOptions.limit</code>. إذا لم تُحدّد قيمة <code>limit</code>، فسيتم تعيينه إلى قيمته الافتراضية (<code>1</code>)، وستُنهى عملية الالتقاط بعد التقاط المستخدم لصورةٍ واحدةٍ فقط.  
تنتهي عملية الالتقاط عندما يغلق المستخدم تطبيق الكاميرا، أو عند بلوغ الحد الأقصى لعدد التسجيلات المحدد بواسطة المعامل <code>CaptureImageOptions.limit</code>. إذا لم تُحدّد قيمة <code>limit</code>، فسيتم تعيينه إلى قيمته الافتراضية (<code>1</code>)، وستُنهى عملية الالتقاط بعد التقاط المستخدم لصورةٍ واحدةٍ فقط.  


عند انتهاء عملية الالتقاط، فسيُستدعى رد النداء <code>CaptureCB</code> مع إعطائه مصفوفة تضم كائنات <code>MediaFile</code> تحتوي معلومات وصفية عن ملفات الصور المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي صورة، فسيُنفّذ رد النداء <code>CaptureErrorCB</code> مع إعطائه كائنًا <code>CaptureError</code> يحتوي على رمز خطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.  
عند انتهاء عملية الالتقاط، فسيُستدعى رد النداء <code>CaptureCB</code> مع إعطائه مصفوفة تضم كائنات <code>MediaFile</code>، والتي تحتوي معلومات وصفية عن ملفات الصور المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي صورة، فسيُنفّذ رد النداء <code>CaptureErrorCB</code> مع إعطائه كائنًا <code>CaptureError</code> يحتوي على رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.  
=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
*أندرويد  
*أندرويد  
سطر 113: سطر 116:
=== ملاحظات خاصة بالمتصفحات (Browsers) ===  
=== ملاحظات خاصة بالمتصفحات (Browsers) ===  


يعمل هذا التابع على منصات Chrome و Firefox و Opera فقط (لأنّ متصفحي IE و Safari لا يدعمان الواجهة البرمجية التي تخص <code>navigator.getUserMedia</code>)  
يعمل هذا التابع على منصات Chrome و Firefox و Opera فقط (لأنّ متصفحي IE و Safari لا يدعمان الواجهة البرمجية التي تخص <code>navigator.getUserMedia</code>).


لا يمكن عرض الصور باستخدام عنوان URL الخاص بالملف المُلتقط إلا في متصفحي Chrome و Opera. يُخزّن متصفح Firefox الصور الملتقطة في وحدة التخزين [[Cordova/storage#.D8.A7.D9.84.D9.88.D8.A7.D8.AC.D9.87.D8.A9 IndexedDB|IndexedDB]] (راجع توثيق [[Cordova/cordova plugin file|إضافة الملفات]])، ونتيجةً لذلك، ستكون الطريقة الوحيدة لإظهار الصورة الملتقطة هي قراءتها وعرضها باستخدام عنوان <code>DataURL</code> الخاص بها.  
لا يمكن عرض الصور باستخدام عنوان URL الخاص بالملف المُلتقط إلا في متصفحي Chrome و Opera. كما يُخزّن متصفح Firefox الصور الملتقطة في وحدة التخزين [[Cordova/storage#.D8.A7.D9.84.D9.88.D8.A7.D8.AC.D9.87.D8.A9 IndexedDB|IndexedDB]] (راجع توثيق [[Cordova/cordova plugin file|إضافة الملفات]])، ونتيجةً لذلك، ستكون الطريقة الوحيدة لإظهار الصورة الملتقطة هي قراءتها وعرضها باستخدام عنوان <code>DataURL</code> الخاص بها.  
=== مثال ===  
=== مثال ===  
<syntaxhighlight lang="javascript">// رد نداء الالتقاط
<syntaxhighlight lang="javascript">// رد نداء الالتقاط
سطر 141: سطر 144:
ٍيبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.  
ٍيبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.  


تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الفيديو، أو عند بلوغ الحد الأقصى من التسجيلات المحدد في المعامل <code>CaptureVideoOptions.limit</code>. في حالة عدم تحديد قيمة المعامل <code>limit</code>، فسيتم تعيينها غند القيمة الافتراضية (<code>1</code>)، وستُنهى العملية بعد تسجيل المستخدم لمقطع فيديو واحد.  
تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الفيديو، أو عند بلوغ الحد الأقصى من التسجيلات المحدد في المعامل <code>CaptureVideoOptions.limit</code>. في حالة عدم تحديد قيمة المعامل <code>limit</code>، فسيتم تعيينها عند القيمة الافتراضية (<code>1</code>)، وستُنهى العملية بعد تسجيل المستخدم لمقطع فيديو واحد.  


عند انتهاء عملية التصوير، يُستدعى رد النداء <code>CaptureCB</code> مع إعطائه مصفوفة تضم كائنات <code>MediaFile</code>، والتي تحتوي معلومات وصفية عن ملفات الفيديو المُصوّرة. إذا أنهى المستخدم العملية قبل التقاط أيّ مقطع فيديو، فسيُنفّذ رد النداء <code>CaptureErrorCB</code> مع إعطائه كائنًا <code>CaptureError</code>، والذي يحتوي على رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.
عند انتهاء عملية التصوير، يُستدعى رد النداء <code>CaptureCB</code> مع إعطائه مصفوفة تضم كائنات <code>MediaFile</code>، والتي تحتوي معلومات وصفية عن ملفات الفيديو المُصوّرة. إذا أنهى المستخدم العملية قبل تصوير أيّ مقطع فيديو، فسيُنفّذ رد النداء <code>CaptureErrorCB</code> مع إعطائه كائنًا <code>CaptureError</code>، والذي يحتوي على رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.


=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
سطر 177: سطر 180:
* المعامل <code>duration</code> غير مدعوم في منصة أندرويد. لذا لا يمكن تحديد أطوال التسجيلات برمجيا.  
* المعامل <code>duration</code> غير مدعوم في منصة أندرويد. لذا لا يمكن تحديد أطوال التسجيلات برمجيا.  
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  
* المعامل <code>limit</code> غير مدغوم في منصة iOS، لذلك لا يمكن إنشاء إلا تسجيلة واحد عند كل استدعاء.  
* المعامل <code>limit</code> غير مدعوم في منصة iOS، لذلك لا يمكن إنشاء إلا تسجيلة واحد عند كل استدعاء.  


==<code>CaptureImageOptions</code>==  
==<code>CaptureImageOptions</code>==  
يُغلّف هذا الكائن إعدادات عملية التقاط الصور.  
يحتوي هذا الكائن على إعدادات عملية التقاط الصور.  
=== خاصيات ===  
=== خاصيات ===  
* <code>limit</code>: تمثل هذه الخاصية الحد الأقصى لعدد الصور التي يمكن للمستخدم التقاطها في كل عملية التقاط. يجب أن تكون القيمة أكبر من أو تساوي <code>1</code> (القيمة الافتراضية هي <code>1</code>).  
* <code>limit</code>: تمثل هذه الخاصية الحد الأقصى لعدد الصور التي يمكن للمستخدم التقاطها في كل عملية التقاط. يجب أن تكون القيمة أكبر من أو تساوي <code>1</code> (القيمة الافتراضية هي <code>1</code>).  
سطر 191: سطر 194:


==<code>CaptureVideoOptions</code>==  
==<code>CaptureVideoOptions</code>==  
يُغلّف هذا الكائن إعدادات عملية التقاط الفيديو.  
يحتوي هذا الكائن على إعدادات عمليات التقاط الفيديو.  
=== خاصيات ===  
=== خاصيات ===  
* <code>limit</code>: تمثل هذه الخاصية الحد الأقصى لعدد مقاطع الفيديو التي يمكن لمستخدم الجهاز تصويرها في كل عملية تصوير. يجب أن تكون القيمة أكبر من أو تساوي <code>1</code> (القيمة الافتراضية هي <code>1</code>).  
* <code>limit</code>: تمثل هذه الخاصية الحد الأقصى لعدد مقاطع الفيديو التي يمكن لمستخدم الجهاز تسجيلها في كل عملية تصوير. يجب أن تكون القيمة أكبر من أو تساوي <code>1</code> (القيمة الافتراضية هي <code>1</code>).  
* <code>duration</code>: تمثل المدة القصوى لمقطع الفيديو بالثواني.  
* <code>duration</code>: تمثل المدةَ القصوى لمقطع الفيديو بالثواني.  
=== مثال ===  
=== مثال ===  
<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 فيديوهات
<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 فيديوهات
سطر 209: سطر 212:


==<code>CaptureCB</code>==  
==<code>CaptureCB</code>==  
يُستدعى رد النداء <code>CaptureCB</code> بعد مرور عمليةِ التقاط أو تصوير وسيطٍ (media) بنجاحٍ.  
يُستدعى رد النداء <code>CaptureCB</code> بعد مرور عمليةِ التقاط أو تصوير الوسيط (media) بنجاحٍ.  
<syntaxhighlight lang="javascript">function captureSuccess( MediaFile[] mediaFiles ) { ... };‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">function captureSuccess( MediaFile[] mediaFiles ) { ... };‎</syntaxhighlight>  
===الوصف===  
===الوصف===  
سطر 227: سطر 230:


==<code>CaptureError</code>==  
==<code>CaptureError</code>==  
يغلف هذا الكائن رمز الخطأ الناتج عن عمليةٍ فاشلةٍ للالتقاط الوسائط.  
يحتوي هذا الكائن رمز الخطأ الناتج عن محاولةٍ فاشلةٍ لالتقاط الوسائط.  
=== خاصيات ===  
=== خاصيات ===  
* <code>code</code>: أحد رموز الخطأ المحددة مسبقًا (انظر أدناه).  
* <code>code</code>: أحد رموز الخطأ المحددة مسبقًا (انظر أدناه).  
سطر 243: سطر 246:
===الوصف===  
===الوصف===  


تنفذ هذه الدالة في حالة حدوث خطأ أثناء محاولة التقاط الوسائط. من الأخطاء الممكنة، نجد انشغال تطبيق الالتقاط بشيء آخر، أو أنّ هناك عملية التقاط أخرى تجري في ذلك الوقت، أو أنّ المستخدم قد ألغى العملية قبل أي التقاطٍ.  
تنفذ هذه الدالة في حالة حدوث خطأ أثناء محاولة التقاط الوسائط. هناك عدة أخطاء ممكنة، مثل انشغال تطبيق الالتقاط بشيء آخر، أو أنّ هناك عملية التقاط أخرى تجري في ذلك الوقت، أو أنّ المستخدم قد ألغى العملية قبل أي التقاطٍ.  


تنفذ هذه الدالة مع إعطائها كائنًا <code>CaptureError</code> يحتوي على رمز الخطأ المقابل <code>code</code>.  
تنفذ هذه الدالة مع إعطائها كائنًا <code>CaptureError</code> يحتوي على رمز الخطأ <code>code</code> المقابل.  
=== مثال ===  
=== مثال ===  
<syntaxhighlight lang="javascript">// رد نداء الخطأ الخاص بالالتقاط
<syntaxhighlight lang="javascript">// رد نداء الخطأ الخاص بالالتقاط
سطر 253: سطر 256:


==<code>ConfigurationData</code>==  
==<code>ConfigurationData</code>==  
يغلّف هذا الكائن مجموعة من معاملات التقاط الوسائط المدعومة من الجهاز.  
يحتوي هذا الكائن مجموعة من معاملات التقاط الوسائط المدعومة من الجهاز.  
===الوصف===  
===الوصف===  


سطر 265: سطر 268:
*<code>audio/wav</code>  
*<code>audio/wav</code>  
=== خاصيات ===  
=== خاصيات ===  
* <code>type</code>: تحتوي هذه الخاصية على السلسلة النصية المشفرة بترميز ASCII، والتي تمثل نوع الوسائط. (<code>DOMString</code>)  
* <code>type</code>: تحتوي هذه الخاصية على سلسلة نصية مُشفرة بالترميز ASCII، والتي تمثل نوع الوسائط. (<code>DOMString</code>)  
* <code>height</code>: ارتفاع الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)  
* <code>height</code>: ارتفاع الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)  
* <code>width</code>: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)  
* <code>width</code>: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)  
سطر 271: سطر 274:
<syntaxhighlight lang="javascript">// الحصول على أوضاع الصور المدعومة
<syntaxhighlight lang="javascript">// الحصول على أوضاع الصور المدعومة
var imageModes = navigator.device.capture.supportedImageModes;
var imageModes = navigator.device.capture.supportedImageModes;
// اختيار الوضع ذي أعلى دقة في العرض
// اختيار الوضع الذي عرضه له أعلى دقة
var width = 0;
var width = 0;
var selectedmode;
var selectedmode;
سطر 281: سطر 284:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


هذا الكائن غير مدعوم من قبل أي منصةٍ. جميع مصفوفات بيانات الإعدادات فارغة.  
هذا الكائن غير مدعوم من قبل أي منصةٍ. وجميع مصفوفات الإعدادات فارغة.  


==<code>MediaFile.getFormatData</code>==  
==<code>MediaFile.getFormatData</code>==  
سطر 291: سطر 294:
===الوصف===  
===الوصف===  


تحاول هذه الدالة بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسستستدعي رد النداء <code>MediaFileDataSuccessCB</code> مع إعطائه كائنًا <code>MediaFileData</code>. وإذا فشلت المحاولة، ستستدعي هذه الدالةُ رد النداء <code>MediaFileDataErrorCB</code>.  
تحاول هذه الدالة بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسستستدعي رد النداء <code>MediaFileDataSuccessCB</code> مع إعطائه كائنًا <code>MediaFileData</code>. وإذا فشلت المحاولة، ستستدعي ردَّ النداء <code>MediaFileDataErrorCB</code>.  
=== المنصات المدعومة ===  
=== المنصات المدعومة ===  
*أندرويد  
*أندرويد  
سطر 304: سطر 307:


==MediaFile==  
==MediaFile==  
يغلف هذا التابع خاصيات ملف الوسائط المُلتقط.  
يحتوي هذا التابع خاصيات ملف الوسائط المُلتقط.  
=== خاصيات ===  
=== خاصيات ===  
* <code>name</code>: اسم الملف، دون معلومات المسار. (<code>DOMString</code>)  
* <code>name</code>: اسم الملف، دون معلومات المسار. (<code>DOMString</code>)  
سطر 315: سطر 318:


==<code>MediaFileData</code>==  
==<code>MediaFileData</code>==  
يُغلّف هذا الكائن معلومات التنسيق الخاصة بملف الوسائط.  
يحتوي هذا الكائن معلومات التنسيق الخاصة بملف الوسائط.  
=== خاصيات ===  
=== خاصيات ===  
* <code>codecs</code>: التنسيق الفعلي لمحتوى الصوت والفيديو. (<code>DOMString</code>)  
* <code>codecs</code>: التنسيق الفعلي لمحتوى الصوت والفيديو. (<code>DOMString</code>)  
* <code>bitrate</code>: متوسط صبيب البث (bitrate) الخاص بالمحتوى. قيمة هذه الخاصية تساوي الصفر للصور. (عدد)  
* <code>bitrate</code>: متوسط صبيب البث (bitrate) الخاص بالمحتوى. قيمة هذه الخاصية تساوي الصفر بالنسبة للصور. (عدد)  
* <code>height</code>: ارتفاع الصورة أو الفيديو بالبكسل. القيمة هي الصفر بالنسبة لمقاطع الصوت. (عدد)  
* <code>height</code>: ارتفاع الصورة أو الفيديو بالبكسل. القيمة تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)  
* <code>width</code>: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت (عدد)  
* <code>width</code>: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت (عدد)  
* <code>duration</code>: طول مقطع الفيديو أو الصوت بالثواني. قيمة هذه الخاصية تساوي صفر بالنسبة للصور. (عدد)  
* <code>duration</code>: طول مقطع الفيديو أو الصوت بالثواني. قيمة هذه الخاصية تساوي الصفر بالنسبة للصور. (عدد)  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  


سطر 343: سطر 346:
عند تسجيل الصوت، أو التقاط الفيديوهات أو الصور على نظام أندرويد، هناك احتمال أن يُنهى التطبيق بعد إرسال [[Cordova/webviews|عارض]] كوردوفا إلى الخلفية من قِبل تطبيق الالتقاط الأصلي. راجع صفحة [http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#lifecycle-guide دليل دورة حياة أندرويد] للحصول على معلومات مُفصّلة عن هذه المشكلة.   
عند تسجيل الصوت، أو التقاط الفيديوهات أو الصور على نظام أندرويد، هناك احتمال أن يُنهى التطبيق بعد إرسال [[Cordova/webviews|عارض]] كوردوفا إلى الخلفية من قِبل تطبيق الالتقاط الأصلي. راجع صفحة [http://cordova.apache.org/docs/en/latest/guide/platforms/android/index.html#lifecycle-guide دليل دورة حياة أندرويد] للحصول على معلومات مُفصّلة عن هذه المشكلة.   


في هذه الحالة، لن يُطلق ردّ نداء النجاح أو الفشل المُمرّر إلى التابع <code>capture</code>، ولكن بدلاً من ذلك ستُسلّم نتائج الاستدعاء عبر حدثٍ من أحداث المستند (document event) يتم إطلاقه بعد الحدث [https://wiki.hsoub.com/Cordova/events#resume resume] الخاص بكوردوفا.  
في هذه الحالة، لن يُطلق ردّ نداء النجاح أو الفشل المُمرّر إلى التابع <code>capture</code>، ولكن بدلاً من ذلك ستُسلّم نتائج الاستدعاء عبر حدثٍ من أحداث المستند (document event)، والذي سيتم إطلاقه بعد الحدث [https://wiki.hsoub.com/Cordova/events#resume resume] الخاص بكوردوفا.  


يجب أن يشترك تطبيقك في الحدثين المحتملين كما هو مُبيّن في المثال التالي:  
يجب أن يشترك تطبيقك في الحدثين المحتملين كما هو مُبيّن في المثال التالي:  
سطر 359: سطر 362:
document.addEventListener('deviceready', onDeviceReady);‎</syntaxhighlight>  
document.addEventListener('deviceready', onDeviceReady);‎</syntaxhighlight>  


تتَبُّع أيِّ أجزاء شيفرتك تصدر عنها هذه النتائج متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين [[Cordova/events#pause|pause]] و [[Cordova/events#resume|resume]] بالشكل المناسب. يرجى ملاحظة أن هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر [[Cordova/webviews|العارض]] أثناء عملية الالتقاط.
تتَبُّع أيِّ أجزاء شيفرتك تصدر عنها هذه النتائج متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين [[Cordova/events#pause|pause]] و [[Cordova/events#resume|resume]] بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر [[Cordova/webviews|العارض]] أثناء عملية الالتقاط.
== انظر أيضا==
== انظر أيضا==
*إضافة <nowiki/>[[Cordova/cordova plugin media|تسجيل الصوت]]
*إضافة <nowiki/>[[Cordova/cordova plugin media|تسجيل الصوت]]

مراجعة 21:18، 21 ديسمبر 2018

تمكّن إضافة الوصول إلى الوسائط المتعددة (cordova-plugin-media-capture) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز.

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

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

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.device.capture);
}

التثبيت

يمكن تثبيت هذه الإضافة عبر الأمر:

cordova plugin add cordova-plugin-media-capture‎

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

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

الكائنات

  • Capture
  • CaptureAudioOptions
  • CaptureImageOptions
  • CaptureVideoOptions
  • CaptureCallback
  • CaptureErrorCB
  • ConfigurationData
  • MediaFile
  • MediaFileData

التوابع

  • capture.captureAudio
  • capture.captureImage
  • capture.captureVideo
  • MediaFile.getFormatData

خاصيات

  • supportedAudioModes: تمثل هذه الخاصية تنسيقات (formats) التسجيل الصوتي التي يدعمها الجهاز. (ConfigurationData[]‎)
  • supportedImageModes: أحجام وتنسيقات الصور المسجلة التي يدعمها الجهاز. (ConfigurationData []‎)
  • supportedVideoModes: دقة (resolution) الفيديوهات المُسجلة وتنسيقاتها المدعومة في الجهاز. (ConfigurationData []‎)

capture.captureAudio

يبدأ هذا التابع تشغيل تطبيق تسجيل الصوت (audio recorder application)، ويُعيد معلومات حول الملفات الصوتية المُسجّلة.

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

الوصف

يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل المقطوعات الصوتية باستخدام تطبيق التسجيل الصوتي الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة.

تنتهي عملية التسجيل عند خروج المستخدم من تطبيق التسجيل الصوتي، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل CaptureAudioOptions.limit. في حال عدم تمرير المعامل limit، فسيأخذ القيمة الافتراضية (1)، وستُنهى عملية الالتقاط بعد تسجيل المستخدم لمقطعٍ صوتي واحد.

عند انتهاء عملية التسجيل، يُنفّذ رد النداء CaptureCallback، مع تمرير مصفوفة إليه تضم كائنات MediaFile تحتوي معلومات وصفية لكل الملفات الصوتية المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي مقطعٍ صوتي، سيُنفّذ رد النداء CaptureErrorCallback مع تمرير كائنٍ CaptureError إليه، والذي سيتضمن رمز الخطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

مثال

// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // افعل شيئا ما بالملف
    }
};
// رد نداء الخطأ الخاص بالالتقاط
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// بدء تسجيل الصوت
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

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

  • لا تتوفر منصة iOS على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.

ملاحظات خاصة بمنصتي Windows Phone الإصدارين 7 و 8

  • لا يحتوي Windows Phone 7 على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.

capture.captureImage

يبدأ هذا التابع تشغيل تطبيق الكاميرا، ويعيد معلومات حول ملفات الصور الملتقطة.

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

الوصف

ٍيبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط عدة صورٍ في جلسة واحدة.

تنتهي عملية الالتقاط عندما يغلق المستخدم تطبيق الكاميرا، أو عند بلوغ الحد الأقصى لعدد التسجيلات المحدد بواسطة المعامل CaptureImageOptions.limit. إذا لم تُحدّد قيمة limit، فسيتم تعيينه إلى قيمته الافتراضية (1)، وستُنهى عملية الالتقاط بعد التقاط المستخدم لصورةٍ واحدةٍ فقط.

عند انتهاء عملية الالتقاط، فسيُستدعى رد النداء CaptureCB مع إعطائه مصفوفة تضم كائنات MediaFile، والتي تحتوي معلومات وصفية عن ملفات الصور المُلتقطة. إذا أنهى المستخدم العملية قبل التقاط أي صورة، فسيُنفّذ رد النداء CaptureErrorCB مع إعطائه كائنًا CaptureError يحتوي على رمز الخطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

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

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

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

  • NSCameraUsageDescription: يحدد سبب محاولةَ التطبيقِ الوصولَ إلى كاميرا المستخدم.
  • NSMicrophoneUsageDescription: يحدد سبب محاولةَ التطبيقِ الوصولَ إلى ميكروفون المستخدم.
  • NSPhotoLibraryUsageDescriptionentry: يحدد سبب محاولة التطبيق الوصولَ إلى مكتبة الصور الخاصة بالمستخدم.

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

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>
<edit-config target="NSMicrophoneUsageDescription" file="*-Info.plist" mode="merge">
    <string>need microphone access to record sounds</string>
</edit-config>
<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need to photo library access to get pictures from there</string>
</edit-config>

ملاحظات خاصة بالمتصفحات (Browsers)

يعمل هذا التابع على منصات Chrome و Firefox و Opera فقط (لأنّ متصفحي IE و Safari لا يدعمان الواجهة البرمجية التي تخص navigator.getUserMedia).

لا يمكن عرض الصور باستخدام عنوان URL الخاص بالملف المُلتقط إلا في متصفحي Chrome و Opera. كما يُخزّن متصفح Firefox الصور الملتقطة في وحدة التخزين IndexedDB (راجع توثيق إضافة الملفات)، ونتيجةً لذلك، ستكون الطريقة الوحيدة لإظهار الصورة الملتقطة هي قراءتها وعرضها باستخدام عنوان DataURL الخاص بها.

مثال

// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // افعل شيئا ما بالملف
    }
};
// رد نداء الخطأ الخاص بالالتقاط
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// بدء عملية التقاط الصورة
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

capture.captureVideo

يبدأ هذا التابع تشغيل تطبيق مُسجّل الفيديو (video recorder application)، ويُعيد معلومات حول ملفات الفيديو المُصوّرة.

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

الوصف

ٍيبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.

تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الفيديو، أو عند بلوغ الحد الأقصى من التسجيلات المحدد في المعامل CaptureVideoOptions.limit. في حالة عدم تحديد قيمة المعامل limit، فسيتم تعيينها عند القيمة الافتراضية (1)، وستُنهى العملية بعد تسجيل المستخدم لمقطع فيديو واحد.

عند انتهاء عملية التصوير، يُستدعى رد النداء CaptureCB مع إعطائه مصفوفة تضم كائنات MediaFile، والتي تحتوي معلومات وصفية عن ملفات الفيديو المُصوّرة. إذا أنهى المستخدم العملية قبل تصوير أيّ مقطع فيديو، فسيُنفّذ رد النداء CaptureErrorCB مع إعطائه كائنًا CaptureError، والذي يحتوي على رمز الخطأ CaptureError.CAPTURE_NO_MEDIA_FILES.

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

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

مثال

// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // افعل شيئا ما بالملف
    }
};
// رد نداء الخطأ الخاص بالالتقاط
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
// بدء تصوير الفيديو
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

CaptureAudioOptions

يحتوي الكائن CaptureAudioOptions على إعدادات عمليات تسجيل الصوت.

خاصيات

  • limit: تمثل هذه الخاصية الحد الأقصى لعدد المقاطع الصوتية التي يمكن لمستخدم الجهاز تسجيلها خلال عملية تسجيلٍ واحدة. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).
  • duration: تمثل المدة القصوى للمقاطع الصوتية بالثواني.

مثال

// حصر عدد عمليات الالتقاط في 3 ملفات وسائط، بحيث لا يتجاوز أيٌّ منها 10 ثواني
var options = { limit: 3, duration: 10 };
navigator.device.capture.captureAudio(captureSuccess, captureError, options);

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

  • المعامل duration غير مدعوم في منصة أندرويد. لذا لا يمكن تحديد أطوال التسجيلات برمجيا.

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

  • المعامل limit غير مدعوم في منصة iOS، لذلك لا يمكن إنشاء إلا تسجيلة واحد عند كل استدعاء.

CaptureImageOptions

يحتوي هذا الكائن على إعدادات عملية التقاط الصور.

خاصيات

  • limit: تمثل هذه الخاصية الحد الأقصى لعدد الصور التي يمكن للمستخدم التقاطها في كل عملية التقاط. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).

مثال

// حصر عدد عمليات الالتقاط في 3 صور
var options = { limit: 3 };
navigator.device.capture.captureImage(captureSuccess, captureError, options);

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

  • المعامل limit غير مدعوم في هذه المنصة، لذلك لا يمكن التقاط إلا صورة واحدة فقط عند كل استدعاء.

CaptureVideoOptions

يحتوي هذا الكائن على إعدادات عمليات التقاط الفيديو.

خاصيات

  • limit: تمثل هذه الخاصية الحد الأقصى لعدد مقاطع الفيديو التي يمكن لمستخدم الجهاز تسجيلها في كل عملية تصوير. يجب أن تكون القيمة أكبر من أو تساوي 1 (القيمة الافتراضية هي 1).
  • duration: تمثل المدةَ القصوى لمقطع الفيديو بالثواني.

مثال

// حصر عدد عمليات الالتقاط في 3 فيديوهات
var options = { limit: 3 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

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

  • يتم تجاهل الخاصية limit. لذلك لا يُسجّل إلا مقطع فيديو واحد فقط عند كل استدعاء.

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

  • تدعم منصة أندرويد خاصيةً quality إضافية، للسماح بتصوير مقاطع الفيديو بجودات مختلفة. القيمة 1 (الافتراضية) تشير إلى جودة عالية، والقيمة 0 تعني جودة منخفضة، والتي تكون عادةً مناسبةً لرسائل MMS. انظر هذه الصفحة لمزيد من التفاصيل.

مثال

// حصر عدد عمليات التصوير في فيديو واحد بجودةٍ منخفضة
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);

CaptureCB

يُستدعى رد النداء CaptureCB بعد مرور عمليةِ التقاط أو تصوير الوسيط (media) بنجاحٍ.

function captureSuccess( MediaFile[] mediaFiles ) { ... };

الوصف

تُنفذ هذه الدالة بعد اكتمال عملية الالتقاط ينجاح. عند هذه النقطة، يكون ملف الوسائط (media file) قد التُقِط، وهذا يعني إمّا أنّ المستخدمَ قد خرج من تطبيق التقاط الوسائط، أو أنّه قد تم بلوغ الحد الأقصى للالتقاط.

كل كائنٍ من كائنات MediaFile يصف أحد ملفات الوسائط المُلتقطة.

مثال

// رد نداء الالتقاط
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // افعل شيئا ما بالملف
    }
};

CaptureError

يحتوي هذا الكائن رمز الخطأ الناتج عن محاولةٍ فاشلةٍ لالتقاط الوسائط.

خاصيات

  • code: أحد رموز الخطأ المحددة مسبقًا (انظر أدناه).

ثوابت

  • CaptureError.CAPTURE_INTERNAL_ERR: فشلت الكاميرا أو الميكروفون في التقاط الصورة أو الصوت.
  • CaptureError.CAPTURE_APPLICATION_BUSY: تطبيق التقاط الكاميرا أو الصوت مشغول حاليًا بخدمة طلبية (request) التقاطٍ أخرى.
  • CaptureError.CAPTURE_INVALID_ARGUMENT: استخدام غير صالح للواجهة البرمجية (على سبيل المثال، قيمة limit أصغر من واحد).
  • CaptureError.CAPTURE_NO_MEDIA_FILES: المستخدم أنهى تطبيق تسجيل الصوت أو الصورة قبل التقاط أي شيء.
  • CaptureError.CAPTURE_PERMISSION_DENIED: المستخدم لا يملك إذن تنفيذ طلبية الالتقاط المحددة.
  • CaptureError.CAPTURE_NOT_SUPPORTED: عملية الالتقاط المطلوبة غير مدعومة.

CaptureErrorCB

يُستدعى رد النداء CaptureErrorCB في حالة حدوث خطأ أثناء عملية التقاط الوسائط.

function captureError( CaptureError error ) { ... };

الوصف

تنفذ هذه الدالة في حالة حدوث خطأ أثناء محاولة التقاط الوسائط. هناك عدة أخطاء ممكنة، مثل انشغال تطبيق الالتقاط بشيء آخر، أو أنّ هناك عملية التقاط أخرى تجري في ذلك الوقت، أو أنّ المستخدم قد ألغى العملية قبل أي التقاطٍ.

تنفذ هذه الدالة مع إعطائها كائنًا CaptureError يحتوي على رمز الخطأ code المقابل.

مثال

// رد نداء الخطأ الخاص بالالتقاط
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

ConfigurationData

يحتوي هذا الكائن مجموعة من معاملات التقاط الوسائط المدعومة من الجهاز.

الوصف

يتضمّن الكائن ConfigurationData بياناتٍ حول أوضاع التقاط الوسائط (media capture modes) التي يدعمها الجهاز. تتضمن بيانات الإعدادا نوع الوسائط MIME، وأبعاد الفيديوهات أو الصور الملتقطة.

يجب أن تلتزم أنواع MIME بالمعيار RFC2046. من أمثلة ذلك:

  • video/3gpp
  • video/quicktime
  • image/jpeg
  • audio/amr
  • audio/wav

خاصيات

  • type: تحتوي هذه الخاصية على سلسلة نصية مُشفرة بالترميز ASCII، والتي تمثل نوع الوسائط. (DOMString)
  • height: ارتفاع الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)
  • width: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)

مثال

// الحصول على أوضاع الصور المدعومة
var imageModes = navigator.device.capture.supportedImageModes;
// اختيار الوضع الذي عرضه له أعلى دقة
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

هذا الكائن غير مدعوم من قبل أي منصةٍ. وجميع مصفوفات الإعدادات فارغة.

MediaFile.getFormatData

يعيد هذا التابع معلومات التنسيق الخاصة بملف الوسائط المُلتقط.

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);

الوصف

تحاول هذه الدالة بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسستستدعي رد النداء MediaFileDataSuccessCB مع إعطائه كائنًا MediaFileData. وإذا فشلت المحاولة، ستستدعي ردَّ النداء MediaFileDataErrorCB.

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

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

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

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

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

الواجهة البرمجية للوصول إلى معلومات تنسيق ملفات الوسائط محدودة، لذلك ليست كل خاصيات MediaFileData مدعومة.

MediaFile

يحتوي هذا التابع خاصيات ملف الوسائط المُلتقط.

خاصيات

  • name: اسم الملف، دون معلومات المسار. (DOMString)
  • fullPath: المسار الكامل للملف، بما في ذلك الاسم. (DOMString)
  • type: نوع mime الخاص بالملف (DOMString)
  • lastModifiedDate: تاريخ ووقت آخر تعديل على الملف. (Date)
  • size: حجم الملف بعدد البايتات. (عدد)

توابع

  • MediaFile.getFormatData: يعيد هذا التابع معلومات التنسيق الخاصة بملف الوسائط.

MediaFileData

يحتوي هذا الكائن معلومات التنسيق الخاصة بملف الوسائط.

خاصيات

  • codecs: التنسيق الفعلي لمحتوى الصوت والفيديو. (DOMString)
  • bitrate: متوسط صبيب البث (bitrate) الخاص بالمحتوى. قيمة هذه الخاصية تساوي الصفر بالنسبة للصور. (عدد)
  • height: ارتفاع الصورة أو الفيديو بالبكسل. القيمة تساوي الصفر بالنسبة لمقاطع الصوت. (عدد)
  • width: عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت (عدد)
  • duration: طول مقطع الفيديو أو الصوت بالثواني. قيمة هذه الخاصية تساوي الصفر بالنسبة للصور. (عدد)

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

تدعم أندرويد خاصيات MediaFileData التالية:

  • codecs: غير مدعومة، وتُعيد null.
  • bitrate: غير مدعومة، وتُعيد صفر.
  • height: مدعومة، لكن فقط لملفات الصور والفيديو.
  • width: مدعومة, لكن لملفات الصور والفيديو فقط.
  • duration: مدعومة، لكن لملفات الصوت والفيديو فقط.

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

تدعم منصة iOS خاصيات MediaFileData التالية:

  • codecs: غير مدعومة، وتُعيد null.
  • bitrate: مدعومة على أجهزة iOS4، للصوت فقط. فيما تُعيد الصفر للصور ومقاطع الفيديو.
  • height: مدعومة، لكن لملفات الصور والفيديو فقط.
  • width: مدعومة، لكن لملفات الصور والفيديو فقط.
  • duration: مدعومة، لكن لملفات الصوت والفيديو فقط.

ملاحظات خاصة حول دورة حياة أندرويد (Android Lifecycle Quirks)

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

في هذه الحالة، لن يُطلق ردّ نداء النجاح أو الفشل المُمرّر إلى التابع capture، ولكن بدلاً من ذلك ستُسلّم نتائج الاستدعاء عبر حدثٍ من أحداث المستند (document event)، والذي سيتم إطلاقه بعد الحدث resume الخاص بكوردوفا.

يجب أن يشترك تطبيقك في الحدثين المحتملين كما هو مُبيّن في المثال التالي:

function onDeviceReady() {
    // capture في حال نجاح استدعاء pendingcaptureresult يُطلق الحدث
    document.addEventListener('pendingcaptureresult', function(mediaFiles) {
        // افعل شيئ ما بالنتيجة
    });
    // capture في حال فشل استدعاء pendingcaptureerror يُطلق الحدث
    document.addEventListener('pendingcaptureerror', function(error) {
        // معالجة الخطأ
    });
}
// deviceready لا تشترك في الحدثين إلا بعد إطلاق الحدث
document.addEventListener('deviceready', onDeviceReady);

تتَبُّع أيِّ أجزاء شيفرتك تصدر عنها هذه النتائج متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين pause و resume بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر العارض أثناء عملية الالتقاط.

 انظر أيضا

مصادر