form data

بيانات النموذج

مكتبة لإنشاء تدفقات "multipart/form-data" قابلة للقراءة. يمكن استخدامه لإرسال النماذج وتحميل الملفات إلى تطبيقات الويب الأخرى.

واجهة برمجة التطبيقات (API) لهذه المكتبة مستوحاة من واجهة XMLHttpRequest-2 FormData.

ثَبَّتَ

 npm install --save form-data

الاستخدام

في هذا المثال، نقوم بإنشاء نموذج يحتوي على 3 حقول تحتوي على سلسلة ومخزن مؤقت ودفق ملف.

 var FormData = require ( 'form-data' ) ;
var fs = require ( 'fs' ) ;

var form = new FormData ( ) ;
form . append ( 'my_field' , 'my value' ) ;
form . append ( 'my_buffer' , new Buffer ( 10 ) ) ;
form . append ( 'my_file' , fs . createReadStream ( '/foo/bar.jpg' ) ) ;

كما يمكنك استخدام دفق استجابة http:

 var FormData = require ( 'form-data' ) ;
var http = require ( 'http' ) ;

var form = new FormData ( ) ;

http . request ( 'http://nodejs.org/images/logo.png' , function ( response ) {
  form . append ( 'my_field' , 'my value' ) ;
  form . append ( 'my_buffer' , new Buffer ( 10 ) ) ;
  form . append ( 'my_logo' , response ) ;
} ) ;

أو تيار طلب @mikeal:

 var FormData = require ( 'form-data' ) ;
var request = require ( 'request' ) ;

var form = new FormData ( ) ;

form . append ( 'my_field' , 'my value' ) ;
form . append ( 'my_buffer' , new Buffer ( 10 ) ) ;
form . append ( 'my_logo' , request ( 'http://nodejs.org/images/logo.png' ) ) ;

لإرسال هذا النموذج إلى تطبيق ويب، اتصل بطريقة submit(url, [callback]) :

 form . submit ( 'http://example.org/' , function ( err , res ) {
  // res – response object (http.IncomingMessage)  //
  res . resume ( ) ;
} ) ;

لمزيد من معالجة الطلبات المتقدمة، تقوم طريقة submit() بإرجاع كائن http.ClientRequest ، أو يمكنك الاختيار من إحدى طرق الإرسال البديلة.

خيارات مخصصة

يمكنك توفير خيارات مخصصة، مثل maxDataSize :

 var FormData = require ( 'form-data' ) ;

var form = new FormData ( { maxDataSize : 20971520 } ) ;
form . append ( 'my_field' , 'my value' ) ;
form . append ( 'my_buffer' , /* something big */ ) ;

يمكن العثور على قائمة بالخيارات المتاحة في البث المشترك

طرق التقديم البديلة

يمكنك استخدام واجهة عميل http الخاصة بالعقدة:

 var http = require ( 'http' ) ;

var request = http . request ( {
  method : 'post' ,
  host : 'example.org' ,
  path : '/upload' ,
  headers : form . getHeaders ( )
} ) ;

form . pipe ( request ) ;

request . on ( 'response' , function ( res ) {
  console . log ( res . statusCode ) ;
} ) ;

أو إذا كنت تفضل تعيين رأس 'Content-Length' لك:

 form . submit ( 'example.org/upload' , function ( err , res ) {
  console . log ( res . statusCode ) ;
} ) ;

لاستخدام رؤوس مخصصة وطول معروف مسبقًا في الأجزاء:

 var CRLF = 'rn' ;
var form = new FormData ( ) ;

var options = {
  header : CRLF + '--' + form . getBoundary ( ) + CRLF + 'X-Custom-Header: 123' + CRLF + CRLF ,
  knownLength : 1
} ;

form . append ( 'my_buffer' , buffer , options ) ;

form . submit ( 'http://example.com/' , function ( err , res ) {
  if ( err ) throw err ;
  console . log ( 'Done' ) ;
} ) ;

