Multer

تعتبر Multer وسيط node.js لمعالجة multipart/form-data, والتي تُستخدم أساسًا لتحميل الملفات. تم بناء هذا الوسيط بالإعتماد على busboy لأجل الحصول على أقصى قدر من الكفاءة.

ملاحظة: لن يقوم Multer بمعالجة أي شكل غير متعدد الأجزاء (multipart/form-data).

الترجمات

هذا الملف متاح أيضًا بلغات أخرى:

• English (الإنجليزية)
• Español (الإسبانية)
• 简体中文 (الصينية)
• 한국어 (الكورية)
• Русский язык (الروسية)
• Việt Nam (الفتنامية)
• Português (البرتغالية)

التنصيب

$ npm install --save multer

الاستعمال

يضيف Multer كائن body وكائن file أو files إلى كائن request. يحتوي الكائن body على قيم مدخلات النص في الإستمارة ، بينما يحتوي الكائن file أو files على الملفات التي تم تحميلها عبر الإستمارة.

مثال على الاستخدام الأساسي:

لا تنسَ <span dir="ltr"> enctype="multipart/form-data" </span> في الإستمارة الخاص بك.

<form action="/profile" method="post" enctype="multipart/form-data">
  <input type="file" name="avatar" />
</form>

var express = require('express')
var multer  = require('multer')
var upload = multer({ dest: 'uploads/' })

var app = express()

app.post('/profile', upload.single('avatar'), function (req, res, next) {
  // req.file is the `avatar` file
  // req.body will hold the text fields, if there were any
})

app.post('/photos/upload', upload.array('photos', 12), function (req, res, next) {
  // req.files is array of `photos` files
  // req.body will contain the text fields, if there were any
})

var uploadMiddleware = upload.fields([{ name: 'avatar', maxCount: 1 }, { name: 'gallery', maxCount: 8 }])
app.post('/cool-profile', uploadMiddleware, function (req, res, next) {
  // req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
  //
  // e.g.
  //  req.files['avatar'][0] -> File
  //  req.files['gallery'] -> Array
  //
  // req.body will contain the text fields, if there were any
})

إذا احتجت لمعالجة إستمارة متعددة الأجزاء للنص فقط ، فيجب عليك استخدام الدالة .none ():

var express = require('express')
var app = express()
var multer  = require('multer')
var upload = multer()

app.post('/profile', upload.none(), function (req, res, next) {
  // req.body contains the text fields
})

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

معلومات الملف

كل ملف يحتوي على المعلومات التالية:

multer(opts)

يقبل Multer كائن الخيارات ، وأهمها خاصية dest، والتي تحدد مكان تحميل الملفات. في حال حذفت كائن الخيارات ، سيتم الاحتفاظ بالملفات في الذاكرة ولن تتم كتابتها مطلقًا على القرص.

بشكل افتراضي ، سيقوم Multer بإعادة تسمية الملفات لتجنب تعارض الأسماء. يمكن تخصيص وظيفة إعادة التسمية وفقا لاحتياجاتك.

فيما يلي الخيارات التي يمكن تمريرها إلى Multer:

في تطبيق ويب متوسط ​​، قد تكون هناك حاجة فقط إلى dest، وتكوينها كما هو موضح في المثال التالي :

var upload = multer({ dest: 'uploads/' })

إذا كنت تريد مزيدًا من التحكم في عمليات التحميل ، فستحتاج إلى استخدام خيار storage بدلاً من dest. يأتي Multer مع محركات التخزين DiskStorage و MemoryStorage ؛ كما تتوفر المزيد من المحركات من أطراف ثالثة.

.single(fieldname)

قبول ملف واحد باسم اسم-المُدخَل. سيتم تخزين الملف في req.file.

.array(fieldname[, maxCount])

قبول مصفوفة من الملفات ، وكلها تحمل اسم اسم-المُدخَل. يظهر خطأ اختياريً إذا تم تحميل ملفات أكثر من maxCount. سيتم تخزين مصفوفة الملفات في req.files.

.fields(fields)

قبول مزيج من الملفات ، المحدد بواسطة المدخلات. سيتم تخزين كائن مع مصفوفات من الملفات في req.files.

يجب أن تكون المدخلات عبارة عن مصفوفة من الكائنات التي توفر بشكل اساسي name واختيارياً maxCount. مثال:

[
  { name: 'avatar', maxCount: 1 },
  { name: 'gallery', maxCount: 8 }
]

.none()

قبول المدخلات النصية فقط. في حالة رفع أي ملف ، سيتم إصدار خطأ بشيفرة "LIMIT _UNEXPECTED _FILE".

.any()

قبول جميع الملفات التي تأتي عبر السلك. سيتم تخزين مصفوفة من الملفات في req.files.

