# 애니메이션
## Content
데이터 차트에서의 애니메이션은 차트의 시각적 매력을 높이고, 데이터 표현을 보다 역동적이고 흥미롭게 만들어 줍니다.
`GC.Spread.Sheets.DataCharts` 네임스페이스의 `IAnimationOption` 인터페이스를 사용하여, 애니메이션의 속성(easing, scale, duration, startDelay 등) 을 정의할 수 있습니다. 이를 통해 사용자는 데이터 차트의 애니메이션 동작을 자유롭게 설정할 수 있습니다.
또한, `AnimationEasing` 열거형은 사전 정의된 이징(easing) 함수들을 제공하여 다양한 애니메이션 효과를 만들 수 있도록 지원합니다. 이 열거형에 포함된 주요 이징 함수에는 `linear`, `swing`, `easeInOutBack`, `easeOutBounce` 등이 있습니다.
## 애니메이션 종류
SpreadJS에서는 아래와 같은 애니메이션을 지원합니다:
### **호버 애니메이션(Hover Animation)**
데이터 포인트 위에 마우스를 올리면, 호버 애니메이션이 실행됩니다.
특히 라인 차트, 레이더 차트, 산점도(scatter), 버블 차트에서는 차트 심볼 위에 마우스를 올릴 때 애니메이션이 활성화됩니다.
| **호버 애니메이션** | **샘플 미리보기** |
| -------- | ------- |
| 데이터 포인트 위에 마우스를 올릴 때 |  |
| 차트 심볼 위에 마우스를 올릴 때 |  |
### **업데이트 애니메이션**
**업데이트 애니메이션**은 다음과 같은 상황에서 자동으로 트리거됩니다:
| **업데이트 애니메이션** | **샘플 미리보기** |
| ---------- | ------- |
| 차트가 처음 렌더링될 때 |  |
| 차트에 데이터가 바인딩될 때 |  |
| 차트의 크기를 조정할 때 |  |
## **애니메이션 속성**
다음은 `IAnimationOption` 인터페이스의 주요 속성 목록입니다:
| **속성** | **설명** |
| --- | --- |
| `duration` | 애니메이션의 지속 시간을 밀리초(ms) 단위로 설정합니다. |
| `easing` | 애니메이션의 종류를 설정합니다.
각 easing 타입은 시간에 따라 애니메이션 변화 속도(rate)가 다릅니다. |
| `scale` | 데이터 포인트에 마우스를 올렸을 때 실행되는 **호버 애니메이션의 확대 비율**을 설정합니다.
이 속성은 `hoverAnimation`에서만 작동하며, 값은 0보다 커야 합니다. |
| `startDelay` | 애니메이션과 동작 사이의 **지연 시간(ms 단위)** 을 설정합니다.
이 속성은 `updateAnimation`에서만 사용할 수 있으며, 차트가 자주 업데이트될 때 성능 문제를 방지하는 데 사용됩니다. |
## **코드 사용 예시**
다음 코드 샘플은 **데이터 차트에서 애니메이션을 구성하고 적용하는 방법**을 보여줍니다.
이 샘플은 “[데이터 차트 생성하기](/spreadjs/docs/v18/features/data-charts/create-data-charts)” 페이지에서 설명된 `salesTable` 데이터를 사용합니다. 따라서 차트를 설정하기 위한 해당 페이지의 **기본 단계들을 먼저 완료**해야 합니다. 설정이 완료된 후에는, 아래 코드를 사용하여 데이터 차트의 애니메이션을 구성할 수 있습니다. 또한 필요에 따라 데이터 소스를 자유롭게 커스터마이징할 수도 있습니다.
```javascript
// 호버 애니메이션
const sheet = spread.getSheet(0);
sheet.name("Hover Animation");
sheet.setValue(16, 0, "Hover Over the Data Chart");
sheet.setValue(16, 9, "Hover Over the Chart Symbol(Triangle)");
const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 480, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
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: 'Product' },
color: { field: 'Product' },
},
config: {
// 데이터 포인트 위에 마우스를 올리면 호버 애니메이션이 실행됩니다.
hoverAnimation: { // IAnimationOption
duration: 600, // 숫자 (밀리초 단위)
scale: 1.5, // 숫자 (값은 0보다 커야 함)
easing: GC.Spread.Sheets.DataCharts.AnimationEasing.easeOutBack, // GC.Spread.Sheets.DataCharts.AnimationEasing
},
}
}
]
});
// 차트 심볼 위에 호버링
const dataChart1 = sheet.dataCharts.add('data-chart-1', 560, 10, 480, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart1.setChartConfig({
tableName: 'Sales',
plots: [
{
type: GC.Spread.Sheets.DataCharts.DataChartType.line,
config: {
// 라인 차트, 레이더 차트, 산점도 차트, 버블 차트에서는
// 차트 심볼 위에 마우스를 올릴 때 호버 애니메이션이 실행됩니다.
hoverAnimation: {
duration: 600,
scale: 1.5,
easing: GC.Spread.Sheets.DataCharts.AnimationEasing.easeOutBounce,
},
style: {
symbolShape: GC.Spread.Sheets.DataCharts.SymbolShape.triangle,
symbolSize: 15,
},
symbols: true,
},
encodings: {
values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
category: { field: 'Product' },
}
}
]
});
// 업데이트 애니메이션
const sheet1 = spread.getSheet(1);
const spreadNS = GC.Spread.Sheets;
sheet1.name("Update Animation");
sheet1.setColumnWidth(0, 150);
sheet1.setRowHeight(18, 35);
sheet1.setValue(1, 7, "Resize the Chart To Show the Animation");
sheet1.setValue(17, 0, "Setting the Encoding Color will trigger the Update Animation");
sheet1.setValue(19, 0, "The update animation will be triggered when the chart is first rendered, binding data into chart and resizing.");
var b0 = new GC.Spread.Sheets.CellTypes.Button();
b0.text("Set Encoding Color");
sheet1.setCellType(18, 0, b0, spreadNS.SheetArea.viewport);
const dataChart3 = sheet1.dataCharts.add('data-chart-3', 10, 10, 480, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart3.setChartConfig({
tableName: 'Sales',
plots: [
{
type: GC.Spread.Sheets.DataCharts.DataChartType.column,
config: {
updateAnimation: {
duration: 600,
startDelay: 1000, // 숫자 (밀리초 단위) // 이 속성은 updateAnimation에서만 작동합니다.
easing: GC.Spread.Sheets.DataCharts.AnimationEasing.easeOutBounce,
},
},
encodings: {
values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
category: { field: 'Product' },
}
}
]
});
spread.bind(GC.Spread.Sheets.Events.ButtonClicked, (sender, args) => {
if (args.sheetName === "Update Animation" && args.row === 18 && args.col === 0) {
// 차트 구성 가져오기
let config = dataChart3.getChartConfig();
// 인코딩 색상 추가
config.plots[0].encodings.color = { field: 'Product' };
// 차트 구성 설정
dataChart3.setChartConfig(config); // 업데이트 애니메이션 트리거
}
})
```