[]
DEMOS DOC DESIGNER API
DOWNLOAD
(Showing Draft Content)

데이터 원본 바인딩

데이터 차트는 데이터를 시각화하기 전에 데이터 원본에 연결되어야 합니다. SpreadJS에서는 일반적으로 데이터가 데이터 매니저를 통해 관리되며, 여기에서 테이블이 정의되고 유지됩니다.

데이터 차트에 데이터를 표시하려면 다음을 수행합니다.

  1. 차트를 테이블에 바인딩합니다.

  2. 테이블 필드를 차트 인코딩에 매핑합니다.

이 항목에서는 데이터 바인딩을 구성하는 방법과 인코딩이 데이터 시각화를 제어하는 방법을 설명합니다.

차트를 테이블에 바인딩

각 데이터 차트는 차트 구성에서 tableName 속성을 설정하여 테이블에 바인딩됩니다.

dataChart.setChartConfig({
  tableName: 'Sales',
  plots: [...]
});

테이블은 데이터 매니저에 존재해야 합니다.

데이터 차트는 여러 관련 테이블의 데이터도 바인딩할 수 있습니다. 여러 테이블을 사용하는 경우:

  • 데이터 매니저에 관계가 정의되어 있어야 합니다.

  • 관련 테이블의 필드는 tableName.fieldName 형식으로 참조할 수 있습니다.

인코딩

인코딩은 데이터 필드가 차트의 시각적 요소에 어떻게 매핑되는지를 정의합니다.

각 플롯은 다음 위치에 인코딩을 정의합니다.

plots[n].encodings

인코딩은 다음을 제어합니다.

  • 어떤 값이 집계되는지

  • 데이터가 어떻게 그룹화되는지

  • 색상, 도구 설명 및 필터가 어떻게 적용되는지

인코딩은 다음과 같이 구성됩니다.

  • 값 인코딩(Value Encoding)

  • 범주 인코딩(Category Encoding)

  • 기타 인코딩(Other Encodings)

값 인코딩

값 인코딩은 어떤 숫자 필드가 측정값으로 시각화되는지(일반적으로 Y축)를 정의합니다.

단일 필드 값 인코딩

가장 일반적인 시나리오는 하나의 값 항목에 하나의 필드를 바인딩하는 것입니다.

encodings: {
  values: [
    {
      field: "Sales",
      aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
    }
  ]
}

image-20260420.52eaa2.png


여러 값 필드가 정의된 경우:

  • 각 필드는 별도의 계열로 처리됩니다.

  • 범례는 값 필드를 기준으로 자동 생성됩니다.

일부 차트 유형(예: Pie 및 Donut)은 하나의 값 필드만 지원합니다.

다중 필드 값 인코딩

지원되는 차트 유형

  • 범위 값 인코딩:

    • Range Column

    • Range Bar

    • Range Area

  • 주가 값 인코딩:

    • Candlestick

    • OHLC

일부 차트 유형은 하나의 논리적 값을 표현하기 위해 여러 데이터 필드를 필요로 합니다.

예를 들면:

  • Range 차트는 하한값과 상한값이 필요합니다.

  • Candlestick 및 OHLC 차트는 시가, 고가, 저가, 종가가 필요합니다.

이러한 차트에서는 여러 필드를 vectors 구조 아래 하나의 값 항목으로 그룹화합니다.


Range 차트 예제

