File upload

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

• 선택 상태 하나로 파일을 고르고, 끌어다 놓고, 제거하세요.
• 네이티브 파일 입력은 Field.Control 로 등록되므로 공유 Form 이 required 검증, 서버 오류, 실제 File 제출을 유지합니다.
• 전송은 자동으로 시작되지 않습니다. 제공한 transport 가 파일마다 실행됩니다.
• 드롭 영역은 점선 테두리가 아닌 표면입니다. 파일을 그 위로 끌면 배경이 강조됩니다.
• 고른 파일은 드롭 영역에 이어 선으로 나뉜 행으로 놓입니다. 그래서 필드가 한 면으로 읽히고, 목록 위에 놓아도 파일이 추가됩니다.
• choose 버튼의 키보드 포커스와 필드 오류 표시가 유지됩니다.

• accept 를 검증으로 취급하지 마세요. 선택 힌트일 뿐이며, 클라이언트 검증은 서버 검증을 대체하지 않습니다.
• FileUpload 가 디렉터리 업로드, 청크 전송, 재개, 서명된 URL 정책을 처리하길 기대하지 마세요. transport 나 제품에서 처리하세요.
• 서버에 이미 업로드된 파일을 로컬 File 처럼 미리 채우지 마세요. 따로 나열하세요.
• Form.onFormSubmit 의 문자열 모델에서 실제 파일을 읽지 마세요. 대신 onSubmit 에서 FormData 를 읽으세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

FileUpload owns Field.Root → Label + Description + dropzone (native Field.Control(type=file) + visible picker label, then one row per file with status/actions/progress) + rejection alert + Field.Error + one polite announcement

키보드와 접근성

네이티브 파일 입력으로 Tab 하면 choose 버튼에 포커스 링이 표시됩니다. Enter 나 Space 는 파일 선택기를 엽니다. 파일 목록에서 Tab 은 Upload, Cancel, Retry, Remove 버튼에 도달합니다. Enter 나 Space 로 활성화하세요. 모든 파일 선택은 끌기 없이 동작합니다. disabled 는 선택과 제출을 막고 진행 중인 전송을 취소합니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { FileUpload, Form } from '@surflane/ui'

<Form
  onSubmit={(event) => {
    event.preventDefault()
    const data = new FormData(event.currentTarget)
    const files = data.getAll('artifacts')
    // Submit using your application transport.
  }}
>
  <FileUpload
    name='artifacts'
    label='Build artifacts'
    description='Up to three JSON files, 1 MB each.'
    accept='.json,application/json'
    multiple
    required
    maxFiles={3}
    maxFileSize={1024 * 1024}
    transport={async (file, { signal, onProgress }) => {
      await yourUpload(file, { signal, onProgress })
    }}
  />
</Form>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