[]
        
(Showing Draft Content)

범례

데이터 차트의 범례(Legend)는 각 선, 막대, 또는 기타 데이터가 어떤 의미를 가지는지 시각적으로 도와주는 요소로, 색상과 크기를 통해 각각을 구분하여 사용자 이해를 돕습니다.

ILegendOptions 인터페이스를 사용하면 데이터 차트에서 범례의 외형과 동작을 정의할 수 있습니다. 이 인터페이스에는 title, type, position, textStyle 등 다양한 선택적 속성이 포함되어 있습니다.

또한, LegendType 열거형을 사용하면 범례 유형(예: 색상 또는 크기)을 지정할 수 있으며, LegendPosition 열거형을 사용하여 범례가 차트 내 어디에 표시될지 위치를 정의할 수 있습니다.


차트 유형에 따른 범례 기호(Symbol) 종류:

  • 사각형(Square): bar, area, sunburst, pie, donut, range 차트에 사용

  • 선(Line): 기호 없는 line 차트에 사용

  • 원(Circle): 기호가 있는 XY 산점도(XY scatter), bubble, area 차트에 사용

  • 원+선(Line with Circle): 기호가 있는 line 차트에 사용

범례 속성

다음은 ILegendOptions 인터페이스의 주요 속성 목록입니다:

속성

설명

샘플 미리보기

type

색상을 통해 데이터를 표현하며, 모든 차트 유형에 적용됩니다.

차트 인코딩에서 범례에 필드를 바인딩하면 색상 범례는 자동으로 나타납니다.

image

또는 기호 크기를 통해 데이터를 표현하며, 보통 bubble 차트에서 사용됩니다.

크기 범례는 기본적으로 표시되지 않으며 명시적으로 설정해야 합니다.

image

title

범례에 설명용 제목을 추가합니다.

제목은 범례에 표현된 내용의 의미나 차원을 설명합니다.

image

position

범례가 차트 내 어디에 위치할지를 결정합니다.

가능한 위치 옵션: None (기본값), Top, Bottom, Left, Right

image

textStyle

범례 영역에 표시되는 텍스트의 외형을 정의합니다.

image

height & width

범례의 높이 및 너비를 차트 전체에 대한 비율(0~1)로 설정합니다.

image

hAlign

범례의 가로 정렬을 설정합니다.

옵션: Left, Center(기본값), Right

image

vAlign

범례의 세로 정렬을 설정합니다.

옵션: Top, Middle(기본값), Bottom

image

padding

범례 내부의 여백을 조정합니다.

기본 여백: { top: 10, bottom: 10, left: 10, right: 10 }

image

코드 사용하기

다음 코드 샘플은 데이터 차트에서 범례(Legend)를 구성하는 방법을 보여줍니다.

이 샘플은 “데이터 차트 생성하기” 페이지에서 설명된 salesTable 데이터를 사용합니다. 따라서 차트를 설정하기 위한 해당 페이지의 기본 단계들을 먼저 완료해야 합니다. 설정이 완료되면, 아래 코드를 사용하여 범례를 구성할 수 있습니다. 또한, 필요에 따라 데이터 소스를 사용자 정의하여 사용할 수도 있습니다

// 1. 유형 
const sheet = spread.getSheet(0);
sheet.setColumnCount(30);
sheet.name("Type");
sheet.setValue(7, 0, "Color Legend");
sheet.setValue(28, 0, "The size legend will not be displayed by default");
sheet.setValue(28, 10, "If you want to display the “size” legend, you need to set the position of the legend.");
// sheet.setValue(23, 0, "Polar coordinate system");
const dataChart = sheet.dataCharts.add('data-chart', 100, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);

// "encodings"에 색상 범례(color legend) 관련 필드가 바인딩되어 있는 한,
// 데이터 차트(DataChart)에는 기본적으로 색상 범례가 표시됩니다.
dataChart.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Salesman' },
                 color: { field: 'Salesman' },
             },
         }
     ],
});


const dataChart2 = sheet.dataCharts.add('data-chart-2', 10, 300, 400, 259, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart2.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.bubble,
             encodings: {
                 values: [
                     { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
                     { field: 'Return', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }
                 ],
                 size: { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
             },
         }
     ],
});

const dataChart3 = sheet.dataCharts.add('data-chart-3', 620, 300, 400, 259, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart3.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.bubble,
             encodings: {
                 values: [
                     { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
                     { field: 'Return', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }
                 ],
                 size: { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.size,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right
             }]
         }]
     }
});

// 2. 제목 
let sheet2 = spread.getSheet(1);
sheet2.name("Title");
sheet2.setValue(16, 0, "The Legend has title 'Product Category'");
const dataChart4 = sheet2.dataCharts.add('data-chart-4', 10, 10, 480, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);

