JenniferSoft Design Docs

Appearance

ColumnChart ​

개요 ​

ColumnChart는 시계열 데이터를 세로 막대 형태로 시각화하는 범용 차트 컴포넌트입니다.

주요 기능 ​

  • 가변 길이 데이터 지원: 임의의 개수의 데이터 포인트를 자동으로 정렬
  • 선택적 축 표시: Y축과 X축을 독립적으로 표시/숨김 가능
  • X축 레이블 회전: 많은 데이터 포인트가 있을 때 레이블 회전 지원
  • 선택 상태 관리: 개별 컬럼 선택 및 시각적 피드백
  • 반응형 레이아웃: Flex 기반으로 컨테이너 크기에 자동 맞춤
  • 이벤트 지원: 클릭, 마우스 호버 등의 인터랙션 이벤트

사용 사례 ​

  • 시간별/일별 메트릭 추이 표시
  • 서비스별 트랜잭션 개수 비교
  • 응답 시간 분포 시각화
  • 에러 발생 빈도 모니터링

Props 인터페이스 ​

ChartItem 타입 ​

typescript
interface ChartItem {
    name: string; // 레이블 텍스트
    value: number; // 차트에 표시될 값
    time?: number; // 선택적 타임스탬프
}

Props ​

typescript
interface Props {
    // 필수
    data: ChartItem[];

    // 선택적 - 축
    showYAxis?: boolean; // Y축 표시 여부 (기본값: false)
    showXAxis?: boolean; // X축 표시 여부 (기본값: false)
    rotateXLabels?: boolean; // X축 레이블 45도 회전 (기본값: false)
    hideYLabelWhenZero?: boolean; // maxCount가 0일 때 Y축 레이블 숨김 (기본값: false)

    // 선택적 - 크기 (px 단위, width의 -1은 100% 가변)
    width?: number; // 차트 너비 (기본값: -1, 즉 100%)
    height?: number; // 차트 높이 (기본값: 200)

    // 선택적 - 스타일 (px 단위)
    gap?: number; // 컬럼 간격 (기본값: 4)
    padding?: number; // 차트 내부 패딩 (기본값: 8)
    borderRadius?: number; // 컬럼 모서리 둥글기 (기본값: 4)

    // 선택적 - 축 스타일 (px 단위)
    yAxisWidth?: number; // Y축 너비 (기본값: 40)
    yAxisPaddingRight?: number; // Y축 오른쪽 패딩 (기본값: 8)
    yAxisFontSize?: number; // Y축 폰트 크기 (기본값: 11)
    yAxisLabelCount?: number; // Y축 레이블 개수 (기본값: 3)
    xAxisHeight?: number; // X축 높이 (기본값: 20)
    xAxisHeightRotated?: number; // X축 높이 (회전 시) (기본값: 40)
    xAxisPaddingTop?: number; // X축 상단 패딩 (기본값: 4)
    xAxisFontSize?: number; // X축 폰트 크기 (기본값: 11)

    // 선택적 - 선택 상태
    // -2: 아무것도 선택 안 함, -1: 전체 선택, >= 0: 특정 컬럼 선택
    selectedIndex?: number; // 선택된 인덱스 (기본값: -1)
}

이벤트 ​

typescript
// 컬럼 클릭 시 발생 (value가 0인 컬럼은 클릭 불가)
emit('select', item: ChartItem, index: number)

// 컬럼에 마우스 호버 시 발생
emit('mouseenter', item: ChartItem, e: MouseEvent)

// 컬럼에서 마우스가 벗어날 때 발생
emit('mouseleave')

기본 사용법 ​

간단한 컬럼 차트를 생성하는 기본 예제입니다:

vue
<script setup>
import { ref } from 'vue';
import { ColumnChart } from '@jennifersoft/apm-components';

const data = ref([
    { name: '00', value: 120, time: 1609459200000 },
    { name: '01', value: 250, time: 1609462800000 },
    { name: '02', value: 180, time: 1609466400000 },
    { name: '03', value: 420, time: 1609470000000 },
    { name: '04', value: 310, time: 1609473600000 },
]);

