이미지 리치 데이터

이미지 리치 데이터는 이미지를 구조화된 데이터로 저장하는 셀 값 유형입니다.

그림 도형이나 배경 이미지와 달리, 이미지 리치 데이터는 셀의 값 자체로 직접 저장됩니다. 시각적 개체가 아닌 데이터로 처리되기 때문에 정렬, 필터링, 수식, 검색, 피벗 테이블과 같은 워크시트 작업에 참여할 수 있습니다.

이미지 리치 데이터는 이미지가 데이터셋의 일부이며 다른 셀 값과 동일한 방식으로 동작해야 하는 시나리오를 위해 설계되었습니다.

데이터 구조

이미지 리치 데이터는 IRichData 인터페이스의 구체적인 구현입니다.

셀에 이미지를 저장하려면 값에 타입 식별자(type discriminator)와 값 payload가 포함되어야 합니다.

구조는 다음과 같습니다.

{
    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 구조를 따르는 객체를 할당하면 이미지 리치 데이터를 생성할 수 있습니다.

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                                // 이미지를 가로 가운데 정렬
    }
});

사용자 지정 크기 및 잘라내기 옵션도 사용할 수 있습니다.

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   // 잘라낸 영역의 높이
    }
});

전체 속성 정의 및 열거형 값은 IRichData 및 IImageRichData API 참조 문서를 참고하세요.

동작 의미 체계

타입 참여

이미지 리치 데이터는 다음과 같습니다.

• 일급(first-class) 셀 값 유형으로 처리됨

• 범위 및 테이블에 저장 가능

• 수식에서 참조 가능

• 피벗 테이블 데이터 원본으로 사용 가능

도형(Shape) 객체로 처리되지는 않습니다.

정렬 의미 체계

정렬 동작은 다음 규칙을 따릅니다.

1. 이미지 리치 데이터는 기본 값 타입과 비교될 때 Excel과 일관된 방식으로 정렬됩니다.

2. 두 개의 이미지 리치 데이터 값을 비교할 때는 altText 속성을 기준으로 우선 정렬됩니다.

필터링 의미 체계

필터링 작업은 altText 속성을 사용하여 이미지 리치 데이터를 평가합니다.

검색 의미 체계

검색 작업은 altText 속성을 사용하여 이미지 리치 데이터를 평가합니다.

수식 의미 체계

이미지 리치 데이터는 다음에서 사용할 수 있습니다.

• 조회 및 참조 함수 (VLOOKUP, XLOOKUP, INDEX, MATCH 등)

• 동적 배열 함수 (SORT, UNIQUE, FILTER 등)

• 논리 비교 연산자 (=, <>)

• COUNT, COUNTA와 같은 개수 계산 함수

• SUMIF, SUMIFS와 같은 함수의 조건 인수

대부분의 수학 및 통계 함수는 이미지 리치 데이터를 지원하지 않습니다.

지원되지 않는 작업은 #VALUE!를 반환하거나 Excel과 다른 결과를 생성할 수 있습니다.

예제 시나리오

예제 1: 피벗 테이블에서 이미지 리치 데이터 사용

열에 서로 다른 altText 값을 가진 이미지 리치 데이터가 포함되어 있으면 해당 열을 피벗 테이블 필드로 사용할 수 있습니다.

이 범위에서 피벗 테이블을 생성하면:

• 이미지가 필드 항목으로 표시됨

• 그룹화 및 필터링은 altText 기준으로 수행됨

• 정렬은 정렬 섹션에서 설명한 동일한 의미 체계를 따름

추가 설정은 필요하지 않습니다.

예제 2: 조건부 서식에서 이미지 리치 데이터 사용

이미지 리치 데이터는 논리 비교를 사용하는 조건부 서식 규칙에서 사용할 수 있습니다.

예:

=B7="Laptop Pro"

셀 B7에 altText가 "Laptop Pro"인 이미지 리치 데이터가 포함되어 있으면 조건은 TRUE로 평가됩니다.

조건부 서식 규칙은 altText 속성을 사용하여 이미지 리치 데이터를 평가합니다.

예제 3: 이미지 리치 데이터 조회

이미지 리치 데이터는 조회 작업에 사용할 수 있습니다.

=XLOOKUP("Laptop Pro", A:A, B:B)

열 A에 일치하는 altText를 가진 이미지 리치 데이터가 포함되어 있으면 열 B의 해당 값이 반환됩니다.

디자이너에서 이미지 삽입

SpreadJS 디자이너를 사용하여 셀에 이미지를 삽입할 수 있습니다.

디자이너에서 이미지 삽입 및 변환에 대한 자세한 내용은 디자이너에서 그림 삽입을 참고하세요.

가져오기 및 내보내기 동작

Excel 가져오기(.xlsx)

• Excel 셀 이미지는 이미지 리치 데이터로 가져옵니다.

• 더 이상 SparklineEx로 매핑되지 않습니다.

.sjs 및 .ssjson 형식의 SparklineEx 가져오기/내보내기 동작은 변경되지 않습니다.

Excel 내보내기

• SVG 이미지는 Excel로 내보낼 때 오류를 발생시킬 수 있습니다.

• API 레벨에서는 자동 유효성 검사 또는 형식 변환을 수행하지 않습니다.

• 디자이너에서는 셀 안에 배치(Place in Cell) 방식으로 삽입한 SVG 이미지를 저장 전에 PNG로 변환합니다.

클립보드 제한 사항

Excel Desktop에서 복사한 이미지 포함 셀은 SpreadJS에 붙여넣을 수 없습니다.

Excel은 <img src="file:///..."> 형식의 로컬 파일 참조가 포함된 HTML 클립보드 데이터를 사용합니다.

브라우저는 로컬 파일 경로에 접근할 수 없으므로 SpreadJS는 이미지 데이터를 가져올 수 없습니다.

이 동작은 Excel Online과 동일합니다.

플랫폼 제한 사항

이미지 리치 데이터는 다음에서 지원되지 않습니다.

• Data Manager

• TableSheet

• GanttSheet

이미지 리치 데이터가 포함된 테이블을 데이터 테이블로 변환하면 이미지 값은 제거됩니다.

관련 기능

이미지 리치 데이터는 다음 기능과 다릅니다.

• IMAGE()함수 (수식으로 생성된 이미지 값)

• 셀 배경 이미지 (시각적 표시 전용)

• 그림 도형 (셀 위에 배치)

Alt Text 동작

이미지 리치 데이터는 이미지 내용을 설명하기 위한 자체 altText 속성을 포함합니다.

• 이 alt text는 Excel 동작과 일관됩니다.

• 수식 입력줄에서 표시할 수 있습니다.

• Alt Text 패널에서 편집할 수 있습니다.

이 속성은 CellRange.altText()를 사용하여 설정하는 셀 대체 텍스트와는 별개입니다.

• 이미지 리치 데이터의 altText는 이미지 값 자체를 설명합니다.

• SpreadJS의 셀 수준 대체 텍스트는 별도의 속성이며 이미지 값에는 영향을 주지 않습니다.