dataChart4.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 title: "Product Category",
             }]
         }]
     }
});


// 3. 위치 
let sheet3 = spread.getSheet(2);
sheet3.name("Position");
sheet3.setValue(13, 0, "Legend Position: Right");
sheet3.setValue(30, 0, "Legend Position: Top");
sheet3.setValue(13, 9, "Legend Position: Left");
sheet3.setValue(30, 9, "Legend Position: Bottom");

const dataChart5 = sheet3.dataCharts.add('data-chart-5', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart5.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,  // Right Position
             }]
         }]
     }
});
const dataChart6 = sheet3.dataCharts.add('data-chart-6', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart6.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.left, // Left Position
             }]
         }]
     }
});
const dataChart7 = sheet3.dataCharts.add('data-chart-7', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart7.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.top,   // Top Position
             }]
         }]
     }
});
const dataChart8 = sheet3.dataCharts.add('data-chart-8', 550, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart8.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,  // Bottom Position
             }]
         }]
     }
});

// 4. 텍스트 스타일 
let sheet4 = spread.getSheet(3);
sheet4.name("Text Style");
sheet4.setValue(17, 0, "Legend Text Style has been changed");

const dataChart9 = sheet4.dataCharts.add('data-chart-9', 10, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart9.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 textStyle: {
                     color: "#483f3f",
                     fontFamily: "Century",
                     fontSize: 14,
                     fontStyle: GC.Spread.Sheets.DataCharts.FontStyle.italic,
                     fontWeight: "Bold"
                 }
             }]
         }]
     }
});

// 5. 높이 및 너비
let sheet5 = spread.getSheet(4);
sheet5.name("Height and Width");
sheet5.setValue(16, 0, "Height of the Legend: 0.5");
sheet5.setValue(16, 10, "Width of the Legend: 0.4");

const dataChart10 = sheet5.dataCharts.add('data-chart-10', 10, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart10.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 // 범례의 높이를 전체 DataChart에 대한 백분율로 설정합니다.
                 height: 0.5, // 값 범위는 0~1 
             }]
         }]
     }
});

const dataChart11 = sheet5.dataCharts.add('data-chart-11', 600, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart11.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 // 범례의 너비를 전체 DataChart에 대한 백분율로 설정합니다.
                 width: 0.4, // 값 범위는 0~1
             }]
         }]
     }
});

 // 6. hAlign
 let sheet6 = spread.getSheet(5);
 sheet6.name("hAlign");
 sheet6.setValue(13, 0, "Horizonal Alignment: Left");
 sheet6.setValue(30, 0, "Horizonal Alignment: Center  (Default Value)");
 sheet6.setValue(13, 9, "Horizonal Alignment: Right");

 const dataChart12 = sheet6.dataCharts.add('data-chart-12', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart12.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                 // 가로 정렬(Horizontal Alignment)을 설정합니다.
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.left   // Left Position
             }]
         }]
     }
 });

 const dataChart13 = sheet6.dataCharts.add('data-chart-13', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart13.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                // 가로 정렬(Horizontal Alignment)을 설정합니다.
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.center   // Center Position (Default)
             }]
         }]
     }
 });

 const dataChart14 = sheet6.dataCharts.add('data-chart-14', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart14.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                 // 가로 정렬(Horizontal Alignment)을 설정합니다.
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.right   // Right Position
             }]
         }]
     }
 });

 // 7. vAlign
 let sheet7 = spread.getSheet(6);
 sheet7.name("vAlign");
 sheet7.setValue(13, 0, "Vertical Alignment: Top");
 sheet7.setValue(30, 0, "Vertical Alignment: Center  (Default Value)");
 sheet7.setValue(13, 9, "Vertical Alignment: Bottom");

 const dataChart15 = sheet7.dataCharts.add('data-chart-15', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart15.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // 세로 정렬(VerticalAlignment)을 설정합니다.
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.top   // Top 위치
             }]
         }]
     }
 });

 const dataChart16 = sheet7.dataCharts.add('data-chart-16', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart16.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // 세로 정렬(VerticalAlignment)을 설정합니다.
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.middle   // Middle 위치 (기본값)
             }]
         }]
     }
 });

 const dataChart17 = sheet7.dataCharts.add('data-chart-17', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart17.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // 세로 정렬(VerticalAlignment)을 설정합니다.
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.bottom   // Bottom 위치
             }]
         }]
     }
 });

 // 8. 패딩
 let sheet8 = spread.getSheet(7);
 sheet8.name("Padding");
 sheet8.setValue(13, 0, "Left Padding: 30");

 const dataChart18 = sheet8.dataCharts.add('data-chart-18', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart18.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 }
             }]
         }]
     }
 });