Cordova/cordova plugin camera

تُعرّف إضافة الكاميرا (cordova-plugin-camera) كائنًا عامًّا هو navigator.camera يوفر واجهة برمجية لالتقاط الصور، واختيار الصور من مكتبة الصور داخل النظام.

على الرغم من أنَّ الكائن navigator.camera مربُوطٌ بالنطاق العام (global scope) للكائن navigator، إلا أنه لا يكون متوفرًا إلا بعد إطلاق الحدث deviceready.

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

التثبيت

يتطلب تثبيت هذه الإضافة الإصدار 5.0 من كوردوفا أو ما بعده:

cordova plugin add cordova-plugin-camera‎

لا يزال بالإمكان تثبيت هذه الإضافة على الإصدارات القديمة من كوردوفا عبر المُعرِّف المهمل:

cordova plugin add org.apache.cordova.camera‎

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

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

توليد التوثيق آليًا

تنبيه: قم بتنفيذ الأمر npm install في مستودع الإضافة لتمكين التوليد التلقائي للتوثيق إن كنت تخطط لإرسال وثائق العلاقات العامة (PR). المستندات تٌُولدها الأداة jsdoc-to-markdown.

يتألف التوثيق من قالب، وملفات الواجهة البرمجية المُستخلصة من شيفرة JavaScript الخاصة بالإضافة؛ يجب إعادة إنشاء التوثيق قبل كل عملية commit (يتم إجراؤها تلقائيًا بواسطة الأداة husky، عبر تنفيذ الأمر npm run gen-docs مع الخطاف precommit - راجع الملف package.json لمزيد من التفاصيل -).

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

منذ الإصدار iOS 10، صار من الإلزامي تقديم وصف للاستخدام (usage description) في الملف info.plist إن كنت تريد الوصول إلى البيانات الحساسة. عندما يستأذن النظام المستخدم للوصول إلى تلك المعلومات، سيُعرض وصف الاستخدام ذاك كجزء من مربع الاستئذان (permission dialog box)، ولكن إذا لم تُوفِِّر وصف الاستخدام، فسيتعطل التطبيق قبل عرض مربع الحوار. كما سترفض Apple التطبيقات التي تصل إلى البيانات الخاصة دون أن تقدم وصفًا للاستخدام.

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

• NSCameraUsageDescription: يحدد سبب وصول تطبيقك إلى كاميرا الجهاز.
• NSPhotoLibraryUsageDescription: يحدد سبب وصول تطبيقك إلى مكتبة صور المستخدم.
• NSLocationWhenInUseUsageDescription: يحدد سبب وصول تطبيقك إلى المعلومات الجغرافية التي تحدد موقع المستخدم أثناء استخدام التطبيق. (عيِّن هذا الوصف إن تم تعيين الخيار CameraUsesGeolocation إلى القيمة true).
• NSPhotoLibraryAddUsageDescription: يحدد سبب طلب تطبيقك إذن الوصول بالكتابة فقط (write-only access) إلى مكتبة صور المستخدم.

لإضافة هذه المُدخلات إلى الملف 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="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need photo library access to get pictures from there</string>
</edit-config>‎

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

<edit-config target="NSPhotoLibraryAddUsageDescription" file="*-Info.plist" mode="merge">
    <string>need photo library access to save pictures there</string>
</edit-config>‎

الواجهة البرمجية (API)

الكائن camera

في هذ القسم، نقدم وصفًا لتوابع وخاصيات الكائن camera.

camera.getPicture(successCallback، errorCallback، options)‎

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

تُمرّر الصورة إلى دالة رد نداء النجاح (success callback) كسلسلة نصية مُرمّزة بالترميز Base64، أو على هيئة عنوانٍ (URI) يشير إلى ملف الصورة.

يفتح التابع camera.getPicture تطبيق الكاميرا الافتراضي للجهاز، والذي يسمح للمستخدمين بالتقاط الصور بشكل افتراضي، إذ يحدث هذا السلوك عندما تتساوى الخاصيتان Camera.sourceType و Camera.PictureSourceType.CAMERA. بمجرد أن يلتقط المستخدم الصورة، يُغلق تطبيق الكاميرا ويُسترجَع (restored) التطبيق.

