الفرق بين المراجعتين لصفحة: «Cordova/cordova plugin media capture»
لا ملخص تعديل |
تحديث |
||
(3 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:إضافة الوصول إلى الوسائط المتعددة في كوردوفا}}</noinclude> | <noinclude>{{DISPLAYTITLE:إضافة الوصول إلى الوسائط المتعددة في كوردوفا}}</noinclude> | ||
[[تصنيف: Cordova]] | [[تصنيف: Cordova]] | ||
[[تصنيف: Plugin]] | [[تصنيف: Cordova Plugin]] | ||
تمكّن إضافة الوصول إلى الوسائط المتعددة ( | تمكّن إضافة الوصول إلى الوسائط المتعددة (cordova-plugin-media-capture) من التقاط الصور وتسجيل الصوت والفيديو على الجهاز. | ||
'''تنبيه''': جمع واستخدام الصور أو الفيديوهات أو الصوتيات من الكاميرا أو الميكروفون | '''تنبيه''': جمع واستخدام الصور أو الفيديوهات أو الصوتيات من الكاميرا أو الميكروفون الخاص بالجهاز يثير مخاوف متعلقة بالخصوصية. يجب أن تناقش سياسةُ الخصوصيةُ في تطبيقك كيفية استخدام التطبيق لهذه الحساسات، وما إن كانت البيانات المسجّلة ستُتشارك مع أطراف أخرى. بالإضافة إلى ذلك، إذا لم يكن استخدام الكاميرا أو الميكروفون واضحًا في واجهة المستخدم، فيجب عليك تقديم إشعار فوري قبل محاولة التطبيق الوصولَ إلى الكاميرا أو الميكروفون (إن لم يكن نظام التشغيل يفعل ذلك بالفعل). ينبغي أن يوفر هذا الإشعار نفس المعلومات المذكورة أعلاه، إضافةً إلى استئذان المُستخدم (على سبيل المثال، عبر تقديم خيارات من قبيل '''حسنًا''' و '''لا شكرًا'''). لاحظ أنّ بعض متاجر التطبيقات قد تُلزم تطبيقك بتقديم إشعار فوري واستئذان المستخدم قبل استخدام الكاميرا أو الميكروفون. لمزيد من المعلومات، يرجى الاطلاع على [[Cordova/privacy|دليل الخصوصية]]. | ||
تعرّف هذه الإضافة كائنًا عامًّا <code>navigator.device.capture</code>. | تعرّف هذه الإضافة كائنًا عامًّا هو <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>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>يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل | );</syntaxhighlight>يبدأ هذا التابع عمليةً غير متزامنةٍ لتسجيل المقاطع الصوتية باستخدام تطبيق تسجيل الصوت الافتراضي للجهاز. تسمح هذه العملية لمستخدم الجهاز بالتقاط عدة تسجيلات في جلسةٍ (session) واحدة. | ||
تنتهي عملية | تنتهي عملية التسجيل عند خروج المستخدم من تطبيق تسجيل الصوت، أو عند بلوغ الحد الأقصى من التسجيلات المحدد من قبل المعامل <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>. | ||
*أندرويد | المنصات المدعومة هي: | ||
*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 على تطبيق افتراضي لتسجيل الصوت، لذا يتم توفير واجهة مستخدم بسيطة. | ||
=== ملاحظات خاصة بمنصتي 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>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، | منذ الإصدار العاشر من منصة 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 الخاص بالملف | لا يمكن عرض الصور باستخدام عنوان 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>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>. | ||
المنصات المدعومة هي: | |||
*أندرويد | *[[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> غير مدعومة في منصة أندرويد. لذا لا يمكن تقييد طول مدة التسجيل برمجيًّا. | ||
=== ملاحظات خاصة بمنصة iOS === | === ملاحظات خاصة بمنصة 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>CaptureVideoOptions</code>== | ==الكائن <code>CaptureVideoOptions</code>== | ||
يحتوي هذا الكائن على الإعدادات التي تضبط عملية التقاط الفيديو. | |||
=== | === الخاصيات === | ||
* <code>limit</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>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> بعد مرور عمليةِ التقاط أو تصوير | يُستدعى رد النداء <code>CaptureCB</code> بعد مرور عمليةِ التقاط أو تصوير الوسيط (media) بنجاحٍ. | ||
<syntaxhighlight lang="javascript">function captureSuccess( MediaFile[] mediaFiles ) { ... };</syntaxhighlight> | <syntaxhighlight lang="javascript">function captureSuccess( MediaFile[] mediaFiles ) { ... };</syntaxhighlight>تُنفذ هذه الدالة بعد اكتمال عملية الالتقاط بنجاح. عند هذه النقطة، يكون ملف الوسائط (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> يحتوي على رمز الخطأ | |||
<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) التي يدعمها الجهاز. تتضمن بيانات | يتضمّن الكائن <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>: تحتوي هذه الخاصية على | * <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>. | ||
المنصات المدعومة هي: | |||
*[[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>: نوع | * <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>: متوسط | * <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|عارض]] كوردوفا إلى الخلفية من قِبل تطبيق الالتقاط الأصلي. راجع صفحة [[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> | في هذه الحالة، لن يُطلق ردّ نداء النجاح أو الفشل المُمرّر إلى التابع <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|<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
بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر العارض أثناء عملية الالتقاط.