إضافة الوصول إلى الوسائط المتعددة في كوردوفا

من موسوعة حسوب
اذهب إلى: تصفح، ابحث

تمكّن إضافة الوصول إلى الوسائط المتعددة (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 بالشكل المناسب. يرجى ملاحظة أنّ هذه الأحداث لن تُطلق إلا على منصة أندرويد، وفقط إذا دُمِّر العارض أثناء عملية الالتقاط.

 انظر أيضًا

مصادر