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

열 정의

SpreadJS의 테이블 시트에서는 런타임 중 의미 있는 열 유형을 사용하여 열을 추가, 업데이트 또는 제거함으로써 테이블을 구성할 수 있습니다.

마지막 열 뒤에 열 추가(Add Column) 버튼을 표시하려면 enableDefineColumn 테이블 시트 옵션을 true로 설정하면 됩니다.

오른쪽 클릭 시에는 열을 수정, 제거, 기본 키로 설정하는 컨텍스트 메뉴가 아래 이미지와 같이 표시됩니다.

image

다음 예제는 테이블 시트에서 Add Column 버튼을 활성화하는 방법을 보여줍니다.

tableSheet.options.enableDefineColumn = true;

기본 제공 열 유형

테이블 시트는 열 유형(Column Type)을 미리 정의된 속성 세트로 설정할 수 있도록 지원하며, 다음과 같은 유형으로 분류됩니다:

Number, Text, Formula, Checkbox, Date, Currency, Percent, Phone, Email, URL, Lookup, CreatedTime, ModifiedTime, Attachment, Select, Barcode 등

각 열 유형에 대해 정의할 수 있는 주요 속성은 아래와 같습니다:

  • value (필수): 열에 포함될 실제 값입니다. 단, 열 유형이 Formula 또는 Lookup이 아닌 경우 수식이나 관계 데이터를 포함할 수 없습니다.

  • caption (선택): 열 헤더에 표시될 이름입니다.

  • type (필수): 사용할 내장 열 유형을 지정합니다. 일부 내장 열 유형은 아래 이미지와 같이 표시됩니다.


    image

SpreadJS가 지원하는 모든 열 유형에 대한 데이터 타입과 샘플 열 옵션은 다음 표에 정리되어 있습니다.

Ask ChatGPT

열 유형

데이터 유형

샘플 열 옵션

Number

number

{

    value: "Number",

    type: "Number",

    caption: "Number",

    dataType: "number",

    defaultValue: 0,

    style: {formatter: "0.00", mask: { pattern: "0{0,}" } }

}

Text

string

{

    value: "Text",

    type: "Text",

    caption: "Text",

    dataType: "string"

}

Formula

depends on the result

{

    name: "NamedFormula", // it's a name of the formula for the Referencing Calculated Fields which will be a named formula

    value: "=[@Amount]*[@UnitPrice]",

    type: "Formula",

    caption: "Total Sales",

    dataType: "formula",

    style: {formatter: "0.00"}

    readonly: true,

}

Lookup

depends on the related

{

    value: "customer.ContactName",

    type: "Lookup",

    caption: "Customer",

    readonly: true,

}

Date

date

type DateTimePickerOptions = {

    showTime: boolean;

    calendarPage: "year" | "month" | "day";

    startDay: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";

};

{

    value: "Date",

    type: "Date",

    caption: "Date",

    dataType: "date",

    style: {

        formatter: "m/d/yyyy",

        cellButtons:[{

            buttonBackColor: "transparent",

            command: "openDateTimePicker",

            enabled: true,

            visibility: 'always',

            imageType: "dropdown",

            useButtonStyle: false,

        }],

        dropDowns:[{

            type: "dateTimePicker",

            // The cell type is DateTimePickerOptions

            option: {

                calendarPage: "day",

                showTime: false,

                startDay: "sunday",

            }

        }]

    }

}

Checkbox

boolean

type CheckboxOptions = {

    type: "checkbox";

    caption: string;

    textTrue: string;

    textIndeterminate: string;

    textFalse: string;

    textAlign: "top" | "bottom" | "left" | "right";

    isThreeState: boolean;

    boxSize: number;

};

{

    value: "Checkbox",

    type: "Checkbox",

    caption: "Checkbox",

    dataType: "boolean",

    style: {

        // The cell type is CheckboxOptions

        cellType: {

            type: "checkbox"

        }

    }

}

Select

depends on the option

type ItemOptions = {

    text: string;

    value: any;

};

type ComboBoxOptions = {

    type: "combobox";

    editorValueType: "text" | "index" | "value";

    items: string[] | ItemOptions[];

    itemHeight: number;

    maxDropDownItems: number;

    editable: boolean;

};

