# 범례
## 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` 인터페이스의 주요 속성 목록입니다:
| **속성** | **설명** | **샘플 미리보기** |
| --- | --- | ------- |
| @rows=2:type | 색상을 통해 데이터를 표현하며, 모든 차트 유형에 적용됩니다.
차트 인코딩에서 범례에 필드를 바인딩하면 색상 범례는 자동으로 나타납니다. |  |
| 또는 기호 크기를 통해 데이터를 표현하며, 보통 bubble 차트에서 사용됩니다.
크기 범례는 기본적으로 표시되지 않으며 명시적으로 설정해야 합니다. |  |
| title | 범례에 설명용 제목을 추가합니다.
제목은 범례에 표현된 내용의 의미나 차원을 설명합니다. |  |
| position | 범례가 차트 내 어디에 위치할지를 결정합니다.
가능한 위치 옵션: `None` (기본값), `Top`, `Bottom`, `Left`, `Right` |  |
| textStyle | 범례 영역에 표시되는 텍스트의 외형을 정의합니다. |  |
| height & width | 범례의 높이 및 너비를 차트 전체에 대한 비율(0\~1)로 설정합니다. |  |
| hAlign | 범례의 가로 정렬을 설정합니다.
옵션: `Left`, `Center`(기본값), `Right` |  |
| vAlign | 범례의 세로 정렬을 설정합니다.
옵션: `Top`, `Middle`(기본값), `Bottom` |  |
| padding | 범례 내부의 여백을 조정합니다.
기본 여백: `{ top: 10, bottom: 10, left: 10, right: 10 }` |  |
## 코드 사용하기
다음 코드 샘플은 **데이터 차트에서 범례(Legend)를 구성하는 방법**을 보여줍니다.
이 샘플은 “[데이터 차트 생성하기](/spreadjs/docs/features/data-charts/create-data-charts)” 페이지에서 설명된 `salesTable` 데이터를 사용합니다. 따라서 차트를 설정하기 위한 해당 페이지의 **기본 단계들을 먼저 완료**해야 합니다. 설정이 완료되면, 아래 코드를 사용하여 범례를 구성할 수 있습니다. 또한, 필요에 따라 데이터 소스를 사용자 정의하여 사용할 수도 있습니다
```javascript
// 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,
}
}]
}]
}
});
```