Web Components 파일 입력 개요

Ignite UI for Web Components 파일 입력 구성 요소는 사용자가 파일을 선택하고 업로드할 수 있는 대화형 방법을 제공합니다. 파일 선택과 같은 파일별 기능을 추가하고, 선택한 파일 이름을 표시하고, 여러 파일 업로드를 지원하여 기본 IgcInputComponent 기능을 확장합니다.

Web Components File Input Example

import { defineComponents, IgcFileInputComponent, IgcInputComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcInputComponent, IgcFileInputComponent);
export class FileInputOverview {
  constructor() {
  }
}

new FileInputOverview();
ts

<!DOCTYPE html>
<html>
  <head>
    <title>File Input Overview</title>
    <meta charset="UTF-8" />

    <link rel="shortcut icon" href="https://static.infragistics.com/xplatform/images/browsers/wc.png" >
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Kanit&display=swap" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Titillium Web" />
    <link rel="stylesheet" href="https://static.infragistics.com/xplatform/css/samples/shared.v5.css" type="text/css" />
  </head>

  <body>
    <div id="root">
      <div class="container sample center">
        <igc-file-input label="File input"></igc-file-input>
      </div>
    </div>
    <!-- This script is needed only for parcel and it will be excluded for webpack -->
    <% if (false) { %><script src="src/index.ts"></script><% } %>

  </body>
</html>
html

/* shared styles are loaded from: */
/* https://static.infragistics.com/xplatform/css/samples */css

Like this sample? Get access to our complete Ignite UI for Web Components toolkit and start building your own apps in minutes. Download it for free.

Usage

파일 입력 구성 요소를 사용하면 사용자가 장치에서 파일을 선택하여 웹 애플리케이션에 업로드할 수 있습니다. 선택한 파일의 이름을 표시하고 찾아보기 버튼과 "선택한 파일 없음" 텍스트에 대한 사용자 지정 옵션을 제공합니다. 또한 구성 요소는 필요에 맞게 동작을 추가로 구성하는 데 사용할 수 있는 속성, 메서드 및 슬롯을 제공합니다.

시작하기

파일 입력 사용을 시작하려면 먼저 다음 명령을 실행하여 Ignite UI for Web Components 설치해야 합니다.

npm install igniteui-webcomponents
cmd

그런 다음 다음과 같이 파일 입력을 가져와야 합니다.

import { defineComponents, IgcFileInputComponent } from 'igniteui-webcomponents';

defineComponents(IgcFileInputComponent);
ts

이제 Web Components 파일 입력의 기본 구성부터 시작할 수 있습니다.

<igc-file-input label="File Input" required=true></igc-file-input>
html

Ignite UI for Web Components에 대한 전체 소개를 보려면 시작하기 항목을 읽어보세요.

구성

Properties

파일 입력 구성 요소는 특정 요구 사항에 따라 동작을 구성할 수 있는 다양한 속성을 제공합니다. 이러한 속성을 사용하면 입력의 기능, 모양 및 유효성 검사를 제어할 수 있습니다.

value- 파일 입력 필드의 현재 값을 설정합니다.
disabled- 파일 입력을 비활성화하여 사용자 상호 작용을 방지합니다.
required- 입력을 필수로 표시합니다. 파일을 선택하지 않으면 양식 제출이 차단됩니다.
invalid- 입력 값이 잘못되었으며 시각적 오류 상태를 트리거하는 데 사용됨을 나타냅니다.
multiple- 여러 파일을 선택할 수 있습니다.
accept- 선택할 수 있는 파일 유형을 정의합니다. 이 속성의 값은 쉼표로 구분된 파일 형식 목록(예: .jpg, .png .gif)이어야 합니다.
autofocus- 페이지가 로드될 때 파일 입력 필드에 자동으로 초점을 맞춥니다.
label- 파일 입력 요소와 연결된 레이블 텍스트를 설정합니다.
placeholder- 파일을 선택하지 않았을 때 표시되는 자리 표시자 텍스트를 제공합니다.

<igc-file-input 
  label="Files Input" 
  accept=".jpg, .png, .gif"
  placeholder="Files missing"
  required
  multiple>
</igc-file-input>
html

Methods

구성 가능한 속성 외에도 File Input 구성 요소는 사용할 수 있는 구성 요소에서 IgcInputComponent 네 가지 유용한 메서드를 상속합니다.

focus()- 파일 입력 요소에 초점을 설정합니다.
blur()- 파일 입력 요소에서 포커스를 제거합니다.
reportValidity()- 입력의 유효성을 확인하고 입력이 유효하지 않은 경우 유효성 검사 메시지를 표시합니다.
setCustomValidity()- 사용자 지정 유효성 검사 메시지를 설정합니다. 제공된 메시지가 비어 있지 않으면 입력이 유효하지 않은 것으로 표시됩니다.

Slots

또한 File Input 구성 요소는 모양과 동작을 사용자 지정하는 데 사용할 수 있는 여러 슬롯을 노출합니다.

