基于模板的工作簿初始化

用户在SpreadJS设计器中新建文件时，通常会从空白工作簿开始。但在诸多应用场景里，用户往往需要依托预设版式、样式或是贴合业务的结构开展操作。

借助templatesConfig配置项，能够自定义设计器的初始使用界面。设计器不再默认开启空白工作簿，而是可以载入预设模板，同时在新建流程中提供多款模板供用户选择。

该功能仅可在设计器组件中使用

启用模板初始化功能

想要启用自定义模板，创建设计器实例时配置templatesConfig参数即可。

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

该参数值为字符串，代表JSON配置文件的存放路径。

若未配置templatesConfig，设计器将沿用默认模式，直接创建空白工作簿。

模板配置文件结构

配置文件内部需以JSON数组格式定义各项模板信息。

示例如下：

[
    {
        name: '空白模板',
        data: './templates/blank.ssjson',
        thumbnail: './templates/blank.png',
    },
    {
        name: '账龄报表',
        data: './templates/aging_report.sjs',
        thumbnail: './templates/aging_report.png',
    },
];

模板属性说明

属性	是否必填	说明
`name`	是	界面上展示的模板名称
`data`	否	模板内容。可以是模板文件链接，也可以是内嵌的工作簿JSON数据。省略该参数则视为空白模板
`thumbnail`	否	用作模板预览图的图片地址或Base64编码字符串。省略则使用默认空白预览图

data参数运行规则

若data为字符串，会被判定为资源链接，设计器读取资源后依据文件后缀匹配加载方式。
若data为对象，会直接当作工作簿JSON数据载入使用。

支持的模板格式

当data参数填写资源链接时，兼容以下文件格式：

.ssjson
.sjs
.xlsx
.xltx
.xlsm
.xltm

默认模板运行规则

配置数组内首个模板（templates[0]）即为默认模板。

以下场景会自动加载应用默认模板：

设计器初始化：执行创建设计器实例代码后，默认模板会自动载入并生成对应工作簿。
重置操作：用户点击新建按钮或触发重置指令时，系统加载默认模板，而非新建空白工作簿。

其余模板仅能由用户手动在模板选择面板中选用。

模板加载完成后，当前工作簿会恢复为未编辑的原始状态。

异步加载注意事项

默认模板采用异步加载模式。

若创建设计器实例后立刻读写编辑工作簿，后续模板加载完成时，此前的修改内容可能会被覆盖。

如需在初始化阶段操作工作簿，需等待模板加载完毕，参考代码如下：

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, '可正常编辑内容');

未配置templatesConfig时，设计器初始化流程为同步执行，旧版本编写的代码无需改动便可正常运行。

运行时更新模板

设计器创建完成后，依旧可以修改模板配置信息。

方式一：使用setData方法

designer.setData('templatesConfig', [
    {
        name: '空白模板',
        data: './templates/blank.ssjson',
        thumbnail: './templates/blank.png',
    },
    {
        name: '财务报表',
        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字段，设计器会同步更新模板配置；若缺失该字段，则保留原有模板设置。

模板配置的改动，仅对后续重置操作生效，不会自动变更当前已打开的工作簿。

异常兜底机制

未设置templatesConfig或配置内容为空时，设计器生成空白工作簿，仅提供默认空白模板选项。
默认模板加载失败时，系统自动切换为空白工作簿。
用户选用的非默认模板加载异常，同样会替换为空白工作簿。

SpreadJS 中文文档