إن كانت الخاصية Camera.sourceType تساوي Camera.PictureSourceType.PHOTOLIBRARY أو Camera.PictureSourceType.SAVEDPHOTOALBUM، فسيظهر مربع حوار يعرض على المستخدمين اختيار إحدى الصور الموجودة.

تُرسَل القيمة المعادة إلى دالة رد نداء النجاح cameraSuccess، وفق إحدى التنسيقات التالية، اعتمادًا على الخيار cameraOptions المحدد:

• سلسلة نصية String مرمَّزة الترميز Base64 الخاص بالصورة.
• سلسلة نصية String تمثل موضع ملف الصورة في الذاكرة المحلية (السلوك الافتراضي).

يمكنك أن تفعل ما تريد بالصورة المرمّزة أو عنواها مثل:

• عرض (Render) الصورة في الوسم <img>، كما هو موضح في المثال أدناه، أو
• حفظها محليًّا (LocalStorage أو Lawnchair ...إلخ)، أو
• نشرها إلى خادم بعيد.

ملاحظة: دقة الصور على الأجهزة الحديثة أصبحت ممتازة. لا تُصغّر جودة الصور المختارة من معرض الجهاز، حتى عند تحديد المعامل quality. لتجنب مشاكل الذاكرة الشائعة، اضبط الخاصية Camera.destinationType إلى القيمة FILE_URI بدلًا من DATA_URL.

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

• أندرويد
• بلاك بيري
• Browser
• فايرفوكس
• FireOS
• iOS
• ويندوز
• WP8
• أوبنتو

يمكن الحصول على المزيد من الأمثلة والملاحظات المخصوصة بمنصات محددة أسفله.

النوع: هو تابع ثابت (static method) للكائن camera.

المعاملات

المعامل	النوع	الشرح
successCallback	onSuccess	رد نداء نجاح العملية.
errorCallback	onError	رد نداء فشل العملية.
options	CameraOptions	خيارات الكاميرا

إليك المثال التالي:

navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);‎

ملاحظات خاصة بمنصة Amazon Fire

تستخدم منصة Amazon Fire مقاصدًا (intents) لبدء نشاط الكاميرا على الجهاز لالتقاط الصور، وقد يفشل النشاط على الهواتف ذات الذاكرة المنخفضة. وفي تلك الحالة، قد لا تظهر الصورة عند استئناف النشاط.

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

يستخدم أندرويد المقاصد (intents) لإطلاق نشاط الكاميرا على الجهاز لالتقاط الصور، وقد يفشل النشاط على الهواتف ذات الذاكرة المنخفضة. وفي تلك الحالة، سيتم تسليم النتيجة المعادة من استدعاء الإضافة عبر الحدث resume. راجع صفحة دليل دورة الحياة في أندرويد لمزيد من المعلومات. ستحتوي pendingResult.result على القيمة التي ستُمرّر إلى ردود النداء (إما عنوان URL أو رسالة خطأ). تحقَّق من قيمة pendingResult.pluginStatus لتحديد ما إذا كان الاستدعاء ناجحًا أم لا.

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

لا تعيد إلا الصور المرمزة وفق الترميز Base64 فقط.

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

يتم حاليًا تقديم إضافة الكاميرا باستخدام نشاطات الويب.

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

تُستعمَل الخاصية CameraUsesGeolocation (قيمة منطقية تساوي false افتراضيًّا) مع العنصر preference لتحديد الموقع الذي التُقطت فيه الصورة. لالتقاط صور JPEG، اضبط هذا الخيار إلى القيمة true للحصول على بيانات الموقع الجغرافي ووضعها في ترويسة الملف EXIF. سيؤدي هذا إلى إرسال طلبية للحصول على أذونات تحديد الموقع الجغرافي إذا تم إعطاؤها القيمة true.

<preference name="CameraUsesGeolocation" value="false" />‎

يمكن أن يتسبب تضمين الدالة alert()‎ التي تخص JavaScript في أيٍّ من دوال رود النداء (callback functions) إلى حدوث مشاكل. غلّف (Wrap) التنبيه داخل الدالة setTimeout()‎ للسماح لمنتقي الصور (image picker) أو العنصر المنبثق (popover) في منصة iOS بالإغلاق الكامل قبل عرض التنبيه:

