파일 업로드 File upload

파일 업로드는 하나 이상의 디바이스의 로컬 파일을 선택하고 첨부하는 데 사용하는 입력 컴포넌트이다.

기본

[(files)]에 파일 목록(KrdsFileInfo[])을 바인딩합니다. 제목은 heading, 설명은 description으로 줍니다. 컴포넌트는 파일을 서버로 보내지 않습니다. 추가된 파일은 pending 상태로 목록에 들어가므로 실제 업로드와 상태 변경은 직접 처리합니다. 파일이 추가되면 (fileAdded), 삭제되면 (fileRemoved), 전체 삭제하면 (cleared)가 발생합니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

@Component({
  selector: 'demo-file-upload-basic',
  imports: [KrdsFileUpload],
  template: `<krds-file-upload heading="타이틀영역" description="컨텐츠 영역" [(files)]="files" />`
})
export default class FileUploadBasic {
  readonly files = signal<KrdsFileInfo[]>([])
}

파일 상태별 표시

KrdsFileInfo의 status에 따라 표시가 달라집니다. uploading은 스피너, completed는 완료 아이콘, pending은 삭제 버튼, error는 errorMessage를 표시합니다. downloadUrl이 있으면 다운로드·바로보기 버튼이 표시되고, 누르면 (download)·(preview)로 그 파일을 보냅니다. 다운로드·바로보기 동작은 직접 구현합니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

const hwp = (id: string, name: string, size: number, extra: Partial<KrdsFileInfo>): KrdsFileInfo => ({
  id,
  file: new File([''], name),
  name,
  size,
  type: 'application/x-hwp',
  status: 'pending',
  ...extra
})

@Component({
  selector: 'demo-file-upload-with-files',
  imports: [KrdsFileUpload],
  template: `<krds-file-upload heading="타이틀영역" description="컨텐츠 영역" [(files)]="files" />`
})
export default class FileUploadWithFiles {
  readonly files = signal<KrdsFileInfo[]>([
    hwp('1', '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp', 17 * 1024, { status: 'uploading' }),
    hwp('2', '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp', 17 * 1024, { status: 'completed' }),
    hwp('3', '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp', 17 * 1024, { status: 'pending' }),
    hwp('4', '전입재등록신고서 [주민등록법 시행령 별지서식 15, 15호의2호].hwp', 25 * 1024 * 1024, {
      status: 'error',
      errorMessage: '등록 가능한 파일 용량을 초과하였습니다.\n20MB 미만의 파일만 등록할 수 있습니다.'
    }),
    hwp('5', '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp', 17 * 1024, { status: 'completed', downloadUrl: '/files/sample.hwp' })
  ])
}

파일 선택 동작

파일선택 버튼이나 업로드 영역으로 끌어다 놓아 파일을 추가합니다. maxFileSize(기본 20MB) 이상인 파일은 error 상태로 추가되고 개수에서 빠지며, (fileError)가 발생합니다. maxFiles(기본 10개)에 이르면 더 추가되지 않습니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

@Component({
  selector: 'demo-file-upload-interactive',
  imports: [KrdsFileUpload],
  template: `
    <krds-file-upload
      heading="파일 업로드"
      description="파일을 선택하거나 드래그하여 업로드하세요."
      [maxFileSize]="20 * 1024 * 1024"
      [(files)]="files"
    />
  `
})
export default class FileUploadInteractive {
  readonly files = signal<KrdsFileInfo[]>([])
}

단일 파일

[multiple]="false"로 지정하면 새로 선택한 파일이 기존 파일을 대신합니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

@Component({
  selector: 'demo-file-upload-single-file',
  imports: [KrdsFileUpload],
  template: `
    <krds-file-upload heading="단일 파일 업로드" description="하나의 파일만 업로드할 수 있습니다." [multiple]="false" [(files)]="files" />
  `
})
export default class FileUploadSingleFile {
  readonly files = signal<KrdsFileInfo[]>([])
}

이미지 파일만

accept에 허용할 확장자나 MIME 타입을 지정합니다. 끌어다 놓은 파일이 형식에 맞지 않으면 error 상태로 추가됩니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

@Component({
  selector: 'demo-file-upload-image-only',
  imports: [KrdsFileUpload],
  template: `
    <krds-file-upload
      heading="이미지 파일 업로드"
      description="JPG, PNG, GIF 파일만 업로드할 수 있습니다."
      accept=".jpg,.jpeg,.png,.gif"
      [maxFiles]="5"
      [(files)]="files"
    />
  `
})
export default class FileUploadImageOnly {
  readonly files = signal<KrdsFileInfo[]>([])
}

비활성화

파일 선택·끌어다 놓기·삭제가 모두 막힙니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

