File uploader

File uploader (파일 업로더)

파일 업로더는 사용자가 특정 위치에 업로드할 하나 이상의 파일을 선택할 수 있게 해주는 컴포넌트예요. 파일 선택 버튼 또는 드래그 앤 드롭 방식으로 콘텐츠를 업로드합니다.

출처: File uploader

본문

개요 (Overview)

파일 업로더는 사용자가 자신의 콘텐츠를 업로드할 수 있게 해줘요. 파일 업로더는 폼에서 흔히 찾을 수 있지만 독립적인 요소로도 존재할 수 있습니다. 파일 업로더에는 두 가지 변형이 있어요—기본 파일 업로더와 드래그 앤 드롭 파일 업로더입니다.

변형 (Variants)

변형 (Variant)	동작 방식 (Way it works)
File uploader	파일 선택 다이얼로그를 띄우는 액션 버튼을 클릭해 하나 이상의 파일을 업로드.
Drag and drop file uploader	선택한 파일을 드롭 존(drop zone) 영역에 직접 드래그 앤 드롭해 업로드.

언제 사용할까요 (When to use)

하나 이상의 파일을 업로드할 때.
파일을 드래그 앤 드롭으로 업로드할 때.
업로드 과정을 보여줄 때.

언제 사용하지 말아야 할까요 (When not to use)

여러 파일을 업로드할 때는 모달에서 업로드를 사용하지 마세요. 업로드된 파일이 세로로 쌓이기 때문입니다.

포맷 (Formatting)

구조 (Anatomy)

제목(Heading): 업로드 섹션을 설명하는 텍스트.
설명(Description): 사용자가 정보에 입각한 선택을 하도록 돕는 텍스트.
버튼 또는 드롭 존 라벨(Button or drop zone label): 업로드할 파일을 선택하는 액션.
업로드된 파일(Uploaded file): 성공적으로 업로드된 파일.
x: x 삭제 아이콘은 업로드된 파일을 제거합니다.

크기 (Sizing)

버튼과 업로드된 파일은 같은 높이여야 해요. 파일 업로더가 다른 입력이 있는 폼에 있다면 일관성을 위해 폼 입력과 파일 업로더에 같은 높이를 사용하세요.

파일 업로더 크기 (File uploader size)	높이 (px/rem)	사용 사례 (Use case)
Large	48/3	작업할 공간이 많을 때 이 크기를 선택.
Medium	40/2.5	기본 크기이며 가능하면 항상 사용해야 함.
Small	32/2	공간이 제한되거나 길고 복잡한 폼에 파일 업로더를 배치할 때 사용.

정렬 (Alignment)

버튼 또는 드롭 존 영역을 업로드된 파일과 왼쪽 정렬하세요. 여러 파일은 세로로 쌓입니다.

배치 (Placement)

파일 업로드 액션으로 버튼을 포함할 때는 사용 사례에 따라 primary 또는 tertiary 버튼을 사용하세요. 페이지에 이미 기본 버튼이 있다면 파일 업로더에 tertiary 버튼을 사용해 기본 액션과 충돌하지 않게 하세요.

콘텐츠 (Content)

주요 요소 (Main elements)

제목 (Heading)

사용자에게 업로드 섹션의 목적을 알려줘요. "Upload files"는 파일 업로더와 함께 나타나는 기본 텍스트입니다.
제목을 한 줄로 제한해 짧고 간결하게 유지하세요.

설명 (Description)

설명은 사용자에게 파일 크기나 형식 제한이 무엇인지 전달하는 데 도움을 줘요.

버튼 또는 드롭 존 라벨 (Button or drop zone label)

버튼 라벨은 간결해야 하며 클릭 시 취해질 액션을 설명해야 해요. "Add files"는 파일 업로더와 함께 나타나는 기본 텍스트입니다.
드롭 존 영역 라벨은 파일을 드롭 존에 드래그 앤 드롭하거나 버튼을 클릭해 파일을 업로드할 수 있다고 설명해야 해요.

업로드된 파일 텍스트 (Uploaded file text)

업로드된 파일의 이름.

넘침 (Overflow)

파일 이름이 부모 요소의 너비를 넘어선다면 생략 부호(…)를 사용하세요. 파일 이름의 전체 길이를 공개하려면 호버 시 툴팁이 나타나야 합니다.

버튼 (Buttons)

파일 업로더 버튼에 아이콘을 사용하는 것은 선택 사항이에요. 버튼 라벨의 동사에 따라 아이콘을 선택하세요. 예를 들어 동사 "Add"에는 "Add" 아이콘을, 동사 "Upload"에는 "Upload" 아이콘을 사용하세요.

추가 가이드 (Further guidance)

더 자세한 콘텐츠 지침은 Carbon의 콘텐츠 가이드라인을 참고하세요.