setTimeout(function() {
    // افعل ما تريد هنا
}, 0);‎

ملاحظات خاصة بمنصة Windows Phone 7

استدعاء تطبيق الكاميرا الأصلي أثناء وصل الجهاز عبر Zune لن ينجح، وسيطلق رد نداء مع الخطأ الحاصل.

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

في منصة Windows Phone 8.1، استخدام SAVEDPHOTOALBUM أو PHOTOLIBRARY كنوع مصدري (source type) سيؤدي إلى تجميد التطبيق إلى حين إعادة منتقي الملفات (file picker) للصورة المختارة، ثم يستأنف بصفحة البداية كما هو موضح في ملف التطبيق config.xml. في حالة استدعاء camera.getPicture من صفحة أخرى، سيؤدي ذلك إلى إعادة تحميل صفحة البداية مرة أخرى، ولن تُستدعى ردي نداء النجاح والخطأ.

لتجنب هذا السلوك، نقترح استخدام نمط التطبيقات أحادية الصفحة (SPA)، أو استدعاء التابع camera.getPicture لأجل صفحة بدء التطبيق فقط.

لمزيد من المعلومات حول الواجهات البرمجية للمنتقي (picker) في Windows Phone 8.1، راجع الصفحة: "كيف يمكن أن يستمر تطبيقك على ويندوز بعد استدعاء منتقي الملفات".

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

لا تدعم Tizen إلا الخاصية destinationType التي تخص Camera.DestinationType.FILE_URI أو الخاصية sourceType التي تخص Camera.PictureSourceType.PHOTOLIBRARY.

أمثلة

المثال التالي سيلتقط صورة ويستعيد موضع ملف الصورة:

navigator.camera.getPicture(onSuccess, onFail, { quality: 50,
    destinationType: Camera.DestinationType.FILE_URI });
function onSuccess(imageURI) {
    var image = document.getElementById('myImage');
    image.src = imageURI;
}
function onFail(message) {
    alert('Failed because: ' + message);
}‎

المثال التالي سيلتقط صورة ويستردها وفق الترميز Base64:

/**
 * لأنه يستهلك الذاكرة حتى مع DATA_URL تنبيه: لا يُنصح باستخدام
 * مع إعدادات الجودة الضعيفة؛ استخدامه قد يؤدي إلى إطلاق أخطاء 
 * NATIVE_URI أو FILE_URI  الذاكرة وإلى تعطل التطبيق. استخدم
 * .بدلا منه
 */
navigator.camera.getPicture(onSuccess, onFail, { quality: 25,
    destinationType: Camera.DestinationType.DATA_URL
});
function onSuccess(imageData) {
    var image = document.getElementById('myImage');
    image.src = "data:image/jpeg;base64," + imageData;
}
function onFail(message) {
    alert('Failed because: ' + message);
}‎

camera.cleanup()‎

يزيل هذا التابع ملفات الصور الوسطية (intermediate image) التي تُحفظ في المخزن المؤقت بعد استدعاء التابع camera.getPicture. ويطبق فقط عندما تساوي Camera.sourceType القيمة Camera.PictureSourceType.CAMERA، وتساوي Camera.destinationType القيمة Camera.DestinationType.FILE_URI.

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

• iOS

النوع: هو ثابت للكائن camera.

مثال

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

navigator.camera.cleanup(onSuccess, onFail);
function onSuccess() {
    console.log("Camera cleanup success.")
}
function onFail(message) {
    alert('Failed because: ' + message);
}‎

camera.onError

دالة رد نداء (callback function) تُستخدم لتوفير رسالة خطأ.

النوع: اسم نوع (typedef) ثابت للكائن camera.

المعاملات

المعامل	النوع	الشرح
message	سلسلة نصية	يتم توفير الرسالة عبر الشيفرة الأصلية للجهاز.

camera.onSuccess

دالة رد نداء تُوفّر بيانات الصورة.

النوع: هو ثابت للكائن camera

المعاملات

المعامل	النوع	الشرح
imageData	سلسلة نصية	سلسلة نصية مرمَّزة وفق الترميز Base64 لمحتوى الصورة، أو عنوان (URI) لملف الصورة، وهذا يتحدد اعتمادًا على الخيار cameraOptions الحالي.

