AddressErrors - 用于表示付款中地址的验证错误

AddressErrors 是付款请求 API 的字典，用于表示付款中地址（通常是帐单地址或送货地址）的验证错误。它的属性如果不为空的话，表示使用 PaymentAddress 描述的地址中的同名成员发生了验证错误。

如果地址的更改导致发生验证错误，则 shippingaddresschange 事件处理函数传递给 PaymentRequestUpdateEvent.updateWith() 的 PaymentDetailsUpdate 中的 shippingAddressErrors 对象是一个 AddressErrors 类型。

请参阅下面的实例，以了解其工作原理。

属性

addressLine

一个 DOMString，如果存在，表示 PaymentAddress 的 addressLine 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

city

一个 DOMString，如果存在，表示 PaymentAddress 的 city 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

country

一个 DOMString，如果存在，表示 PaymentAddress 的 country 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

dependentLocality

一个 DOMString，如果存在，表示 PaymentAddress 的 dependentLocality 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

organization

一个 DOMString，如果存在，表示 PaymentAddress 的 organization 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

phone

一个 DOMString，如果存在，表示 PaymentAddress 的 phone 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

postalCode

一个 DOMString，如果存在，表示 PaymentAddress 的 postalCode 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

recipient

一个 DOMString，如果存在，表示 PaymentAddress 的 recipient 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

region

一个 DOMString，如果存在，表示 PaymentAddress 的 region 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

regionCode

一个 DOMString，如果存在，表示 PaymentAddress 的 regionCode 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

sortingCode

一个 DOMString，如果存在，表示 PaymentAddress 的 sortingCode 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

过时的属性

这些属性已从规范中删除，不应再使用。

languageCode

一个 DOMString，如果存在，表示 PaymentAddress 的 languageCode 属性验证不通过。字符串的内容提供了易于理解的验证失败的解释，以及纠正问题的理想建议。

使用注意

请记住，某些错误可能是用户无法修复的。尽量避免让用户改正他们不能更改的内容，并且在某些情况下，无论如何您都需要允许接受验证错误（例如，您根据邮政数据库验证地址，用户输入了一个新的地址，但是该地址不在数据库中）。

实例

代码段：限制目标国家

function handleAddressChange(ev) {
  const validCountries = ["US", "CA", "GB", "JP", "CN", "MX"];

  const genericAddressError = "无法运送到指定地址。请检查是否有任何错误。";
  const invalidCountryError = "目前，我们只运送到美国，加拿大，英国，日本，中国和德国。";

  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);
}

有关此代码的工作方式的描述，请参见处理地址变更。

完整的例子

在这里，我们将看到上述实例的完整的工作版本（当然，它没有连接到实际的付款处理程序，因此实际上不处理任何付款）。在该实例中，我们处理向组织发送的捐赠，该组织将向捐赠者发送一份 “感谢” 礼物，因此该组织要求提供运输信息以及允许支付捐赠。

JavaScript

付款请求数据

首先，我们声明变量 supportedHandlers，它与 PaymentMethodData 兼容，还声明了 defaultPaymentDetails ，它是一个 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: '原始捐款金额',
      amount: {currency: 'USD', value: '65.00'}
    }
  ],
  shippingOptions: [
    {
      id: 'standard',
      label: '标准运输',
      amount: {currency: 'USD', value: '0.00'},
      selected: true
    }
  ]
};

supportedHandlers 描述了支持的付款处理程序及其详细信息。在此实例中，仅支持基本卡处理程序，并且将其配置为允许使用 Visa，Master Card，American Express 和 Discover 的借记卡和信用卡。

defaultPaymentDetails 描述了所请求的付款。说明所要求的总金额（包括标签和使用的货币），一个项目列表（在这种情况下，仅有 “原始捐赠金额” 一行）以及可用的运输选项列表；在这种情况下，也只有一个。

处理付款

主要的付款处理代码可在接下来的 process() 方法中找到。

let request;

