xl3가 보존하는 것과 보존하지 않는 것
xl3가 내 템플릿에 맞는지는 결국 한 가지로 갈립니다. 워크북이 그대로 나오는가? 이 문서가 기능 단위로 답합니다.
아래 내용은 전부 명세에서 정한 것이고, 특정 구현의 우연한 동작이 아닙니다. 유예로 표시된 항목은 의도적으로 미뤄둔 것이며 그 사실이 ADR에 적혀 있습니다. "아무도 확인하지 않았다"와는 다릅니다.
세 가지 판정
| 판정 | 의미 |
|---|---|
| 보존 | 템플릿과 동일하게 나옵니다. 규격을 따르는 모든 구현이 반드시 이렇게 해야 합니다. |
| 보존, 범위는 확장 안 됨 | 기능은 살아남지만 범위는 템플릿이 준 좌표를 그대로 유지합니다. @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 참고. |
범위를 가진 규칙
살아남기는 하지만 범위는 템플릿이 지정한 자리에 머뭅니다. 엔진이 규칙을 조용히 넓혀서 언급되지 않은 행까지 덮는 일은 하지 않습니다 — 자동으로 확장되는 조건부 서식은 작성자가 일부러 제외한 바닥글 행까지 번질 수 있습니다.
| 기능 | 판정 | 템플릿에서 해결하는 방법 |
|---|---|---|
| 조건부 서식 | 보존, 범위는 확장 안 됨 | 템플릿에서 규칙을 열 전체($A:$A)에 걸어두세요. 실측: 1행 블록이 3행으로 늘어나도 규칙은 A2:A2에 남습니다. |
| 데이터 유효성 검사 (드롭다운, 제약) | 보존, 범위는 확장 안 됨 | 같은 방법. 실측: B2에 지정한 검사는 확장 후에도 B2에만 남습니다. |
| 이름 정의 | 보존, 범위는 확장 안 됨 | 워크북 범위·시트 범위 모두 살아남지만, 확장된 영역을 향해 참조가 다시 맞춰지지는 않습니다. |
| 인쇄 영역, 인쇄 제목 | 보존, 범위는 확장 안 됨 | 인쇄 영역을 열 전체($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 참고. |
반복 블록 안의 서식
범위와 셀별 서식은 서로 반대 방향으로 동작합니다. 이 차이에서 많이 걸립니다.
템플릿에서 A2:A2에 걸린 범위는 열 개 행이 나와도 여전히 A2:A2입니다. 반면 그
열 개 행은 모두 A2의 숫자 서식과 셀 스타일을 지닙니다 — 엔진이 쓴 셀은 템플릿
셀의 서식을 가져가고, 첫 행만이 아니라 모든 행이 그렇습니 다.
뒤쪽 절반이 들리는 것보다 중요합니다. 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확장을 견디는지 확인합니다 — 위에서 설명한 함정입니다.- 위 표의 모든 행에 대한 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 — 매크로·네트워크·파일시스템 입장