مثال

مثال على استعمال التابع onSuccess لإظهار صورة:

// إظهار الصورة
//
function cameraCallback(imageData) {
   var image = document.getElementById('myImage');
   image.src = "data:image/jpeg;base64," + imageData;
}‎

camera.CameraOptions

كائن يضم معاملات اختيارية لتخصيص إعدادات الكاميرا.

النوع: ثابت للكائن camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
quality	عدد	50	جودة الصورة المحفوظة، ويعبَّر عنها بعدد من المجال 0-100، حيث يمثل العدد 100 الدقة الكاملة، دون أي خسارة نتيجة ضغط الملفات. (لاحظ أن المعلومات حول دقة الكاميرا غير متوفرة.)
destinationType	DestinationType	FILE_URI	اختيار تنسيق القيمة المعادة.
sourceType	PictureSourceType	CAMERA	تحديد مصدر الصورة.
allowEdit	قيمة منطقية	false	السماح بتعديل بسيط على الصورة قبل الاختيار.
encodingType	EncodingType	JPEG	اختيار ترميز ملف الصورة المعادة.
targetWidth	عدد		العرض بالبكسل لتغيير مقياس الصورة. يجب استخدامه مع targetHeight. نسبة أبعاد الصورة (Aspect ratio) تبقى ثابتة.
targetHeight	عدد		الارتفاع بالبكسل لتغيير مقياس الصورة. يجب استخدامه مع targetWidth. نسبة أبعاد الصور تبقى ثابتة.
mediaType	MediaType	PICTURE	تعيين نوع الوسائط (medias) المراد الاختيار من بينها. يعمل هذا المعامل فقط عندما يساوي PictureSourceType القيمة PHOTOLIBRARY أو SAVEDPHOTOALBUM.
correctOrientation	قيمة منطقية		تدوير الصورة لتصحيح اتجاه الجهاز أثناء التقاط الصورة.
saveToPhotoAlbum	قيمة منطقية		حفظ الصورة في ألبوم الصور على الجهاز بعد التقاطها.
popoverOptions	CameraPopoverOptions		خيارات مخصوصة بمنصة iOS فقط، والتي تحدد موضع popover في iPad.
cameraDirection	Direction	BACK	اختيار الكاميرا المراد استخدامها (الأمامية أو الخلفية).

ملاحظات خاصة بمنصة Amazon Fire

• تتجاهل هذه المنصة المعامل allowEdit.
• تعرض كل من Camera.PictureSourceType.PHOTOLIBRARY و Camera.PictureSourceType.SAVEDPHOTOALBUM نفس ألبوم الصور.

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

• أي قيمةٍ للخاصية cameraDirection ستُنتج صورًا خلفية (back-facing photos).
• لا يمكن التنبؤ بسلوك allowEdit على منصة أندرويد: في أندرويد، تحاول هذه الإضافة العثور على تطبيقٍ واستخدامه على جهاز المستخدم لأجل اقتصاص (cropping) الصورة. لا تتحكم الإضافة في التطبيق الذي يحدده المستخدم لإجراء عملية اقتصاص الصور، ومن المحتمل جدًا أن يختار المستخدم خيارًا غير متوافقٍ معها، وهذا قد يتسبب في فشل الإضافة. لا تحدث أية مشاكل في كثير من الأحيان لأن معظم الأجهزة مُزوّدة بتطبيقٍ يعالج الاقتصاص بطريقة متوافقة مع هذه الإضافة (صور Google Plus)، ولكن لا يمكن الاعتماد على هذا دائمًا. إن كان تعديل الصور أمرًا ضروريًا لتطبيقك، ففكّر في استخدام مكتبة أو إضافة خارجية توفر أداة أكثر كفاءة في تعديل للصور.
• تعرض كلٌّ من Camera.PictureSourceType.PHOTOLIBRARY و Camera.PictureSourceType.SAVEDPHOTOALBUM نفس ألبوم الصور.
• تتجاهل منصة أندرويد المعامل encodingType إن لم تكن الصورة معدلة (أي إن كانت قيمة quality تساوي 100، وكانت قيمة correctOrientation تساوي false، ولم تُحدد الخاصيتان targetHeight و targetWidth). سيُعيد مصدر الإضافة CAMERA دائمًا الملف JPEG المعطى من قبل الكاميرا الأصلية، وسيُعيد المصدران PHOTOLIBRARY و SAVEDPHOTOALBUM الملف المحدد وفق ترميزه الحالي.

