Vant는 모바일 웹 인터페이스용 Vue를 대상으로 합니다. AddressList, Field, CellGroup은 데스크톱 관리 테이블 대신 간결한 수신 주소 행과 양식 셀을 제공합니다. Sample-kit 흐름에서는 이러한 기본 구성 요소를 사용하고, 별도의 요약 영역에 선택한 배송지를 표시합니다.
기본 역할은 --van-primary-color를 통해 파란색으로 지정됩니다. 성공, 위험, 경고에는 각각 별도의 색상 변수가 사용됩니다. 이 예시에서는 ConfigProvider를 통해 기본 색상을 #176b77로 의도적으로 변경했습니다. 이 청록색을 공식 Vant 브랜드 색상이라고 부르는 것은 아닙니다. 독자적으로 제작한 종이 질감 그래픽은 장식용이며 컨트롤 상태를 나타내지 않습니다.
Vant는 4, 8, 12, 16, 24, 32픽셀의 패딩 값을 제공합니다. 이는 스크린샷에서 추정한 값이 아니라 실제 기본 변수입니다. 주소 목록 항목에는 작은 패딩 토큰을 사용하고, 양식과 주문 요약을 구분하기 위해 주변 미리보기에는 더 넓은 섹션 간격을 적용합니다.
지정된 텍스트 크기는 10~16픽셀이고, 이에 대응하는 줄 높이는 14~22픽셀입니다. 주소 텍스트에는 별도의 13px 구성 요소 변수가 있습니다. 모바일 제품은 이러한 컨트롤 기본값보다 큰 편집용 텍스트가 필요할 수 있습니다. 예시 제목은 독자적으로 지정한 32px 크기이며, 페이지 중단점에서 27px로 줄어듭니다.
AddressList에는 id, name, tel, address와 선택적 isDefault가 포함된 목록 레코드를 전달합니다. v-model 값은 선택한 레코드를 식별합니다. 요약은 현재 목록에서 해당 ID를 찾아 계산하므로, 수신자를 수정하면 별도의 요약 상태를 두지 않아도 표시된 배송지가 즉시 업데이트됩니다.
사용할 수 없는 창고는 disabled-list에 전달하고, 비활성 상태를 명확히 설명하는 텍스트를 표시합니다. 맥락을 위해 계속 표시하지만 배송지로 선택할 수는 없습니다. 기본값 배지는 레코드의 기본 상태를 나타냅니다. 현재 선택과는 별개이며 다른 라디오 옵션을 선택해도 바뀌지 않습니다.
수정 이벤트는 주소 레코드를 전달합니다. 편집기는 수정 가능한 필드만 반응형 초안에 복사하고, 변경되지 않는 ID는 별도로 저장합니다. 취소하면 저장된 주소를 수정하지 않고 초안만 숨깁니다. 저장하면 ID가 일치하는 레코드를 바꾸거나 새 레코드를 추가한 다음, 해당 ID를 선택합니다.
이 예제는 하단 팝업을 여는 대신 목록 아래에 인라인 편집기를 표시합니다. 따라서 문서에 삽입된 상태에서도 예제 전체를 사용할 수 있습니다. Vant는 표준화된 주소 입력을 위한 AddressEdit도 제공합니다. 이 예제에서는 특정 국가의 행정 구역 데이터를 전제로 하지 않도록 Form과 Field를 사용합니다.
Form은 validate-trigger="onSubmit"을 사용합니다. 수신인 검사기는 공백을 제거한 뒤 두 글자 이상인지 확인합니다. 전화번호 검사기는 맨 앞의 선택적 더하기 기호와 숫자, 공백, 괄호, 하이픈으로 구성된 적당한 길이의 문자열을 허용합니다. 주소 검사기는 공백이 아닌 문자가 열 개 이상 있는지 확인합니다. 이 검사는 동작 방식을 보여 주기 위한 것으로, 우편 주소 확인이나 모든 전화번호에 적용되는 보편적인 유효성 검사가 아닙니다.
native-type="submit"인 기본 Button을 누르면 네이티브 폼이 제출됩니다. Vant는 규칙을 통과한 뒤에만 submit을 발생시킵니다. 오류는 해당 Field 옆에 표시되며, scroll-to-error는 유효하지 않은 필드가 화면에 보이도록 이동합니다. 미리보기에서는 편집을 시작할 때 첫 번째 수신인 입력란에도 포커스를 둡니다. 유효성 검사에 실패해도 초안은 유지됩니다.
Vant 디자인 시스템 ConfigProvider로 카멜 케이스 값을 CSS 변수에 매핑하기
ConfigProvider가 CamelCase 값을 CSS 변수에 매핑합니다
theme-vars 객체에는 primaryColor, buttonPrimaryBackground, buttonPrimaryBorderColor, addressListPadding이 포함됩니다. ConfigProvider는 이 이름들을 각각 대응하는 --van-* 변수에 매핑합니다. 별도로 격리된 이 문서에서는 theme-vars-scope="global"을 사용합니다. 루트에 선언된 별칭이 변경된 기본 색상 역할을 기준으로 적용되기 때문입니다. 기본 색상 역할과 기본 버튼의 두 값을 모두 재정의하면 기본 동작 버튼과 라디오 선택의 색상을 일관되게 유지할 수 있습니다.
theme 속성을 light와 dark 사이에서 전환하면 Vant 구성 요소의 테마가 바뀝니다. 페이지의 배경과 텍스트에도 테마 변수를 사용해 별도로 스타일을 지정해야 합니다. 프로바이더만 설정해서는 애플리케이션의 모든 요소에 색상이 적용되지 않습니다. 장식용 종이 샘플은 두 테마 모두에서 재질 색상을 그대로 유지합니다.
AddressList는 고정된 추가 버튼을 위해 보통 하단 여백 80픽셀을 확보합니다. 미리보기에서는 show-add-button을 false로 설정하고, 일반 인라인 Button을 제공합니다. 또한 addressListPadding을 12픽셀로 변경해 고정 동작 버튼이 따로 떠 있거나, 삽입된 예제 하단에 불필요한 빈 공간이 생기지 않도록 합니다.
넓은 화면에서는 목록과 재질 요약이 두 열로 표시됩니다. 원래 중단점인 680px 아래에서는 세로로 쌓입니다. 기본 AddressList의 height:100%는 명시적으로 height:auto로 재설정해 패널이 다음 그리드 행과 겹치지 않고 콘텐츠에 맞춰지게 합니다. 전역 최소 뷰포트 높이는 사용하지 않으므로, 부모 페이지가 콘텐츠에 맞춰 삽입된 문서의 크기를 정할 수 있습니다. 좁은 화면에서는 주소 이름이 줄바꿈되어 페이지 너비가 강제로 늘어나지 않습니다.
Vant의 기본 리셋은 기본 포커스 윤곽선을 제거합니다. 함께 제공되는 페이지 스타일시트는 버튼, 입력란, 텍스트 영역 및 tabindex가 지정된 컨트롤에 3픽셀의 focus-visible 링을 다시 적용합니다. 이는 애플리케이션 수준에서 추가한 것으로, 라이브러리를 가져오는 것만으로 접근성 작업이 모두 완료된다는 뜻은 아닙니다. 테마 전환 컨트롤에는 접근 가능한 이름과 눈에 보이는 레이블을 제공합니다.
상태 알림은 로컬 저장 또는 배송지 선택 결과를 기록합니다. 배송을 예약한 것은 아니라는 점도 명확히 알립니다. 이 예제에는 체크아웃 엔드포인트, 저장소 또는 외부 부수 효과가 없습니다. 실제 체크아웃에는 구매 전에 서버 측 주소 확인, 배송 가능 여부 확인, 최종 검토가 필요합니다.
전체 SFC는 구성 요소를 로컬에서 가져옵니다. 진입 파일은 Locale.use를 통해 영어 로케일을 설정하고, 기존 레이아웃 스타일시트보다 먼저 vant/lib/index.css를 가져옵니다. 확인된 패키지는 Vue 3에서 사용하는 Vant 4.10.2입니다. 영어 로케일 가져오기에 사용된 .mjs 확장자는 설치된 ESM 파일과 일치합니다.
독립 실행형 미리보기에는 JavaScript, CSS 및 아이콘 글꼴이 문서에 포함되어 있습니다. 번들된 WOFF2 글꼴은 유지하고 사용하지 않는 원격 WOFF 대체 글꼴은 제거했으므로, 이 예제는 서드파티 글꼴 요청에 의존하지 않습니다. 프로덕션 애플리케이션에서는 호스팅된 데모 URL을 그대로 복사하지 말고 자체 번들러와 에셋 정책을 사용해야 합니다.
컴포넌트의 기하 구조는 Vant에서 가져오며, 페이지 중단점 680px는 애플리케이션에서 정한 값입니다.
미리보기에서는 기본 초기화가 기본 윤곽선을 제거하므로, 포커스 링이 다시 표시되도록 복원합니다.
04
Vant 디자인 시스템 AI 에이전트 설정
구현 시작점
Vue 3 및 Vant 4.10.2에서 검증했습니다. 이 예제는 메모리 내 상태 외에는 주소를 저장하지 않습니다.
자바스크립트
// Create the project first:
// npm create vite@latest vant-specimen -- --template vue
// cd vant-specimen && npm install
// In a Vite Vue 3 project:
// npm install [email protected]
// Save the complete SFC as App.vue and the supplied layout as style.css.
import {createApp} from 'vue';
import {Locale} from 'vant';
import enUS from 'vant/es/locale/lang/en-US.mjs';
import 'vant/lib/index.css';
import './style.css';
import App from './App.vue';
Locale.use('en-US',enUS);
createApp(App).mount('#app');
// index.html must contain <div id="app"></div>.
// Keep the template index.html and replace its entry with the code above.
// npm run dev
프로젝트를 위한 프롬프트
에이전트 프롬프트
Vant 4.10.2 sample-kit 주소 선택기를 바탕으로 시작합니다. 주소 목록을 추가하거나 수정할 때 기본 AddressList와 Form/Field 편집 흐름을 유지하고, 필드 유효성 검사와 선택된 주소 상태도 보존합니다. Locale 설정, en-US 모듈, ConfigProvider 테마 범위, 콘텐츠 높이에 맞춘 AddressList 조정을 유지합니다. 취소 시 기존 주소를 대체하지 않아야 하며, 유효성 검사를 통과하면 로컬 주소 컬렉션만 업데이트해야 합니다. 주소만 다루는 이 예제에 결제 또는 배송 시간대 관련 성공 문구를 추가하지 마세요.
05
Vant 디자인 시스템의 출처 및 범위
Vant 4.10.2. 기본 토큰과 원래 페이지에서 정한 값은 구분되어 있습니다. 예시 주소는 허구이며, 선택 및 수정은 로컬에서만 이루어집니다.