prefix & suffix- 기본 입력 영역 앞이나 뒤에 콘텐츠를 삽입할 수 있습니다.
helper-text- 입력 아래에 힌트 또는 안내 메시지를 표시합니다. 서식 지정 팁 또는 필드 요구 사항과 같은 추가 지침을 제공하는 데 유용합니다.
file-selector-text- 파일 선택 버튼에 표시되는 텍스트를 사용자 지정할 수 있습니다.
file-missing-text- 파일을 선택하지 않은 경우 입력 필드에 표시되는 텍스트를 설정합니다.
value-missing- 필요한 필드 유효성 검사가 실패할 때 사용자 지정 콘텐츠를 렌더링합니다. (즉, 파일이 필요하지만 제공되지 않은 경우).
invalid– 입력이 유효하지 않은 상태일 때 사용자 지정 콘텐츠를 렌더링할 수 있습니다.
custom-error - Displays content when a custom validation message is set using the setCustomValidity() method.

import { defineComponents, IgcIconComponent, IgcFileInputComponent, registerIconFromText } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcIconComponent, IgcFileInputComponent);
const uploadIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M440-200h80v-167l64 64 56-57-160-160-160 160 57 56 63-63v167ZM240-80q-33 0-56.5-23.5T160-160v-640q0-33 23.5-56.5T240-880h320l240 240v480q0 33-23.5 56.5T720-80H240Zm280-520v-200H240v640h480v-440H520ZM240-800v200-200 640-640Z"/></svg>';

const imageIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h560q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560H200v560Zm40-80h480L570-480 450-320l-90-120-120 160Zm-40 80v-560 560Z"/></svg>'

export class FileInputPrefixSuffix {
  constructor() {
    registerIconFromText("uploadFile", uploadIcon);
    registerIconFromText("imageIcon", imageIcon);
  }
}

new FileInputPrefixSuffix();
ts

<!DOCTYPE html>
<html>
  <head>
    <title>File Input Prefix & Suffix</title>
    <meta charset="UTF-8" />

    <link rel="shortcut icon" href="https://static.infragistics.com/xplatform/images/browsers/wc.png" >
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Kanit&display=swap" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Titillium Web" />
    <link rel="stylesheet" href="https://static.infragistics.com/xplatform/css/samples/shared.v5.css" type="text/css" />
  </head>

  <body>
    <div id="root">
      <div class="container sample center">
        <igc-file-input label="Input with slots">
          <igc-icon name="imageIcon" slot="prefix"></igc-icon>
          <igc-icon name="uploadFile" slot="suffix"></igc-icon>
          <span slot="helper-text">Sample helper text.</span>
          <span slot="file-selector-text">Upload</span>
          <span slot="value-missing">Please upload file</span>
        </igc-file-input>
      </div>
    </div>
    <!-- This script is needed only for parcel and it will be excluded for webpack -->
    <% if (false) { %><script src="src/index.ts"></script><% } %>

  </body>
</html>
html

/* shared styles are loaded from: */
/* https://static.infragistics.com/xplatform/css/samples */css

Integration

파일 입력 구성 요소는 HTML 양식 요소와 원활하게 통합됩니다. 위에서 설명한 메서드와 속성을 사용하면 표준 HTML Forms 내에서 동작과 유효성 검사를 효과적으로 관리할 수 있습니다.