تحذير: تأكد من أنك تعالج دائمًا الملفات التي يقوم المستخدم بتحميلها. لا تقم أبداً بإضافة multer باعتبارها أداة وسيطة عامة ، حيث يمكن للمستخدم الضار تحميل الملفات إلى مسار غير متتوقع. استخدم هذه الدالة فقط على المسارات التي تتعامل فيها مع الملفات التي تم تحميلها.

storage

DiskStorage

يمنحك محرك تخزين القرص التحكم الكامل في تخزين الملفات على القرص.

var storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, '/tmp/my-uploads')
  },
  filename: function (req, file, cb) {
    cb(null, file.fieldname + '-' + Date.now())
  }
})

var upload = multer({ storage: storage })

هناك خياران متاحان ، destination و filename. كلاهما يعملان على تحديد مكان تخزين الملف.

يتم استخدام destination لتحديد أي مجلد يجب تخزين الملفات المحملة. يمكن أيضًا إعطاء هذا كـسلسلة (مثل '/tmp/uploads'). إذا لم يتم إعطاء destination ، فسيتم استخدام الدليل الافتراضي لنظام التشغيل للملفات المؤقتة.

ملاحظة: أنت مسؤول عن إنشاء الدليل عند توفر destination كدالة. عند المرور بسلسلة ، سوف يتأكد multer من إنشاء الدليل من أجلك.

يتم استخدام اسم الملف لتحديد ما يجب تسمية الملف داخل المجلد. إذا لم يتم تقديم اسم الملف، فسيتم إعطاء كل ملف اسمًا عشوائيًا لا يتضمن أي امتداد للملف.

ملاحظة: لن يقوم multer بإلحاق اي ملحق ملف لك، الدالة الخاص بك يجب أن تقوم بإرجاع اسم ملف كامل بملحق الملف.

يتم تمرير كل دالة من خلال الطلب (req) وبعض المعلومات حول الملف (file`) للمساعدة في اتخاذ القرار.

لاحظ أن req.body ربما لم يتم ملؤها بالكامل بعد. يعتمد ذلك على الترتيب الذي يقوم به العميل من خلال نقل المدخلات والملفات إلى الخادم.

MemoryStorage

يخزن محرك تخزين الذاكرة الملفات الموجودة في الذاكرة ككائنات ذاكرة (Buffer). ليس لديها أي خيارات.

var storage = multer.memoryStorage()
var upload = multer({ storage: storage })

عند استخدام ذاكرة التخزين ، ستحتوي معلومات الملف على مُدخَل يسمى buffer الذي يحتوي على الملف بأكمله.

تحذير: يمكن أن يؤدي تحميل ملفات كبيرة جدًا أو ملفات صغيرة نسبيًا بأعداد كبيرة و بسرعة كبيرة إلى نفاد ذاكرة التطبيق عند استخدام ذاكرة التخزين.

limits

كائن يحدد حدود حجم الخصائص الاختيارية التالية. يقوم Multer بتمرير هذا الكائن إلى busboy مباشرة ، ويمكن العثور على تفاصيل الخصائص من خلال صفحة busboy's.

تتوفر القيم الصحيحة التالية:

يمكن أن يساعد تحديد الحدود في حماية موقعك من هجمات حجب الخدمة (DoS).

fileFilter

اضبط هذا على دالة للتحكم في الملفات التي ينبغي تحميلها وأي الملفات يجب تخطيها. يجب أن تبدو دالة كما يلي:

function fileFilter (req, file, cb) {

  // The function should call `cb` with a boolean
  // to indicate if the file should be accepted

  // To reject this file pass `false`, like so:
  cb(null, false)

  // To accept the file pass `true`, like so:
  cb(null, true)

  // You can always pass an error if something goes wrong:
  cb(new Error('I don\'t have a clue!'))

}

معالجة الأخطاء

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

إذا كنت تريد إنتقاء الأخطاء والحصول على أخطاء Multer فقط، فيمكنك نداء بدالة الوسيطة من قبل نفسك. أيضًا ، إذا كنت تريد التقاط أخطاء Multer فقط ، فيمكنك استخدام صنف MulterError المتصل بالكائن multer نفسه (على سبيل المثال err instanceof multer.MulterError).

var multer = require('multer')
var upload = multer().single('avatar')

app.post('/profile', function (req, res) {
  upload(req, res, function (err) {
    if (err instanceof multer.MulterError) {
      // A Multer error occurred when uploading.
    } else if (err) {
      // An unknown error occurred when uploading.
    }

    // Everything went fine.
  })
})

محرك التخزين الخاص بك

للحصول على معلومات حول كيفية إنشاء محرك التخزين الخاص بك ، راجع محرك تخزين Multer.

الترخيص

MIT