ملاحظات خاصة بمنصة BlackBerry 10

• تتجاهل هذه المنصة المعامل quality والمعامل allowEdit.
• Camera.MediaType غير مدعوم.
• تتجاهل المعامل correctOrientation والمعامل cameraDirection.

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

• تتجاهل هذه المنصة المعامل quality.
• تتجاهل Camera.DestinationType وتساوي 1 (عنوان [URI] ملف الصورة).
• تتجاهل المعامل allowEdit.
• تتجاهل المعامل PictureSourceType (يختاره المستخدم عبر نافذة الحوار).
• تتجاهل encodingType و targetWidth و targetHeight.
• Camera.MediaType غير مدعوم.
• تتجاهل المعامل correctOrientation والمعامل cameraDirection.

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

• عند استخدام destinationType.FILE_URI، تُحفظ الصور في المجلد المؤقت للتطبيق. تُحذف محتويات مجلد التطبيق المؤقت عند انتهاء التطبيق.
• عند استخدام destinationType.NATIVE_URI و sourceType.CAMERA، تُحفظ الصور في ألبوم الصور المحفوظة، بغض النظر عن قيمة المعامل saveToPhotoAlbum.
• عند استخدام destinationType.NATIVE_URI و sourceType.PHOTOLIBRARY أو sourceType.SAVEDPHOTOALBUM، يتم تجاهل جميع خيارات التعديل، ويعاد رابطٌ يُشير إلى الصورة الأصلية.

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

• الخيارات غير مدعومة.
• يُعاد دائمًا عنوان للملف (FILE URI).

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

• تتجاهل هاتان المنصتان المعاملات allowEdit، و correctOrientation، و cameraDirection،
• تتجاهل هاتان المنصتان المعامل saveToPhotoAlbum. ملاحظة مهمة: دائمًا تُنسخ الصور التي تم التقاطها باستخدام الواجهة البرمجية لإضافة الكاميرا على ويندوز 8 (WP8/8) في ذاكرة ألبوم (roll) الكاميرا الخاصة بالهاتف. استنادًا إلى إعدادات المستخدم، قد يعني هذا أيضًا أن الصورة ستُحمّل تلقائيًا إلى الخدمة OneDrive. يمكن أن يعني هذا أن الصورة ستكون متاحة لجمهور أكبر من الجمهور الذي يستهدفه تطبيقك. إن كان هذا أمرًا غير مرغوب، فستحتاج إلى تنفيذ CameraCaptureTask كما هو مبيّن في توثيق MSDN. يمكنك أن تقوم أيضًا بالتعليق أو التصويت لصالح حل المشكلة في متعقب المشكلات.
• تتجاهل المنصتان الخاصية mediaType في cameraOptions، لأنَّ بيئة العمل SDK في منصة ويندوز لا توفر طريقة لاختيار مقاطع الفيديو من PHOTOLIBRARY.

Camera.DestinationType

تُعرّف الخاصية DestinationType تنسيق مُخرجات استدعاء التابع Camera.getPicture.

ملاحظة: على منصة iOS، تمرير DestinationType.NATIVE_URI إلى جانب PictureSourceType.PHOTOLIBRARY أو PictureSourceType.SAVEDPHOTOALBUM سيُعطل أي تعديلات على الصورة (تغيير الحجم، تغيير الجودة، الاقتصاص، ...إلخ) بسبب اختلاف التنفيذ (implementation) من منصة إلى أخرى.