function process() {
  let options = {requestShipping: true};

  try {
    request = new PaymentRequest(supportedHandlers, defaultPaymentDetails, options);
    // 在此处添加事件监听器。
    request.onshippingaddresschange = handleAddressChange;
    // 调用 show() 以触发浏览器的付款流程。
    request.show().then(function(instrumentResponse) {
      // 对 UI 的响应进行处理。
      console.log("得到响应！");
    })
    .catch(function(err) {
      // 对 request.show() 中的错误进行处理。
      console.error(`来自 show() 的错误：${err}`);
    });
  } catch (e) {
    // 捕获尝试创建 PaymentRequest 对象的所有错误。
  }
}

这段代码创建了一个新的 PaymentRequest，提供了我们在上面设置的受支持的处理程序和付款方式，以及其他选项（在这种情况下，我们想询问运输信息）。

之后，我们为 shippingaddresschange 事件设置处理程序，以便我们可以验证地址信息并调用请求的 show() 方法开始进入付款用户界面。

处理地址变更

当触发 shippingaddresschange 事件时，我们会调用 handleAddressChange() 方法，以确定该国家 / 地区是否是我们允许的发货目的地之一。

function handleAddressChange(ev) {
  const validCountries = ["US", "CA", "GB", "JP", "CN", "MX"];

  const genericAddressError = "无法运送到指定地址。请检查是否有任何错误。";
  const invalidCountryError = "目前，我们只运送到美国，加拿大，英国，日本，中国和德国。";

  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 事件不会直接收到 PaymentRequest 对象，因此我们从事件的 target 属性中获取该对象。如果请求的 shippingAddress 的 country 值不在 validCountries 数组中，我们生成错误。

这是通过删除当前在请求上设置的所有运输选项，然后设置一个名为 shippingAddressErrors 的对象来实现的，该对象包含一个 country 属性，该属性是一条错误消息，描述了为什么不允许指定国家 / 地区作为值。

然后，创建一个 PaymentDetailsUpdate 对象，并将其 error 对象设置为有关地址错误的通用消息，并重置该对象的值从 shippingAddressErrors 中获取，并附加 “...defaultPaymentDetails” 作为对象的值。

最后一步是调用事件的 updateWith() 方法，并传递一个 updateDetails 对象。这样可以使 Payment Request API 知道出现指定的一个或多个错误，但允许用户继续尝试编辑地址。

设置立即捐赠按钮

这段代码在 window 上的 load 事件中创建了处理程序，该处理程序又添加了所需的 click 事件处理程序到 “立即捐赠” 按钮，以便单击该按钮即可开始付款过程。

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

有关事件处理程序及其工作方式的信息，请参见 addEventListener()。

HTML

这是此实例的简单 HTML。

<p>为我们值得的事业捐款 65 美元，我们将向您发送一份礼物，以表示感谢！</p>
<button id="pay">立即捐款</button>

结果

最终完整的 AddressErrors 例子如下：

<p>为我们值得的事业捐款 65 美元，我们将向您发送一份礼物，以表示感谢！</p>
<button id="pay">立即捐款</button>
        

<script>
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
    }
  ]
}; 

let request;

function process() {
  let options = {requestShipping: true};

  try {
    request = new PaymentRequest(supportedHandlers, defaultPaymentDetails, options);
    // 在此处添加事件监听器。
    request.onshippingaddresschange = handleAddressChange;
    // 调用 show() 以触发浏览器的付款流程。
    request.show().then(function(instrumentResponse) {
      // 对 UI 的响应进行处理。
      console.log("得到响应！");
    })
    .catch(function(err) {
      // 对 request.show() 中的错误进行处理。
      console.error(`来自 show() 的错误：${err}`);
    });
  } catch (e) {
    // 捕获尝试创建 PaymentRequest 对象的所有错误。
  }
}

function handleAddressChange(ev) {
  const validCountries = ["US", "CA", "GB", "JP", "CN", "MX"];

  const genericAddressError = "无法运送到指定地址。请检查是否有任何错误。";
  const invalidCountryError = "目前，我们只运送到美国，加拿大，英国，日本，中国和德国。";

  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);
}

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

尝试一下 »

规范

规范	状态	备注
Payment Request API AddressErrors 的定义	候选推荐	初始定义。

桌面浏览器兼容性

暂无兼容数据