الإضافة 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>‎

الواجهة البرمجية

camera

camera.getPicture (successCallback، errorCallback، options)

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

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

إن كانت الخاصية [#module_Camera.PictureSourceType Camera.PictureSourceType.CAMERA] تساوي Camera.sourceType أو Camera.PictureSourceType.PHOTOLIBRARY، فسيظهر مربع حوار يمكّن للمستخدمين من اختيار إحدى الصور الموجودة.

تُرسل القيمة المعادة إلى دالة الاستجابة Camera.PictureSourceType.SAVEDPHOTOALBUM، وفق إحدى التنسيقات التالية، اعتمادًا على الخيار [#module_camera.onSuccess cameraSuccess] المحدد:

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

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

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

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

DATA_URL

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

يمكن الحصول على المزيد من الأمثلة من Supported Platforms. كما يمكنك الاطلاع على بعض الملاحظات المخصوصة بمنصات محددة من [#camera-getPicture-examples here].

[#camera-getPicture-quirks here]: تابع ثابت (static method) للكائن Kind المعامل النوع الشرح successCallback camera errorCallback onSuccess options onError CameraOptions

CameraOptions Example


camera.cleanup()‎

يزيل هذا التابع ملفات الصور الوسطية التي تُحفظ في المخزن المؤقت بعد استدعاء 

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

. ويطبق فقط عندما تساوي [#module_camera.getPicture camera.getPicture] القيمة Camera.sourceType وتساوي Camera.PictureSourceType.CAMERA القيمة Camera.destinationType.

Camera.DestinationType.FILE_URI

  • iOS

Supported Platforms: تابع ثابت للكائن Kind camera Example

camera.onError : function

دالة استجابة (Callback function) تُستخدم لتوفير رسالة خطأ. 

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

:وسم typedef ثابت من الكائن Kind

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


camera.onSuccess: function

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

string: وسم typedef ثابت من الكائن Kind المعاملات النوع الشرح imageData camera ترميز لبيانات الصورة وفق الترميز Base64، أو عنوان (URI) لملف الصورة، اعتمادًا على الخيار string الساري.

[#module_camera.CameraOptions cameraOptions] Example


camera.CameraOptions : Object

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

  • // Show image
//
function cameraCallback(imageData) {
   var image = document.getElementById('myImage');
   image.src = "data:image/jpeg;base64," + imageData;
}‎

[#CameraOptions-quirks Quirks]:وسم typedef ثابت من الكائن Kind camera الاسم النوع القيمة الافتراضية الشرح quality Properties number جودة الصورة المحفوظة، مُعبّر عنها بعدد من المجال 0-100، حيث يمثل العدد 100 الدقة الكاملة، عادة بدون أي خسارة من ضغط الملفات. (لاحظ أن المعلومات حول دقة الكاميرا غير متوفرة.) destinationType 50 DestinationType اختر تنسيق القيمة المعادة. sourceType FILE_URI PictureSourceType تحديد مصدر الصورة. allowEdit CAMERA Boolean السماح بتعديل بسيط على الصورة قبل الاختيار. encodingType false EncodingType اختيار ترميز ملف الصورة المعادة. targetWidth JPEG

العرض بالبكسل لتكبير الصورة. يجب استخدامه مع number. نسبة أبعاد الصورة (Aspect ratio) تبقى ثابتة. targetHeight targetHeight

الارتفاع بالبكسل لتكبير الصورة. يجب استخدامه مع number. نسبة أبعاد الصور تبقى ثابتة. mediaType targetWidth MediaType تعيين نوع الوسائط (medias) المراد الاختيار من بينها. يعمل هذا المعامل فقط عندما يساوي PICTURE القيمة PictureSourceType أو PHOTOLIBRARY. correctOrientation SAVEDPHOTOALBUM

تدوير الصورة لتصحيح اتجاه الجهاز أثناء التقاط الصورة. saveToPhotoAlbum Boolean

حفظ الصورة في ألبوم الصور على الجهاز بعد التقاطها. popoverOptions Boolean

خيارات مخصوصة بمنصة iOS فقط، والتي تحدد موضع popover في iPad. cameraDirection CameraPopoverOptions Direction اختيار الكاميرا المراد استخدامها (االأمامية أو الخلفية).


camera

Camera.DestinationType : enum

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

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


Camera.EncodingType : enum

2: خاصية تعداد (enum) ثابتة للكائن Kind Camera الاسم النوع القيمة الافتراضية الشرح JPEG Properties number تعيد هذه الخاصية صورة مشفرة وفق الترميز JPEG PNG 0 number تعيد صورة مشفرة وفق الترميز PNG


Camera.MediaType : enum

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


Camera.PictureSourceType : enum

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

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


Camera.PopoverArrowDirection : enum

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

2: خاصية تعداد (enum) ثابتة للكائن Kind Camera الاسم النوع القيمة الافتراضية ARROW_UP Properties number ARROW_DOWN 1 number ARROW_LEFT 2 number ARROW_RIGHT 4 number ARROW_ANY 8 number


Camera.Direction : enum

15: خاصية تعداد (enum) ثابتة للكائن Kind Camera الاسم النوع القيمة الافتراضية الشرح BACK Properties number استخدام الكاميرا الخلفية FRONT 0 number استخدام الكاميرا الأمامية


CameraPopoverOptions

هذه معاملات مخصوصة بمنصة iOS فقط، حيث تحدد موضع عنصر الإرساء (anchor element) واتجاه السهم في العنصر المُنبثق عند اختيار الصور من مكتبة أو ألبوم iPad. لاحظ أنه قد يتغير حجم العنصر المنبثق للتكيف مع اتجاه السهم والشاشة. تأكد من أخذ تغييرات الاتجاه بعين الاعتبار عند تحديد موضع عنصر الإرساء. المعامل النوع القيمة الافتراضية الشرح [x] 1 Number عدد يمث إحداثية الأفاصيل (x) بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق. [y] 0 Number عدد يمث إحداثية الأراتيب (y) بالبكسل من عنصر الشاشة الذي يُرسى عليه العنصر المنبثق. [width] 32 Number العرض، بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق. [height] 320 Number الارتفاع بالبكسل، لعنصر الشاشة الذي يُرسى عليه العنصر المنبثق. [arrowDir] 480 PopoverArrowDirection الاتجاه الذي يجب أن يشير إليه السهم العنصر المنبثق.


CameraPopoverHandle

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

ARROW_ANY

  • iOS

Supported Platforms Example


camera.getPicture Errata

مثال

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

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);
}‎

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

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);
}‎

التفضيلات (iOS)

  • /**
 * 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);
}‎
    (قيمة منطقية، القيمة الافتراضية تساوي false). لالتقاط صور JPEG، اضبط هذا الخيار عند القيمة true للحصول على بيانات الموقع الجغرافي في رأس الملف EXIF. سيؤدي هذا إلى إرسال طلبية للحصول على أذونات تحديد الموقع الجغرافي إذا تم تعيينها عند القيمة true.

CameraUsesGeolocation

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

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

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

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

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

لمزيد من المعلومات. ستحتوي the Android Lifecycle guide على القيمة التي ستُمرّر إلى الاستجابات - callbacks - (إما عنوان URL أو رسالة خطأ). تحقق من pendingResult.result لتحديد ما إذا كان الاستدعاء ناجحًا أم لا.

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

يمكن أن تعيد الصورالمشفرة وفق الترميز Base64 فقط.

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

يتم حاليًا تقديم الإضافة Camera باستخدام pendingResult.pluginStatus.

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

يمكن أن يتسبب تضمين دالة جافااسكريبت Web Activities في أي من دوال الاستجابة إلى حدوث مشاكل. غلّف التنبيه داخل الدالة alert() للسماح لمنتقي الصور الخاص أو العنصر المنبثق popover بمنصة iOS لأجل الإغلاق الكامل قبل عرض التنبيه: setTimeout()

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

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

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

على منصة Windows Phone 8.1، استخدام 

setTimeout(function() {
    // do your thing here!
}, 0);‎

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

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

المزيد من المعلومات حول الواجهات البرمجية لمنتقي Windows Phone 8.1 راجع هذه الصفحة: camera.getPicture

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

لا تدعم Tizen إلا How to continue your Windows Phone app after calling a file picker الخاصة بـ destinationType أو Camera.DestinationType.FILE_URI الخاصة بـ sourceType.


CameraOptions Errata

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

  • ستُنتج القيمةُ Camera.PictureSourceType.PHOTOLIBRARY صورًا خلفية (back-facing photos).
  • تتجاهل هذه المنصة المعامل cameraDirection.
  • يعرض كل من allowEdit و Camera.PictureSourceType.PHOTOLIBRARY نفس ألبوم الصور.

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

  • ستُنتجُ القيمةُ Camera.PictureSourceType.SAVEDPHOTOALBUM صورًا خلفية (back-facing photo).
  • cameraDirection في أندرويد تحاول هذه الإضافة العثور على تطبيق واستخدامه على جهاز المستخدم لأجل الاقتصاص (cropping) من الصورة. لا تتحكم الإضافة في التطبيق الذي يحدده المستخدم لإجراء عملية اقتصاص الصور، ومن المحتمل جدًا أن يختار المستخدم خيارًا غير متوافقٍ، ويتسبب في فشل الإضافة. يعمل هذا الأمر في بعض الأحيان لأن معظم الأجهزة مُزوّدة بتطبيقٍ يعالج الاقتصاص بطريقة متوافقة مع هذه الإضافة (صور Google Plus)، ولكن لا يمكن الاعتماد على هذا دائمًا. إن كان تعديل الصور أمرًا ضروريًا لتطبيقك، فكّر في البحث عن مكتبة أو إضافة خارجية توفر أداة أكثر كفاءة في تعديل للصور.
  • يعرض كل من allowEdit is unpredictable on Android and it should not be used! و Camera.PictureSourceType.PHOTOLIBRARY نفس ألبوم الصور.
  • تتجاهل منصة المعامل Camera.PictureSourceType.SAVEDPHOTOALBUM إن لم تكن الصورة معدلة (أي إن كانت encodingType تساوي 100، وكانت quality تساوي false، ولم يُحدد لا correctOrientation أو targetHeight). سيُعيد مصدر targetWidth دائمًا ملف JPEG المعطى من قبل الكاميرا الأصليةـ وسيُعيد مصدرا CAMERA و PHOTOLIBRARY الملف المحدد وفق ترميزه الحالي.

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

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

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

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

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

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

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

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

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

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

عينة: التقاط الصور، اختيار الصور من مكتبة الصور، والحصول على الصور المصغرة

تتيح لك الإضافة Camera إجراء أشياء مثل فتح كاميرا الجهاز والتقاط صورة، أو فتح منتقي الملفات واختيار ملف معيّن. توضح الشيفرات البرمجية في هذا القسم مختلف المهام الممكنة، بما في ذلك:

  • فتح الكاميرا والتقاط صورة cameraOptions
  • التقاط صورة وإعادة صورة مصغرة [#takePicture take a Picture] (صورة مُعدلة الحجم)
  • التقاط صورة و [#getThumbnails return thumbnails]
  • [#convert generate a FileEntry object] اختيار صورة من مكتبة الصور
  • اختيار صورة بتنسيق JPEG وإعادة صورة مصغرة [#selectFile Select a file] (صورة مُعدلة الحجم)
  • اختيار صورة و [#getFileThumbnails return thumbnails]

التقاط صورة

قبل أن تتمكن من التقاط صورة، تحتاج أولا إلى ضبط بعض خيارات إضافة الكاميرا لكي تُمرّر إلى دالة الإضافة [#convert generate a FileEntry object] . هذه مجموعة من التوصيات المهمة. في هذا المثال، ستُنشئ الكائن الذي ستستخدمه لأجل خيارات الكاميرا، وستُعيّن getPicture ديناميكيًا لدعم كل من إضافة الكاميرا ومنتقي الملفات. sourceType

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

يمكنك التقاط صورة من خلال تمرير كائن الخيارات إلى 

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;
}‎

، والذي يأخذ الكائن CameraOptions كوسيط ثالث. عند استدعاء getPicture، قم بتمرير 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

لعرض الصورة على بعض المنصات، قد تحتاج إلى تضمين الجزء الرئيسي من العنوان (URI) في العنصر Content-Security-Policy من الوسم 

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

في الملف index.html. على سبيل المثال، في منصة ويندوز 10، يمكنك تضمين <meta> في الوسم 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 مع الكائن CameraOptions الخاص بك. في هذا المثال، ستغيّر حجم الصورة المعادة لتلائم مربعًا بحجم 100 بكسل × 100 بكسل (يتم الاحتفاظ بنسبة العرض إلى الارتفاع [aspect ratio]، لذلك فالعدد 100 بكسل سيساوي إما الارتفاع أو العرض، مهما كان الأكبر في المصدر).

targetWidth

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

عند اختيار ملف باستخدام منتقي الملفات، فيجب عليك أيضًا تعيين الكائن CameraOptions. في هذا المثال، سنُعيّن 

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);
}‎

عند القيمة sourceType. لفتح منتقي الملفات، استدع Camera.PictureSourceType.SAVEDPHOTOALBUM تمامًا كما فعلت في المثال السابق، مع تمرير دوال الاستجابة (callbacks) للنجاح والخطأ إلى جانب الكائن CameraOptions.

getPicture

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

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

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

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

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

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);
}‎

على عنوان (URI) الملف المُعاد من قبل تطبيق الكاميرا. إن كنت بحاجة إلى استخدام كائن FileEntry، اضبط window.resolveLocalFileSystemURL عند القيمة destinationType في كائن CameraOptions (هذه هي أيضًا القيمة الافتراضية).

ملاحظة تحتاج إلى Camera.DestinationType.FILE_URI لاستدعاء File plugin.

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

في المثال الموضح في الشيفرة البرمجية السابقة، يمكنك استدعاء دالة التطبيق 

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);
    });
}‎

إن لم تحصل على كائن FileEntry صالح. الصورة المعادة من قبل تطبيق الكاميرا يجب أن تُنتج كائن FileEntry صالح، ولكن قد يختلف سلوك المنصات على بعض المحاكيات للملفات المُعادة من منتقي الملفات.

يمكنك الاطلاع على مثال عن الكتابة في FileEntry من هنا createNewFileEntry.

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

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Cordova/cordova_plugin_camera&oldid=26347"