{

    value: "Select",

    type: "Select",

    caption: "Select",

    dataType: "number",

    style: {

        // The cell type is ComboBoxOptions

        cellType: {

            type: "combobox",

        }

    }

}

Currency

number

{

    value: "Currency",

    type: "Currency",

    caption: "Currency",

    dataType: "number",

    style: {formatter: "[$$-409]#,##0.00"}

}

Percent

number

{

    value: "Percent",

    type: "Percent",

    caption: "Percent",

    dataType: "number",

    style: {formatter: "0%"}

}

Phone

string

{

    value: "Phone",

    type: "Phone",

    caption: "Phone",

    dataType: "string",

    style: {

        mask: {

            pattern: "1 \(0{3}\) 0{3}-0{4}"

        }

    }

}

Email

string

{

    value: "Email",

    type: "Email",

    caption: "Email",

    dataType: "string",

    style: {

        mask: {

            pattern: "[a0.\-]{1,}@[a0.\\-]{1,}.(com|cn|gov|edu)"

        }

    }

}

URL

string

type HyperlinkOptions = {

    type: "hyperlink";

    linkColor: ColorString;

    visitedLinkColor: ColorString;

    text: string;

    linkToolTip: string;

    target: "blank" | "self" | "parent" | "top";

    activeOnClick: boolean;

};

{

    value: "URL",

    type: "URL",

    caption: "URL",

    dataType: "string",

    style: {

        // The cell type is HyperlinkOptions

        cellType: {

            type: "hyperlink"

        }

    }

}

CreatedTime

date

{

    value: "CreatedTime",

    type: "CreatedTime",

    caption: "CreatedTime",

    dataType: "date",

    defaultValue: "=NOW()",

    readonly: true,

    trigger: {

        when: "onNew",

        formula: "=NOW()",

    },

    style: {

        formatter: "m/d/yyyy",

        // not necessary options(cell buttons and dropDowns)

        cellButtons:[{

            buttonBackColor: "transparent",

            command: "openDateTimePicker",

            enabled: true,

            visibility: 'always',

            imageType: "dropdown",

            useButtonStyle: false,

        }],

        dropDowns:[{

            type: "dateTimePicker",

            option: {

                calendarPage: "day",

                showTime: false,

                startDay: "sunday",

            }

        }]

    }

}

ModifiedTime

date

{

    value: "ModifiedTime",

    type: "ModifiedTime",

    caption: "ModifiedTime",

    dataType: "date",

    readonly: true,

    trigger: {

        when: "onNewAndUpdate",

        formula: "=NOW()",

        fields: "*",

    },

    style: {

     formatter: "m/d/yyyy",

     // not necessary options(cell buttons and dropDowns)

      cellButtons:[{

        buttonBackColor: "transparent",

        command: "openDateTimePicker",

        enabled: true,

        visibility: 'always',

        imageType: "dropdown",

        useButtonStyle: false,

        }],

        dropDowns:[{

            type: "dateTimePicker",

            option: {

                calendarPage: "day",

                showTime: false,

                startDay: "sunday",

            }

        }]

    }

}

Attachement

object

type FileUploadOptions = {

    type: "fileUpload";

    maxSize?: number;

    accept?: string;

    isPreviewEnabled?: boolean;

    isDownloadEnabled?: boolean;

    isClearEnabled?: boolean;

    marginTop?: number;

    marginRight?: number;

    marginBottom?: number;

    marginLeft?: number;

    valuePath?: string;

};

{

    value: "Attachment",

    type: "Attachment",

    caption: "Attachment",

    style: {

    // The cell type is FileUploadOptions

        cellType: {

            type: "fileUpload"

        }

    }

}

Barcode

depends on the input

{

    value: "Barcode",

    type: "Barcode",

    caption: "Barcode",

    defaultValue: 0,

    style: {

        formatter: "=BC_QRCODE([@Barcode],\"#000000\",\"#FFFFFF\",\"L\",2,\"auto\",\"auto\",false,0,,\"UTF-8\",,,,)"

    }

}

원격 구성

SpreadJS의 테이블 시트는 다음과 같이 사용자 정의 함수를 통해 원격 테이블과 통신할 수 있도록 지원합니다.

함수 이름

설명

샘플 정의

getColumns

