# 이미지 리치 데이터 ## Content 이미지 리치 데이터는 이미지를 구조화된 데이터로 저장하는 셀 값 유형입니다. 그림 도형이나 배경 이미지와 달리, 이미지 리치 데이터는 셀의 값 자체로 직접 저장됩니다. 시각적 개체가 아닌 데이터로 처리되기 때문에 정렬, 필터링, 수식, 검색, 피벗 테이블과 같은 워크시트 작업에 참여할 수 있습니다. 이미지 리치 데이터는 이미지가 데이터셋의 일부이며 다른 셀 값과 동일한 방식으로 동작해야 하는 시나리오를 위해 설계되었습니다. ## 데이터 구조 이미지 리치 데이터는 `IRichData` 인터페이스의 구체적인 구현입니다. 셀에 이미지를 저장하려면 값에 타입 식별자(type discriminator)와 값 payload가 포함되어야 합니다. 구조는 다음과 같습니다. ```auto { richDataType: "Image", value: { src: string, imageBase64Data?: string, altText?: string, drawType?: number, width?: number, height?: number, clipX?: number, clipY?: number, clipWidth?: number, clipHeight?: number, vAlign?: number, hAlign?: number } } ``` * `richDataType`은 반드시 `"Image"`로 설정해야 합니다. * `value`에는 이미지 소스 및 선택적 레이아웃/잘라내기 설정이 포함됩니다. `altText` 속성은 정렬, 필터링, 검색 및 논리 비교 작업에서 기본 비교 키로 사용됩니다. ### 예제 `sheet.setValue`를 사용하여 `IImageRichData` 구조를 따르는 객체를 할당하면 이미지 리치 데이터를 생성할 수 있습니다. ```auto var sheet = spread.getActiveSheet(); sheet.setValue(0, 0, { richDataType: "Image", // 값을 이미지 리치 데이터로 식별 value: { src: "https://example.com/product.png", // 이미지 URL altText: "Laptop Pro", // 정렬, 필터링, 검색 및 논리 비교 작업에 사용 drawType: 0, // 가로세로 비율 유지 및 셀 내부에 맞춤 vAlign: 1, // 이미지를 세로 가운데 정렬 hAlign: 1 // 이미지를 가로 가운데 정렬 } }); ``` ![example1-20260414.f05a37.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/example1-20260414.f05a37-20260528.42ff15.gif?width=600) 사용자 지정 크기 및 잘라내기 옵션도 사용할 수 있습니다. ```auto sheet.setValue(1, 0, { richDataType: "Image", value: { src: "https://example.com/product.png", altText: "Laptop Pro (Cropped)", drawType: 3, // 사용자 지정 크기 모드 활성화 width: 80, // 사용자 지정 너비(픽셀) height: 60, // 사용자 지정 높이(픽셀) clipX: 20, // 잘라낸 영역의 시작 X 위치 clipY: 20, // 잘라낸 영역의 시작 Y 위치 clipWidth: 100, // 잘라낸 영역의 너비 clipHeight: 100 // 잘라낸 영역의 높이 } }); ``` ![example2-20260414.1797c7.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/example2-20260414.1797c7-20260528.038094.gif?width=600) 전체 속성 정의 및 열거형 값은 [`IRichData`](/spreadjs/docs/v19/) 및 [`IImageRichData`](/spreadjs/docs/v19/) API 참조 문서를 참고하세요. ## 동작 의미 체계 ### 타입 참여 이미지 리치 데이터는 다음과 같습니다. * 일급(first-class) 셀 값 유형으로 처리됨 * 범위 및 테이블에 저장 가능 * 수식에서 참조 가능 * 피벗 테이블 데이터 원본으로 사용 가능 도형(Shape) 객체로 처리되지는 않습니다. ### 정렬 의미 체계 정렬 동작은 다음 규칙을 따릅니다. 1. 이미지 리치 데이터는 기본 값 타입과 비교될 때 Excel과 일관된 방식으로 정렬됩니다. 2. 두 개의 이미지 리치 데이터 값을 비교할 때는 `altText` 속성을 기준으로 우선 정렬됩니다. ![sort-20260403.e10666.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/sort-20260403.e10666-20260528.6515ef.gif?width=600) >type=note > **참고:** > > * 두 값의 `altText`가 동일한 경우 정렬 동작은 Microsoft Excel과 다를 수 있습니다. > * Excel은 셀 이미지 비교 규칙을 공개적으로 문서화하지 않았기 때문에 완전한 동작 동일성을 보장할 수는 없습니다. ### 필터링 의미 체계 필터링 작업은 `altText` 속성을 사용하여 이미지 리치 데이터를 평가합니다. ![filter-20260403.98d0c2.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/filter-20260403.98d0c2-20260528.d764b8.gif?width=600) ### 검색 의미 체계 검색 작업은 `altText` 속성을 사용하여 이미지 리치 데이터를 평가합니다. ![search-20260403.3fc627.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/search-20260403.3fc627-20260528.b2b999.gif?width=600) ### 수식 의미 체계 이미지 리치 데이터는 다음에서 사용할 수 있습니다. * [조회 및 참조 함수](/spreadjs/docs/formulareference/FormulaFunctions/lookup-reference-functions) (`VLOOKUP`, `XLOOKUP`, `INDEX`, `MATCH` 등) * [동적 배열 함수](/spreadjs/docs/features/formulas/dynamic-array-formulas) (`SORT`, `UNIQUE`, `FILTER` 등) * 논리 비교 연산자 (`=`, `<>`) * `COUNT`, `COUNTA`와 같은 개수 계산 함수 * `SUMIF`, `SUMIFS`와 같은 함수의 조건 인수 대부분의 수학 및 통계 함수는 이미지 리치 데이터를 지원하지 않습니다. 지원되지 않는 작업은 `#VALUE!`를 반환하거나 Excel과 다른 결과를 생성할 수 있습니다. ## 예제 시나리오 ### 예제 1: 피벗 테이블에서 이미지 리치 데이터 사용 열에 서로 다른 `altText` 값을 가진 이미지 리치 데이터가 포함되어 있으면 해당 열을 피벗 테이블 필드로 사용할 수 있습니다. 이 범위에서 피벗 테이블을 생성하면: * 이미지가 필드 항목으로 표시됨 * 그룹화 및 필터링은 `altText` 기준으로 수행됨 * 정렬은 정렬 섹션에서 설명한 동일한 의미 체계를 따름 추가 설정은 필요하지 않습니다. ![pt-20260407.fdf3cf.gif](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/pt-20260407.fdf3cf-20260528.6e7a12.gif?width=600) ### 예제 2: 조건부 서식에서 이미지 리치 데이터 사용 이미지 리치 데이터는 논리 비교를 사용하는 조건부 서식 규칙에서 사용할 수 있습니다. 예: ```auto =B7="Laptop Pro" ``` 셀 `B7`에 `altText`가 `"Laptop Pro"`인 이미지 리치 데이터가 포함되어 있으면 조건은 `TRUE`로 평가됩니다. 조건부 서식 규칙은 `altText` 속성을 사용하여 이미지 리치 데이터를 평가합니다. ![image-20260407.897ba2.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260407.897ba2-20260528.faa957.png?width=600) ### 예제 3: 이미지 리치 데이터 조회 이미지 리치 데이터는 조회 작업에 사용할 수 있습니다. ```auto =XLOOKUP("Laptop Pro", A:A, B:B) ``` 열 A에 일치하는 `altText`를 가진 이미지 리치 데이터가 포함되어 있으면 열 B의 해당 값이 반환됩니다. ![image-20260407.d2cf50.png](https://gcdocumentsitekrblob.blob.core.windows.net/document-site-files/images/36b63360-fb01-457c-a448-c3ce32aaf454/image-20260407.d2cf50-20260528.298d79.png?width=600) ## 디자이너에서 이미지 삽입 SpreadJS 디자이너를 사용하여 셀에 이미지를 삽입할 수 있습니다. 디자이너에서 이미지 삽입 및 변환에 대한 자세한 내용은 [디자이너에서 그림 삽입](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/insert-pictures-in-designer)을 참고하세요. ## 가져오기 및 내보내기 동작 ### Excel 가져오기(.xlsx) * Excel 셀 이미지는 이미지 리치 데이터로 가져옵니다. * 더 이상 `SparklineEx`로 매핑되지 않습니다. `.sjs` 및 `.ssjson` 형식의 `SparklineEx` 가져오기/내보내기 동작은 변경되지 않습니다. ### Excel 내보내기 * SVG 이미지는 Excel로 내보낼 때 오류를 발생시킬 수 있습니다. * API 레벨에서는 자동 유효성 검사 또는 형식 변환을 수행하지 않습니다. * 디자이너에서는 *셀 안에 배치(Place in Cell)* 방식으로 삽입한 SVG 이미지를 저장 전에 PNG로 변환합니다. ## 클립보드 제한 사항 Excel Desktop에서 복사한 이미지 포함 셀은 SpreadJS에 붙여넣을 수 없습니다. Excel은 `` 형식의 로컬 파일 참조가 포함된 HTML 클립보드 데이터를 사용합니다. 브라우저는 로컬 파일 경로에 접근할 수 없으므로 SpreadJS는 이미지 데이터를 가져올 수 없습니다. 이 동작은 Excel Online과 동일합니다. ## 플랫폼 제한 사항 이미지 리치 데이터는 다음에서 지원되지 않습니다. * Data Manager * TableSheet * GanttSheet 이미지 리치 데이터가 포함된 테이블을 [데이터 테이블로 변환](/spreadjs/docs/features/tablegen/convert-fromto-data-table)하면 이미지 값은 제거됩니다. ## 관련 기능 이미지 리치 데이터는 다음 기능과 다릅니다. * [IMAGE()함수](/spreadjs/docs/formulareference/FormulaFunctions/sparkline-functions/IMAGE) (수식으로 생성된 이미지 값) * [셀 배경 이미지](/spreadjs/docs/features/worksheet/backimage) (시각적 표시 전용) * [그림 도형](/spreadjs/docs/features/UnderstandingShapes/picture-shape) (셀 위에 배치) >type=note > 그림 도형와 이미지 리치 데이터는 디자이너에서 서로 변환할 수 있습니다. > 자세한 내용은 [디자이너에서 그림 삽입](/spreadjs/docs/spreadjs-designer-component/spdesignerwork/insert-pictures-in-designer)를 참고하세요. ## Alt Text 동작 이미지 리치 데이터는 이미지 내용을 설명하기 위한 자체 `altText` 속성을 포함합니다. * 이 alt text는 Excel 동작과 일관됩니다. * 수식 입력줄에서 표시할 수 있습니다. * Alt Text 패널에서 편집할 수 있습니다. 이 속성은 `CellRange.altText()`를 사용하여 설정하는 셀 대체 텍스트와는 별개입니다. * 이미지 리치 데이터의 `altText`는 이미지 값 자체를 설명합니다. * SpreadJS의 셀 수준 대체 텍스트는 별도의 속성이며 이미지 값에는 영향을 주지 않습니다.