청구지 또는 배송 주소를 수집합니다. 필드, 순서, 유효성 검사는 선택한 국가를 따릅니다. 거리 주소 자동 완성(휴대폰에서는 전체 화면)과 주소를 읽거나 검증하는 메서드를 포함합니다.
이 페이지는 @whop/elements@1.10.0 및 @whop/elements-react@1.10.0을 다룹니다.
v1.0.0부터 지원.
Payments 안에 마운트됩니다. props와 콜백은 생성 옵션 또는 React props로 전달합니다. validate()와 getValues()를 호출하려면 생성된 핸들 또는 React ref를 보관하세요.
mode당 하나. 하나의 Payments 핸들 아래에서 각 mode 값마다 <AddressElement />를 하나씩 마운트하세요. 같은 mode로 두 번째 마운트를 시도하면 거부됩니다. 엘리먼트의 mode는 생성 시 설정되므로, 변경하려면 엘리먼트를 제거하고 새로 생성하세요.
WhopPayments 스코프 안에 마운트됩니다. 선택한 국가 고유의 형식으로 청구지 주소를 수집하며, 바인딩 여부와 관계없이 컨트롤러가 토큰 생성 시 이를 읽습니다.
청구와 확인 토큰을 소유하는 <Payments> 안에 마운트합니다. <Payments> 자체는 <WhopElements> 안에 마운트됩니다. 구매자 국가 고유의 형식으로 청구지 주소를 렌더링하고 프로바이더에 게시하므로, createConfirmationToken은 아무것도 전달받지 않아도 이를 가져옵니다.
수집할 주소 유형으로, billing(기본값) 또는 shipping입니다. 브라우저 자동 완성 용도도 함께 설정합니다. 하나의 핸들 아래에 각각 하나씩 마운트할 수 있습니다. 청구 정보는 billing 엘리먼트에서 가져오며, billing 엘리먼트가 마운트되지 않은 경우 shipping 엘리먼트에서 가져옵니다. 기본값은 "billing"입니다.
"split" | "none" | "combined"
이름 행입니다. 전체 이름 필드 하나(기본값), 이름/성 분리 필드, 또는 없음 중 하나입니다. 기본값은 "combined"입니다.
"never" | "toggle" | "always"
주소 2행입니다. 항상 표시(기본값), 텍스트 버튼으로 표시(toggle), 또는 수집하지 않음 중 하나입니다. 기본값은 "always"입니다.
object
첫 렌더링 전에 한 번 적용되는 초기값입니다(address.country는 ISO 3166-1 alpha-2 국가 코드). IP 기반 국가 감지보다 우선합니다.
표시 속성
string
object
표시 속성
string
string
string
string
"business" | "individual"
string
string
string
string
string
string
"full" | "compact" | "wrap"
full(기본값)은 레이블이 있는 필드를 세로로 쌓습니다. compact는 자리 표시자를 레이블로 사용하는 필드를 하나의 테두리 안에 그룹화합니다. wrap은 full의 개별 필드를 유지하면서 도시, 주, 우편번호를 나란히 배치합니다. 이 필드들과 full에서 이미 나란히 배치되는 쌍(이름과 성, 조직)은 너비가 허용하는 만큼 한 행에 배치되고, 너비가 좁아지면 줄바꿈됩니다. 기본값은 "full"입니다.
"above" | "floating"
above(기본값)는 각 레이블을 필드 밖에 둡니다. full 레이아웃에서는 필드 위에, compact에서는 자리 표시자로 표시합니다. floating은 두 레이아웃 모두에서 각 레이블을 필드의 자리 표시자로 사용하고, 필드에 값이 입력되면 입력된 텍스트 위에 작은 레이블을 표시합니다. 기본값은 "above"입니다. v1.5.0부터 지원.
"minimal" | "full"
full(기본값)은 선택한 국가의 전체 주소 형식을 따릅니다. minimal은 국가와 우편번호만 수집합니다. name은 이와 별개로 필수 이름 필드를 추가합니다. 생략하려면 name을 none으로 설정하세요. 이 엘리먼트는 결제 수단에 필요한 필드를 추가하지 않습니다. 카드 확인에는 이름, 국가, 우편번호가 필요하므로 name을 활성화된 상태로 두거나 billingDetails.name을 전달하세요. 기본값은 "full"입니다.
"none" | "name" | "name_with_type"
조직 필드입니다. 없음(기본값), 이름만, 또는 사업자/개인 선택기가 포함된 이름 중 하나입니다. 기본값은 "none"입니다.
boolean
구매자의 IP로 기본 국가를 설정합니다(첫 렌더링 전에 결정). 실패하면 컨트롤러의 countryHint, 그다음 US로 대체됩니다. 기본값은 true입니다.
string[]
허용되는 ISO 3166-1 alpha-2 국가 코드입니다. 코드가 하나이면 선택기는 계속 표시되지만 해당 국가만 제공합니다.
boolean
거리 주소에 Google Places 제안을 활성화합니다. 일치하는 항목이 없거나 Places가 차단된 경우 목록에 일치 항목이 없다고 표시하고 구매자가 주소를 직접 입력할 수 있게 합니다. 휴대폰에서는 키보드가 가리지 않도록 제안이 거리 필드 아래가 아니라 거리 필드의 검색 버튼에서 전체 화면으로 열립니다. 일반 입력을 사용하려면 false로 설정하세요. 기본값은 true입니다.
boolean
처음부터 모든 주소 필드를 표시합니다. 기본적으로(false) 양식은 거리 주소로 시작하며, 구매자가 제안을 선택하거나 주소를 입력하거나 직접 입력을 선택하면 나머지 필드를 표시합니다. 기본값은 false입니다. v1.6.0부터 지원.
object[]
주소 양식과 함께 렌더링되는 추가 필드입니다. 값은 유효성 검사를 거쳐 별도의 custom 맵으로 전달됩니다.
표시 속성
string
필수
string
필수
"phone" | "text" | "select" | "date"
필수
string
필수
"after_name", "after_organization", "before_country", "after_address" 중 하나입니다.
boolean
string[]
string
string
string
defaultValues와 IP 감지 이후의 대체 국가입니다. ISO 3166-1 alpha-2 코드를 사용하세요. 빈 값이면 US로 대체됩니다. 기본값은 ""입니다.
이벤트
생성 옵션 또는 React props로 콜백을 전달합니다.
onChange
주소가 변경될 때 실행됩니다. 국가별 필드와 필수 사용자 지정 필드가 모두 유효하면 complete가 true입니다. address는 postal_code를 포함해 확인 토큰의 billing_details 이름을 따릅니다. country는 ISO 3166-1 alpha-2 코드입니다. 사용자 지정 값은 custom에 있습니다.
object
숨기기 속성
boolean
필수
object
필수
표시 속성
string
string
string
string
"business" | "individual"
string
string
string
string
string
string
필수
Record<string, string>
필수
onLoaderStart
로딩 스켈레톤이 처음 그려진 후, onReady 전에 실행됩니다.
onReady
엘리먼트가 처음으로 완전히 그려진 후 실행됩니다.
onError
엘리먼트가 로드에 실패하거나 충돌할 때 실행됩니다. 대체 화면은 계속 표시됩니다. 프로그래밍 방식으로 처리하려면 code를 사용하세요. sourceKey는 실패한 호스트 상태 소스를 식별합니다.
object
숨기기 속성
string
필수
string
string
메서드
create가 반환한 핸들에서, 또는 React ref를 통해 호출합니다.
validate
양식의 유효성을 검사하고 모든 인라인 오류를 표시하며, 예외를 발생시키지 않습니다. complete, address, errors를 반환합니다. errors는 complete가 true일 때만 정확히 비어 있습니다. 키는 postal_code, line1 같은 계약 이름을 사용하고, 사용자 지정 필드에는 custom:<key>, 로딩 중에는 일시적으로 form을 사용합니다.반환값Promise<object>
boolean
필수
object
필수
표시 속성
string
string
string
string
"business" | "individual"
string
string
string
string
string
string
필수
Record<string, string>
필수
getValues
유효성 검사나 오류 표시 없이 address와 custom을 반환합니다.반환값Promise<object>
object
필수
표시 속성
string
string
string
string
"business" | "individual"
string
string
string
string
string
string
필수
Record<string, string>
필수
mount
target에 엘리먼트를 마운트하고 로딩을 시작합니다. React 컴포넌트는 자동으로 마운트됩니다.매개변수
string | HTMLElement
필수
destroy
엘리먼트를 제거하고 프레임과 구독을 해제합니다. 여러 번 호출해도 됩니다. React는 엘리먼트를 자동으로 제거합니다.
update
마운트된 엘리먼트에 새 props를 병합합니다. React에서는 대신 컴포넌트 props를 변경하세요.매개변수
Partial<AddressElementProps>
필수
스타일링
appearance.classes를 통해 다음 부분의 스타일을 지정합니다. 속성 이름은 카멜 케이스 또는 케밥 케이스를 사용하고 단위를 포함하세요. 페이지 스타일시트는 엘리먼트의 프레임에 적용되지 않습니다. 프레임워크는 각 선언을 삽입하기 전에 유효성을 검사합니다.
클래스
대상
.whop-Address
주소 양식 루트
.whop-AddressErrorSummary
유효성 검사에서 누락되거나 잘못된 필드가 드러날 때 표시되는 요약 줄
.whop-AddressField
주소 양식의 필드 셀 하나
.whop-AddressFieldError
주소 필드의 오류 줄: 전체 레이아웃에서는 필드 아래, 컴팩트 레이아웃에서는 작성기 메시지용으로 그룹 아래에 표시
.whop-AddressFieldInput
주소 양식의 텍스트 입력
.whop-AddressFieldInputInvalid
주소 입력이 유효성 검사에 실패하는 동안 추가됨
.whop-AddressFieldInvalid
컴팩트 필드 셀이 유효성 검사에 실패하는 동안 추가됨
.whop-AddressFieldLabel
주소 필드 레이블: 필드 위, 또는 플로팅 레이블 사용 시 필드 안
.whop-AddressFieldSelect
주소 양식의 선택 항목(국가, 주, 조직 유형)
.whop-AddressGroup
컴팩트 레이아웃에서 모든 필드를 담는 테두리 그룹
.whop-AddressLine2Toggle
접힌 주소 2행 토글
.whop-AddressManualEntry
접힌 양식 아래의 “Enter address manually” 텍스트 버튼 — 국가별 전체 형식을 펼침
컨트롤러를 생성하여 콘텐츠에 전달하는 WhopPayments(accountID:charge:) 스코프 안에 마운트하세요. 이메일 로그인으로 구매자가 확인되면 payments.buyer는 로그인한 구매자입니다. Whop은 이러한 판매의 판매 대행자이며 createConfirmationToken은 WhopBrandingElement 없이는 거부되므로, 이 엘리먼트도 화면에 있어야 합니다. 스타일은 .whopElementsAppearance(_:)로 지정합니다. 모듈은 지갑 SDK의 WhopElements가 아니라 Elements입니다. 시작하기 및 Appearance를 참고하세요.
Props
'billing' | 'shipping'
자동 완성 용도입니다. 기본값은 billing입니다.
'full' | 'compact'
full은 모든 필드에 레이블을 붙여 세로로 쌓습니다. compact는 레이블을 자리 표시자로 옮깁니다. 기본값은 full입니다.
'full' | 'minimal'
full은 국가의 전체 형식을 따릅니다. minimal은 국가와 우편번호만 수집합니다. 기본값은 full입니다.
'combined' | 'split' | 'none'
전체 이름 필드 하나, 이름과 성, 또는 이름 필드 없음입니다. 기본값은 combined입니다.
'none' | 'name' | 'name_with_type'
조직을 수집할지 여부와 사업자인지 개인인지도 물을지 여부입니다. 기본값은 none입니다.
'toggle' | 'always' | 'never'
두 번째 주소 행이 표시되는 방식입니다. 기본값은 toggle이며, “Add address line 2” 버튼을 표시합니다.
string[]
국가 선택기를 이 ISO 3166-1 alpha-2 코드로 제한합니다. 선택된 결제 수단 자체의 국가 목록은 이를 더 좁힐 뿐 넓히지 않습니다.
boolean
구매자의 IP로 기본 국가를 설정합니다.
string
defaultValues와 IP 감지 이후의 대체 국가입니다. ISO 3166-1 alpha-2.
선언된 위치(after_name, after_organization, before_country, after_address)에 렌더링되는 추가 필드입니다. 필수 필드는 complete의 조건이 됩니다.
(payload: AddressChangePayload) => void
편집할 때마다 현재 스냅샷과 함께 실행됩니다.
StyleProp<ViewStyle>
엘리먼트의 외부 View에 적용됩니다. 테마 지정에는 이 화면의 모든 엘리먼트에 적용되는 프로바이더의 appearance.parts를 사용하는 것이 좋습니다. 현재 React Native 파트 이름은 웹의 whop-* 클래스 이름과 별개의 체계이므로, 웹 appearance 객체를 그대로 옮겨 쓸 수 없습니다.
ReactNode
엘리먼트가 로드되는 동안 기본 스켈레톤 대신 렌더링됩니다.
() => void
엘리먼트가 상호작용 가능해지면 한 번 실행됩니다. <Payments>가 이를 그룹화하므로 보통은 <Payments> 자체의 onLoadingChange를 사용하는 것이 좋습니다.
이 엘리먼트의 로드 또는 구성 실패입니다. 어떤 경우든 엘리먼트는 자체 오류 화면을 렌더링합니다.
AddressChangePayload
onChange가 반환하는 값:
complete: boolean: 국가에서 요구하는 모든 필드가 채워지고 유효함
address: EmittedAddress: 구매자가 지금까지 입력한 내용
custom: Record<string, string>: 선언한 customFields의 값
상태
국가 카탈로그가 로드되는 동안 세 필드 스켈레톤이 표시된 후 양식이 표시됩니다. 형식은 고정된 세트가 아니라 국가별이므로 국가를 변경하면 필드가 다시 구성됩니다. 국가에서 요구하는 모든 필드가 채워지고 유효하면 onChange가 complete를 보고합니다.
알아두면 좋은 점
detectCountry가 켜져 있으면 국가는 구매자의 IP, 그다음 countryHint, 그다음 US 순으로 기본 설정됩니다. defaultValues.address.country는 이 세 가지보다 모두 우선합니다.
autocomplete는 웹과 마찬가지로 기본적으로 켜져 있지만, Google Places가 아닌 플랫폼 지오코더가 제공하므로 API 키, 계정, 추가 종속성이 필요하지 않습니다. iOS는 입력 중인 일부 문자열에 여러 후보로 응답하는 실시간 입력 API인 MKLocalSearchCompleter를 사용합니다. Android는 부분 입력에서 예측하는 대신 완전한 주소를 해석하는 android.location.Geocoder를 사용합니다. 대략 하나의 결과가 나오며, 거리를 절반만 입력한 경우 더 대략적인 결과가 나옵니다. Android에는 키가 필요 없는 자동 완성 기능이 없으며, 대안인 Places SDK는 수 메가바이트를 추가하고 이 SDK를 삽입하는 모든 앱에 위치 권한을 강제합니다.
어느 플랫폼이든 기능이 부족할 때는 의도적으로 조용히 처리됩니다. 백엔드나 네트워크가 없거나 일치 항목이 없는 지오코더는 아무것도 표시하지 않으며, 구매자는 처음처럼 주소를 직접 입력합니다. 자동 완성은 절대 체크아웃을 막지 않습니다.
전달되는 주소는 웹 엘리먼트 및 확인 토큰의 billing_details와 같은 키를 사용하므로 하나의 페이로드 형태가 여러 플랫폼에서 작동합니다.
마운트된 주소 엘리먼트는 프로바이더의 청구 정보 소스입니다. 언마운트하면 createConfirmationToken은 직접 전달한 값으로 대체됩니다.
앱을 <WhopElements getToken={…}>로 한 번 감싼 다음, 엘리먼트를 <Payments>로 감싸 마운트하세요. 시작하기 및 Appearance를 참고하세요.
Assistant
Responses are generated using AI and may contain mistakes.