AddressErrors | Web API

在此页

特性
用法注意事项
范例
规范
浏览器兼容性
相关话题

AddressErrors 字典用于支付请求 API to to report validation errors in a physical address (typically a billing address or a shipping address). Any members which is present indicates that a validation error occurred for the member of the same name in an address described using PaymentAddress .

AddressErrors is the type of the object returned by shippingAddressErrors 在 PaymentDetailsUpdate passed into PaymentRequestUpdateEvent.updateWith() 通过 shippingaddresschange event handler if a change to the address resulted in a validation error occurring.

见 examples below to see how this works.

特性

addressLine: DOMString which, if present, indicates that the addressLine 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
city: DOMString which, if present, indicates that the city 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
country: DOMString which, if present, indicates that the country 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
dependentLocality: DOMString which, if present, indicates that the dependentLocality 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
organization: DOMString which, if present, indicates that the organization 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
phone: DOMString which, if present, indicates that the phone 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
postalCode: DOMString which, if present, indicates that the postalCode 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
recipient: DOMString which, if present, indicates that the recipient 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
region: DOMString which, if present, indicates that the region 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
regionCode: DOMString which, if present, indicates that the regionCode 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.
sortingCode: DOMString which, if present, indicates that the sortingCode 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.

过时特性

These properties have been removed from the specification and should no longer be used.

languageCode: DOMString which, if present, indicates that the languageCode 特性为 PaymentAddress could not be validated. The contents of the string provide a human-readable explanation of the validation failure, and ideally suggestions to correct the problem.

用法注意事项

Keep in mind that some violation errors may be outside the ability of the user to fix. Try to avoid asking the user to make corrections to things they can't change, and there may be situations in which you need to allow validation errors to be accepted anyway (for example, if you validate addresses against a postal service database and a new home has been built and its address is not yet in the database).

范例

Snippet: Limiting destination countries

This first example is just a snippet showing an implementation of the event handler for the shippingaddresschange event which checks to be sure the chosen address is located within one of a limited number of countries.

function handleAddressChange(ev) {
  const validCountries = ["US", "CA", "GB", "JP", "CN", "MX"];
  const genericAddressError = "Unable to ship to the given address. Please check for any errors.";
  const invalidCountryError = "At this time, we only ship to the United States, Canada, Great Britain, Japan, China, and Germany.";
  let shippingAddress = ev.target.shippingAddress;
  let shippingAddressErrors = {};
  let updateDetails = {};
  if (!validCountries.includes(shippingAddress.country)) {
    ev.target.shippingOptions = [];
    shippingAddressErrors.country = invalidCountryError;
    updateDetails = {
      error: genericAddressError,
      shippingAddressErrors,
      ...defaultPaymentDetails
    };
  }
  ev.updateWith(updateDetails);
}

见 Handling address changes for a description of how this code works.

Complete example

Here we'll see a complete, working version of the example above (except of course that it's not connected to an actual payment handler, so no payments are actually processed). In the example, we're handling a donation to an organization that will be sending a "thank you" gift to the donor, so it requests shipping information along with allowing the donation payment itself.

JavaScript

Payment Request data

First, we declare the variables supportedHandlers , which is compatible with PaymentMethodData ，和 defaultPaymentDetails , which is a PaymentDetailsUpdate 对象。

let supportedHandlers = [
  {
    supportedMethods: "basic-card",
    data: {
      supportedNetworks: ["visa", "mastercard", "amex", "discover"],
      supportedTypes: ["credit", "debit"]
    }
  }
];
let defaultPaymentDetails = {
  total: {label: 'Donation', amount: {currency: 'USD', value: '65.00'}},
  displayItems: [
    {
      label: 'Original donation amount',
      amount: {currency: 'USD', value: '65.00'}
    }
  ],
  shippingOptions: [
    {
      id: 'standard',
      label: 'Standard shipping',
      amount: {currency: 'USD', value: '0.00'},
      selected: true
    }
  ]
};

