xl3가 보존하는 것과 보존하지 않는 것
xl3가 내 템플릿에 맞는지는 결국 한 가지로 갈립니다. 워크북이 그대로 나오는가? 이 문서가 기능 단위로 답합니다.
아래 내용은 전부 명세에서 정한 것이고, 특정 구현의 우연한 동작이 아닙니다. 유예로 표시된 항목은 의도적으로 미뤄둔 것이며 그 사실이 ADR에 적혀 있습니다. "아무도 확인하지 않았다"와는 다릅니다.
네 가지 판정
| 판정 | 의미 |
|---|---|
| 보존 | 템플릿과 동일하게 나옵니다. 규격을 따르는 모든 구현이 반드시 이렇게 해야 합니다. |
| 보존하고 확장 | 규칙은 살아남고, @repeat 블록 안에 완전히 포함된 범위는 출력 행과 함께 늘어납니다. 블록에 일부만 겹친 범위는 작성 의도를 추측하지 않고 그대로 둡니다. |
| 보존, 범위는 확장 안 됨 | 기능은 살아남지만 범위는 템플릿이 준 좌표를 그대로 유지합니다. @repeat이 시트를 1행에서 50행으로 늘려도 범위는 그 1행만 덮습니다. 각 항목마다 템플릿에서 해결하는 방법이 있습니다. |
| 유예 | XTL 0.1은 아무것도 보장하지 않습니다. 살아남을 수도, 사라질 수도 있고, 규격을 따르는 두 구현이 서로 다르게 동작해도 됩니다. 1.1 전에는 여기에 기대지 마세요. |
레이아웃과 서식
| 기능 | 판정 | 비고 |
|---|---|---|
| 셀 스타일 — 글꼴, 채우기, 테두리, 정렬 | 보존 | |
| 숫자·날짜 서식 | 보존 | @repeat으로 늘어난 모든 행이 물려받습니다. 첫 행만이 아닙니다 — 반복 블록 안의 서식 참고. |
| 행 높이, 열 너 비 | 보존 | |
| 병합 셀 | 보존 | 템플릿과 원본 데이터 행 양쪽 모두 (ADR-0033, ADR-0035). |
| 이미지와 앵커 | 보존 | @repeat이 위쪽에 행을 넣어도 앵커는 밀리지 않습니다. 이미지는 머리글·바닥글·측면 등 블록 밖에 두세요. |
| 틀 고정, 창 나누기 | 보존 | |
| 셀 메모 | 보존 | {{ [컬럼] }} 셀에 달린 메모는 렌더된 셀에 그대로 남습니다. |
| 시트 보호, 셀별 잠금·숨김 플래그 | 보존 | 엔진이 쓴 셀은 합성한 기본값이 아니라 템플릿 셀의 잠금 상태를 물려받습니다. |
| 워크북 속성 — 테마, 문서 속성 | 보존 | fixture 120-workbook-properties-preserved. |
| 정적 셀의 네이티브 Excel 수식 | 보존 | xl3가 만들지 않은 수식은 손대지 않고 통과합니다 (ADR-0046). Excel이 열 때 계산할 수 있는 것은 이쪽으로 두세요 — Cookbook 16 참고. |
범위를 가진 규칙
범위를 가진 기능에는 두 가지 계약이 있습니다. 조건부 서식과 데이터 유효성 검사는
작성 범위가 @repeat 블록 안에 완전히 포함될 때만 출력 행과 함께 늘어납니다. 일부만
겹친 범위는 작성자가 제외한 바닥글까지 번지지 않도록 그대로 둡니다. 이름 정 의와 인쇄
설정은 좌표를 바꾸지 않고 보존합니다.
| 기능 | 판정 | 템플릿에서 해결하는 방법 |
|---|---|---|
| 조건부 서식 | 보존하고 확장 | 1행 블록 안의 A2:A2 규칙은 블록이 3행을 출력하면 A2:A4로 늘어납니다. 열 전체 범위는 이미 출력을 덮으므로 그대로이고, 일부만 겹친 범위도 작성한 대로 보존됩니다. |
| 데이터 유효성 검사 (드롭다운, 제약) | 보존하고 확장 | 반복 템플릿 행 안의 셀에 지정한 검사는 대응하는 출력 행으로 복제됩니다. 블록 밖의 검사는 건드리지 않습니다. |
| 이름 정의 | 보존, 범위는 확장 안 됨 | 워크북 범위·시트 범위 모두 살아남지만, 확장된 영역을 향해 참조가 다시 맞춰지지는 않습니다. |
| 인쇄 영역, 인쇄 제목 | 보존, 범위는 확장 안 됨 | 인쇄 영역을 열 전체($A:$Z)나 반복 머리글 행($1:$1)으로 지정하세요. |
1.1로 미룬 것
네 가지 기능은 1.0에서 의도적으로 구현에 맡겨 두었습니다 (ADR-0076). 계획을 세울 수 있도록 레퍼런스 구현의 현재 동작을 아래에 적었지만, 어느 것도 보장이 아닙니다 — 그게 유예의 뜻입니다.
| 기능 | 레퍼런스 구현의 현재 동작 |
|---|---|
| 피벗 테이블 | 통과하지 않습니다. 작성도 보존도 되지 않습니다. |
| 스파크라인 | 마찬가지로 통과하지 않습니다. |
| 구조화된 표 (ListObject) | 표 자체는 살아남지만 ref가 확장되지 않습니다. @repeat 행에 걸쳐 만든 표는 원래 덮던 행만 계속 덮습니다. 템플릿에서 ref를 열 전체로 넓혀 두세요. |
| 페이지 나누기 | 사라집니다. 개념상 "인쇄 영역" 옆에 있어 보이지만 거기에 포함되지 않습니다. 변환 후 호스트 쪽에서 설정하세요. |
| 차트 | 구현에 맡김 (ADR-0036 항목 3). 레퍼런스 구현은 ExcelJS로 읽고 쓰는데 차트 지원이 불완전합니다 — 차트가 살아남는다고 기대하지 마세요. |
의도적으로 제거하는 것
| 기능 | 동작 |
|---|---|
| 매크로 (VBA, XLM) | 항상 제거됩니다. .xlsm 입력은 매크로를 뺀 XLSX로 받아들이고 경고를 냅니다. 매크로는 실행되지 않으며, 1.x 동안 호스트나 템플릿이 되돌릴 방법은 없습니다. SECURITY.md 참고. |
반복 블록 안의 서식
범위 규칙과 셀별 서식은 서로 다른 계약으로 늘어납니다. 반복 블록 안에 완전히 포함된 조건부 서식과 데이터 유효성 검사는 블록과 함께 확장되지만, 이름 정의와 인쇄 설정은 확장되지 않습니다. 이와 별개로 출력된 모든 행은 템플릿 셀의 숫자 서식과 스타일을 지닙니다. 첫 행만 그런 것이 아닙니다.
마지막 보장은 들리는 것보다 중요합니다. 2..N행에서 서식이 빠지는 것은 조용한 데이터
손실입니다. 첫 행만 1,234.50이고 나머지가 1234.5인 열은 서식 실수처럼 보이고,
실제 서식 실수와 구분이 되지 않습니다. data-loss 태그가 붙은 픽스처 아홉 개가 이
회귀를 막기 위해 존재합니다.
크기 한계
| 한계 | 값 |
|---|---|
| 메모리 | 규모가 커지면 출력 셀당 약 2.2 KB, 여기에 약 130 MB의 기본값이 더해집니다. 200만 셀이면 최대 RSS가 대략 4.2 GB 필요합니다. |
| 한 번의 변환당 셀 수 | 약 200만 개까지 끝까지 검증했습니다. 2 GB 호스트에는 약 50만 개가 들어갑니다. 그보다 큰 작업이 돌 것이라 가정하기 전에 셀당 2.2 KB로 호스트 크기를 잡으세요. |
| 셀 문자열 길이 | xl3는 준 것을 그대로 씁니다. Excel은 32,767자를 넘는 셀을 읽을 때 거부하는데, xl3는 미리 검사하지 않습니다 — 결과물이 Excel에서 열려야 한다면 넘기기 전에 길이를 확인하세요 (ADR-0032). |
사용 가능한 메모리를 넘기면 xl3 에러가 아니라 호스트 수준의 out-of-memory로
나타납니다 — xl3가 잡을 수 없습니다. 오래 걸리는 변환은 AbortSignal을 받습니다.
어디까지 기계로 검증되나
일부입니다. 그리고 어느 부분인지 아는 것이 중요합니다.
123-feature-preservation은 이름 정의와 셀 메모가 렌더를 거쳐 살아남는지를 Stage 1 셀 값 비교로 확인합니다.170-data-loss-numfmt-preserved-across-expansion은 Stage 2에서 숫자 서식이@repeat확장을 견디는지 확인합니다 — 위에서 설명한 함정입니다.171-cf-dv-range-extension은 Stage 2에서 블록 안에 포함된 조건부 서식과 데이터 유효성 범위는 확장되고 일부만 겹친 범위는 그대로인지 확인합니다.- 위 표의 모든 행에 대한 Stage 2 정규화 비교는 아직 ADR-0006의 canonicalizer 작업을 기다리고 있습니다.
즉 픽스처가 뒤를 받치지 않는 행은 기계로 검증된 것이 아니라 명세상의 약속입니다. 모든 구현이 같은 적합성 코퍼스를 돌리므로 검증되는 것은 어디서나 검증되지만, 코퍼스가 아직 이 표 전체를 덮지는 못합니다. 이 문서는 그렇지 않은 척하기 보다 그렇다고 말하는 쪽을 택합니다.
이 결정들이 사는 곳
이 문서는 규범 문서를 쉬운 말로 옮긴 것입니다. 서로 어긋나면 그쪽이 이깁니다.
spec/evaluation.md§ Styles and Workbook Structure — 규범적 규칙- ADR-0036 — 아홉 기능의 보존 매트릭스와, 각 항목을 "보존하고 확장까지"가 아니라 "그대로 보존"으로 정한 이유
- ADR-0076 — 피벗·스파크라인·ListObject·페이지 나누기를 1.1로 유예한 결정과 실측 동작
- ADR-0046 — 정적 셀의 네이티브 Excel 수식
- ADR-0032 — 문자열 길이 등 주변부 한계
- ADR-0022 — Excel 버전 호환성
- SECURITY.md — 매크로·네트워크·파일시스템 입장