문서 › 웹 컴포넌트
웹 컴포넌트 <excel-82>: 속성과 이벤트
끌어다 놓는 폼 컴포넌트의 속성, JS 속성·메서드, 상태, 이벤트, CSS 변수와 ::part().
<excel-82> 는 끌어다 놓기 영역과 파일 선택 버튼, 요약(이름·형식·열 수·줄 수), 통과/실패 표시, 오류·경고 목록, 미리보기 표, 양식 내려받기, 업로드 진행 막대를 가진 웹 컴포넌트입니다. Shadow DOM을 쓰고, 키보드로 조작할 수 있으며 결과를 aria-live로 알립니다.
<excel-82 headers="이름,전화번호,금액" min-rows="1" accept="xlsx,xls,csv"
locale="ko" preview-rows="5" template-download="xlsx"></excel-82>속성
규칙 속성을 바꾸면 이미 넣은 파일을 다시 검사합니다.
| 속성 | 설명 |
|---|---|
headers | 기대하는 머리글. 쉼표로 구분하거나 JSON 배열. 순서까지 같아야 하고 NFC 정규화 후 비교 |
columns | 열 수 |
min-rows, max-rows | 데이터 행 수의 범위 |
sheet | 시트 이름 또는 0부터 시작하는 번호(기본: 첫 시트) |
header-row | 머리글 행 번호(1부터, 기본 1) |
accept | 허용 형식. xlsx,xls,csv 중에서 쉼표로 |
max-size | 최대 바이트 수(기본 52428800 = 50 MB) |
strict-warnings | 경고(개인정보·매크로·숨김·병합·확장자 불일치·행 불일치·중복 머리글·셀 오류)를 오류로 올림 |
template | 양식 파일 URL. 머리글·열 수 규칙을 그 파일에서 가져옴. 속성 규칙과 같이 쓰면 속성이 우선 |
locale | en(기본), ko |
preview-rows | 미리보기 행 수(기본 5, 0이면 숨김) |
template-download | csv 또는 xlsx. 양식 내려받기 버튼을 보여 줌(headers가 있을 때) |
name, required, disabled | 폼 연동 |
upload | 업로드할 URL. 없으면 업로드하지 않음 |
upload-as | file(기본, multipart) 또는 json({ fileName, sheet, columns, rows }) |
upload-field | multipart 필드 이름(기본 file) |
upload-auto | 기본 true. false면 폼 제출 때 업로드한 뒤 다시 제출 |
telemetry | off면 사용 통계를 보내지 않음 |
JS 속성과 메서드
.file, .result(check 결과), .info(inspect 결과), .state, .rules(JS로 주면 속성 규칙을 대신함), .uploadResponse, .check(file), .upload(), .reset(), 그리고 폼 검증용 .form, .validity, .validationMessage, .checkValidity(), .reportValidity().
const x = document.querySelector('excel-82');
x.addEventListener('check', (e) => {
console.log(e.detail.ok, e.detail.errors); // check 결과
});
x.rules = { headers: ['이름', '금액'], rows: { min: 1 } }; // 속성 규칙을 대신함
await x.check(file); // 코드로 파일 넣기
x.reset();상태
idle → checking → invalid | valid → uploading → uploaded | uploadfailed. required인데 파일이 없을 때, invalid, uploading, uploadfailed 상태에서는 폼 제출이 막힙니다. 자세한 내용은 업로드와 폼에 있습니다.
이벤트
모두 bubbles·composed 입니다.
| 이벤트 | 시점 | detail |
|---|---|---|
check | 검사가 끝났을 때 | check 결과 |
beforeupload | 업로드 직전(preventDefault()로 취소) | { file, init } — init.headers에 인증 헤더를 넣음 |
uploadprogress | 업로드 중 | { loaded, total } |
uploaded | 업로드 완료 | { status, response } |
uploaderror | 업로드 실패 | { status?, error } |
모양 바꾸기
CSS 변수 --e82-accent, --e82-error, --e82-warn, --e82-bg, --e82-fg, --e82-border, --e82-radius. 다크 모드(prefers-color-scheme)를 따릅니다.
::part(): drop, label, choose, input, summary, status, issues, preview, template, progress, retry, notice.
excel-82 { --e82-accent: #0b5fff; --e82-radius: 12px; }
excel-82::part(drop) { padding: 32px; }