يمكن لـ Form-Data التعرف على جميع المعلومات المطلوبة وجلبها من الأنواع الشائعة للتدفقات ( fs.readStream و http.response و mikeal's request )، بالنسبة لبعض الأنواع الأخرى من التدفقات، ستحتاج إلى توفير المعلومات المتعلقة بالملف يدويًا:

 someModule . stream ( function ( err , stdout , stderr ) {
  if ( err ) throw err ;

  var form = new FormData ( ) ;

  form . append ( 'file' , stdout , {
    filename : 'unicycle.jpg' , // ... or:
    filepath : 'photos/toys/unicycle.jpg' ,
    contentType : 'image/jpeg' ,
    knownLength : 19806
  } ) ;

  form . submit ( 'http://example.com/' , function ( err , res ) {
    if ( err ) throw err ;
    console . log ( 'Done' ) ;
  } ) ;
} ) ;

تتجاوز الخاصية filepath filename وقد تحتوي على مسار نسبي. يُستخدم هذا عادةً عند تحميل ملفات متعددة من الدليل.

بالنسبة لحالات الحافة، مثل طلب POST إلى URL مع سلسلة استعلام أو لتمرير بيانات اعتماد مصادقة HTTP، يمكن تمرير الكائن إلى form.submit() كمعلمة أولى:

 form . submit ( {
  host : 'example.com' ,
  path : '/probably.php?extra=params' ,
  auth : 'username:password'
} , function ( err , res ) {
  console . log ( res . statusCode ) ;
} ) ;

في حال كنت بحاجة أيضًا إلى إرسال رؤوس HTTP مخصصة مع طلب POST، يمكنك استخدام مفتاح headers في المعلمة الأولى للنموذج form.submit() :

 form . submit ( {
  host : 'example.com' ,
  path : '/surelynot.php' ,
  headers : { 'x-test-header' : 'test-header-value' }
} , function ( err , res ) {
  console . log ( res . statusCode ) ;
} ) ;

طُرق

• إلحاق باطل ( حقل السلسلة ، القيمة المختلطة [، الخيارات المختلطة ]).
• الرؤوس getHeaders( [ الرؤوس userHeaders ] )
• سلسلة getBoundary ()
• مجموعة باطلة ()
• المخزن المؤقت getBuffer()
• عدد صحيح getLengthSync()
• عدد صحيح getLength ( رد وظيفة )
• القيمة المنطقية لهاKnownLength()
• طلب إرسال ( المعاملات ، رد الاتصال وظيفة )
• سلسلة إلى سلسلة ()

إلحاق باطل ( حقل السلسلة ، القيمة المختلطة [، الخيارات المختلطة ])

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

 var form = new FormData ( ) ;
form . append ( 'my_string' , 'my value' ) ;
form . append ( 'my_integer' , 1 ) ;
form . append ( 'my_boolean' , true ) ;
form . append ( 'my_buffer' , new Buffer ( 10 ) ) ;
form . append ( 'my_array_as_json' , JSON . stringify ( [ 'bird' , 'cute' ] ) )

يمكنك توفير سلسلة للخيارات، أو كائن.

 // Set filename by providing a string for options
form . append ( 'my_file' , fs . createReadStream ( '/foo/bar.jpg' ) , 'bar.jpg' ) ;

// provide an object.
form . append ( 'my_file' , fs . createReadStream ( '/foo/bar.jpg' ) , { filename : 'bar.jpg' , contentType : 'image/jpeg' , knownLength : 19806 } ) ; 

الرؤوس getHeaders( [ الرؤوس userHeaders ] )

تضيف هذه الطريقة رأس content-type الصحيح إلى المصفوفة المتوفرة من userHeaders .

سلسلة getBoundary ()

قم بإرجاع حدود بيانات النموذج. بشكل افتراضي، يتكون الحد من 26 - متبوعًا بـ 24 رقمًا، على سبيل المثال:

 -- -- -- -- -- -- -- -- -- -- -- -- -- 515890814546601021194782 

مجموعة باطلة ( حدود السلسلة)

قم بتعيين سلسلة الحدود، وتجاوز السلوك الافتراضي الموضح أعلاه.

ملاحظة: يجب أن تكون الحدود فريدة وقد لا تظهر في البيانات.

المخزن المؤقت getBuffer()

قم بإرجاع حزمة طلب بيانات النموذج الكاملة كمخزن مؤقت. يمكنك إدراج هذا المخزن المؤقت في Axios على سبيل المثال لإرسال بيانات متعددة الأجزاء.

 var form = new FormData ( ) ;
form . append ( 'my_buffer' , Buffer . from ( [ 0x4a , 0x42 , 0x20 , 0x52 , 0x6f , 0x63 , 0x6b , 0x73 ] ) ) ;
form . append ( 'my_file' , fs . readFileSync ( '/foo/bar.jpg' ) ) ;

axios . post ( 'https://example.com/path/to/api' ,
            form . getBuffer ( ) ,
            form . getHeaders ( )
          )

ملاحظة: نظرًا لأن الإخراج من النوع Buffer، يمكنك فقط إلحاق الأنواع التي يقبلها Buffer: string، أو Buffer، أو ArrayBuffer، أو Array، أو Array-like Object . على سبيل المثال، سوف يؤدي ReadStream إلى حدوث خطأ.

عدد صحيح getLengthSync()

نفس getLength ولكنه متزامن.

ملاحظة: لا يقوم getLengthSync بحساب طول التدفقات.

عدد صحيح getLength ( رد وظيفة )

إرجاع مزامنة Content-Length . يتم استخدام رد الاتصال لمعالجة الأخطاء والمتابعة بمجرد حساب الطول

 this . getLength ( function ( err , length ) {
  if ( err ) {
    this . _error ( err ) ;
    return ;
  }

  // add content length
  request . setHeader ( 'Content-Length' , length ) ;

  ...
} . bind ( this ) ) ; 

القيمة المنطقية لهاKnownLength()

يتحقق مما إذا كان طول القيم المضافة معروفًا.

طلب إرسال ( المعاملات ، رد الاتصال وظيفة )

إرسال النموذج إلى تطبيق ويب.

 var form = new FormData ( ) ;
form . append ( 'my_string' , 'Hello World' ) ;

form . submit ( 'http://example.com/' , function ( err , res ) {
  // res – response object (http.IncomingMessage)  //
  res . resume ( ) ;
} ) ; 

سلسلة إلى سلسلة ()

إرجاع بيانات النموذج كسلسلة. لا تستخدم هذا إذا كنت ترسل ملفات أو مخازن مؤقتة، استخدم getBuffer() بدلاً من ذلك.

التكامل مع المكتبات الأخرى

طلب

تقديم النموذج باستخدام الطلب:

 var formData = {
  my_field : 'my_value' ,
  my_file : fs . createReadStream ( __dirname + '/unicycle.jpg' ) ,
} ;

request . post ( { url : 'http://service.com/upload' , formData : formData } , function ( err , httpResponse , body ) {
  if ( err ) {
    return console . error ( 'upload failed:' , err ) ;
  }
  console . log ( 'Upload successful!  Server responded with:' , body ) ;
} ) ;

لمزيد من التفاصيل، راجع الملف التمهيدي للطلب.

جلب العقدة

يمكنك أيضًا إرسال نموذج باستخدام جلب العقدة:

 var form = new FormData ( ) ;

form . append ( 'a' , 1 ) ;

fetch ( 'http://example.com' , { method : 'POST' , body : form } )
    . then ( function ( res ) {
        return res . json ( ) ;
    } ) . then ( function ( json ) {
        console . log ( json ) ;
    } ) ; 

أكسيوس

في Node.js يمكنك نشر ملف باستخدام axios:

 const form = new FormData ( ) ;
const stream = fs . createReadStream ( PATH_TO_FILE ) ;

form . append ( 'image' , stream ) ;

// In Node.js environment you need to set boundary in the header field 'Content-Type' by calling method `getHeaders`
const formHeaders = form . getHeaders ( ) ;

axios . post ( 'http://example.com' , form , {
  headers : {
    ... formHeaders ,
  } ,
} )
. then ( response => response )
. catch ( error => error ) 

ملحوظات

• طريقة getLengthSync() لا تحسب طول التدفقات، استخدم خيارات knownLength كحل بديل.
• سيرسل getLength(cb) خطأً كمعلمة أولى لرد الاتصال إذا تعذر حساب طول الدفق (على سبيل المثال، أرسل دفقًا مخصصًا بدون استخدام knownLength ).
• لن يضيف submit content-length إذا كان طول النموذج غير معروف أو غير قابل للحساب.
• بدء الإصدار 2.x أسقط FormData الدعم لـ [email protected] .
• بدء الإصدار 3.x أسقط FormData الدعم لـ [email protected] .

رخصة

يتم إصدار بيانات النموذج بموجب ترخيص MIT.