Skip to main content
Version: Next

Taro.request(option)

Initiates an HTTPS request. Read related instructions before use.

Data Parameters

The data ultimately sent to the server must be a String. If the passed data is not a String, it will be converted to the String type according to the following rules:

  • Data from the GET method is converted to a query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...).

  • Data from the POST method with header['content-type'] being application/json is serialized into the JSON format.

  • Data from the POST method with header['content-type'] being application/x-www-form-urlencoded is converted to a query string (encodeURIComponent(k)=encodeURIComponent(v)&encodeURIComponent(k)=encodeURIComponent(v)...)

Reference

Type

<T = any, U = any>(option: Option<U>) => RequestTask<T>

Parameters

Option

PropertyTypeDefaultRequiredDescription
urlstringYesDeveloper server API URL
dataUNoRequest parameter
dataType"json" | "other"NoThe returned data format
headerRecord<string, any>NoSets request Header. Referer is not available in Header.

content-type is application/jsonby default.
method"OPTIONS" | "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "TRACE" | "CONNECT"NoHTTP request method
responseType"text" | "arraybuffer"NoThe response data format
jsonpbooleanfalseNoSpecify whether to use jsonp to fetch data on the H5 side
jsonpCachebooleanfalseNoSpecifies whether data fetched using jsonp should be cached on the H5 side
mode"no-cors" | "cors" | "same-origin"same-originNoSpecifies whether cross-domain requests are allowed on the H5 side
credentials"same-origin" | "include" | "omit"omitNoSpecify whether to carry cookies on the H5 side
cache"default" | "no-cache" | "reload" | "force-cache" | "only-if-cached"defaultNoSpecify the cache mode on the H5 side
timeoutnumber2000NoSpecify the request timeout on the H5 side
retryTimesnumber2NoSpecify the number of request retries on the H5 side
backupstring | string[]NoSpecify the backup requestion for requests on the H5 side
dataCheck() => booleanNoSpecify the data validation function for the request response on the H5 side, and if the result is false, request backup requestion.
useStorebooleanfalseNoSpecify whether the request on the H5 side uses caching.
storeCheckKeystringNoSet the key for the request cache checks on the H5 side
storeSignstringNoSet the request cache signature on the H5 side
storeCheck() => booleanNoSet the request checksum function on the H5 side, generally not required
complete(res: CallbackResult) => voidNoThe callback function used when the API call completed (always executed whether the call succeeds or fails)
fail(res: CallbackResult) => voidNoThe callback function for a failed API call
success(res: CallbackResult) => voidNoThe callback function for a successful API call

SuccessCallbackResult

PropertyTypeDescription
dataTData returned by the developer server
headerRecord<string, any>HTTP Response Header returned by the developer server
statusCodenumberHTTP status code returned by the developer server
errMsgstringCall result

dataType

Valid values of object.dataType

ValueDescription
jsonThe returned data is in the JSON format. Call JSON.parse on the returned data.
OthersDo not call JSON.parse on the returned data.

method

Valid values of object.method

ValueDescription
OPTIONSHTTP request OPTIONS
GETHTTP request GET
HEADHTTP request HEAD
POSTHTTP request POST
PUTHTTP request PUT
DELETEHTTP request DELETE
TRACEHTTP request TRACE
CONNECTHTTP request CONNECT

responseType

Valid values of object.responseType

ValueDescription
textThe response data is in the text format.
arraybufferThe response data is in the ArrayBuffer format.

cors_mode

Valid values of CORS mode

ValueDescription
no-corsCross-domain requests will get an opaque response
corsAllow cross-domain requests
same-originRequests are always made to the current source

credentials

Valid values of credentials

ValueDescription
includeAlways send authentication information such as cookies, HTTP Basic authentication, etc. local to the requested resource domain.
same-originAuthentication information such as cookies, HTTP Basic authentication, etc. is only sent if the URL is the same source as the response script.
omitNo cookies are sent.

Sample Code

Example 1

Taro.request({
url: 'test.php', // This value for demonstration purposes only is not a real API URL.
data: {
x: '',
y: ''
},
header: {
'content-type': 'application/json' // Default value
},
success: function (res) {
console.log(res.data)
}
})

Example 2

const res = await Taro.request(params)

API Support

APIWeChat Mini-ProgramBaidu Smart-ProgramAlipay Mini-ProgramByteDance Mini-ProgramQQ Mini-ProgramH5React Native
Taro.request✔️✔️✔️✔️✔️✔️✔️