테이블에서 열 목록을 가져옵니다.

getColumns: { url: apiColumnUrl }

addColumn

테이블에 열을 추가합니다.

addColumn: { url: apiColumnUrl, method: 'POST' }

updateColumn

테이블의 열 속성을 업데이트합니다.

updateColumn: { url: apiColumnUrl, method: 'PUT' }

removeColumn

테이블에서 열을 제거합니다.

removeColumn: { url: apiColumnUrl, method: 'DELETE' }

batch

변경 사항을 배치 모드로 한 번에 전송합니다.

batch: { url: apiUrl + 'Collection' }

각 사용자 정의 함수가 데이터 구조와 상호작용할 때의 요청 및 응답 예시:

사용자 정의 함수

요청 데이터

응답 데이터

getColumns

없음

Column[]

addColumn

ColumnWithDefaultData

ColumnData

updateColumn

ModifiedColumnData

ModifiedColumnData

removeColumn

ColumnData

ColumnData

batch

BatchItemData[]

BatchResultData[]

컬럼 관련 원격 API는 autoSync 및 batch 모드에서의 Handle Requests와 유사하게 사용자 정의 함수로 처리할 수 있습니다.

Ask ChatGPT

var orderTable = dataManager.addTable("orderTable", {
        remote: {
            read: function(): Promise<any[]>{
                return Promise.resolve([...])
            },
            getColumns: function(): Promise<Column[]>{
                return Promise.resolve([...])
            },
            addColumn: function(change): Promise<ny>{
                return Promise.resolve()
            },
            updateColumn: function(change): Promise<any>{
                return Promise.resolve();
            },
            removeColumn: function(change): Promise<any>{
                return Promise.resolve();
            },
            // batch: function(changes): Promise<any>{
            //   return Promise.resolve([...]);
            // },
        },
        autoSync: true,
        // batch: true
 });

autoSync 모드가 활성화된 경우, 테이블 시트에서 열(column)의 변경 사항은 즉시 원격 테이블과 동기화됩니다. 그러나 batch 모드가 활성화된 경우, 열 변경 사항은 로컬에 저장됩니다. 이후 submitChange 명령을 호출하면 변경된 열 정보와 변경된 데이터 정보가 함께 원격 테이블로 전송됩니다.

[
    { "type": "updateColumn", "column": { field: 'columnName', dataType: 'number', ...otherproperties }, "originalColumn": { field: 'columnName0', ...otherproperties } },
    { "type": "addColumn", "column": { field: 'columnName1', dataType: 'number', ...otherproperties }, },
    { "type": "removeColumn", "column": { field: 'columnName2', ...otherproperties }, },
   
    { "type": "delete", "dataItem": { ...} },
    { "type": "insert", "dataItem": { ...} },
    { "type": "update", "dataItem": { ...}, "oldDataItem": { ...}, "sourceIndex": 1 }
]

반면 cancelChange 명령을 호출하면 모든 변경 사항이 취소됩니다. batch 모드에서는 getChanges 명령을 통해 테이블 시트의 열 변경 및 데이터 변경 사항을 함께 가져올 수 있습니다.

열 정의를 위한 명령

SpreadJS는 DefineColumn, ModifyColumn, RemoveColumn 등의 명령을 통해 열을 추가, 수정 또는 삭제할 수 있는 기능을 제공합니다. 이러한 명령은 IColumn 인터페이스에 정의된 value, dataType, defaultValue, isPrimaryKey, type, name 등의 속성을 사용하여 테이블 열을 구현할 수 있게 합니다.

열 정의

다음은 DefineColumn 명령을 구현하는 샘플 코드입니다:

spread.commandManager().execute({
  cmd: "DefineColumn",
  sheetName: spread.getActiveSheetTab().name(),
  // col: 3, // optional
  column: {
    type: 'Number', // 열 유형 지정
    value: 'Number1', //  열 유형에서 파생된 열 인스턴스의 식별자
    caption: '# Number1', // 해당 문화권(culture)에 맞는 열의 표시 형식 
    style: { formatter: '#,##0.00_);[Red](#,##0.00)' } // 서식 지정자(formatter)는 직접 지정할 수도 있고 UI 작업을 통해 변환될 수도 있음 
  } as GC.Data.IColumn,
});

