الفرق بين المراجعتين ل"Cordova/cordova plugin camera"
سطر 60: | سطر 60: | ||
يُمكّن التابع <code>getPicture</code> من التقاط صورة باستخدام الكاميرا، أو الحصول على صورة من معرض الصور في الجهاز. | يُمكّن التابع <code>getPicture</code> من التقاط صورة باستخدام الكاميرا، أو الحصول على صورة من معرض الصور في الجهاز. | ||
− | تُمرّر الصورة إلى دالة النجاح (success callback) | + | تُمرّر الصورة إلى دالة النجاح (success callback) كسلسلة نصية مُرمّز بالترميز Base64، أو على هيئة عنوانٍ (URI) يشير إلى ملف الصورة. |
− | + | يفتح التابع <code>camera.getPicture</code> تطبيق الكاميرا الافتراضي للجهاز، والذي يسمح للمستخدمين بالتقاط الصور بشكل افتراضي - يحدث هذا السلوك، عندما تتساوى الخاصيتان <code>Camera.sourceType</code> و <code>Camera.PictureSourceType.CAMERA</code>. بمجرد أن يلتقط المستخدم الصورة، يُغلق تطبيق الكاميرا ويُسترجع (restored) التطبيق. | |
− | إن كانت الخاصية <code>Camera.sourceType</code> تساوي <code>Camera.PictureSourceType.PHOTOLIBRARY</code> أو <code>Camera.PictureSourceType.SAVEDPHOTOALBUM</code>، فسيظهر مربع حوار | + | إن كانت الخاصية <code>Camera.sourceType</code> تساوي <code>Camera.PictureSourceType.PHOTOLIBRARY</code> أو <code>Camera.PictureSourceType.SAVEDPHOTOALBUM</code>، فسيظهر مربع حوار يعرض على المستخدمين اختيار إحدى الصور الموجودة. |
− | تُرسل القيمة المعادة إلى دالة | + | تُرسل القيمة المعادة إلى دالة النجاح<code>cameraSuccess</code>، وفق إحدى التنسيقات التالية، اعتمادًا على الخيار <code>cameraOptions</code> المحدد: |
* سلسلة نصية <code>String</code> تحتوي على الترميز-Base64 الخاص بالصورة. | * سلسلة نصية <code>String</code> تحتوي على الترميز-Base64 الخاص بالصورة. | ||
* سلسلة نصية <code>String</code> تمثل موضع ملف الصورة في الذاكرة المحلية (السلوك الافتراضي). | * سلسلة نصية <code>String</code> تمثل موضع ملف الصورة في الذاكرة المحلية (السلوك الافتراضي). | ||
− | يمكنك أن تفعل ما تريد بالصورة المرمّزة أو عنواها، على سبيل المثال: | + | يمكنك أن تفعل ما تريد بالصورة المرمّزة أو عنواها، يمكنك على سبيل المثال: |
* عرض (Render) الصورة في الوسم <code><img></code>، كما هو موضح في المثال أدناه | * عرض (Render) الصورة في الوسم <code><img></code>، كما هو موضح في المثال أدناه | ||
− | * حفظ البيانات محليا ( | + | * حفظ البيانات محليا ([[Cordova/storage#.D8.A7.D9.84.D9.88.D8.A7.D8.AC.D9.87.D8.A9 LocalStorage|LocalStorage]] أو [http://brianleroux.github.com/lawnchair/ Lawnchair]، الخ) |
− | * نشر البيانات إلى خادم بعيد | + | * نشر البيانات إلى خادم بعيد. |
− | ''' | + | '''ملاحظة''': دقة الصور على الأجهزة الحديثة جيدة للغاية. لا تُصغّر جودة الصور المختارة من معرض الجهاز، حتى عند تحديد المعامل <code>quality</code>. لتجنب مشاكل الذاكرة الشائعة، اضبط الخاصية <code>Camera.destinationType</code> عند القيمة <code>FILE_URI</code> بدلاً من <code>DATA_URL</code>. |
− | + | ===== المنصات المدعومة ===== | |
*أندرويد | *أندرويد | ||
*بلاك بيري | *بلاك بيري | ||
سطر 88: | سطر 88: | ||
* أوبونتو | * أوبونتو | ||
− | يمكن الحصول على المزيد من الأمثلة | + | يمكن الحصول على المزيد من الأمثلة والملاحظات المخصوصة بمنصات محددة أسفله. |
− | ''' | + | '''النوع''': <code>getPicture</code> هو تابع ثابت (static method) للكائن <code>camera</code>. |
− | المعامل | + | {| class="wikitable" |
− | النوع | + | !المعامل |
− | الشرح | + | !النوع |
− | successCallback | + | !الشرح |
− | <code>onSuccess</code> | + | |- |
− | errorCallback | + | |<code>successCallback</code> |
− | <code>onError</code> | + | |<code>onSuccess</code> |
− | options | + | | |
− | <code>CameraOptions</code> | + | |- |
− | + | |<code>errorCallback</code> | |
+ | |<code>onError</code> | ||
+ | | | ||
+ | |- | ||
+ | |<code>options</code> | ||
+ | |<code>CameraOptions</code> | ||
+ | |خيارات الكاميرا | ||
+ | |} | ||
− | + | ===== مثال ===== | |
− | <syntaxhighlight lang="javascript">navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);</syntaxhighlight> | + | <syntaxhighlight lang="javascript">navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);</syntaxhighlight> |
− | |||
− | |||
− | |||
+ | ==== <code>camera.cleanup()</code> ==== | ||
يزيل هذا التابع ملفات الصور الوسطية التي تُحفظ في المخزن المؤقت بعد استدعاء [#module_camera.getPicture camera.getPicture]. ويطبق فقط عندما تساوي <code>Camera.sourceType</code> القيمة <code>Camera.PictureSourceType.CAMERA</code> وتساوي <code>Camera.destinationType</code> القيمة <code>Camera.DestinationType.FILE_URI</code>. | يزيل هذا التابع ملفات الصور الوسطية التي تُحفظ في المخزن المؤقت بعد استدعاء [#module_camera.getPicture camera.getPicture]. ويطبق فقط عندما تساوي <code>Camera.sourceType</code> القيمة <code>Camera.PictureSourceType.CAMERA</code> وتساوي <code>Camera.destinationType</code> القيمة <code>Camera.DestinationType.FILE_URI</code>. | ||
− | ''' | + | '''المنصات المدعومة''' |
*iOS | *iOS | ||
سطر 217: | سطر 222: | ||
<code>BACK</code> | <code>BACK</code> | ||
اختيار الكاميرا المراد استخدامها (االأمامية أو الخلفية). | اختيار الكاميرا المراد استخدامها (االأمامية أو الخلفية). | ||
− | |||
سطر 354: | سطر 358: | ||
<code>1</code> | <code>1</code> | ||
استخدام الكاميرا الأمامية | استخدام الكاميرا الأمامية | ||
− | |||
سطر 385: | سطر 388: | ||
<code>ARROW_ANY</code> | <code>ARROW_ANY</code> | ||
الاتجاه الذي يجب أن يشير إليه السهم العنصر المنبثق. | الاتجاه الذي يجب أن يشير إليه السهم العنصر المنبثق. | ||
− | |||
سطر 393: | سطر 395: | ||
مقبض (handle) لعارض صور منبثق (image picker popover). | مقبض (handle) لعارض صور منبثق (image picker popover). | ||
− | ''' | + | '''المنصات المدعومة''' |
*iOS | *iOS | ||
سطر 459: | سطر 461: | ||
==== ملاحظات خاصة بمنصة iOS ==== | ==== ملاحظات خاصة بمنصة iOS ==== | ||
− | يمكن أن يتسبب تضمين دالة [[JavaScript| | + | يمكن أن يتسبب تضمين دالة [[JavaScript|جافااسكريبت]] <code>alert()</code> في أي من دوال الاستجابة إلى حدوث مشاكل. غلّف التنبيه داخل الدالة <code>setTimeout()</code> للسماح لمنتقي الصور الخاص أو العنصر المنبثق popover بمنصة iOS لأجل الإغلاق الكامل قبل عرض التنبيه: |
<syntaxhighlight lang="javascript">setTimeout(function() { | <syntaxhighlight lang="javascript">setTimeout(function() { | ||
// do your thing here! | // do your thing here! |
مراجعة 19:20، 13 ديسمبر 2018
تُعرّف الإضافة 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);
camera.cleanup()
يزيل هذا التابع ملفات الصور الوسطية التي تُحفظ في المخزن المؤقت بعد استدعاء [#module_camera.getPicture camera.getPicture]. ويطبق فقط عندما تساوي Camera.sourceType
القيمة Camera.PictureSourceType.CAMERA
وتساوي Camera.destinationType
القيمة Camera.DestinationType.FILE_URI
.
المنصات المدعومة
- iOS
Kind: تابع ثابت للكائن camera
Example
navigator.camera.cleanup(onSuccess, onFail);
function onSuccess() {
console.log("Camera cleanup success.")
}
function onFail(message) {
alert('Failed because: ' + message);
}
camera.onError : function
دالة استجابة (Callback function) تُستخدم لتوفير رسالة خطأ.
Kind:وسم typedef ثابت من الكائن camera
المعاملات
النوع
الشرح
message
string
يتم توفير الرسالة عبر الشيفرة الأصلية للجهاز.
camera.onSuccess: function
دالة استجابة تُوفّر بيانات الصورة.
Kind: وسم typedef ثابت من الكائن camera
المعاملات
النوع
الشرح
imageData
string
ترميز لبيانات الصورة وفق الترميز Base64، أو عنوان (URI) لملف الصورة، اعتمادًا على الخيار [#module_camera.CameraOptions cameraOptions] الساري.
Example
// Show image
//
function cameraCallback(imageData) {
var image = document.getElementById('myImage');
image.src = "data:image/jpeg;base64," + imageData;
}
camera.CameraOptions : Object
معاملات اختيارية لتخصيص إعدادات الكاميرا.
- [#CameraOptions-quirks Quirks]
Kind:وسم typedef ثابت من الكائن camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
quality
number
50
جودة الصورة المحفوظة، مُعبّر عنها بعدد من المجال 0-100، حيث يمثل العدد 100 الدقة الكاملة، عادة بدون أي خسارة من ضغط الملفات. (لاحظ أن المعلومات حول دقة الكاميرا غير متوفرة.)
destinationType
DestinationType
FILE_URI
اختر تنسيق القيمة المعادة.
sourceType
PictureSourceType
CAMERA
تحديد مصدر الصورة.
allowEdit
Boolean
false
السماح بتعديل بسيط على الصورة قبل الاختيار.
encodingType
EncodingType
JPEG
اختيار ترميز ملف الصورة المعادة.
targetWidth
number
العرض بالبكسل لتكبير الصورة. يجب استخدامه مع targetHeight
. نسبة أبعاد الصورة (Aspect ratio) تبقى ثابتة.
targetHeight
number
الارتفاع بالبكسل لتكبير الصورة. يجب استخدامه مع targetWidth
. نسبة أبعاد الصور تبقى ثابتة.
mediaType
MediaType
PICTURE
تعيين نوع الوسائط (medias) المراد الاختيار من بينها. يعمل هذا المعامل فقط عندما يساوي PictureSourceType
القيمة PHOTOLIBRARY
أو SAVEDPHOTOALBUM
.
correctOrientation
Boolean
تدوير الصورة لتصحيح اتجاه الجهاز أثناء التقاط الصورة.
saveToPhotoAlbum
Boolean
حفظ الصورة في ألبوم الصور على الجهاز بعد التقاطها.
popoverOptions
CameraPopoverOptions
خيارات مخصوصة بمنصة iOS فقط، والتي تحدد موضع popover في iPad.
cameraDirection
Direction
BACK
اختيار الكاميرا المراد استخدامها (االأمامية أو الخلفية).
camera
Camera.DestinationType : enum
يُعرّف تنسيق مُخرجات استدعاء Camera.getPicture
. ملاحظة: على منصة iOS، تمرير DestinationType.NATIVE_URI
مع PictureSourceType.PHOTOLIBRARY
أو PictureSourceType.SAVEDPHOTOALBUM
سيُعطل أي تعديلات على الصورة (تغيير الحجم، تغيير الجودة، الاقتصاص، إلخ) بسبب خصوصيات التقديم (implementation specific).
Kind: خاصية تعداد (enum) ثابتة للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
DATA_URL
number
0
تُعاد سلسلة نصية وفق الترميز base64. تركز DATAURL كثيرًا على الذاكرة، وقد تتسبب في تعطل التطبيق أو نفاذ الذاكرة. استخدم FILEURI أو NATIVE_URI إن أمكن
FILE_URI
number
1
إعادة عنوان (uri ) الملف (content://media/external/images/media/2 لمنصة أندرويد)
NATIVE_URI
number
2
إعادة العنوان (uri) الأصلي (على سبيل المثال، asset-library://... لمنصة iOS)
Camera.EncodingType : enum
Kind: خاصية تعداد (enum) ثابتة للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
JPEG
number
0
تعيد هذه الخاصية صورة مشفرة وفق الترميز JPEG
PNG
number
1
تعيد صورة مشفرة وفق الترميز PNG
Camera.MediaType : enum
Kind: خاصية تعداد (enum) الثابت للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
PICTURE
number
0
تمكن هذه الخاصية من اختيار الصور الثابتة وحسب. القيمة الافتراضية ستعيد التنسيق المحدد عبر DestinationType
VIDEO
number
1
تسمح باختيار الفيديو فقط، وتعيد العنوان (URL) وحسب.
ALLMEDIA
number
2
تسمح بالاختيار من جميع أنواع الوسائط
Camera.PictureSourceType : enum
يعرف تنسيق مُخرجات استدعاء Camera.getPicture
. ملاحظة: على منصة iOS، الذي تمرير PictureSourceType.PHOTOLIBRARY
أو PictureSourceType.SAVEDPHOTOALBUM
إلى جانب DestinationType.NATIVE_URI
سيعطل أي تعديلات على الصورة (تغيير الحجم أو تغيير الجودة أو الافتصاص إلخ) بسبب اختلاف طرق التقديم (implementation).
Kind: خاصية تعداد (enum) ثابتة للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
PHOTOLIBRARY
number
0
اختيار صورة من مكتبة الصور في بالجهاز (تشبه SAVEDPHOTOALBUM في أندرويد)
CAMERA
number
1
التقاط صورة عبر الكاميرا
SAVEDPHOTOALBUM
number
2
اختيار صورة من ألبوم Camera Roll الموجود في الجهاز (مثل PHOTOLIBRARY في منصة أندرويد)
Camera.PopoverArrowDirection : enum
تطابق الثوابت UIPopoverArrowDirection الخاصة بمنصة iOS لتحديد موضع السهم (arrow location) على العنصر المنبثق popover.
Kind: خاصية تعداد (enum) ثابتة للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
ARROW_UP
number
1
ARROW_DOWN
number
2
ARROW_LEFT
number
4
ARROW_RIGHT
number
8
ARROW_ANY
number
15
Camera.Direction : enum
Kind: خاصية تعداد (enum) ثابتة للكائن Camera
Properties
الاسم
النوع
القيمة الافتراضية
الشرح
BACK
number
0
استخدام الكاميرا الخلفية
FRONT
number
1
استخدام الكاميرا الأمامية
CameraPopoverOptions
هذه معاملات مخصوصة بمنصة iOS فقط، حيث تحدد موضع عنصر الإرساء (anchor element) واتجاه السهم في العنصر المُنبثق عند اختيار الصور من مكتبة أو ألبوم iPad. لاحظ أنه قد يتغير حجم العنصر المنبثق للتكيف مع اتجاه السهم والشاشة. تأكد من أخذ تغييرات الاتجاه بعين الاعتبار عند تحديد موضع عنصر الإرساء.
المعامل
النوع
القيمة الافتراضية
الشرح
[x]
Number
0
عدد يمث إحداثية الأفاصيل (x) بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[y]
Number
32
عدد يمث إحداثية الأراتيب (y) بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[width]
Number
320
العرض، بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[height]
Number
480
الارتفاع بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق.
[arrowDir]
PopoverArrowDirection
ARROW_ANY
الاتجاه الذي يجب أن يشير إليه السهم العنصر المنبثق.
CameraPopoverHandle
مقبض (handle) لعارض صور منبثق (image picker popover).
المنصات المدعومة
- iOS
Example
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)
});
// Reposition the popover if the orientation changes.
window.onorientationchange = function() {
var cameraPopoverHandle = new CameraPopoverHandle();
var cameraPopoverOptions = new CameraPopoverOptions(0, 0, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY);
cameraPopoverHandle.setPosition(cameraPopoverOptions);
}
camera.getPicture Errata
مثال
المثال التالي سيلتقط صورة ويستعيد موضع ملف الصورة:
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:
/**
* Warning: Using DATA_URL is not recommended! The DATA_URL destination
* type is very memory intensive, even with a low quality setting. Using it
* can result in out of memory errors and application crashes. Use FILE_URI
* or NATIVE_URI instead.
*/
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);
}
التفضيلات (iOS)
- CameraUsesGeolocation (قيمة منطقية، القيمة الافتراضية تساوي false). لالتقاط صور JPEG، اضبط هذا الخيار عند القيمة true للحصول على بيانات الموقع الجغرافي في رأس الملف EXIF. سيؤدي هذا إلى إرسال طلبية للحصول على أذونات تحديد الموقع الجغرافي إذا تم تعيينها عند القيمة true.
<preference name="CameraUsesGeolocation" value="false" />
ملاحظات خاصة بمنصة Amazon Fire
تستخدم منصة Amazon Fire مقاصدًا لبدء نشاط الكاميرا على الجهاز لالتقاط الصور، وعلى الهواتف ذات الذاكرة المنخفضة، قد يفشل هذا النشاط. في هذه الحالة، قد لا تظهر الصورة عند استئناف النشاط.
ملاحظات خاصة بمنصة أندرويد
يستخدم أندرويد المقاصد (intents) لإطلاق نشاط الكاميرا على الجهاز لالتقاط الصور، وعلى الهواتف ذات الذاكرة المنخفضة، قد يفشل النشاط. في هذه الحالة، سيتم تسليم النتيجة المعادة من استدعاء الإضافة عبر الحدث resume. راجع صفحة the Android Lifecycle guide لمزيد من المعلومات. ستحتوي pendingResult.result
على القيمة التي ستُمرّر إلى الاستجابات - callbacks - (إما عنوان URL أو رسالة خطأ). تحقق من pendingResult.pluginStatus
لتحديد ما إذا كان الاستدعاء ناجحًا أم لا.
ملاحظات خاصة بالمتصفحات (Browsers)
يمكن أن تعيد الصورالمشفرة وفق الترميز Base64 فقط.
ملاحظات خاصة بمنصة Firefox
يتم حاليًا تقديم الإضافة Camera باستخدام Web Activities.
ملاحظات خاصة بمنصة iOS
يمكن أن يتسبب تضمين دالة جافااسكريبت alert()
في أي من دوال الاستجابة إلى حدوث مشاكل. غلّف التنبيه داخل الدالة setTimeout()
للسماح لمنتقي الصور الخاص أو العنصر المنبثق popover بمنصة iOS لأجل الإغلاق الكامل قبل عرض التنبيه:
setTimeout(function() {
// do your thing here!
}, 0);
ملاحظات خاصة بمنصة Windows Phone 7
استدعاء تطبيق الكاميرا الأصلي أثناء وصل الجهاز عبر Zune لن ينجح، وسيطلق دالة خطأ (error callback).
ملاحظات خاصة بمنصة ويندوز
على منصة Windows Phone 8.1، استخدام SAVEDPHOTOALBUM
أو PHOTOLIBRARY
كنوع مصدري (source type) سيؤدي إلى تجميد التطبيق إلى حين إعادة منتقي الملفات (file picker) للصورة المختارة، ثم يستأنف بصفحة البداية كما هو موضح في ملف التطبيق config.xml
. في حالة استدعاء camera.getPicture
من صفحة أخرى، سيؤدي ذلك إلى إعادة تحميل صفحة البداية ثانية، ولن تُستدعى دالتا النجاح والخطأ.
لتجنب هذا نقترح استخدام نمط التطبيقات أحادية الصفحة (SPA)، أو استدعاء camera.getPicture
فقط لأجل صفحة بدء التطبيق.
المزيد من المعلومات حول الواجهات البرمجية لمنتقي Windows Phone 8.1 راجع هذه الصفحة: How to continue your Windows Phone app after calling a file picker
ملاحظات خاصة بمنصة Tizen
لا تدعم Tizen إلا destinationType
الخاصة بـ Camera.DestinationType.FILE_URI
أو sourceType
الخاصة بـ Camera.PictureSourceType.PHOTOLIBRARY
.
CameraOptions Errata
ملاحظات خاصة بمنصة Amazon Fire
- ستُنتج القيمةُ
cameraDirection
صورًا خلفية (back-facing photos). - تتجاهل هذه المنصة المعامل
allowEdit
. - يعرض كل من
Camera.PictureSourceType.PHOTOLIBRARY
وCamera.PictureSourceType.SAVEDPHOTOALBUM
نفس ألبوم الصور.
ملاحظات خاصة بمنصة أندرويد
- ستُنتجُ القيمةُ
cameraDirection
صورًا خلفية (back-facing photo). - allowEdit is unpredictable on Android and it should not be used! في أندرويد تحاول هذه الإضافة العثور على تطبيق واستخدامه على جهاز المستخدم لأجل الاقتصاص (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
- الخيارات (options) غير مدعومة
- يُعاد دائمًا عنوان ملف (FILE URI)
ملاحظات خاصة بمنصتي Windows Phone الإصدارين 7 و 8
- تتجاهل هاتان المنصتان المعامل
allowEdit
. - تتجاهل المنصتان المعامل
correctOrientation
. - تتجاهل المنصتان المعامل
cameraDirection
. - تتجاهل المنصتان المعامل
saveToPhotoAlbum
. ملاحظة هامة: دائمًا تُنسخ الصور التي تم التقاطها باستخدام الواجهة البرمجية للإضافة Cordova camera على ويندوز 8 (WP8/8) الواجهة في ذاكرة (roll) الكاميرا الخاصة بالهاتف. استنادًا إلى إعدادات المستخدم، قد يعني هذا أيضًا أن الصورة ستُحمّل تلقائيًا إلى الخدمة OneDrive. يمكن أن يعني هذا أن الصورة ستكون متاحة لجمهور أكبر من الجمهور الذي يستهدفه تطبيقك. إن كانت هذه مشكلة لتطبيقك، فستحتاج إلى تقديم CameraCaptureTask كما هو مبيّن في توثيق documented on MSDN. يمكنك أن تقوم أيضًا بالتعليق أو التصويت لصالح حل المشكلة في issue tracker. - تتجاهل المنصتان خاصية
mediaType
فيcameraOptions
، لأن بيئة العمل SDK في منصة Windows Phone لا توفر طريقة لاختيار مقاطع الفيديو من PHOTOLIBRARY.
عينة: التقاط الصور، اختيار الصور من مكتبة الصور، والحصول على الصور المصغرة
تتيح لك الإضافة Camera إجراء أشياء مثل فتح كاميرا الجهاز والتقاط صورة، أو فتح منتقي الملفات واختيار ملف معيّن. توضح الشيفرات البرمجية في هذا القسم مختلف المهام الممكنة، بما في ذلك:
- فتح الكاميرا والتقاط صورة [#takePicture take a Picture]
- التقاط صورة وإعادة صورة مصغرة [#getThumbnails return thumbnails] (صورة مُعدلة الحجم)
- التقاط صورة و [#convert generate a FileEntry object]
- [#selectFile Select a file] اختيار صورة من مكتبة الصور
- اختيار صورة بتنسيق JPEG وإعادة صورة مصغرة [#getFileThumbnails return thumbnails] (صورة مُعدلة الحجم)
- اختيار صورة و [#convert generate a FileEntry object]
التقاط صورة
قبل أن تتمكن من التقاط صورة، تحتاج أولا إلى ضبط بعض خيارات إضافة الكاميرا لكي تُمرّر إلى دالة الإضافة getPicture
. هذه مجموعة من التوصيات المهمة. في هذا المثال، ستُنشئ الكائن الذي ستستخدمه لأجل خيارات الكاميرا، وستُعيّن sourceType
ديناميكيًا لدعم كل من إضافة الكاميرا ومنتقي الملفات.
function setOptions(srcType) {
var options = {
// Some common settings are 20, 50, and 100
quality: 50,
destinationType: Camera.DestinationType.FILE_URI,
// In this app, dynamically set the picture source, Camera or photo gallery
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);
// You may choose to copy the picture, save it somewhere, or upload.
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) {
// Do something
}, function cameraError(error) {
console.debug("Unable to obtain picture: " + error, "app");
}, options);
}
اختيار ملف من مكتبة الصور
عند اختيار ملف باستخدام منتقي الملفات، فيجب عليك أيضًا تعيين الكائن CameraOptions. في هذا المثال، سنُعيّن sourceType
عند القيمة Camera.PictureSourceType.SAVEDPHOTOALBUM
. لفتح منتقي الملفات، استدع getPicture
تمامًا كما فعلت في المثال السابق، مع تمرير دوال الاستجابة (callbacks) للنجاح والخطأ إلى جانب الكائن CameraOptions.
function openFilePicker(selection) {
var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
var options = setOptions(srcType);
var func = createNewFileEntry;
navigator.camera.getPicture(function cameraSuccess(imageUri) {
// Do something
}, 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") {
// To downscale a selected image,
// Camera.EncodingType (e.g., JPEG) must match the selected image type.
options.targetHeight = 100;
options.targetWidth = 100;
}
navigator.camera.getPicture(function cameraSuccess(imageUri) {
// Do something with image
}, 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 (هذه هي أيضًا القيمة الافتراضية).
ملاحظة تحتاج إلى File plugin لاستدعاء window.resolveLocalFileSystemURL
.
هنا استدعاء window.resolveLocalFileSystemURL
. يُمرّر عنوان الصورة إلى هذه الدالة من دالة النجاح الخاصة بـ getPicture
. تتلقى دالة الاستجابة للنجاح (success handler) الخاصة بـ resolveLocalFileSystemURL
الكائن FileEntry.
function getFileEntry(imgUri) {
window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) {
// Do something with the FileEntry object, like write to it, upload it, etc.
// writeFile(fileEntry, imgUri);
console.log("got file: " + fileEntry.fullPath);
// displayFileData(fileEntry.nativeURL, "Native URL");
}, function () {
// If don't get the FileEntry (which may happen when testing
// on some emulators), copy to a new FileEntry.
createNewFileEntry(imgUri);
});
}
في المثال الموضح في الشيفرة البرمجية السابقة، يمكنك استدعاء دالة التطبيق createNewFileEntry
إن لم تحصل على كائن FileEntry صالح. الصورة المعادة من قبل تطبيق الكاميرا يجب أن تُنتج كائن FileEntry صالح، ولكن قد يختلف سلوك المنصات على بعض المحاكيات للملفات المُعادة من منتقي الملفات.
يمكنك الاطلاع على مثال عن الكتابة في FileEntry من هنا File plugin README.
تنشئ الشيفرة المعروضة هنا ملفًا في ذاكرة التخزين المؤقت لتطبيقك (في التخزين المحمي sandboxed) باسم tempFile.jpeg
. باستخدام كائن FileEntry الجديد، يمكنك نسخ الصورة إلى الملف، أو القيام بشيء آخر مثل تحميلها.
function createNewFileEntry(imgUri) {
window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) {
// JPEG file
dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) {
// Do something with it, like write to it, upload it, etc.
// writeFile(fileEntry, imgUri);
console.log("got file: " + fileEntry.fullPath);
// displayFileData(fileEntry.fullPath, "File copied to");
}, onErrorCreateFile);
}, onErrorResolveUrl);
}