# Address Element Use the Address Element to collect complete billing and shipping addresses. Address Element 是一个可嵌入的 UI 组件，用于接受完整的地址。用它来收集收货地址，或者当需要完整的账单地址时使用，例如出于税务目的。 | 期权 | 描述 | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Theme** | Use the dropdown to choose a theme or customize the theme with the [Elements Appearance API](https://docs.stripe.com/elements/address-element.md#appearance). | | **桌面和移动设备大小** | Use the dropdown to set the max pixel width of the parent element that the Address Element is mounted to. You can set it to 750px (desktop) or 320px (mobile). | | **Customer location** | Use this [option](https://docs.stripe.com/js/elements_object/create#stripe_elements-options-locale) to choose a location for accepting complete addresses. Changing the location localizes the UI language. | | **Phone number** | Enable this [option](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-fields-phone) to allow phone number collection when an address is entered or when using an existing contact. | | **Autocomplete** | Enable this [option](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-autocomplete) to decrease checkout time, reduce validation errors, and increase checkout conversion with built-in address autocomplete. Stripe supports 236 regional address formats, including right-to-left address formats. | | **Contacts** | Enable this [option](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-contacts) to add a new address or change an existing address or phone number. | ## 开始使用 You can use the Address Element with either the Checkout elements integration (Elements with Checkout Sessions API) or the Advanced integration (Elements with Payment Intents API). [Compare the features and availability](https://docs.stripe.com/payments/online-payments.md#compare-features-and-availability) to see which integration suits your use case. [Collect addresses (Elements with Checkout Sessions API)](https://docs.stripe.com/payments/advanced/collect-addresses.md?payment-ui=embedded-components): Use the Checkout elements integration to collect addresses. [Collect addresses (Advanced integration)](https://docs.stripe.com/payments/advanced/collect-addresses.md?payment-ui=elements): Use the Advanced integration to collect addresses. [Clone a sample app (Advanced integration)](https://github.com/stripe-samples/link) ## Create an Address Element 在创建 Address Element 时，请指定将其用于收货模式还是计费模式。 #### 收货模式 在收货模式下，该元素执行两项操作： - 收集收货地址。 - 为客户提供也将其用作账单地址的选项。 ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { mode: 'shipping' }; const elements = stripe.elements({ clientSecret, appearance }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const addressElement = elements.create('address', options); addressElement.mount('#address-element'); ``` #### 计费模式 在计费模式下，该元素仅收集账单地址。 ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { mode: 'billing' }; const elements = stripe.elements({ clientSecret, appearance }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const addressElement = elements.create('address', options); addressElement.mount('#address-element'); ``` ### 将 Address Element 与其他元素结合使用 您可以用多个 Address Element（每种模式一种）来收集收货地址和账单地址。 如果您需要收集收货地址和账单地址，并且只想使用一个 Address Element，请在配送模式下使用 Address Element，并使用 [Payment Element](https://docs.stripe.com/payments/payment-element.md) 仅收集必要的账单地址详情。 在将 Address Element 与其他元素结合使用时，在确认 PaymentIntent 或 SetupIntent 时会有一些自动行为。Address Element 会在确认 PaymentIntent 或 SetupIntent 时验证完整性，如有验证错误，则会为每个字段显示错误。 ## Use an address The Address Element automatically works with the [Payment](https://docs.stripe.com/payments/payment-element.md) or Express Checkout Element. When a customer provides an address and a payment method, Stripe combines them into a single *PaymentIntent* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) with the address in the correct field. ### Automatic behavior The element’s default behavior depends on its mode. #### Shipping mode In shipping mode, the address is stored in these fields: - It appears in the [shipping](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-shipping) field. - If the customer indicates it’s also the billing address, it also appears in the [billing_details](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-payment_method_data-billing_details) field. To enable combining information, create all elements from the same `Elements` object, as in this example: ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { mode: 'shipping' }; const paymentElementOptions = { layout: 'accordion'}; const elements = stripe.elements({ clientSecret }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const addressElement = elements.create('address', options); const paymentElement = elements.create('payment', paymentElementOptions); addressElement.mount('#address-element'); paymentElement.mount('#payment-element'); ``` #### Billing mode In billing mode, the address is stored in the [billing_details](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-payment_method_data-billing_details) field. To enable combining information, create all elements from the same `Elements` object, as in this example: ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { mode: 'billing' }; const paymentElementOptions = { layout: 'accordion'}; const elements = stripe.elements({ clientSecret }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const addressElement = elements.create('address', options); const paymentElement = elements.create('payment', paymentElementOptions); addressElement.mount('#address-element'); paymentElement.mount('#payment-element'); ``` ### Custom behavior Normally, the Address Element’s default behavior is enough. But in a complex payment flow, you might need to write custom responses to the customer’s input. For information, see [Listen for address input](https://docs.stripe.com/payments/advanced/collect-addresses.md). ## Autocomplete If your customer selects a supported country for their address, then they see the autocomplete options. The Address Element can autocomplete addresses for the following countries: - AU - BE - BR - CA - CH - DE - ES - FR - GB - IE - IN - IT - JP - MX - MY - NL - NO - NZ - PH - PL - RU - SE - SG - TR - US - ZA If you use the Address Element and the Payment Element together, Stripe enables autocomplete with no configuration required. This is done using a Stripe-provided Google Maps API key. > By using autocomplete, you agree to comply with the [Google Maps Platform Acceptable Use Policy](https://cloud.google.com/maps-platform/terms/aup). If you violate this policy, we might disable autocomplete, or take any other action as necessary. If you use the Address Element alone, you must use your own [Google Maps API Places Library key](https://developers.google.com/maps/documentation/javascript/places), which is managed separately from your Stripe account. Pass the key in the [autocomplete.apiKey](https://docs.stripe.com/js/elements_object/create_address_element#address_element_create-options-autocomplete-apiKey) option. ## Autofill with Link [Link](https://docs.stripe.com/payments/link.md) saves and autofills payment and shipping information for the options you’ve enabled. For example, if the Link customer has a saved phone number, Stripe autofills the phone number only if phone number collection is enabled. When a returning Link customer authenticates, Stripe autofills their shipping information in the Address element. ![使用多个元素创建支付表单](https://b.stripecdn.com/docs-statics-srv/assets/link-with-elements.f60af275f69b6e6e73c766d1f9928457.png) 使用多个元素创建支付表单 To enable autofill, create all elements from the same `Elements` object, as in this example: ```javascript const stripe = Stripe('<>'); const appearance = { /* appearance */ }; const options = { mode: 'shipping' }; const paymentElementOptions = { layout: 'accordion'}; const elements = stripe.elements({ clientSecret }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const linkAuthElement = elements.create('linkAuthentication'); const addressElement = elements.create('address', options); const paymentElement = elements.create('payment', paymentElementOptions); linkAuthElement.mount('#link-auth-element'); addressElement.mount('#address-element'); paymentElement.mount('#payment-element'); ``` ## 外观 You can use the Appearance API to control the style of all elements. Choose a theme or update specific details. ![Examples of light and dark modes for the address element.](https://b.stripecdn.com/docs-statics-srv/assets/address_appearance_example.c7884ea763b05e5881d65ed2b2afadbc.png) 例如，选择“扁平”主题，并覆盖主文本颜色。 ```javascript const stripe = Stripe('<>'); const appearance = { theme: 'flat', variables: { colorPrimaryText: '#262626' } }; const options = { /* options */ }; const elements = stripe.elements({ clientSecret, appearance }); // 在一个工作的集成中，这是后端传递的一个值，带有详细信息，如付款金额。详情见完整样本。 const addressElement = elements.create('address', options); addressElement.mount('#address-element'); ``` See the Appearance API documentation for the [Elements with Checkout Sessions API integration](https://docs.stripe.com/payments/checkout/customization/appearance.md?payment-ui=embedded-components) or the [Advanced integration](https://docs.stripe.com/elements/appearance-api.md) for a full list of themes and variables.