const handleSelect = (item, index) => {
    console.log('Selected:', item.name, 'at index', index);
};
</script>

<template>
    <ColumnChart
        :data="data"
        :height="150"
        :showYAxis="true"
        :showXAxis="true"
        @select="handleSelect"
    />
</template>

인터랙티브 데모 ​

Axes
Size & Style
Data
Presets
936
468
0
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

데이터 구조 ​

ColumnChart는 ChartItem[] 타입의 데이터를 받습니다:

typescript
interface ChartItem {
    name: string; // X축에 표시될 레이블
    value: number; // 차트에 표시될 숫자 값
    time?: number; // 선택적 타임스탬프 (milliseconds)
}

샘플 데이터 ​

typescript
const sampleData: ChartItem[] = [
    { name: '00:00', value: 120, time: 1609459200000 },
    { name: '01:00', value: 250, time: 1609462800000 },
    { name: '02:00', value: 180, time: 1609466400000 },
    { name: '03:00', value: 420, time: 1609470000000 },
    { name: '04:00', value: 310, time: 1609473600000 },
    { name: '05:00', value: 190, time: 1609477200000 },
];

고급 사용법 ​

1. 미니 차트 (축 없음) ​

시각적 표시기로 사용하기 위한 최소한의 차트:

vue
<ColumnChart
    :data="data"
    :height="20"
    :gap="1"
    :showYAxis="false"
    :showXAxis="false"
/>

2. 선택 상태 관리 ​

사용자 선택을 추적하고 시각적으로 표시:

vue
<script setup>
import { ref } from 'vue';
import { ColumnChart } from '@jennifersoft/apm-components';

const selectedIndex = ref(-1);

const handleSelect = (item, index) => {
    // 같은 컬럼 재선택 시 선택 해제
    selectedIndex.value = selectedIndex.value === index ? -1 : index;
};
</script>

<template>
    <ColumnChart
        :data="data"
        :selectedIndex="selectedIndex"
        @select="handleSelect"
    />
</template>

3. Y축 레이블 개수 조정 ​

더 세밀한 Y축 스케일 표시:

vue
<ColumnChart
    :data="data"
    :showYAxis="true"
    :yAxisLabelCount="5"
    :height="200"
/>

4. 반응형 차트 ​

컨테이너 너비에 자동으로 맞춤:

vue
<div style="width: 100%;">
  <ColumnChart
    :data="data"
    :width="-1"
    :showYAxis="true"
    :showXAxis="true"
  />
</div>

5. X축 레이블 회전 (많은 데이터) ​

48개 이상의 데이터 포인트가 있을 때:

vue
<ColumnChart
    :data="largeDataset"
    :showXAxis="true"
    :rotateXLabels="true"
    :xAxisHeightRotated="40"
/>

6. 커스텀 스타일링 ​

차트 외관 조정:

vue
<ColumnChart
    :data="data"
    :gap="8"
    :borderRadius="8"
    :padding="12"
    :yAxisFontSize="12"
    :xAxisFontSize="10"
/>

선택 상태 값 (selectedIndex) ​

  • -2: 아무것도 선택 안 함 (모든 컬럼이 연한 색상)
  • -1: 전체 선택 (모든 컬럼이 기본 색상) - 기본값
  • >= 0: 특정 인덱스의 컬럼만 선택 (선택된 컬럼은 진한 색상, 나머지는 연한 색상)

주의사항 ​

  1. 데이터 개수: 너무 많은 데이터(100개 이상)는 성능에 영향을 줄 수 있습니다
  2. 레이블 길이: X축 레이블이 너무 길면 rotateXLabels를 사용하세요
  3. 0값 클릭: value가 0인 컬럼은 클릭이 불가능합니다
  4. 최소 높이: 의미 있는 시각화를 위해 최소 60px 이상의 높이를 권장합니다
  5. Y축 레이블: hideYLabelWhenZero는 모든 값이 0일 때 Y축 레이블을 공백으로 표시합니다

의존성 ​

  • Vue 3: Composition API (ref, computed)
  • @jennifersoft/apm-components: ChartItem 타입
  • CSS Variables: 테마 색상 (--gray-*, --blue-*, --overlay-*)