النوع: خاصية تعداد (enum) ثابتة للكائن Camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
quality	عدد	0	تُعاد سلسلة نصية وفق الترميز base64. تركز DATAURL كثيرًا على الذاكرة، وقد تتسبب في تعطل التطبيق أو نفاذ الذاكرة. استخدم FILEURI أو NATIVE_URI إن أمكن.
FILE_URI	عدد	1	إعادة عنوان uri الملف (content://media/external/images/media/2 لمنصة أندرويد).
sourceType	عدد	2	إعادة العنوان uri الأصلي (مثل asset-library://...‎ في منصة iOS).

Camera.EncodingType

النوع: خاصية تعداد (enum) ثابتة للكائن Camera

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
JPEG	عدد	0	تعيد هذه الخاصية صورة بصيغة JPEG.
PNG	عدد	1	تعيد صورة بصيغة PNG.

Camera.MediaType

النوع: خاصية تعداد (enum) الثابت للكائن Camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
PICTURE	عدد	0	تمكن هذه الخاصية من اختيار الصور الثابتة وحسب. القيمة الافتراضية ستعيد التنسيق المحدد عبر DestinationType.
VIDEO	عدد	1	تسمح باختيار الفيديو فقط، وتعيد العنوان URL وحسب.
ALLMEDIA	عدد	2	تسمح بالاختيار من جميع أنواع الوسائط.

Camera.PictureSourceType

تعرف الخاصية PictureSourceType تنسيق مُخرجات استدعاء التابع Camera.getPicture.

ملاحظة: على منصة iOS، تمرير PictureSourceType.PHOTOLIBRARY أو PictureSourceType.SAVEDPHOTOALBUM إلى جانب DestinationType.NATIVE_URI سيعطل أي تعديلات على الصورة (تغيير الحجم أو تغيير الجودة أو الافتصاص إلخ) بسبب اختلاف طرق التنفيذ (implementation).

النوع: خاصية تعداد (enum) ثابتة للكائن Camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
PHOTOLIBRARY	عدد	0	اختيار صورة من مكتبة الصور في بالجهاز (تشبه SAVEDPHOTOALBUM في أندرويد).
CAMERA	عدد	1	التقاط صورة عبر الكاميرا.
SAVEDPHOTOALBUM	عدد	2	اختيار صورة من ألبوم Camera Roll الموجود في الجهاز (مثل PHOTOLIBRARY في منصة أندرويد).

Camera.PopoverArrowDirection

تطابق هذه الخاصية الثوابت UIPopoverArrowDirection الخاصة بمنصة iOS لتحديد موضع السهم (arrow location) على العنصر المنبثق (popover).

النوع: خاصية تعداد (enum) ثابتة للكائن Camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية
ARROW_UP	عدد	1
ARROW_DOWN	عدد	2
ARROW_LEFT	عدد	3
ARROW_RIGHT	عدد	4
ARROW_ANY	عدد	5

Camera.Direction

النوع: خاصية تعداد (enum) ثابتة للكائن Camera.

الخاصيات

الاسم	النوع	القيمة الافتراضية	الشرح
BACK	عدد	0	استخدام الكاميرا الخلفية.
FRONT	عدد	1	استخدام الكاميرا الأمامية.

CameraPopoverOptions

هذه معاملات مخصوصة بمنصة iOS فقط، إذ تحدد موضع عنصر الإرساء (anchor element) واتجاه السهم في العنصر المُنبثق (popover) عند اختيار الصور من مكتبة أو ألبوم iPad. لاحظ أنه قد يتغير حجم العنصر المنبثق حتى يتكيف مع اتجاه السهم والشاشة. تأكد من أخذ تغييرات الاتجاه بالحسبان عند تحديد موضع عنصر الإرساء.

المعامل	النوع	القيمة الافتراضية	الشرح
[x]	عدد	0	عدد يمثل إحداثيات المحور x بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[y]	عدد	32	عدد يمثل المحور y بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[width]	عدد	320	العرض، بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[height]	عدد	480	الارتفاع بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[arrowDir]	PopoverArrowDirection	ARROW_ANY	الاتجاه الذي يجب أن يشير إليه السهم في العنصر المنبثق.

CameraPopoverHandle

مقبض (handle) لعارض الصور المنبثق (image picker popover).

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

• iOS

مثال

navigator.camera.getPicture(onSuccess, onFail,
{
    destinationType: Camera.DestinationType.FILE_URI,
    sourceType: Camera.PictureSourceType.PHOTOLIBRARY,
    popoverOptions: new CameraPopoverOptions(300, 300, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY)
});
// إعادة موضعة العنصر المنبثق عند تغيير الاتجاه
window.onorientationchange = function() {
    var cameraPopoverHandle = new CameraPopoverHandle();
    var cameraPopoverOptions = new CameraPopoverOptions(0, 0, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY);
    cameraPopoverHandle.setPosition(cameraPopoverOptions);
}‎

طريقة الاستخدام

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

توضح الشيفرات البرمجية في هذا القسم مختلف المهام الممكنة، بما في ذلك:

• فتح الكاميرا والتقاط صورة.
• التقاط صورة وإعادة صورة مصغرة - thumbnail - (صورة مُعدلة الحجم).
• التقاط صورة وإنشاء كائن FileEntry.
• اختيار صورة من مكتبة الصور.
• اختيار صورة بتنسيق JPEG وإعادة صورة مصغرة (صورة مُعدلة الحجم).
• اختيار صورة وإنشاء كائن FileEntry.

التقاط صورة

قبل أن تتمكن من التقاط صورة، تحتاج أولا إلى ضبط بعض خيارات إضافة الكاميرا لأجل تمريرها إلى التابع getPicture.

في هذا المثال، سنُنشِئ الكائن الذي سنستخدمه لأجل خيارات الكاميرا، وستُعيّن الخاصية sourceType ديناميكيًا لدعم كل من إضافة الكاميرا ومنتقي الملفات:

function setOptions(srcType) {
    var options = {
        // من الخيارات الشائعة: 20 - 50 - 100
        quality: 50,
        destinationType: Camera.DestinationType.FILE_URI,
        // في هذا التطبيق، التعيين الديناميكي لمصدر الصورة أو الكاميرا أو ألبوم الصور
        sourceType: srcType,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        allowEdit: true,
        correctOrientation: true  //تصحيح خصوصيات الاتجاه في أندرويد
    }
    return options;
}‎

في العادة، ستحتاج إلى استخدام FILEURI بدلًا من DATAURL لتجنب معظم مشاكل الذاكرة. تعد الصيغة JPEG هي الصيغة الموصى به في منصة أندرويد.

يمكنك التقاط صورة من خلال تمرير كائن الخيارات إلى التابع getPicture، والذي سيأخذ الكائن CameraOptions كوسيط ثالث. عند استدعاء setOptions، قم بتمرير Camera.PictureSourceType.CAMERA كمصدر للصورة.

function openCamera(selection) {
    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;
    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        displayImage(imageUri);
        // يمكنك نسخ الصورة أو تخزينها أو تحميلها
        func(imageUri);
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}‎

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

function displayImage(imgUri) {
    var elem = document.getElementById('imageFile');
    elem.src = imgUri;
}‎

لعرض الصورة على بعض المنصات، قد تحتاج إلى تضمين الجزء الرئيسي من العنوان URI في العنصر Content-Security-Policy من الوسم <meta> في الملف index.html. على سبيل المثال، في منصة ويندوز 10، يمكنك تضمين ms-appdata:‎ في الوسم <meta>.

إليك المثال التالي:

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">‎

التقاط صورة وإعادة صورة مصغرة

للحصول على صور أصغر، يمكنك إعادة صورة مُعدّلة الحجم عن طريق تمرير القيمتين targetHeight و targetWidth مع كائن الخيارات CameraOptions. في هذا المثال، سنغيّر حجم الصورة المعادة لتلائم مربعًا بحجم 100 بكسل × 100 بكسل (يتم الحفاظ على نسبة الأبعاد [aspect ratio]، لذلك فالعدد 100 بكسل سيساوي إما الارتفاع أو العرض، مهما كان الأكبر في المصدر).

function openCamera(selection) {
    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;
    if (selection == "camera-thmb") {
        options.targetHeight = 100;
        options.targetWidth = 100;
    }
    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // افعل شيئا ما
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}‎

اختيار ملف من مكتبة الصور

عند اختيار ملف باستخدام منتقي الملفات، يجب عليك أيضًا تعيين الكائن CameraOptions. في هذا المثال، سنُعيّن الخاصية sourceType عند القيمة Camera.PictureSourceType.SAVEDPHOTOALBUM. ولفتح منتقي الملفات، استدع التابع getPicture تمامًا كما فعلت في المثال السابق، مع تمرير دالة رد نداء النجاح (success callback) والخطأ (error callback) مع الكائن CameraOptions.

function openFilePicker(selection) {
    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;
    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // افعل شيئا ما
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}‎

اختيار صورة وإعادة صورة مصغرة

تغيير حجم الملف المحدد بواسطة منتقي الملفات مشابه لتغيير الحجم باستخدام تطبيق الكاميرا. اضبط قيم الخيارات targetHeight و targetWidth بالشكل التالي:

function openFilePicker(selection) {
    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;
    if (selection == "picker-thmb") {
        // لتصغير الصورة المختارة
        // ينبغي أن تطابق نوع الصورة المختارة (JPEG مثل) Camera.EncodingType  
        options.targetHeight = 100;
        options.targetWidth = 100;
    }
    navigator.camera.getPicture(function cameraSuccess(imageUri) {
        // افعل شيئا ما بالصورة
    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");
    }, options);
}‎

التقاط صورة والحصول على كائن FileEntry

إن كنت تريد القيام بشيء ما مثل نسخ صورة إلى موضع آخر، أو تحميلها إلى مكان ما باستخدام الإضافة FileTransfer، فستحتاج إلى الحصول على الكائن FileEntry للصورة المعادة. للقيام بذلك، استدع التابع window.resolveLocalFileSystemURL على عنوان URI الملف المُعاد من قبل تطبيق الكاميرا. إن كنت بحاجة إلى استخدام كائن FileEntry، اضبط الخيار destinationType إلى القيمة Camera.DestinationType.FILE_URI في الكائن CameraOptions (هذه هي القيمة الافتراضية).

ملاحظة: تحتاج إلى إضافة الملفات لأجل استدعاء window.resolveLocalFileSystemURL.

في المثال التالي سنستدعي window.resolveLocalFileSystemURL. وسنُمرّر عنوان الصورة إلى هذه الدالة عبر دالة رد نداء النجاح (success callback) الخاصة بالتابع getPicture. يستلم معالج عملية النجاح للتابع resolveLocalFileSystemURL الكائنَ FileEntry.

function getFileEntry(imgUri) {
    window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) {
        // مثل الكتابة فيه أو تحميله FileEntry افعل شيئا ما بالكائن
        // writeFile(fileEntry, imgUri);
        console.log("got file: " + fileEntry.fullPath);
        // displayFileData(fileEntry.nativeURL, "Native URL");
    }, function () { 
      // (وهو ما يمكن أن يحدث على بعض المحاكيات) FileEntry  إن لم تحصل على كائن
      //  جديد FileEntry قم بالنسخ في كائن
        createNewFileEntry(imgUri);
    });
}‎