로딩 상태 (Loading states)

업로드 중인 파일은 세 가지 구분된 상태를 가져요—loading, success, uploaded.

인터랙션 (Interactions)

마우스 (Mouse)

파일이 첨부된 상태로 드롭 존 영역 경계 안 아무 곳에 마우스를 드래그하면 그 영역 안에 놓아 업로드를 시작할 수 있어요.

업로드된 파일을 제거하려면 "x"(또는 delete) 아이콘을 클릭하세요.

키보드 (Keyboard)

업로드 버튼 또는 드롭 존 (Upload button or drop zone):

파일 업로더 버튼 또는 드롭 존은 Space 또는 Enter를 눌러 활성화할 수 있어요.
파일 선택 다이얼로그가 닫힌 후에는 포커스가 사용자의 시선 지점을 유지하고 이를 호출한 요소로 돌아가야 합니다.

업로드된 파일 (Uploaded file):

Tab을 누르면 포커스가 "x" 아이콘으로 이동합니다.
"x" 아이콘에 포커스가 있는 동안 Space 또는 Enter를 누르면 파일이 삭제됩니다.

추가 키보드 인터랙션은 접근성 탭을 참고하세요.

검증 (Validation)

특정 파일을 성공적으로 업로드할 수 없으면 오류 상태가 표시됩니다. 메시지가 얼마나 설명적이어야 하는지에 따라 단일 줄 또는 다중 줄 오류 상태 옵션이 있어요. 오류 메시지는 사용자가 오류를 해결하도록 돕는 명확한 지침을 제공해야 합니다.

오류가 개별 파일이 아닌 파일 업로더 전체와 관련된 것이라면 인라인 오류 알림을 대신 사용할 수 있어요.

파일 업로더 (File uploader)

파일 업로더는 전통적으로 파일 선택 다이얼로그를 띄우는 액션 버튼을 클릭해 하나 이상의 파일을 업로드합니다. 다이얼로그에서 하나 이상의 파일을 선택하면 선택된 파일이 페이지의 파일 업로더 아래로 채워집니다. 업로드가 성공적으로 완료되기 전에 파일이 일시적으로 로딩 상태를 표시할 수 있습니다.

드래그 앤 드롭 파일 업로더 (Drag and drop file uploader)

드래그 앤 드롭 파일 업로더는 드롭 존 영역에 파일을 드래그 앤 드롭해 직접 업로드하는 데 사용돼요. 또는 드롭 존 안의 텍스트 링크 설명을 클릭해 파일 선택 다이얼로그로 파일을 열 수 있습니다.

드롭 존 컴포넌트는 사용자가 페이지의 영역에 파일을 드래그 앤 드롭하거나 버튼을 활성화해 업로드할 수 있게 해줘요. 기본적으로 드래그 앤 드롭 파일 업로더는 여러 파일이 드롭 존 영역에 놓일 수 있게 합니다. 그러나 단일 파일 업로드로 제한하는 기능도 제공합니다.

여러 파일 업로드 (Uploading multiple files)

파일을 드롭 존 영역으로 드래그할 때 드롭 존 테두리의 색상과 두께가 바뀌어 영역이 활성화되어 파일을 받을 준비가 되었음을 나타냅니다. 또한 커서가 드롭 존 영역에 닿으면 업로드하려는 파일의 미리보기로 바뀝니다. 커서 변경 스타일은 사용 중인 브라우저에 의해 렌더링됩니다.

드롭 존 영역으로 드래그되는 파일

여러 파일을 업로드할 수 있을 때 성공적으로 업로드된 파일

단일 파일 업로드 (Uploading a single file)

드래그 앤 드롭 파일 업로더를 사용할 때 요구 사항이 단일 파일 업로드만 허용한다면, 단일 파일을 드롭 존 영역으로 드래그해 업로드하세요. 업로드되면 드롭 존 영역이 제거되어 단일 파일을 성공적으로 업로드했음을 보여줍니다. 업로드된 파일의 닫기 아이콘을 클릭해 제거하세요.

단일 파일만 업로드할 수 있을 때 성공적으로 업로드된 파일

참고 자료 (References)

Page Laubheimer, Drag–and–Drop: How to Design for Ease of Use (Nielsen Norman Group, 2020)

더 알아보기 (Learn more)

파일 업로더는 사용자의 파일 업로드를 위한 컴포넌트예요. 클릭 방식(File uploader)과 드래그 앤 드롭 방식(Drag and drop file uploader) 중 상황에 맞게 선택하고, 버튼·업로드 파일 높이를 일관되게 유지하세요. 업로드 실패 시에는 명확한 오류 메시지와 검증 상태를 제공해 사용자가 문제를 해결할 수 있게 해야 합니다.