public class Workbook extends Object implements Storable
Workbook工作薄实例即表示一个Excel文件,它包含一个或多个Sheet工作表,
Workbook收集全局属性,如文档属性、样式,字符串共享区等。
在导出Excel文件时需要遵循以下三个步骤:
addSheet(org.ttzero.excel.entity.Sheet)添加Worksheet工作表(必须)writeTo(java.nio.file.Path)方法来执行写入操作(必须)当前仅支持xlsx(默认)和csv格式输出,保存为csv格式须在调用writeTo之前调用saveAsCSV()方法,
如果当前Workbook包含多个Worksheet则会生成多个csv文件并将多个文件压缩为zip格式。
常用的属性包含setCreator(java.lang.String)设置作者, setCompany(java.lang.String)设置公司名,
setAutoSize(boolean)设置自适应列宽和setZebraLine(org.ttzero.excel.entity.style.Fill)设置斑马线,
前两种需要打开文件详细属性查看,后两种起美化作用有利于阅读,后两个属性可以设置到Workbook或各Worksheet中,
如果设置到Workbook则会应用于所有Worksheet,当Workbook和Worksheet均设置了同一属性则Worksheet优先。
writeTo(java.nio.file.Path)方法是一个终止符它将执行实际的写操作,所以需要将该方法放在所有语句之后,
任何放置在该方法之后的指令将会被忽略。
本工具将数据源和输出协议分开设计,工作表Sheet为数据源,IWorkbookWriter和IWorksheetWriter
为输出协议,实现不同的输出协议即实现不同格式化输出,已实现的XMLWorksheetWriter和
CSVWorksheetWriter就是xlsx和csv格式的输出协议实现。
工作薄Workbook对应的输出协议为IWorkbookWriter,它负责协调所有部件输出并将所有零散的文件组装为OpenXml格式。
一个典型的导出示例:
new Workbook("双11销量统计")
// 设置作者
.setCreator("作者")
// 设置自适应列宽
.setAutoSize(true)
// 添加一个名为"总销量排行"的Worksheet
.addSheet(new ListSheet<Item>("总销量排行")
.setData(new ArrayList<>())) // <- 这里替换为实际数据
// 添加一个名为"单品销量排行"的Worksheet
.addSheet(new ListMapSheet<>("单品销量排行")
.setData(new ArrayList<>())) // <- 这里替换为实际数据
// 指定输出路径 '/tmp/"双11销量统计".xlsx'
.writeTo(Paths.get("/tmp/"));
参考文档:
| 构造器和说明 |
|---|
Workbook()
创建一个未命名工作薄
如果writeTo方法指定的File或Path为文件夹时,未命名工作薄将会以'新建文件'作为文件名
|
Workbook(String name)
创建一个工作薄并指定名称
|
Workbook(String name,
String creator)
创建一个工作薄并指定名称和作者
|
| 限定符和类型 | 方法和说明 |
|---|---|
Workbook |
addContentType(ContentType.Type type)
添加资源类型,导出图片时按照图片格式添加不同的资源类型,一般情况下开发者不需要关心
|
Workbook |
addContentTypeRel(Relationship rel)
添加ContentType关系,一般情况下开发者不需要关心
|
Workbook |
addSheet(Sheet sheet)
添加一个工作表
Sheet,新添加的工作表总是排在队列最后,
可以使用insertSheet(int, org.ttzero.excel.entity.Sheet)插入到指定位置 |
Workbook |
bestSpeed()
将压缩等级设为
1以获取更快的速度 |
Workbook |
cancelZebraLine()
取消斑马线
|
protected void |
checkAndInitWriter()
检查并创建工作薄协议
IWorkbookWriter |
Workbook |
defaultZebraLine()
指定以默认斑马线输出,默认背景颜色为
#EFF5EB |
Workbook |
forceExport()
强制导出
注意:设置此标记后将无视安全规则导出Java对象中的所有字段,请根据实际情况谨慎使用
|
String |
getCompany()
获取当前工作薄公司名
|
int |
getCompressionLevel()
获取压缩等级
|
ContentType |
getContentType()
获取全局的资源类型,一般情况下开发者不需要关心
|
Core |
getCore()
获取文档属性,包含主题,关键词,分类等信息
|
String |
getCreator()
获取当前工作薄作者
|
CustomProperties |
getCustomProperties()
获取自定义属性类
|
int |
getDrawingCounter()
获取当前工作薄包含多少张图片
|
int |
getForceExport()
获取当前工作薄是否为“强制导出”
|
int |
getMediaCounter()
获取当前工作薄含有多媒体的工作表个数
|
String |
getName()
获取当前工作薄名称
|
BiConsumer<Sheet,Integer> |
getProgressConsumer()
获取进度监听器
|
SharedStrings |
getSharedStrings()
获取全局字符串共享区,此共享区独立于Worksheet,所有worksheet共享
|
Sheet |
getSheet(String sheetName)
返回指定名称的工作表
Sheet
注意:只能查找那些在创建时设置了名称的工作表 |
Sheet |
getSheetAt(int index)
获取指定位置的工作表
如果使用
insertSheet(int, org.ttzero.excel.entity.Sheet)方法插入了一个较大的下标,调用此方法可能返回null值。 |
Sheet[] |
getSheets()
获取所有
Sheet集合
注意:返回的对象是一个浅拷贝对其做任何修改将影响最终效果 |
int |
getSize()
获取当前工作薄包含的工作表个数
|
Styles |
getStyles()
获取全局样式
Styles |
Watermark |
getWatermark()
获取水印
Watermark |
Watermark |
getWaterMark()
已过时。
重命名为
getWatermark() |
IWorkbookWriter |
getWorkbookWriter()
获取工作薄输出协议
IWorkbookWriter |
Fill |
getZebraFill()
获取斑马线背景样式
|
boolean |
hasZebraFill()
判断当前工作薄是否设置了全局斑马线背景
|
int |
incrementDrawingCounter()
图片记数器自增
|
int |
incrementMediaCounter()
媒体记数器,一般情况下media与worksheet对应
|
Workbook |
insertSheet(int index,
Sheet sheet)
在指定下标插入一个工作表
Sheet |
boolean |
isAutoSize()
获取当前工作薄是否为自适应宽度
|
Workbook |
markAsReadOnly()
文档保护-标记只读
|
Workbook |
onProgress(BiConsumer<Sheet,Integer> progressConsumer)
添加一个进度监听器,可以在较大导出时展示进度
new Workbook().onProgress((sheet, row) -> {
System.out.println(sheet + " write " + row + " rows");
})
|
Workbook |
putCustomProperties(Map<String,Object> properties)
添加自定义属性,自定义属性可以从"信息"->"属性"->"自定义属性"查看
注意:只支持
"文本"、"数字"、"日期"以及"布尔值",其它数据类型将使用toString强转换为文本 |
Workbook |
putCustomProperty(String key,
Object value)
添加自定义属性,自定义属性可以从"信息"->"属性"->"自定义属性"查看
注意:只支持
"文本"、"数字"、"日期"以及"布尔值",其它数据类型将使用toString强转换为文本 |
Workbook |
remove(int index)
移除指定位置的工作表
Sheet |
Object |
removeCustomProperty(String key)
删除自定义属性
|
Workbook |
saveAsCSV()
另存为Comma-Separated Values格式,默认使用','逗号分隔
|
Workbook |
saveAsCSV(Charset charset)
以指定字符集保存为Comma-Separated Values格式,默认使用','逗号分隔
|
Workbook |
saveAsCSVWithBom()
另存为Comma-Separated Values格式并保存BOM,默认使用','逗号分隔
|
Workbook |
saveAsCSVWithBom(Charset charset)
以指定字符集保存为Comma-Separated Values格式并保存BOM,默认使用','逗号分隔
|
Workbook |
setAutoSize(boolean autoSize)
设置全局自适应列宽
|
Workbook |
setCompany(String company)
设置公司名,建议控制在64个字符以内
|
Workbook |
setCore(Core core)
设置文档属性,包含主题,关键词,分类等信息
|
Workbook |
setCreator(String creator)
设置作者
设置作者后可以通过查看文件属性来查看作者
|
Workbook |
setName(String name)
设置工作薄名称,如果writeTo方法指定的Path或File为文件夹时该名称将作为最终文件名
|
Workbook |
setStyles(Styles styles)
设置全局样式
Styles |
Workbook |
setWatermark(Watermark watermark)
设置水印
Watermark,可以使用Watermark.of(java.lang.String)静态方法创建 |
Workbook |
setWaterMark(Watermark watermark)
已过时。
|
Workbook |
setWorkbookWriter(IWorkbookWriter workbookWriter)
设置自定义工作薄输出协议
|
Workbook |
setZebraLine(Fill fill)
设置斑马线背景,斑马线是由相同间隔的背景色造成的视觉效果,有助于从视觉上区分每行数据,
但刺眼的背景色可能造成相反的效果,设置之前最好在Office中提前预览效果
|
void |
writeTo(File file)
指定输出路径,File可以是文件夹或者文件
如果File为文件夹时将在该文件夹下生成名为
getName() + IWorkbookWriter.getSuffix()的文件,
文件后缀随输出协议变动。 |
void |
writeTo(OutputStream os)
导出到
OutputStream流,适用于小文件Excel直接导出的场景
public void export(HttpServletResponse response) throws IOException {
String fileName = java.net.URLEncoder.encode("abc.xlsx", "UTF-8");
response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\""
+ fileName + "\"; filename*=utf-8''" + fileName);
new Workbook()
.addSheet(new ListSheet<Item>("总销量排行", new ArrayList<>()))
// 直接写到Response
.writeTo(response.getOutputStream());
} |
void |
writeTo(Path path)
指定输出路径,Path可以是文件夹或者文件
如果Path为文件夹时将在该文件夹下生成名为
getName() + IWorkbookWriter.getSuffix()的文件,
文件后缀随输出协议变动。 |
public Workbook()
如果writeTo方法指定的File或Path为文件夹时,未命名工作薄将会以'新建文件'作为文件名
public Workbook(String name)
name - 工作薄名public String getName()
public Workbook setName(String name)
name - 工作薄名,长度最好不超过255个字符public String getCreator()
public String getCompany()
public int getSize()
public Core getCore()
public SharedStrings getSharedStrings()
SharedStringspublic Workbook setWatermark(Watermark watermark)
Watermark,可以使用Watermark.of(java.lang.String)静态方法创建watermark - 水印@Deprecated public Watermark getWaterMark()
getWatermark()Watermark@Deprecated public Workbook setWaterMark(Watermark watermark)
setWatermark(Watermark)Watermark,可以使用Watermark.of(java.lang.String)静态方法创建watermark - 水印public Workbook setAutoSize(boolean autoSize)
autoSize - true: 自适应宽度,false:固定宽度(默认)public boolean isAutoSize()
public Workbook forceExport()
注意:设置此标记后将无视安全规则导出Java对象中的所有字段,请根据实际情况谨慎使用
public int getForceExport()
public Workbook setCreator(String creator)
设置作者后可以通过查看文件属性来查看作者
creator - 作者public Workbook setCompany(String company)
company - 公司名public Workbook setZebraLine(Fill fill)
fill - 背景样式Fillpublic Workbook cancelZebraLine()
public Workbook defaultZebraLine()
#EFF5EBpublic boolean hasZebraFill()
public IWorkbookWriter getWorkbookWriter()
IWorkbookWriterpublic Workbook addSheet(Sheet sheet)
Sheet,新添加的工作表总是排在队列最后,
可以使用insertSheet(int, org.ttzero.excel.entity.Sheet)插入到指定位置sheet - 工作表public Workbook insertSheet(int index, Sheet sheet)
Sheetindex - 指定工作表插入的位置(从0开始)sheet - 待插入的工作表public Sheet getSheetAt(int index)
如果使用insertSheet(int, org.ttzero.excel.entity.Sheet)方法插入了一个较大的下标,调用此方法可能返回null值。
例如在下标为100的位置插入了一个工作表,获取第90位的工作薄将返回一个null值。
index - 工作表在队列中的位置(从0开始)SheetIndexOutOfBoundsException - 如果下标为负数或者超过工作薄队列长度public Sheet getSheet(String sheetName)
Sheet
注意:只能查找那些在创建时设置了名称的工作表
sheetName - 待查找的工作表名称public Workbook onProgress(BiConsumer<Sheet,Integer> progressConsumer)
new Workbook().onProgress((sheet, row) -> {
System.out.println(sheet + " write " + row + " rows");
})progressConsumer - 进度监听器public BiConsumer<Sheet,Integer> getProgressConsumer()
public Workbook saveAsCSV()
public Workbook saveAsCSVWithBom()
public Workbook saveAsCSV(Charset charset)
charset - 指定输出字符集public Workbook saveAsCSVWithBom(Charset charset)
charset - 指定输出字符集public void writeTo(Path path) throws IOException
如果Path为文件夹时将在该文件夹下生成名为getName() + IWorkbookWriter.getSuffix()的文件,
文件后缀随输出协议变动。如果存在相同的文件名则会在文件名后面添加'(n)',n为自增的数字,例已存在"abc.xlsx",
再次导出时将保存为"abc(1).xlsx"。如果Path为明确的文件绝对路径,那将保存在Path的绝对路径下,已存在相同文件时会覆盖原文件,
需要注意覆盖失败的情况
writeTo 在接口中 Storablepath - Excel保存位置IOException - I/O操作异常public void writeTo(OutputStream os) throws IOException, ExcelWriteException
OutputStream流,适用于小文件Excel直接导出的场景
public void export(HttpServletResponse response) throws IOException {
String fileName = java.net.URLEncoder.encode("abc.xlsx", "UTF-8");
response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\""
+ fileName + "\"; filename*=utf-8''" + fileName);
new Workbook()
.addSheet(new ListSheet<Item>("总销量排行", new ArrayList<>()))
// 直接写到Response
.writeTo(response.getOutputStream());
}os - 输出流IOException - I/O操作异常ExcelWriteException - 其它运行时异常public void writeTo(File file) throws IOException
如果File为文件夹时将在该文件夹下生成名为getName() + IWorkbookWriter.getSuffix()的文件,
文件后缀随输出协议变动。如果存在相同的文件名则会在文件名后面添加'(n)',n为自增的数字,例已存在"abc.xlsx",
再次导出时将保存为"abc(1).xlsx"。如果File为明确的文件绝对路径,那将保存在File的绝对路径下,已存在相同文件时会覆盖原文件,
需要注意覆盖失败的情况
file - Excel保存位置IOException - I/O操作异常public Workbook setWorkbookWriter(IWorkbookWriter workbookWriter)
workbookWriter - 自定义工作薄IWorkbookWriter协议protected void checkAndInitWriter()
IWorkbookWriterpublic Workbook addContentType(ContentType.Type type)
type - 资源类型ContentType.Typepublic Workbook addContentTypeRel(Relationship rel)
rel - Relationship关系public ContentType getContentType()
ContentType对象public int incrementDrawingCounter()
public int getDrawingCounter()
public int incrementMediaCounter()
public int getMediaCounter()
public Workbook putCustomProperty(String key, Object value)
注意:只支持"文本"、"数字"、"日期"以及"布尔值",其它数据类型将使用toString强转换为文本
key - 属性名,不超过256个字符value - 属性值,public Workbook putCustomProperties(Map<String,Object> properties)
注意:只支持"文本"、"数字"、"日期"以及"布尔值",其它数据类型将使用toString强转换为文本
properties - 批量属性public Object removeCustomProperty(String key)
key - 指定属性名nullpublic CustomProperties getCustomProperties()
Custom自定义属性类public Workbook markAsReadOnly()
public Workbook bestSpeed()
1以获取更快的速度public int getCompressionLevel()
Copyright © 2025. All rights reserved.