في المثال الموضح في الشيفرة السابقة، يمكنك استدعاء التابع createNewFileEntry في حال لم يكن الكائن FileEntry الذي حصلت عليه صالحًا. يجب أن تنتج الصورة المعادة من قبل تطبيق الكاميرا كائنًا FileEntry صالحًا، ولكن سلوك المنصات على بعض المحاكيات قد يختلف بالنسبة للملفات التي يعيدها منتقي الملفات.

يمكنك الاطلاع على مثال يوضح الكتابة في الكائن FileEntry من هنا.

تنشئ الشيفرة التالية ملفًا في ذاكرة التخزين المؤقت لتطبيقك (في التخزين المحمي sandboxed) باسم tempFile.jpeg. باستخدام الكائن FileEntry الجديد، يمكنك نسخ الصورة إلى الملف، أو القيام بشيء آخر مثل تحميلها.

function createNewFileEntry(imgUri) {
    window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) {
        // JPEG الملف
        dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) {
            // افعل شيئا به، مثل الكتابة فيه أو تحميله
            // writeFile(fileEntry, imgUri);
            console.log("got file: " + fileEntry.fullPath);
            // displayFileData(fileEntry.fullPath, "File copied to");
        }, onErrorCreateFile);
    }, onErrorResolveUrl);
}‎

انظر أيضًا

• إضافة حالة الجهاز
• إضافة الوصول إلى الملفات
• دليل تطوير الإضافات في كوردوفا

مصادر

• صفحة cordova-plugin-camera في توثيق كوردوفا الرسمي.