# 게이지 KPI 스파크라인
## Content
SpreadJS는 **Gauge KPI 스파크라인**을 제공하며, KPI 값에 대한 성과를 시각화하는 데 사용할 수 있습니다.
이 스파크라인은 **경영 성과의 효율성**을 나타내거나 **판매 목표** 등을 제시하는 데 사용할 수 있습니다.
**Gauge KPI 스파크라인은 다음 값을 사용하여 지표를 표시합니다:**
* **Target Value**: 예상 값을 나타내며, 하단에 표시됩니다.
* **Current Value**: 현재 값을 나타냅니다.
* **Minimum Value**: 예상되는 가장 작은 값입니다. target value 및 current value보다 작아야 합니다.
* **Maximum Value**: 예상되는 가장 큰 값입니다. target value 및 current value보다 커야 합니다.
## Gauge KPI 스파크라인 유형
SpreadJS는 **Circle**, **Vertical**, **Horizontal**의 세 가지 유형의 Gauge KPI 스파크라인을 제공합니다.
`GaugeKPISparkline` 함수에서 `gaugeType` 옵션을 통해 설정할 수 있습니다.
Gauge KPI 스파크라인 수식의 인수
| 인수 | 타입 | 설명 |
| --- | --- | --- |
| **targetValue** | 필수 / 숫자 | Gauge KPI 스파크라인의 목표값입니다. `minValue`와 `maxValue` 사이여야 합니다. |
| **currentValue** | 필수 / 숫자 | Gauge KPI 스파크라인의 현재값입니다. `minValue`와 `maxValue` 사이여야 합니다. |
| **minValue** | 필수 / 숫자 | 최소값입니다. `maxValue`보다 작아야 합니다. |
| **maxValue** | 필수 / 숫자 | 최대값입니다. `minValue`보다 커야 합니다. |
| **showLabel** | 선택 / 불리언 | 모든 값에 대한 레이블을 표시할지 여부를 지정합니다.
`false`일 경우 레이블을 표시하지 않습니다.
`true`일 경우 셀 너비 및 높이에 맞는 레이블만 표시됩니다.
기본값은 `true`입니다. |
| **targetValueLabel** | 선택 / 문자열 | target value에 대한 레이블로 표시할 문자열입니다.
기본값은 `targetValue`입니다. |
| **currentValueLabel** | 선택 / 문자열 | current value에 대한 레이블로 표시할 문자열입니다.
기본값은 `currentValue`입니다. |
| **minValueLabel** | 선택 / 문자열 | min value에 대한 레이블로 표시할 문자열입니다.
기본값은 `minValue`입니다. |
| **maxValueLabel** | 선택 / 문자열 | max value에 대한 레이블로 표시할 문자열입니다.
기본값은 `maxValue`입니다. |
| **fontArray** | 선택 / CalcArray | 네 가지 레이블 유형에 대한 폰트 서식을 포함하는 문자열 배열입니다:
\- Target value label: 기본값 `"16px Calibri"`
\- Current value label: 기본값 `"bold 22px Calibri"`
\- Min/Max value labels: 기본값 `"12px Calibri"`
`showLabel` 옵션이 `true`여야 적용됩니다. |
| **minAngle** | 선택 / 숫자 | 원형 타입의 최소 각도 값입니다. `maxAngle`보다 작아야 합니다.
각도는 시계 시간에 대응되며, `0`은 12시, `-90`은 9시, `90`은 3시, `-180` 또는 `180`은 6시를 의미합니다.
기본값은 `-90`입니다.
`gaugeType`은 `0`(circle 타입)이어야 합니다. |
| **maxAngle** | 선택 / 숫자 | 원형 타입의 최대 각도 값입니다. `minAngle`보다 커야 합니다.
기본값은 `90`입니다.
`gaugeType`은 `0`(circle 타입)이어야 합니다. |
| **radiusRatio** | 선택 / 숫자 | 내원 반지름과 외원 반지름의 비율입니다. 외원 반지름은 셀 크기에 따라 결정됩니다.
값의 범위는 `0~1`, 기본값은 `0`입니다.
`gaugeType`은 `0`(circle 타입)이어야 합니다. |
| **gaugeType** | 선택 / 숫자 | KPI 스파크라인의 유형을 지정합니다:
0 - Circle
1 - Vertical Bar
2 - Horizontal Bar
기본값은 Circle입니다. |
| **colorRange** | 선택 / 반복 가능한 CalcArray | 지정된 값 사이의 색상 범위입니다.
형식: `{startValue, endValue, color_string}`
`startValue`는 범위 시작 값, `endValue`는 범위 끝 값이며, `color_string`은 해당 구간의 색상입니다.
`startValue`는 `endValue`보다 작아야 하며, 두 값 모두 `minValue`와 `maxValue` 사이여야 합니다.
기본 색상 범위는 `minValue`부터 `maxValue`까지 연한 회색으로 채워집니다. |
Gauge KPI 스파크라인 수식의 구문은 다음과 같습니다:
`=GAUGEKPISPARKLINE (targetValue, currentValue, minValue, maxValue,showLabel?,targetValueLabel?,currentValueLabel?,minValueLabel?,maxValueLabel?, fontArray?, minAngle?, maxAngle?, radiusRatio?, gaugeType?, colorRange?)`
## **사용 사례**
Gauge KPI 스파크라인은 회사의 연간 매출 실적을 모니터링하는 데 사용됩니다.
수익(Revenue), 이익(Profit), 판매(Sales)와 같은 지표를 목표값과 실제값에 따라 측정함으로써 데이터를 쉽게 시각화하고, 의미 있는 결론을 도출하는 데 도움을 줍니다.
```javascript
// Spread 초기화
var spread = new GC.Spread.Sheets.Workbook(document.getElementById('ss'), { sheetCount: 2 });
// 시트 가져오기
var sheet1 = spread.sheets[0];
var sheet2 = spread.sheets[1];
// 그리드라인 숨김
sheet1.options.gridline = { showVerticalGridline: false, showHorizontalGridline: false };
// 열/행 헤더 숨김
sheet1.options.colHeaderVisible = false;
sheet1.options.rowHeaderVisible = false;
// 열 너비 설정
for (var i = 0; i < 3; i++)
sheet1.setColumnWidth(i, 340);
for (var i = 0; i < 4; i++)
sheet2.setColumnWidth(i, 70);
for (var i = 0; i < 5; i++)
sheet2.setColumnWidth(i, 170);
// 행 높이 설정
sheet1.setRowHeight(0, 35, GC.Spread.Sheets.SheetArea.dataArea);
sheet1.setRowHeight(1, 280, GC.Spread.Sheets.SheetArea.dataArea);
// 데이터 설정
sheet1.setValue(0, 0, "Sales($'000) Dashboard FY 2019-20", GC.Spread.Sheets.SheetArea.dataArea);
var dataArray1 =
[
["Parameters", "Target", "Current", "Min", "Max"],
["Revenue", 900, 1200, 0, 2000],
["Profit", 1200, 1100, 0, 2000],
["Sales", 1600, 1800, 0, 2000]
];
sheet2.setArray(0, 0, dataArray1);
// GaugeKPISparkline 수식 설정
sheet1.setFormula(1, 0, '=GAUGEKPISPARKLINE(Sheet2!B2,Sheet2!C2,Sheet2!D2,Sheet2!E2,TRUE,TEXT(Sheet2!B3/1000,"$0.0K"),Sheet2!A2,TEXT(Sheet2!D2/1000,"$0.0K"),TEXT(Sheet2!E2/1000,"$0.0K"),{"normal normal 11pt Calibri","normal bold 16pt Calibri","normal normal 9pt Calibri","normal normal 9pt Calibri"},-90,90,0.4,0,{0,1200,"#FFB2BD"},{1200,1500,"#FFDFB0"},{1500,2000,"#BCEAB4"})');
sheet1.setFormula(1, 1, '=GAUGEKPISPARKLINE(Sheet2!B3,Sheet2!C3,Sheet2!D3,Sheet2!E3,TRUE,TEXT(Sheet2!B3/1000,"$0.0K"),Sheet2!A3,TEXT(Sheet2!D3/1000,"$0.0K"),TEXT(Sheet2!E3/1000,"$0.0K"),{"normal normal 11pt Calibri","normal bold 16pt Calibri","normal normal 9pt Calibri","normal normal 9pt Calibri"},-90,90,0.4,0,{0,1200,"#FFB2BD"},{1200,1500,"#FFDFB0"},{1500,2000,"#BCEAB4"})');
sheet1.setFormula(1, 2, '=GAUGEKPISPARKLINE(Sheet2!B4,Sheet2!C4,Sheet2!D4,Sheet2!E4,TRUE,TEXT(Sheet2!B4/1000,"$0.0K"),Sheet2!A4,TEXT(Sheet2!D4/1000,"$0.0K"),TEXT(Sheet2!E4/1000,"$0.0K"),{"normal normal 11pt Calibri","normal bold 16pt Calibri","normal normal 9pt Calibri","normal normal 9pt Calibri"},-90,90,0.6,0,{0,1200,"#FFB2BD"},{1200,1500,"#FFDFB0"},{1500,2000,"#BCEAB4"})');
sheet1.addSpan(0, 0, 1, 3, GC.Spread.Sheets.SheetArea.dataArea);
// 행0 스타일
style1 = new GC.Spread.Sheets.Style();
style1.font = "bold 28px Calibri";
style1.foreColor = "white";
style1.backColor = "#14928F";
style1.hAlign = GC.Spread.Sheets.HorizontalAlign.center;
sheet1.setStyle(0, 0, style1, GC.Spread.Sheets.SheetArea.dataArea);
// 행1 스타일
var style = new GC.Spread.Sheets.Style();
style.backColor = "#B4E7E2";
for (var i = 0; i < 3; i++) {
sheet1.setStyle(1, i, style, GC.Spread.Sheets.SheetArea.dataArea);
}
```