الإضافة 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 لتوليد المستندات.
بتـالف التوثيق من قالب، وملفات الواجهة البرمجية المُستخلصة من شيفرة جافاسكريبت الخاصة بالإضافة، يجب إعادة إنشاء التوثيق قبل كل عملية التزام - 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.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
- أوبونتو
يمكن الحصول على المزيد من الأمثلة والملاحظات المخصوصة بمنصات محددة أسفله.
النوع: getPicture
هو تابع ثابت (static method) للكائن camera
.
المعاملات
المعامل | النوع | الشرح |
---|---|---|
successCallback
|
onSuccess
|
|
errorCallback
|
onError
|
|
options
|
CameraOptions
|
خيارات الكاميرا |
مثال
navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);
خيارات (iOS)
CameraUsesGeolocation
(قيمة منطقية، القيمة الافتراضية تساويfalse
). لالتقاط صور JPEG، اضبط هذا الخيار عند القيمةtrue
للحصول على بيانات الموقع الجغرافي في رأس الملف EXIF. سيؤدي هذا إلى إرسال طلبية للحصول على أذونات تحديد الموقع الجغرافي إذا تم إعطاؤها القيمةtrue
.
<preference name="CameraUsesGeolocation" value="false" />
ملاحظات خاصة بمنصة Amazon Fire
تستخدم منصة Amazon Fire مقاصدًا (intents) لبدء نشاط الكاميرا على الجهاز لالتقاط الصور، وعلى الهواتف ذات الذاكرة المنخفضة، قد يفشل هذا النشاط. وفي تلك الحالة، قد لا تظهر الصورة عند استئناف النشاط.
ملاحظات خاصة بمنصة أندرويد
يستخدم أندرويد المقاصد (intents) لإطلاق نشاط الكاميرا على الجهاز لالتقاط الصور، وعلى الهواتف ذات الذاكرة المنخفضة، قد يفشل النشاط. وفي تلك الحالة، سيتم تسليم النتيجة المعادة من استدعاء الإضافة عبر الحدث resume
. راجع صفحة دليل دورة الحياة في أندرويد لمزيد من المعلومات. ستحتوي pendingResult.result
على القيمة التي ستُمرّر إلى الاستجابات - callbacks - (إما عنوان URL أو رسالة خطأ). تحقق من قيمة pendingResult.pluginStatus
لتحديد ما إذا كان الاستدعاء ناجحًا أم لا.
ملاحظات خاصة بالمتصفحات (Browsers)
لا تعيد إلا الصورالمشفرة وفق الترميز Base64 فقط.
ملاحظات خاصة بمنصة Firefox
يتم حاليًا تقديم إضافة الكاميرا باستخدام نشاطات الويب.
ملاحظات خاصة بمنصة iOS
يمكن أن يتسبب تضمين دالة جافااسكريبت alert()
في أيٍّ من دوال الاستجابة (callback functions) إلى حدوث مشاكل. غلّف (Wrap) التنبيه داخل الدالة setTimeout()
للسماح لمنتقي الصور (image picker) أو العنصر المنبثق popover في منصة iOS بالإغلاق الكامل قبل عرض التنبيه:
setTimeout(function() {
// افعل ما تريد هنا
}, 0);
ملاحظات خاصة بمنصة Windows Phone 7
استدعاء تطبيق الكاميرا الأصلي أثناء وصل الجهاز عبر Zune لن ينجح، وسيطلق دالة خطأ (error callback).
ملاحظات خاصة بمنصة ويندوز
على منصة 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 تنبيه: لا يُنصح باستخدام
* يستهلك الذاكرة، حتى مع إعدادات الجودة الضعيفة، استخدامه DATA_URL
* FILE_URI قد يؤدي إلى إطلاق أخطاء الذاكرة وإلى تعطل التطبيق، استخدم
* بدلا منه NATIVE_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
مثال
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
دالة استجابة تُوفّر بيانات الصورة.
النوع: اسم نوع (typedef) ثابت للكائن camera
المعاملات
المعامل | النوع | الشرح |
---|---|---|
imageData
|
سلسلة نصية | ترميز لبيانات الصورة وفق الترميز Base64، أو عنوان (URI) لملف الصورة، اعتمادًا على الخيار cameraOptions الساري.
|
مثال
// إظهار الصورة
//
function cameraCallback(imageData) {
var image = document.getElementById('myImage');
image.src = "data:image/jpeg;base64," + imageData;
}
camera.CameraOptions
كائن يضم معاملات اختيارية لتخصيص إعدادات الكاميرا.
النوع: اسم نوع (typedef) ثابت للكائن 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 و 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 //Corrects Android orientation quirks
}
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
. تتلقى دالة الاستجابة للنجاح (success handler) الخاصة بالتابع 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_device
- دليل تطوير الإضافات في كوردوفا