const name = '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'

@Component({
  selector: 'demo-file-upload-disabled',
  imports: [KrdsFileUpload],
  template: ` <krds-file-upload heading="비활성화 상태" description="파일 업로드가 비활성화된 상태입니다." disabled [(files)]="files" /> `
})
export default class FileUploadDisabled {
  readonly files = signal<KrdsFileInfo[]>([
    { id: '3', file: new File([''], name), name, size: 17 * 1024, type: 'application/x-hwp', status: 'pending' }
  ])
}

읽기 전용

업로드 영역과 삭제 버튼 없이 파일 목록만 표시합니다.

import { Component, signal } from '@angular/core'
import { KrdsFileUpload, type KrdsFileInfo } from '@krds.ui/angular'

const name = '위임장(주민등록법 시행령 별지 제15호의2호서식).hwp'

@Component({
  selector: 'demo-file-upload-read-only',
  imports: [KrdsFileUpload],
  template: ` <krds-file-upload heading="읽기 전용" description="업로드된 파일만 확인할 수 있습니다." readonly [(files)]="files" /> `
})
export default class FileUploadReadOnly {
  readonly files = signal<KrdsFileInfo[]>([
    {
      id: '5',
      file: new File([''], name),
      name,
      size: 17 * 1024,
      type: 'application/x-hwp',
      status: 'completed',
      downloadUrl: '/files/sample.hwp'
    }
  ])
}

KrdsFileUpload

선택자 krds-file-upload

Inputs

이름	타입	기본값	설명
`[(files)]`	`KrdsFileInfo[]`	`[]`	파일 목록
`heading`	`string`	-	제목 (기본 title 속성과 겹쳐 툴팁이 뜨지 않게 heading으로 받음)
`description`	`string`	-	설명
`placeholder`	`string`	`'첨부할 파일을 여기에 끌어다 놓거나, 파일 선택 버튼을 눌러 파일을 직접 선택해주세요.'`	끌어다 놓는 영역의 안내 문구
`size`	`'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'`	`'medium'`	파일선택 버튼 크기
`accept`	`string`	-	허용 파일 형식 (예: '.jpg,.png,.pdf', 'image/*')
`maxFiles`	`number`	`10`	최대 파일 개수 (오류 항목은 세지 않음)
`maxFileSize`	`number`	`20 * 1024 * 1024`	최대 파일 크기 (bytes, 이 크기 이상이면 오류)
`multiple`	`boolean`	`true`	여러 파일 선택 (끄면 새 파일이 기존 파일을 대체)
`disabled`	`boolean`	`false`	비활성화
`readonly`	`boolean`	`false`	읽기 전용 (추가·삭제 없이 다운로드·바로보기만)
`dragAndDrop`	`boolean`	`true`	끌어다 놓기
`showDownload`	`boolean`	`true`	다운로드 버튼 표시
`showPreviewButton`	`boolean`	`true`	바로보기 버튼 표시
`showClearAll`	`boolean`	`true`	전체 파일 삭제 버튼 표시
`name`	`string`	`'myFile'`	파일 input의 name

Outputs

이름	값	설명
`fileAdded`	`KrdsFileInfo`	파일을 추가했을 때
`fileRemoved`	`string`	파일을 삭제했을 때 (파일 id)
`fileError`	`KrdsFileError`	추가한 파일이 검사(크기·형식)에 실패했을 때
`cleared`	`void`	전체 파일 삭제 버튼을 눌렀을 때
`download`	`KrdsFileInfo`	파일의 다운로드 버튼을 눌렀을 때
`preview`	`KrdsFileInfo`	파일의 바로보기 버튼을 눌렀을 때

타입

/** 파일 업로드 목록의 파일 */
export interface KrdsFileInfo {
  /** 파일 id */
  id: string
  /** 파일 객체 */
  file: File
  /** 파일명 */
  name: string
  /** 파일 크기 (bytes) */
  size: number
  /** 파일 타입 (MIME) */
  type: string
  /** 업로드 상태 (업로드는 사용하는 쪽에서 처리하고 상태만 바꿔 넘긴다) */
  status: 'pending' | 'uploading' | 'completed' | 'error'
  /** 오류 문구 */
  errorMessage?: string
  /** 다운로드 주소 (있으면 다운로드·바로보기 버튼) */
  downloadUrl?: string
}

/** 파일 검사 실패 이벤트 */
export interface KrdsFileError {
  file: KrdsFileInfo
  error: string
}

파일 업로드 File upload ​

기본 ​

파일 상태별 표시 ​

파일 선택 동작 ​

단일 파일 ​

이미지 파일만 ​

비활성화 ​

읽기 전용 ​

KrdsFileUpload ​