열 수정

아래 샘플 코드는 ModifyColumn 명령을 구현하는 방법을 보여줍니다.

spread.commandManager().execute({
  cmd: "ModifyColumn",
  sheetName: spread.getActiveSheetTab().name(),
  col: 3,
  column: {
    type: 'Text', // 열 유형 지정
    value: 'Text1',//  열 유형에서 파생된 열 인스턴스의 식별자
    caption: 'A Text1',// 해당 문화권(culture)에 맞는 열의 표시 형식 
  } as GC.Data.IColumn,
});

열 삭제

다음 샘플 코드는RemoveColumn 명령을 구현하는 방법을 보여줍니다.

spread.commandManager().execute({
  cmd: "RemoveColumn",
  sheetName: spread.getActiveSheetTab().name(),
  col: 3,
});

사용자 정의 열 정의

테이블 시트는 defineColumnCommand, submitDefineColumnCommand와 같은 사용자 정의 명령을 통해 열 유형을 사용자 정의하거나 일부 특별한 열 유형을 추가할 수 있는 기능을 제공합니다. 또한, columnTypeItems 명령을 사용하여 기본 제공 열 유형을 업데이트할 수 있습니다.

다음 코드 샘플은 특별한 열 유형을 추가하거나 기본 제공 열 유형을 업데이트하는 방법을 보여줍니다.

// 표시할 영 유형을 선택
const items = tableSheet.options.columnTypeItems.filter((item)=>item.name === 'Select' || item.name === 'Attachment' || item.name === 'Barcode' || item.name === 'CreatedTime' || item.name === 'ModifiedTime' || item.name === 'Currency')

tableSheet.options.columnTypeItems = tableSheet.options.columnTypeItems.slice(0, 4).concat(items);

// 사용자 정의 열 유형 추가
tableSheet.options.columnTypeItems.unshift({ name: 'CustomizingType', text: 'Progress', iconClass: 'gc-defined-column-type-icon-number'
});

defineColumnCommand는 Add Column 버튼 또는 Modify Column 메뉴 항목에서 열 정의 팝업을 여는 기본 명령을 대체하는 명령을 지정합니다.

다음 샘플 코드는 defineColumnCommand를 구현하는 방법을 보여줍니다.

// 열 정의 팝업 열기 처리
const defineCommand = tableSheet.options.defineColumnCommand;
tableSheet.options.defineColumnCommand = 'defineColumnCustom';
  spread.commandManager().register('defineColumnCustom', {
    canUndo: false,
    execute: function (context, options) {
    // 사용자 정의 UI를 구성할 수 있음 (열 수정/추가 시)
    // 샘플에서는 기본 UI 열기
       options.cmd = defineCommand;
       spread.commandManager().execute(options);
    }
});

submitDefineColumnCommand는 열 정의 팝업에서 "Submit" 버튼을 선택할 때 정의된 열 옵션을 제출하는 명령을 지정합니다.

다음 샘플 코드는 submitDefineColumnCustom을 구현하는 방법을 보여줍니다.

// 정의된 열 옵션 보내기 처리
tableSheet.options.submitDefineColumnCommand = 'submitDefineColumnCustom';
spread.commandManager().register('submitDefineColumnCustom', {
  canUndo: false,
  execute: function (context, options) {
    if (options.command === 'DefineColumn' && options.column.type === 'CustomizingType') {
        options.column.defaultValue = 0.1;
        options.column.style = {
          formatter: "=HBARSPARKLINE([@"+options.column.value+"], \"#66B032\")"
        };
}
  options.cmd = options.command;
  spread.commandManager().execute(options);
}
});

SpreadJS 디자이너 사용하기

SpreadJS 디자이너에 테이블 시트 디자인(TABLE SHEET DESIGN) > 옵션(Options) 그룹에서 열 정의 활성화(Enable Define Column) 체크박스를 선택하여 열을 정의할 수 있는 기능을 제공합니다.

image

또한, 원격 데이터 테이블이 지원되는 경우, 데이터(DATA) > 데이터원본(DataSource) > 표(Table) 섹션을 통해 SpreadJS 디자이너에서 원격 API를 구성하여 원격 데이터 테이블과 통신할 수 있습니다.

Ask ChatGPT

image