encodings: {
  values: [{
    vectors: {
      lower: { field: "Return" },
      upper: { field: "Sales" }
    },
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: { field: "Product" }
}

image-20260417.190d58.png

주가 차트 예제

encodings: {
  values: [{
    vectors: {
      open:  { field: "open" },
      high:  { field: "high" },
      low:   { field: "low" },
      close: { field: "close" }
    }
  }],
  category: { field: "date" }
}

image-20260417.a41881.png

이 구조에서:

  • 각 이름이 지정된 벡터는 특정 필드에 바인딩됩니다.

  • 해당 차트 유형에 필요한 모든 벡터를 제공해야 합니다.

별도의 값 항목을 사용하는 기존 구성도 계속 동작하지만, 명확성과 일관성을 위해 벡터 구조 사용을 권장합니다.

참고:

벡터가 필요한 차트 유형에서는 모든 필수 필드를 제공해야 합니다. 필수 벡터 필드가 누락되면 차트가 올바르게 렌더링되지 않습니다.

범주 인코딩

범주 인코딩은 데이터가 특정 차원(일반적으로 X축)을 기준으로 어떻게 그룹화되는지를 정의합니다.

단일 범주

단일 범주는 하나의 필드에 바인딩됩니다.

encodings: {
  category: {
    field: "timePeriod"
  }
}

image-20260417.27b715.png

계층형 범주

계층형 범주는 하나의 플롯 내에서 여러 수준의 그룹화를 허용합니다.

다음과 같이 자연스럽게 계층 구조를 가지는 데이터에 유용합니다.

  • 연도 → 분기 → 월

  • 지역 → 국가 → 도시

중첩된 child 객체를 사용하여 계층 수준을 정의합니다.


예제

encodings: {
  values: [{
    field: "Sales",
    aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum
  }],
  category: {
    field: "Year",
    child: {
      field: "Quarter",
      child: {
        field: "Month"
      }
    }
  }
}

image-20260417.f76f78.png


주요 특징:

  • 중첩 순서가 그룹화 순서를 정의합니다.

  • 각 수준은 상위 수준의 그룹화를 세분화합니다.

  • 모든 수준은 동일한 집계 규칙을 공유합니다.

  • child가 정의되지 않으면 일반 범주처럼 동작합니다.

지원되는 차트 유형

지원되지 않는 차트 유형

  • Column

  • Range Column

  • Stacked Column

  • Percent Stacked Column

  • Bar

  • Range Bar

  • Stacked Bar

  • Percent Stacked Bar

  • Area

  • Range Area

  • Stacked Area

  • Percent Stacked Area

  • Line

  • Candlestick

  • OHLC

  • Pie

  • Donut

  • Radar

  • Polar charts

  • Treemap

  • Funnel

  • Scatter

  • Bubble

참고:

모든 계층 수준은 동시에 렌더링됩니다. 계층형 범주는 확장, 축소 또는 드릴다운 기능을 제공하지 않습니다.

기타 인코딩

  • details - 각 범주 내에서 데이터를 하위 그룹으로 나눕니다. 대부분의 차트 유형은 최대 하나의 details 필드만 지원합니다.

  • color - 플롯 및 범례의 색상 할당에 사용할 필드를 정의합니다.

  • size - 연속적인 크기 스케일을 적용합니다. 버블 차트에서만 지원됩니다.

  • tooltip - 도구 설명에 표시할 필드를 지정합니다.

  • filter - 집계 전에 원본 데이터에 필터를 적용합니다. 숫자 및 문자열 필터링과 중첩 논리 조건을 지원합니다.

코드 사용

데이터 차트는 SpreadJS 데이터 매니저가 관리하는 테이블에 바인딩됩니다.

차트를 구성하기 전에 다음을 수행해야 합니다.

  1. 데이터 매니저 초기화

  2. 테이블 등록

  3. (선택 사항) 테이블 간 관계 정의

1단계 - 데이터 매니저 초기화

const dataManager = spread.dataManager();

2단계 - 테이블 등록

차트를 생성하기 전에 필요한 모든 테이블을 등록합니다.

// Sales 테이블
const salesTable = createSalesTable(dataManager);
await salesTable.fetch();

// Orders 테이블
const ordersTable = createOrders(dataManager);
await ordersTable.fetch();

// Order details 테이블
const orderDetailsTable = createOrderDetails(dataManager);
await orderDetailsTable.fetch();

// 계층형 Sales 테이블 (계층형 범주 예제에서 사용)
const hierarchySalesTable = createHierarchySalesTable(dataManager);
await hierarchySalesTable.fetch();

3단계 - 테이블 관계 정의(선택 사항)

여러 테이블을 바인딩할 경우 테이블 간 관계를 정의해야 합니다.

dataManager.addRelationship(
    ordersTable, "orderId",
    "orderDetailsTable",
    orderDetailsTable, "OrderId",
    "ordersTable"
);

4단계 - 기본 데이터 바인딩 예제

다음 예제는 Sales 테이블에 Column 차트를 바인딩합니다.

const sheet = spread.getSheet(0);
sheet.name("Binding Data");

const dataChart = sheet.dataCharts.add('data-chart', 10, 10, 600, 400);

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"
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Product"
        }
    }
});

image-20260420.54c315.png

5단계 - 여러 테이블 바인딩

관계가 존재하는 경우 경로 식을 사용하여 관련 테이블의 필드를 참조할 수 있습니다.

다음 예제는 Orders 테이블에 차트를 바인딩하고 관련된 orderDetailsTable의 데이터를 집계합니다.

let sheet2 = spread.getSheet(1);
sheet2.name("Binding Multiple Tables");

const dataChart2 = sheet2.dataCharts.add('data-chart-2', 10, 10, 600, 400);

dataChart2.setChartConfig({
    tableName: 'Orders',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'orderDetailsTable.Sales'
            }],
            category: {
                field: 'shipCountry'
            }
        }
    }],
    config: {
        header: {
            title: "Sales by Country (Multiple Tables)"
        }
    }
});

image-20260420.2a67b9.png

6단계 - 계층형 범주 바인딩

데이터 차트는 category 인코딩 내에 중첩된 child 필드를 정의하여 다단계 범주 그룹화를 지원합니다.

다음 예제는 계층형 범주 구조(연도 → 분기 → 월)를 사용하여 Column 차트를 바인딩합니다.

let sheet3 = spread.getSheet(2);
sheet3.name("Hierarchical Category Binding");

const dataChart3 = sheet3.dataCharts.add('data-chart-3', 10, 10, 600, 400);

dataChart3.setChartConfig({
    tableName: 'HierarchySales',
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.column,
        encodings: {
            values: [{
                field: 'sales'
            }],
            category: {
                field: "year",
                    child: {
                        field: "quarter",
                            child: {
                                field: "month"
                            }
                        }
            }
        }
    }],
    config: {
        header: {
            title: "Hierarchical Column Chart"
        }
    }
});

image-20260420.808e30.png

전체 예제

다음 함수들의 구현은 이 항목에 포함되어 있지 않습니다.

  • createSalesTable

  • createOrders

  • createOrderDetails

  • createHierarchySalesTable

모든 테이블 생성 유틸리티를 포함한 전체 실행 예제는 다음에서 다운로드할 수 있습니다.

BindDataSourceExample.js