supportedHandlers describes the supported payment handlers and the details for those. In this example, only the Basic Card handler is supported, and it's configured to permit both debit and credit cards from Visa, Master Card, American Express, and Discover.

defaultPaymentDetails describes the payment being requested. A description of the total amount being requested (including a label and the currency used), a list of the line items (in this case only one, "Original donation amount"), and a list of shipping options available; in this case only one.

Process the payment

The main payment processing code is found in the process() method, up next.

let request;
function process() {
  let options = {requestShipping: true};
  try {
    request = new PaymentRequest(supportedHandlers, defaultPaymentDetails, options);
    // Add event listeners here.
    request.onshippingaddresschange = handleAddressChange;
    // Call show() to trigger the browser's payment flow.
    request.show().then(function(instrumentResponse) {
      // Do something with the response from the UI.
      console.log("Got response!");
    })
    .catch(function(err) {
      // Do something with the error from request.show().
      console.error(`Error from show(): ${err}`);
    });
  } catch (e) {
    // Catch any errors from trying to create the PaymentRequest object.
  }
}

This code creates a new PaymentRequest , providing the supported handlers and payment options we set up above, as well as additional options (in this case, that we want to ask for shipping information).

After that, we set up the handler for the shippingaddresschange event so we can validate address information and call the request's show() method to start running the payment UI.

Handling address changes

handleAddressChange() method, called when shippingaddresschange events occur, is where we'll look to see if the country is one of those we allow as shipping destinations.

function handleAddressChange(ev) {
  const validCountries = ["US", "CA", "GB", "JP", "CN", "MX"];
  const genericAddressError = "Unable to ship to the given address. Please check for any errors.";
  const invalidCountryError = "At this time, we only ship to the United States, Canada, Great Britain, Japan, China, and Germany.";
  let shippingAddress = ev.target.shippingAddress;
  let shippingAddressErrors = {};
  let updateDetails = {};
  if (!validCountries.includes(shippingAddress.country)) {
    ev.target.shippingOptions = [];
    shippingAddressErrors.country = invalidCountryError;
    updateDetails = {
      error: genericAddressError,
      shippingAddressErrors,
      ...defaultPaymentDetails
    };
  }
  ev.updateWith(updateDetails);
}

shippingaddresschange event doesn't receive the PaymentRequest object directly, so we fetch it from the target property of the event. If the request's shippingAddress has a value for country which isn't in the array validCountries , we generate the error.

That's done by removing all shipping options currently set on the request, then set up an object named shippingAddressErrors which contains a country property which is an error message describing why the stated country isn't being permitted as a value.

Then a PaymentDetailsUpdate object is created with its error set to a generic message about address errors and with the reset of the object's values taken from shippingAddressErrors , and, using " ...defaultPaymentDetails " as the final entry in the object, the remeainder of the properties' values are taken from defaultPaymentDetails .

The final step is to call the event's updateWith() method, passing along the updateDetails object. This lets the Payment Request API know to present the specified error or errors but to allow the user to keep trying to edit the address.

Setting up the Donate Now button

This code creates a handler for the load event on the window which in turn adds the needed click event handler to the "Donate Now" button so that clicking it starts the payment process.

window.addEventListener("load", function(ev) {
  document.getElementById("pay").addEventListener("click", process, false);
}, false);

见 addEventListener() for information about event handlers and how they work.

HTML

Here's the simple HTML for this example.

<p>Donate US $65 to our worthwhile cause and we will send you a totally
not-useless gift as a token of our thanks!</p>
<button id="pay">Donate Now</button>

结果

The final product is below.

注意： if you have content blocking features enabled in your browser, the example may not work inline below. In that case, you can view the example on its own page .

规范

规范	状态	注释
支付请求 API The definition of 'AddressErrors' in that specification.	候选推荐	初始定义。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

No compatibility data found. Please contribute data for "api.AddressErrors" (depth: 1) to the MDN 兼容性数据存储库 .

元数据

最后修改： Sep 5, 2019

在此页

特性