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

من موسوعة حسوب
لا ملخص تعديل
تحديث
 
(3 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة)
سطر 1: سطر 1:
<noinclude>{{DISPLAYTITLE:إضافة الوصول إلى الوسائط المتعددة في كوردوفا}}</noinclude>
<noinclude>{{DISPLAYTITLE:إضافة الوصول إلى الوسائط المتعددة في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
[[تصنيف: Cordova]]
[[تصنيف: Plugin]]
[[تصنيف: Cordova Plugin]]
تمكّن إضافة الوصول إلى الوسائط المتعددة (<code>cordova-plugin-media-capture</code>) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز.
تمكّن إضافة الوصول إلى الوسائط المتعددة (cordova-plugin-media-capture) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز.


'''تنبيه''': جمع واستخدام الصور أو الفيديوهات أو الصوتيات من الكاميرا أو الميكروفون الخص بالجهاز يثير مخاوف متعلقة بالخصوصية. يجب أن تناقش سياسةُ الخصوصيةُ في تطبيقك كيفية استخدام التطبيق لأجهزة الاستشعار هذه، وما إن كانت البيانات المسجّلة ستُتشارك مع أطراف أخرى. بالإضافة إلى ذلك، إذا لم يكن استخدام الكاميرا أو الميكروفون واضحًا في واجهة المستخدم، فيجب عليك تقديم إشعار فوري قبل محاولة التطبيق الوصولَ إلى الكاميرا أو الميكروفون (إن لم يكن نظام التشغيل يفعل ذلك بالفعل). ينبغي أن يوفر هذا الإشعار نفس المعلومات المذكورة أعلاه، إضافة إلى استئذان المُستخدم (على سبيل المثال، عبر تقديم خيارات من قبيل '''حسنًا''' و '''لا شكرًا'''). لاحظ أنّ بعض متاجر التطبيقات قد تُلزم تطبيقك بتقديم إشعار فوري واستئذان المستخدم قبل استخدام الكاميرا أو الميكروفون. لمزيد من المعلومات، يرجى الاطلاع على [[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);
function onDeviceReady() {
function onDeviceReady() {
     console.log(navigator.device.capture);
     console.log(navigator.device.capture);
سطر 15: سطر 15:


== المنصات المدعومة ==  
== المنصات المدعومة ==  
*أندرويد  
*[[Cordova/platforms android|أندرويد]]
*Browser  
*Browser  
*iOS  
*[[Cordova/platforms ios|iOS]]
*ويندوز  
*[[Cordova/platforms windows|ويندوز]]


==الكائنات==  
==الكائنات==  
سطر 37: سطر 37:
*<code>MediaFile.getFormatData</code>  
*<code>MediaFile.getFormatData</code>  


== خاصيات ==  
== الخاصيات ==  
* <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>يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل المقاطع الصوتية باستخدام تطبيق تسجيل الصوت الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة.  


تنتهي عملية الالتقاط عند خروج المستخدم من تطبيق التسجيل الصوتي، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل <code>CaptureAudioOptions.limit</code>. في حال عدم تمرير المعامل <code>limit</code>، فسيأخذ القيمة الافتراضية (<code>1</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>.  
عند انتهاء عملية التسجيل، يُنفّذ رد النداء <code>CaptureCallback</code>، مع تمرير مصفوفة إليه تضم كائنات <code>MediaFile</code> تحتوي معلومات وصفية لكل الملفات الصوتية المُلتقطَة. إذا أنهى المستخدم العملية قبل التقاط أي مقطعٍ صوتي، سيُنفّذ رد النداء <code>CaptureErrorCallback</code> مع تمرير كائنٍ من النوع <code>CaptureError</code> إليه، والذي سيتضمن رمز الخطأ <code>CaptureError.CAPTURE_NO_MEDIA_FILES</code>.  
=== المنصات المدعومة ===
 
*أندرويد  
المنصات المدعومة هي:
*iOS  
*[[Cordova/platforms android|أندرويد]]
*ويندوز  
*[[Cordova/platforms ios|iOS]]
=== مثال ===
*[[Cordova/platforms windows|ويندوز]]
<syntaxhighlight lang="javascript">// رد نداء الالتقاط
مثال على استعمال التابع <code>captureAudio</code>:<syntaxhighlight lang="javascript">// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
var captureSuccess = function(mediaFiles) {
     var i, path, len;
     var i, path, len;
سطر 71: سطر 71:
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});‎</syntaxhighlight>  
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});‎</syntaxhighlight>  
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  
* لا تتوفر منصة iOS على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.  
* لا تحتوي منصة iOS على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.  
=== ملاحظات خاصة بمنصتي Windows Phone الإصدارين 7 و 8 ===  
=== ملاحظات خاصة بمنصتي Windows Phone الإصدارين 7 و 8 ===  
* لا يحتوي Windows Phone 7 على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.  
* لا يحتوي Windows Phone 7 على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة.  
سطر 79: سطر 79:
<syntaxhighlight lang="javascript">navigator.device.capture.captureImage(
<syntaxhighlight lang="javascript">navigator.device.capture.captureImage(
     CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
     CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);‎</syntaxhighlight>  
);‎</syntaxhighlight>يبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط عدة صورٍ في جلسة واحدة.
===الوصف===


ٍيبدأ هذا التابع عمليةً غير متزامنة لالتقاط الصور باستخدام تطبيق الكاميرا الخاص بالجهاز. تتيح هذه العملية للمستخدمين التقاط أكثر من صورة واحدة في جلسة واحدة.  
تنتهي عملية الالتقاط عندما يغلق المستخدم تطبيق الكاميرا، أو عند بلوغ الحد الأقصى لعدد التسجيلات المحدد بواسطة المعامل <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>.
المنصات المدعومة هي:
=== المنصات المدعومة ===
*[[Cordova/platforms android|أندرويد]]
*أندرويد  
*Browser  
*Browser  
*iOS  
*[[Cordova/platforms ios|iOS]]
*ويندوز  
*[[Cordova/platforms windows|ويندوز]]
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  


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


تتطلب هذه الإضافة أوصاف الاستخدام التالية:  
تتطلب هذه الإضافة أوصاف الاستخدام التالية:  
سطر 113: سطر 111:
=== ملاحظات خاصة بالمتصفحات (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">// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
var captureSuccess = function(mediaFiles) {
     var i, path, len;
     var i, path, len;
سطر 136: سطر 134:
<syntaxhighlight lang="javascript">navigator.device.capture.captureVideo(
<syntaxhighlight lang="javascript">navigator.device.capture.captureVideo(
     CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
     CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);‎</syntaxhighlight>  
);‎</syntaxhighlight>يبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.  
===الوصف===
 
ٍيبدأ هذا التابع عمليةً غير متزامنة لتسجيل الفيديوهات باستخدام تطبيق تسجيل الفيديو على الجهاز. تتيح العملية للمستخدم التقاط عدة تسجيلات في جلسة واحدة.  


تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الفيديو، أو عند بلوغ الحد الأقصى من التسجيلات المحدد في المعامل <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>.


=== المنصات المدعومة ===
المنصات المدعومة هي:
*أندرويد  
*[[Cordova/platforms android|أندرويد]]
*iOS  
*[[Cordova/platforms ios|iOS]]
*ويندوز  
*[[Cordova/platforms windows|ويندوز]]
=== مثال ===
مثال عن استعمال التابع <code>captureVideo</code>:<syntaxhighlight lang="javascript">// رد نداء الالتقاط
<syntaxhighlight lang="javascript">// رد نداء الالتقاط
var captureSuccess = function(mediaFiles) {
var captureSuccess = function(mediaFiles) {
     var i, path, len;
     var i, path, len;
سطر 165: سطر 159:
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});‎</syntaxhighlight>  
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});‎</syntaxhighlight>  


==<code>CaptureAudioOptions</code>==  
==الكائن <code>CaptureAudioOptions</code>==  
يحتوي الكائن <code>CaptureAudioOptions</code> على إعدادات عمليات تسجيل الصوت.  
يحتوي الكائن <code>CaptureAudioOptions</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>: تمثل المدة القصوى للمقاطع الصوتية بالثانية.  
=== مثال ===
إليك المثال التالي حول استعمال الكائن <code>CaptureAudioOptions</code>:<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 ملفات وسائط، بحيث لا يتجاوز أيٌّ منها 10 ثواني
<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 ملفات وسائط، بحيث لا يتجاوز أيٌّ منها 10 ثواني
var options = { limit: 3, duration: 10 };
var options = { limit: 3, duration: 10 };
navigator.device.capture.captureAudio(captureSuccess, captureError, options);‎</syntaxhighlight>  
navigator.device.capture.captureAudio(captureSuccess, captureError, options);‎</syntaxhighlight>  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  
* المعامل <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>).  
=== مثال ===
إليك المثال التالي حول استعمال الكائن <code>CaptureImageOptions</code>:<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 صور
<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 صور
var options = { limit: 3 };
var options = { limit: 3 };
navigator.device.capture.captureImage(captureSuccess, captureError, options);‎</syntaxhighlight>  
navigator.device.capture.captureImage(captureSuccess, captureError, options);‎</syntaxhighlight>  
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  
* المعامل <code>limit</code> غير مدعوم في هذه المنصة، لذلك لا يمكن التقاط إلا صورة واحدة فقط عند كل استدعاء.  
* الخاصية <code>limit</code> غير مدعومة في هذه المنصة، لذلك لا يمكن التقاط إلا صورة واحدة فقط عند كل استدعاء.  


==<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>: تمثل المدة القصوى لمقطع الفيديو بالثواني.  
=== مثال ===
إليك المثال التالي حول الكائن <code>CaptureVideoOptions</code>:<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 فيديوهات
<syntaxhighlight lang="javascript">// حصر عدد عمليات الالتقاط في 3 فيديوهات
var options = { limit: 3 };
var options = { limit: 3 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎</syntaxhighlight>  
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎</syntaxhighlight>  
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  
* يتم تجاهل الخاصية <code>limit</code>. لذلك لا يُسجّل إلا مقطع فيديو واحد فقط عند كل استدعاء.  
* يتم تجاهل الخاصية <code>limit</code>. لذلك، لا يُسجّل إلا مقطع فيديو واحد فقط عند كل استدعاء.  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  
* تدعم منصة أندرويد خاصيةً <code>quality</code> إضافية، للسماح بتصوير مقاطع الفيديو بجودات مختلفة. القيمة <code>1</code> (الافتراضية) تشير إلى جودة عالية، والقيمة <code>0</code> تعني جودة منخفضة، والتي تكون عادةً مناسبةً لرسائل MMS. انظر [http://developer.android.com/reference/android/provider/MediaStore.html#EXTRA_VIDEO_QUALITY هذه الصفحة] لمزيد من التفاصيل.  
* تدعم منصة أندرويد الخاصية <code>quality</code> الإضافية، التي تسمح بتصوير مقاطع الفيديو بجودات مختلفة. القيمة <code>1</code> (الافتراضية) تشير إلى جودة عالية، والقيمة <code>0</code> تعني جودة منخفضة، والتي تكون عادةً مناسبةً لرسائل MMS. انظر [http://developer.android.com/reference/android/provider/MediaStore.html#EXTRA_VIDEO_QUALITY هذه الصفحة] لمزيد من التفاصيل.  
=== مثال ===
اطلع على المثال التالي الذي يشرح كيفية استعمال الكائن <code>CaptureVideoOptions</code>:<syntaxhighlight lang="javascript">// حصر عدد عمليات التصوير في فيديو واحد بجودةٍ منخفضة
<syntaxhighlight lang="javascript">// حصر عدد عمليات التصوير في فيديو واحد بجودةٍ منخفضة
var options = { limit: 1, quality: 0 };
var options = { limit: 1, quality: 0 };
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎</syntaxhighlight>  
navigator.device.capture.captureVideo(captureSuccess, captureError, options);‎</syntaxhighlight>  


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


كل كائنٍ من كائنات <code>MediaFile</code> يصف أحد ملفات الوسائط المُلتقطة.  
كل كائنٍ من كائنات <code>MediaFile</code> يصف أحد ملفات الوسائط المُلتقطة. <syntaxhighlight lang="javascript">// رد نداء الالتقاط
=== مثال ===
<syntaxhighlight lang="javascript">// رد نداء الالتقاط
function captureSuccess(mediaFiles) {
function captureSuccess(mediaFiles) {
     var i, path, len;
     var i, path, len;
سطر 226: سطر 211:
};‎</syntaxhighlight>  
};‎</syntaxhighlight>  


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


==<code>CaptureErrorCB</code>==  
==<code>CaptureErrorCB</code>==  
يُستدعى رد النداء <code>CaptureErrorCB</code> في حالة حدوث خطأ أثناء عملية التقاط الوسائط.  
يُستدعى رد النداء <code>CaptureErrorCB</code> في حالة حدوث خطأ أثناء عملية التقاط الوسائط.  
<syntaxhighlight lang="javascript">function captureError( CaptureError error ) { ... };‎</syntaxhighlight>  
<syntaxhighlight lang="javascript">function captureError( CaptureError error ) { ... };‎</syntaxhighlight>تنفذ هذه الدالة في حالة حدوث خطأ أثناء محاولة التقاط الوسائط. هناك عدة أخطاء ممكنة، مثل انشغال تطبيق الالتقاط بشيء آخر، أو أنّ هناك عملية التقاط أخرى تجري في ذلك الوقت، أو أنّ المستخدم قد ألغى العملية قبل أي التقاطٍ. 
===الوصف===


تنفذ هذه الدالة في حالة حدوث خطأ أثناء محاولة التقاط الوسائط. من الأخطاء الممكنة، نجد انشغال تطبيق الالتقاط بشيء آخر، أو أنّ هناك عملية التقاط أخرى تجري في ذلك الوقت، أو أنّ المستخدم قد ألغى العملية قبل أي التقاطٍ.
تنفذ هذه الدالة مع إعطائها كائنًا من النوع <code>CaptureError</code> يحتوي على رمز الخطأ <code>code</code> المقابل. <syntaxhighlight lang="javascript">// رد نداء الخطأ الخاص بالالتقاط
 
تنفذ هذه الدالة مع إعطائها كائنًا <code>CaptureError</code> يحتوي على رمز الخطأ المقابل <code>code</code>.  
=== مثال ===
<syntaxhighlight lang="javascript">// رد نداء الخطأ الخاص بالالتقاط
var captureError = function(error) {
var captureError = function(error) {
     navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
     navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};‎</syntaxhighlight>  
};‎</syntaxhighlight>  


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


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


يجب أن تلتزم أنواع MIME بالمعيار [http://www.ietf.org/rfc/rfc2046.txt RFC2046]. من أمثلة ذلك:  
يجب أن تلتزم أنواع MIME بالمعيار [http://www.ietf.org/rfc/rfc2046.txt RFC2046]. من أمثلة ذلك:  
سطر 264: سطر 243:
*<code>audio/amr</code>  
*<code>audio/amr</code>  
*<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>: عدد يحدِّد عرض الصورة أو الفيديو بالبكسل. قيمة هذه الخاصية تساوي الصفر بالنسبة لمقاطع الصوت.  
=== مثال ===
إليك المثال التالي:<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: سطر 259:
}‎</syntaxhighlight>  
}‎</syntaxhighlight>  


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


==<code>MediaFile.getFormatData</code>==  
==<code>MediaFile.getFormatData</code>==  
سطر 288: سطر 266:
     MediaFileDataSuccessCB successCallback,
     MediaFileDataSuccessCB successCallback,
     [MediaFileDataErrorCB errorCallback]
     [MediaFileDataErrorCB errorCallback]
);‎</syntaxhighlight>  
);‎</syntaxhighlight>يحاول هذا التابع بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسيستدعي رد النداء <code>MediaFileDataSuccessCB</code> مع إعطائه كائنًا من النوع <code>MediaFileData</code>. وإذا فشلت المحاولة، ستستدعي ردَّ النداء <code>MediaFileDataErrorCB</code>.
===الوصف===


تحاول هذه الدالة بشكل غير متزامن استرداد معلومات التنسيق لملف الوسائط. في حالة نجاح ذلك، فسستستدعي رد النداء <code>MediaFileDataSuccessCB</code> مع إعطائه كائنًا <code>MediaFileData</code>. وإذا فشلت المحاولة، ستستدعي هذه الدالةُ رد النداء <code>MediaFileDataErrorCB</code>.
المنصات المدعومة هي:
=== المنصات المدعومة ===
*[[Cordova/platforms android|أندرويد]]
*أندرويد  
*[[Cordova/platforms ios|iOS]]
*iOS  
*[[Cordova/platforms windows|ويندوز]]
*ويندوز  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  


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


==MediaFile==  
==الكائن <code>MediaFile</code>==  
يغلف هذا التابع خاصيات ملف الوسائط المُلتقط.  
يحتوي هذا الكائن خاصيات ملف الوسائط المُلتقط.  
=== خاصيات ===  
=== الخاصيات ===  
* <code>name</code>: اسم الملف، دون معلومات المسار. (<code>DOMString</code>)  
* <code>name</code>: اسم الملف، دون معلومات المسار. (<code>DOMString</code>)  
* <code>fullPath</code>: المسار الكامل للملف، بما في ذلك الاسم. (<code>DOMString</code>)  
* <code>fullPath</code>: المسار الكامل للملف، بما في ذلك الاسم. (<code>DOMString</code>)  
* <code>type</code>: نوع mime الخاص بالملف (<code>DOMString</code>)  
* <code>type</code>: نوع MIME الخاص بالملف. (<code>DOMString</code>)  
* <code>lastModifiedDate</code>: تاريخ ووقت آخر تعديل على الملف. (<code>Date</code>)  
* <code>lastModifiedDate</code>: تاريخ ووقت آخر تعديل على الملف. (<code>Date</code>)  
* <code>size</code>: حجم الملف بعدد البايتات. (عدد)  
* <code>size</code>: حجم الملف بعدد البايتات. (<code>Number</code>)  
===توابع===  
===التوابع===  
* <code>MediaFile.getFormatData</code>: يعيد هذا التابع معلومات التنسيق الخاصة بملف الوسائط.  
* <code>MediaFile.getFormatData</code>: يعيد هذا التابع معلومات التنسيق الخاصة بملف الوسائط.  


==<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>: عدد يحدد طول مقطع الفيديو أو الصوت بالثواني. قيمة هذه الخاصية تساوي الصفر بالنسبة للصور.  
===ملاحظات خاصة بمنصة أندرويد ===  
===ملاحظات خاصة بمنصة أندرويد ===  


تدعم أندرويد خاصيات <code>MediaFileData</code> التالية:  
تدعم أندرويد خاصيات الكائن <code>MediaFileData</code> التالية:  
* <code>codecs</code>: غير مدعومة، وتُعيد <code>null</code>.  
* <code>codecs</code>: غير مدعومة، وتُعيد <code>null</code>.  
* <code>bitrate</code>: غير مدعومة، وتُعيد صفر.  
* <code>bitrate</code>: غير مدعومة، وتُعيد صفر.  
* <code>height</code>: مدعومة، لكن فقط لملفات الصور والفيديو.  
* <code>height</code>: مدعومة، ولكن فقط لملفات الصور والفيديو.  
* <code>width</code>: مدعومة, لكن لملفات الصور والفيديو فقط.  
* <code>width</code>: مدعومة ولكن لملفات الصور والفيديو فقط.  
* <code>duration</code>: مدعومة، لكن لملفات الصوت والفيديو فقط.  
* <code>duration</code>: مدعومة، ولكن لملفات الصوت والفيديو فقط.  
=== ملاحظات خاصة بمنصة iOS ===  
=== ملاحظات خاصة بمنصة iOS ===  


تدعم منصة iOS خاصيات <code>MediaFileData</code> التالية:  
تدعم منصة iOS خاصيات الكائن <code>MediaFileData</code> التالية:  
* <code>codecs</code>: غير مدعومة، وتُعيد <code>null</code>.  
* <code>codecs</code>: غير مدعومة، وتُعيد <code>null</code>.  
* <code>bitrate</code>: مدعومة على أجهزة iOS4، للصوت فقط. فيما تُعيد الصفر للصور ومقاطع الفيديو.  
* <code>bitrate</code>: مدعومة على أجهزة iOS4، للصوت فقط. فيما تُعيد القيمة 0 للصور ومقاطع الفيديو.  
* <code>height</code>: مدعومة، لكن لملفات الصور والفيديو فقط.  
* <code>height</code>: مدعومة، لكن لملفات الصور والفيديو فقط.  
* <code>width</code>: مدعومة، لكن لملفات الصور والفيديو فقط.  
* <code>width</code>: مدعومة، لكن لملفات الصور والفيديو فقط.  
سطر 341: سطر 317:
== ملاحظات خاصة حول دورة حياة أندرويد (Android Lifecycle Quirks) ==  
== ملاحظات خاصة حول دورة حياة أندرويد (Android Lifecycle Quirks) ==  


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


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


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


تتَبُّع أيِّ أجزاء شيفرتك تصدر عنها هذه النتائج متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين [[Cordova/events#pause|pause]] و [[Cordova/events#resume|resume]] بالشكل المناسب. يرجى ملاحظة أن هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر [[Cordova/webviews|العارض]] أثناء عملية الالتقاط.
تتَبُّع أيِّ الأجزاء التي يصدر عنها هذه النتائج في شيفرتك أمرٌ متروكٌ لك. تأكد من حفظ حالة تطبيقك واستعادتها في الحدثين [[Cordova/events#pause|<code>pause</code>]] و [[Cordova/events#resume|<code>resume</code>]] بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر [[Cordova/webviews|العارض]] أثناء عملية الالتقاط.
== انظر أيضا==
== انظر أيضًا==
*إضافة <nowiki/>[[Cordova/cordova plugin media|تسجيل الصوت]]
*إضافة <nowiki/>[[Cordova/cordova plugin media|تسجيل الصوت]]
*إضافة <nowiki/>[[Cordova/cordova plugin file|الوصول إلى الملفات]]
*إضافة <nowiki/>[[Cordova/cordova plugin file|الوصول إلى الملفات]]
*[[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]]
*[[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]]
*[[Cordova/privacy|إدارة الخصوصية]]
==مصادر==
==مصادر==
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-media-capture/index.html صفحة cordova-plugin-media-capture في توثيق كوردوفا الرسمي.]
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-media-capture/index.html صفحة cordova-plugin-media-capture في توثيق كوردوفا الرسمي.]

المراجعة الحالية بتاريخ 21:36، 3 ديسمبر 2020

تمكّن إضافة الوصول إلى الوسائط المتعددة (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‎

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

الكائنات

  • 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.

المنصات المدعومة هي:

مثال على استعمال التابع captureAudio:

// رد نداء الالتقاط
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.

المنصات المدعومة هي:

ملاحظات خاصة بمنصة 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.

المنصات المدعومة هي:

مثال عن استعمال التابع captureVideo:

// رد نداء الالتقاط
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: تمثل المدة القصوى للمقاطع الصوتية بالثانية.

إليك المثال التالي حول استعمال الكائن CaptureAudioOptions:

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

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

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

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

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

الكائن CaptureImageOptions

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

الخاصيات

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

إليك المثال التالي حول استعمال الكائن CaptureImageOptions:

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

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

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

الكائن CaptureVideoOptions

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

الخاصيات

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

إليك المثال التالي حول الكائن CaptureVideoOptions:

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

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

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

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

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

اطلع على المثال التالي الذي يشرح كيفية استعمال الكائن CaptureVideoOptions:

// حصر عدد عمليات التصوير في فيديو واحد بجودةٍ منخفضة
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.

المنصات المدعومة هي:

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

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

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

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

الكائن MediaFile

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

الخاصيات

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

التوابع

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

الكائن MediaFileData

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

الخاصيات

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

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

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

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

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

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

  • codecs: غير مدعومة، وتُعيد null.
  • bitrate: مدعومة على أجهزة iOS4، للصوت فقط. فيما تُعيد القيمة 0 للصور ومقاطع الفيديو.
  • 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 بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر العارض أثناء عملية الالتقاط.

 انظر أيضًا

مصادر