form data
v4.0.1
用於建立可讀的"multipart/form-data"流的庫。可用於向其他 Web 應用程式提交表單和文件上傳。
該函式庫的 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' ) ) ;為了將此表單提交到 Web 應用程序，請呼叫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並且可能包含相對路徑。這通常在從目錄上傳多個檔案時使用。
對於邊緣情況，例如使用查詢字串對 URL 進行 POST 請求或傳遞 HTTP 驗證憑證，可以將物件作為第一個參數傳遞給form.submit() ：
form . submit ( {
host : 'example.com' ,
path : '/probably.php?extra=params' ,
auth : 'username:password'
} , function ( err , res ) {
console . log ( res . statusCode ) ;
} ) ;如果您還需要透過 POST 請求傳送自訂 HTTP 標頭，您可以在form.submit()的第一個參數中使用headers鍵：
form . submit ( {
host : 'example.com' ,
path : '/surelynot.php' ,
headers : { 'x-test-header' : 'test-header-value' }
} , function ( err , res ) {
console . log ( res . statusCode ) ;
} ) ;將資料附加到表單中。您可以提交任何格式（字串、整數、布林值、緩衝區等）。但是，不支援數組，需要使用者將其轉換為字串。
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 } ) ; 此方法將正確的content-type標頭新增至提供的userHeaders陣列。
傳回 formData 的邊界。預設情況下，邊界由 26 -後跟 24 個數字組成，例如：
-- -- -- -- -- -- -- -- -- -- -- -- -- 515890814546601021194782 設定邊界字串，覆蓋上述預設行為。
注意：邊界必須是唯一的，並且可能不會出現在資料中。
返回完整的formdata請求包，作為Buffer。您可以在例如 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 將導致錯誤。
與getLength相同但同步。
注意：getLengthSync不計算流長度。
返回非同步Content-Length 。回調用於處理錯誤並在計算長度後繼續
this . getLength ( function ( err , length ) {
if ( err ) {
this . _error ( err ) ;
return ;
}
// add content length
request . setHeader ( 'Content-Length' , length ) ;
...
} . bind ( this ) ) ; 檢查添加值的長度是否已知。
將表單提交到 Web 應用程式。
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 ) ;
} ) ;有關更多詳細信息，請參閱請求自述文件。
您也可以使用 node-fetch 提交表單：
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選項作為解法。knownLength在自訂流中發送） getLength(cb)將發送錯誤作為回調的第一個參數。submit不會新增content-length 。2.x FormData 開始，已放棄對[email protected]的支援。3.x版本開始，FormData 已放棄對[email protected]的支援。 Form-Data 是在 MIT 許可下發布的。
