템플릿 기반 통합 문서 초기화

사용자가 SpreadJS 디자이너에서 새 파일을 만들면 일반적으로 빈 통합 문서에서 시작합니다. 그러나 많은 애플리케이션에서는 사용자가 미리 정의된 레이아웃, 스타일 또는 비즈니스 전용 구조를 기반으로 작업을 시작해야 합니다.

templatesConfig 옵션을 사용하면 디자이너의 시작 환경을 정의할 수 있습니다. 빈 통합 문서를 여는 대신, 디자이너가 미리 정의된 템플릿으로 초기화되도록 하고 새로 만들기(New) 워크플로에서 여러 템플릿 선택지를 제공할 수 있습니다.

템플릿 기반 초기화 사용

사용자 지정 템플릿을 사용하려면 디자이너 인스턴스를 생성할 때 templatesConfig 옵션을 지정합니다.

const designer = new GC.Spread.Sheets.Designer.Designer("container", {
  templatesConfig: "/templates/templatesConfig.json"
});

값은 JSON 구성 파일의 경로를 나타내는 문자열입니다.

templatesConfig를 지정하지 않으면 디자이너는 기본 동작을 유지하며 빈 통합 문서를 생성합니다.

템플릿 구성 파일 구조

구성 파일은 템플릿 정의를 포함하는 JSON 배열이어야 합니다.

예제:

[
  {
    "name": "Blank",
    "data": "./templates/blank.ssjson",
    "thumbnail": "./templates/blank.png"
  },
  {
    "name": "Aging Report",
    "data": "./templates/aging_report.sjs",
    "thumbnail": "./templates/aging_report.png"
  }
]

템플릿 속성

data 동작

• data가 문자열이면 URL로 처리됩니다. 디자이너는 리소스를 가져온 후 파일 확장자에 따라 로드 방식을 결정합니다.

• data가 객체이면 Workbook JSON 데이터로 처리되어 직접 적용됩니다.

지원되는 템플릿 형식

data가 URL인 경우 다음 형식을 지원합니다.

• .ssjson

• .sjs

• .xlsx

• .xltx

• .xlsm

• .xltm

기본 템플릿 동작

구성 배열의 첫 번째 템플릿(templates[0])은 기본 템플릿으로 처리됩니다.

다음 경우 자동으로 적용됩니다.

• 디자이너 초기화 - new Designer() 호출 후 기본 템플릿이 로드되어 통합 문서에 적용됩니다.

• 초기화 작업 - 사용자가 새로 만들기(New) 를 선택하거나 초기화 작업을 수행하면 빈 통합 문서를 생성하는 대신 기본 템플릿이 로드됩니다.

다른 템플릿은 사용자가 템플릿 선택기에서 명시적으로 선택한 경우에만 적용됩니다.

템플릿이 성공적으로 로드되면 해당 통합 문서는 수정되지 않은 새 파일 상태로 처리됩니다.

비동기 로드 고려 사항

기본 템플릿은 비동기적으로 로드됩니다.

디자이너 인스턴스를 생성한 직후 통합 문서에 접근하거나 수정하면 템플릿 로드 완료 시 변경 내용이 덮어써질 수 있습니다.

초기화 과정에서 통합 문서를 조작해야 하는 경우 템플릿 로드가 완료될 때까지 기다려야 합니다.

const designer = new GC.Spread.Sheets.Designer.Designer("container", {
  templatesConfig: "/templates/templatesConfig.json"
});

await designer.waitForDefaultTemplateLoaded();

const workbook = designer.getWorkbook();
workbook.getActiveSheet().setValue(0, 0, "Safe to modify");

templatesConfig가 구성되지 않은 경우 디자이너 초기화는 동기 방식으로 유지됩니다. 이전 버전의 기존 코드는 수정 없이 계속 사용할 수 있습니다.

런타임에 템플릿 업데이트

디자이너가 생성된 이후에도 템플릿 구성을 업데이트할 수 있습니다.

setData 사용:

designer.setData("templatesConfig", [
  {
    name: "Blank",
    data: "./templates/blank.ssjson",
    thumbnail: "./templates/blank.png"
  },
  {
    name: "Financial Report",
    data: "./templates/financial_report.sjs",
    thumbnail: "./templates/financial_report.png"
  }
]);

setConfig 사용:

const config = {
  ...GC.Spread.Sheets.Designer.DefaultConfig,
  templatesConfig: "/templates/newTemplatesConfig.json"
};

designer.setConfig(config);

setConfig에 templatesConfig 속성이 포함되어 있으면 디자이너는 템플릿 구성을 업데이트합니다.

setConfig에 templatesConfig 속성이 없으면 기존 템플릿 구성은 유지됩니다.

templatesConfig 변경 사항은 이후 초기화 작업에만 영향을 미치며 현재 로드된 통합 문서는 자동으로 변경되지 않습니다.

이벤트

DesignerResetDone

이 이벤트는 초기화 작업이 완료되고 선택된 템플릿이 완전히 로드된 후 발생합니다.

designer.bind(
  GC.Spread.Sheets.Designer.Events.DesignerResetDone,
  () => {
    console.log("Reset completed and template applied.");
  }
);

FileLoading 및 FileLoaded

초기화, 리셋 또는 템플릿 선택 중 템플릿을 로드할 때도 표준 파일 로드 이벤트가 발생합니다. 이러한 이벤트는 파일을 열 때와 동일하게 동작합니다.

대체 동작

• templatesConfig가 설정되지 않았거나 비어 있으면 디자이너는 빈 통합 문서를 생성하며 기본 빈 템플릿만 사용할 수 있습니다.

• 기본 템플릿 로드에 실패하면 디자이너는 빈 통합 문서로 대체합니다.

• 기본 템플릿이 아닌 템플릿의 로드에 실패한 경우에도 빈 통합 문서가 대신 사용됩니다.