import { defineComponents, IgcFileInputComponent, IgcInputComponent, IgcDialogComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';
import './index.css'

defineComponents(IgcInputComponent, IgcFileInputComponent, IgcDialogComponent);
export class FileInputForm {
  constructor() {

    window.onload = function () {
      document.getElementById("fInput")?.focus();
    }

    document.getElementById('form1')?.addEventListener('submit', (event: SubmitEvent) => {
      event.preventDefault();
      showDialog(event.target as HTMLFormElement);
    })

    function showDialog(data: HTMLFormElement) {
      var filePath = data.fInput.value
      const dialog = document.createElement('igc-dialog');
      dialog.title = 'Form submission result';
      dialog.addEventListener('igcClosed', () => dialog.remove());

      const dump = document.createElement('pre');
      dump.textContent = filePath.replace("C:\\fakepath\\", "");

      dialog.appendChild(dump);
      document.body.appendChild(dialog);

      dialog.show();
    }
  }
}

new FileInputForm();
ts

<!DOCTYPE html>
<html>
  <head>
  <title>File Input in Form</title>
  <meta charset="UTF-8" />
  
  <link rel="shortcut icon" href="https://static.infragistics.com/xplatform/images/browsers/wc.png">
  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Kanit&display=swap" />
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Titillium Web" />
  <link rel="stylesheet" href="https://static.infragistics.com/xplatform/css/samples/shared.v5.css" type="text/css" />
  </head>

  <body>
  <div id="root">
    <div class="container sample center">
      <form id='form1' enctype="multipart/form-data">
        <fieldset>
          <igc-file-input id="fInput" name="fInput" label="Required field" multiple required>
            <p slot="helper-text">You can upload any type of file.</p>
            <p slot="value-missing">You must upload a file</p>
          </igc-file-input>
          <igc-button variant="outlined" type="submit">Submit</igc-button>
          <igc-button variant="outlined" type="reset">Reset</igc-button>
        </fieldset>
      </form>
    </div>
  </div>
  <!-- This script is needed only for parcel and it will be excluded for webpack -->
  <% if (false) { %>
    <script src="src/index.ts"></script>
    <% } %>
  </body>

</html>html

/* shared styles are loaded from: */
/* https://static.infragistics.com/xplatform/css/samples */

igc-button {
  margin-top: 10px;
}css

Limitations

파일 입력 구성 요소에는 현재 다음과 같은 제한 사항이 있습니다.

"찾아보기" 단추 및 "선택한 파일 없음" 메시지의 기본 문자열은 자동으로 지역화되지 않습니다. 이러한 문자열은 모든 로케일에서 동일하게 유지되지만 적절한 슬롯 또는 플레이스홀더 바인딩을 사용하여 수동으로 사용자 지정할 수 있습니다.
속성을 통해 파일을 수동으로 설정할 수 없습니다 value. 파일 선택은 파일 선택기를 통해서만 수행할 수 있습니다. 그러나 빈 문자열을'' 전달하여 필드를 재설정할 수 있습니다.

Accessibility & ARIA Support

File Input 구성 요소는 포커스를 받을 수 있고 대화형이므로 완전한 키보드 및 화면 판독기 접근성을 보장합니다. 구성 요소는 속성을 사용하여 label 레이블을 지정할 수 있으며, 이 속성은 native <label> 요소를 활용하여 의미상 정확하고 액세스 가능한 레이블을 제공합니다.

접근성 권장사항을 지원하기 위해 구성요소는 관련 ARIA 속성도 적용합니다.

aria-invalid- 입력이 잘못된 상태인 경우 "true"로 설정합니다.
aria-describedby- 도우미 텍스트 요소가 있는 경우 자동으로 연결되어 보조 기술이 추가 정보를 알릴 수 있습니다.

Styling

이 컴포넌트는 스타일링에 사용할 수 있는 CSS 파트를 File Input 노출합니다. 다음 표에는 노출된 모든 CSS 부분이 나열되어 있습니다.

이름	설명
`container`	모든 기본 입력 요소를 보유하는 기본 래퍼입니다.
`input`	기본 입력 요소입니다.
`label`	기본 레이블 요소입니다.
`file-names`	파일 이름 래퍼입니다.
`file-selector-button`	찾아보기 단추입니다.
`prefix`	접두사 래퍼.
`suffix`	접미사 래퍼.
`helper-text`	도우미 텍스트 래퍼입니다.

igc-file-input::part(file-names) {
  background-color: var(--ig-primary-50);
  color: var(--ig-gray-400);
}

igc-file-input::part(suffix) {
  color: var(--ig-primary-700-contrast);
  background-color: var(--ig-primary-700);
}

igc-file-input::part(label) {
  color: var(--ig-gray-600);
}
scss

import { defineComponents, IgcFileInputComponent, IgcInputComponent, registerIconFromText } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';
import './FileInputStyling.css';

defineComponents(IgcFileInputComponent, IgcInputComponent);
const uploadIcon =
  '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h560q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560H200v560Zm40-80h480L570-480 450-320l-90-120-120 160Zm-40 80v-560 560Z"/></svg>'

export class FileInputStyling {
  constructor() {
    registerIconFromText("uploadFile", uploadIcon);
  }
}

new FileInputStyling();
ts

<!DOCTYPE html>
<html>
  <head>
    <title>File Input Styling</title>
    <meta charset="UTF-8" />

    <link rel="shortcut icon" href="https://static.infragistics.com/xplatform/images/browsers/wc.png" >
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Kanit&display=swap" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Titillium Web" />
    <link rel="stylesheet" href="https://static.infragistics.com/xplatform/css/samples/shared.v5.css" type="text/css" />
  </head>

  <body>
    <div id="root">
      <div class="container sample center">
        <igc-file-input label="Input styling">
          <igc-icon name="uploadFile" slot="suffix"></igc-icon>
        </igc-file-input>
      </div>
    </div>
    <!-- This script is needed only for parcel and it will be excluded for webpack -->
    <% if (false) { %><script src="src/index.ts"></script><% } %>

  </body>
</html>
html

igc-file-input {
    --blackground: var(--ig-primary-700);
    --foreground: var(--ig-primary-700-contrast);
}

igc-file-input:focus::part(suffix),
igc-file-input::part(file-selector-button),
igc-file-input::part(suffix) {
    /* Style the file selector button */
    --input-prefix-background: var(--blackground);
    --input-prefix-color: var(--foreground);

    /* Style the custom suffix */
    --input-suffix-background: var(--blackground);
    --input-suffix-background--focused: var(--blackground);
    --input-suffix-background--filled: var(--blackground);

    color: var(--foreground);
}

igc-file-input::part(label) {
    color: var(--ig-gray-600);
}

css

/* shared styles are loaded from: */
/* https://static.infragistics.com/xplatform/css/samples */css