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 许可下发布的。
