diff --git a/fesod/src/main/java/org/apache/fesod/sheet/annotation/ExcelProperty.java b/fesod/src/main/java/org/apache/fesod/sheet/annotation/ExcelProperty.java index aec91359a..9f9d058c9 100644 --- a/fesod/src/main/java/org/apache/fesod/sheet/annotation/ExcelProperty.java +++ b/fesod/src/main/java/org/apache/fesod/sheet/annotation/ExcelProperty.java @@ -24,7 +24,6 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; -import org.apache.fesod.sheet.annotation.format.DateTimeFormat; import org.apache.fesod.sheet.converters.AutoConverter; import org.apache.fesod.sheet.converters.Converter; @@ -74,14 +73,4 @@ * @return Converter */ Class> converter() default AutoConverter.class; - - /** - * - * default @see org.apache.fesod.sheet.util.TypeUtil if default is not meet you can set format - * - * @return Format string - * @deprecated please use {@link DateTimeFormat} - */ - @Deprecated - String format() default ""; } diff --git a/fesod/src/test/java/org/apache/fesod/sheet/annotation/ExcelPropertyFormatTest.java b/fesod/src/test/java/org/apache/fesod/sheet/annotation/ExcelPropertyFormatTest.java new file mode 100644 index 000000000..26e9b4350 --- /dev/null +++ b/fesod/src/test/java/org/apache/fesod/sheet/annotation/ExcelPropertyFormatTest.java @@ -0,0 +1,201 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +package org.apache.fesod.sheet.annotation; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import java.io.FileInputStream; +import java.io.IOException; +import java.nio.file.Path; +import java.time.LocalDate; +import java.time.LocalDateTime; +import java.util.ArrayList; +import java.util.Collections; +import java.util.Date; +import java.util.LinkedList; +import java.util.List; +import lombok.Data; +import org.apache.fesod.sheet.FastExcel; +import org.apache.fesod.sheet.annotation.format.DateTimeFormat; +import org.apache.fesod.sheet.context.AnalysisContext; +import org.apache.fesod.sheet.read.listener.ReadListener; +import org.apache.fesod.sheet.util.StringUtils; +import org.apache.poi.ss.usermodel.Row; +import org.apache.poi.xssf.usermodel.XSSFWorkbook; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +public class ExcelPropertyFormatTest { + + @Data + static class FormatSample { + @ExcelProperty() + @DateTimeFormat("yyyy-MMM-dd") + private Date date2; + + @ExcelProperty() + @DateTimeFormat("yyyy-MMM-dd") + private LocalDate dateLocalDate2; + } + + @Test + public void testSingleFormatSampleWriteAndRead(@TempDir Path tempDir) throws IOException { + List singleElementList = new LinkedList<>(); + FormatSample sample = new FormatSample(); + sample.setDate2(new Date()); + sample.setDateLocalDate2(LocalDate.of(2025, 2, 1)); + singleElementList.add(sample); + String fileName = + tempDir.resolve(System.currentTimeMillis() + "_single.xlsx").toString(); + FastExcel.write(fileName, FormatSample.class).sheet("UnitTest").doWrite(singleElementList); + try (FileInputStream fis = new FileInputStream(fileName); + XSSFWorkbook workbook = new XSSFWorkbook(fis)) { + Row dataRow = workbook.getSheetAt(0).getRow(1); + assertEquals("yyyy-MMM-dd", dataRow.getCell(0).getCellStyle().getDataFormatString()); + assertEquals("yyyy-MMM-dd", dataRow.getCell(1).getCellStyle().getDataFormatString()); + } + } + + /** + * Test cell format string after writing date format pattern with Chinese characters. + */ + @Data + static class ChinesePatternSample { + @ExcelProperty + @DateTimeFormat("yyyy年MM月dd日HH时mm分ss秒") + private Date fullDate; + + @ExcelProperty + @DateTimeFormat("yyyy年MM月dd日") + private LocalDate localDate; + } + + @Test + public void testChinesePatternFormat(@TempDir Path tempDir) throws IOException { + ChinesePatternSample sample = new ChinesePatternSample(); + sample.setFullDate(new Date()); + sample.setLocalDate(LocalDate.of(2025, 1, 2)); + String fileName = tempDir.resolve("chinese_pattern.xlsx").toString(); + FastExcel.write(fileName, ChinesePatternSample.class) + .sheet("ChineseFormat") + .doWrite(Collections.singletonList(sample)); + try (FileInputStream fis = new FileInputStream(fileName); + XSSFWorkbook workbook = new XSSFWorkbook(fis)) { + Row dataRow = workbook.getSheetAt(0).getRow(1); + assertEquals( + "yyyy年MM月dd日HH时mm分ss秒", dataRow.getCell(0).getCellStyle().getDataFormatString()); + assertEquals("yyyy年MM月dd日", dataRow.getCell(1).getCellStyle().getDataFormatString()); + } + } + + /** + * Test different fields with different formats. + */ + @Data + static class MultiPatternSample { + @ExcelProperty + @DateTimeFormat("yyyy/MM/dd") + private Date dateSlash; + + @ExcelProperty + @DateTimeFormat("dd-MM-yyyy") + private LocalDate dateDash; + + @ExcelProperty + @DateTimeFormat("yyyy-MM-dd HH:mm") + private LocalDateTime dateTimeMinute; + } + + @Test + public void testMultiplePatternsPerRow(@TempDir Path tempDir) throws IOException { + MultiPatternSample s = new MultiPatternSample(); + s.setDateSlash(new Date()); + s.setDateDash(LocalDate.of(2024, 12, 31)); + s.setDateTimeMinute(LocalDateTime.of(2025, 3, 4, 15, 20)); + String file = tempDir.resolve("multi_pattern.xlsx").toString(); + FastExcel.write(file, MultiPatternSample.class).sheet("MultiFormat").doWrite(Collections.singletonList(s)); + try (FileInputStream fis = new FileInputStream(file); + XSSFWorkbook workbook = new XSSFWorkbook(fis)) { + Row row = workbook.getSheetAt(0).getRow(1); + assertEquals("yyyy/MM/dd", row.getCell(0).getCellStyle().getDataFormatString()); + assertEquals("dd-MM-yyyy", row.getCell(1).getCellStyle().getDataFormatString()); + assertEquals("yyyy-MM-dd HH:mm", row.getCell(2).getCellStyle().getDataFormatString()); + } + } + + /** + * Write Date with pattern, read to String field with annotation pattern, verify the read string matches the formatted value. + */ + @Data + static class WriteDateModel { + @ExcelProperty + @DateTimeFormat("yyyy-MM-dd HH:mm:ss") + private Date eventTime; + } + + @Data + static class ReadStringModel { + @ExcelProperty + @DateTimeFormat("yyyy-MM-dd HH:mm:ss") + private String eventTime; // Should be formatted as string when reading + } + + static class CapturingListener implements ReadListener { + private final List list = new ArrayList<>(); + + @Override + public void invoke(ReadStringModel data, AnalysisContext context) { + list.add(data); + } + + @Override + public void doAfterAllAnalysed(AnalysisContext context) {} + + List getList() { + return list; + } + } + + /** + * Test null date field: should write blank cell and not throw exception if value is not set. + */ + @Data + static class NullDateSample { + @ExcelProperty + @DateTimeFormat("yyyy-MM-dd") + private Date mayBeNull; + } + + @Test + public void testNullDateFieldWritesBlank(@TempDir Path tempDir) throws IOException { + NullDateSample sample = new NullDateSample(); + String file = tempDir.resolve("null_date.xlsx").toString(); + FastExcel.write(file, NullDateSample.class).sheet("Null").doWrite(Collections.singletonList(sample)); + try (FileInputStream fis = new FileInputStream(file); + XSSFWorkbook workbook = new XSSFWorkbook(fis)) { + Row row = workbook.getSheetAt(0).getRow(1); + assertNotNull(row, "expect row existing"); + assertTrue( + StringUtils.isBlank(row.getCell(0).getStringCellValue()), + "Empty date field should write as blank cell"); + } + } +} diff --git a/website/docs/help/large-data.md b/website/docs/help/large-data.md deleted file mode 100644 index 15b6aa0d8..000000000 --- a/website/docs/help/large-data.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: 'large-data' -title: 'Large Data' ---- - -# Big Data Files - -## Reading - -### Overview - -When reading files larger than 10 MB, Excel 03 is unable to handle them and consumes significantly more memory. Excel 2007 introduces the concept of [Shared Strings](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/working-with-the-shared-string-table), which can consume a significant amount of memory. -If all shared strings are loaded into memory, the memory usage can be approximately 3 to 10 times the size of the Excel file. Therefore, FastExcel uses a strategy of first storing the file and then deserialising it to read the data, thereby saving memory. Of course, after deserialising the file, efficiency will decrease by approximately 30-50% (this is not fixed and depends on the hit rate, which may exceed 100%). - -If the read efficiency is acceptable, use the default setting. The permanent memory usage (for the entire process of reading a single Excel file) generally does not exceed 50MB (most likely around 30MB), and the remaining temporary memory is quickly recycled by the garbage collector. - -### Default Policy - -By default, large file processing is automatically determined. Shared strings under 5M are stored in memory, which occupies approximately 15-50M of memory. Strings over 5M are stored in files, and file storage also requires additional memory to store temporary shared strings, with a default of 20M. Apart from the memory used by shared strings, other memory usage is minimal, so it can be estimated at 10MB. Therefore, the default of approximately 30MB is sufficient to read an extremely large file. - -### Configure Memory - -If you want to customise the settings, first determine how much memory you are willing to allocate for reading a very large Excel file. -For example, if you want the Excel file to occupy a maximum of 100MB of memory during the reading process (this is the permanent memory usage during reading, not including memory immediately reclaimed by the young generation), then set the size of the shared string stored in the file to 20MB (less than 20MB is stored in memory, more than 20MB is stored in a temporary file), and then set the memory size occupied by the temporary shared string when stored in the file to approximately 90MB. - -If the maximum number of file entries is only a few hundred thousand, and the Excel file is only a few dozen megabytes, and there is no high concurrency, and memory is sufficient, - -```java -// Force memory storage, so a 20M Excel file will use 150M of memory (many temporary objects, so 100M will be constantly GC'd). -// This will be much more efficient than the complex strategy above. -// Just to clarify, all I did was add the readCache(new MapCache()) parameter. For the rest, refer to other examples. -FastExcel.read().readCache(new MapCache()); -``` - -High concurrency requirements, and often involve extremely large files. - -```java -// The first parameter specifies how many MB of shared string data will be stored in the file (default is 5 MB). -// The second parameter specifies how many MB of cache data will be stored in memory when using file storage (default is 20 MB). -// For example, if you want to use 100 MB of memory (this refers to permanent memory usage during parsing, excluding temporary objects) to parse an Excel file, the calculation shows it to be approximately 20 MB + 90 MB, so set the parameters to: 20 and 90. -// Here's a clarification: the only addition is the readCacheSelector(new SimpleReadCacheSelector(5, 20)) parameter; the rest follows the examples provided. -FastExcel.read().readCacheSelector(new SimpleReadCacheSelector(5, 20)); -``` - -### About maxCacheActivateSize - -When using file storage, FastExcel splits the shared string into batches of **1000** items and then stores them in file storage. Excel typically reads shared strings in sequential order, so by default, 1000 entries (approximately 20MB) are kept in memory. If a match is found, the data is returned directly; if not, the file is read. Therefore, the size should not be set too small, as this makes it difficult to find a match and results in constant file reads. Conversely, setting it too large can consume excessive memory. - -To determine whether `maxCacheActivateSize` needs adjustment, enabling `debug` logs will output `Already put :4000000` as the last value, which can be estimated to be 4 million. Then, checking `Cache misses count:4001` yields a value of 4,000. `4 million / 4,000 = 1,000` indicates that `maxCacheActivateSize` is already very reasonable. If the value is less than 500, there is a significant issue. Values between 500 and 1000 should be acceptable. diff --git a/website/docs/introduce.md b/website/docs/introduce.md index 17045f33f..c4d2788a8 100644 --- a/website/docs/introduce.md +++ b/website/docs/introduce.md @@ -8,12 +8,13 @@ slug: / ## Introduction -**Apache Fesod (Incubating)** is a high-performance and memory-efficient Java library for reading and writing Excel +**Apache Fesod (Incubating)** is a high-performance and memory-efficient Java library for reading and writing +spreadsheet files, designed to simplify development and ensure reliability. Apache Fesod (Incubating) can provide developers and enterprises with great freedom and flexibility. We plan to introduce more new features in the future to continually enhance user experience and tool usability. Apache Fesod ( -Incubating) is committed to being your best choice for handling Excel files. +Incubating) is committed to being your best choice for handling spreadsheet files. The name fesod(pronounced `/ˈfɛsɒd/`), an acronym for "fast easy spreadsheet and other documents" expresses the project's origin, background and vision. @@ -21,10 +22,11 @@ project's origin, background and vision. ### Features - **High-performance Reading and Writing**: Apache Fesod (Incubating) focuses on performance optimization, capable of - efficiently handling large-scale Excel data. Compared to some traditional Excel processing libraries, it can + efficiently handling large-scale spreadsheet data. Compared to some traditional spreadsheet processing libraries, it + can significantly reduce memory consumption. - **Simplicity and Ease of Use**: The library offers a simple and intuitive API, allowing developers to easily integrate - it into projects, whether for simple Excel operations or complex data processing. + it into projects, whether for simple spreadsheet operations or complex data processing. - **Stream Operations**: Apache Fesod (Incubating) supports stream reading, minimizing the problem of loading large amounts of data at once. This design is especially important when dealing with hundreds of thousands or even millions of rows of data. @@ -33,7 +35,7 @@ project's origin, background and vision. ### Read -Below is an example of reading an Excel document: +Below is an example of reading a spreadsheet document: ```java // Implement the ReadListener interface to set up operations for reading data @@ -51,14 +53,14 @@ public class DemoDataListener implements ReadListener { public static void main(String[] args) { String fileName = "demo.xlsx"; - // Read Excel file - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); + // Read file + Fesod.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); } ``` ### Write -Below is a simple example of creating an Excel document: +Below is a simple example of creating a spreadsheet document: ```java // Sample data class @@ -89,6 +91,6 @@ private static List data() { public static void main(String[] args) { String fileName = "demo.xlsx"; // Create a "Template" sheet and write data - FastExcel.write(fileName, DemoData.class).sheet("Template").doWrite(data()); + FesodSheet.write(fileName, DemoData.class).sheet("Template").doWrite(data()); } ``` diff --git a/website/docs/quickstart/example.md b/website/docs/quickstart/example.md index a6cac63c9..171ef7640 100644 --- a/website/docs/quickstart/example.md +++ b/website/docs/quickstart/example.md @@ -3,11 +3,11 @@ id: 'simple-example' title: 'Simple example' --- -# Simple example +## Fesod Sheet Examples -## Read +### Read the spreadsheet -Below is an example of reading an Excel document: +Below is an example of reading a spreadsheet document: ```java // Implement the ReadListener interface to set up operations for reading data @@ -25,14 +25,14 @@ public class DemoDataListener implements ReadListener { public static void main(String[] args) { String fileName = "demo.xlsx"; - // Read Excel file - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); + // Read file + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); } ``` -### Write +### Write the spreadsheet -Below is a simple example of creating an Excel document: +Below is a simple example of creating a spreadsheet document: ```java // Sample data class @@ -63,6 +63,6 @@ private static List data() { public static void main(String[] args) { String fileName = "demo.xlsx"; // Create a "Template" sheet and write data - FastExcel.write(fileName, DemoData.class).sheet("Template").doWrite(data()); + FesodSheet.write(fileName, DemoData.class).sheet("Template").doWrite(data()); } ``` diff --git a/website/docs/quickstart/guide.md b/website/docs/quickstart/guide.md index 249d975fa..8e394ceff 100644 --- a/website/docs/quickstart/guide.md +++ b/website/docs/quickstart/guide.md @@ -7,7 +7,7 @@ title: 'Guide' ## Compatibility Information -The following table lists the minimum Java language version requirements for each version of the FastExcel library: +The following table lists the minimum Java language version requirements for each version of the Fesod library: | Version | JDK Version Support Range | Notes | |---------|---------------------------|-------| @@ -16,17 +16,17 @@ The following table lists the minimum Java language version requirements for eac | 1.1.x | JDK8 - JDK21 | | | 1.0.x | JDK8 - JDK21 | | -We strongly recommend using the latest version of FastExcel, as performance optimizations, bug fixes, and new features +We strongly recommend using the latest version of Fesod, as performance optimizations, bug fixes, and new features in the latest version will enhance your experience. -> Currently, FastExcel uses POI as its underlying package. If your project already includes POI-related components, you +> Currently, Fesod uses POI as its underlying package. If your project already includes POI-related components, you > will need to manually exclude POI-related jar files. ## Version Update For detailed update logs, refer -to [Details of version updates](https://github.com/fast-excel/fastexcel/blob/main/CHANGELOG.md). You can also find all -available versions in the [Maven Central Repository](https://mvnrepository.com/artifact/cn.idev.excel/fastexcel). +to [Details of version updates](https://github.com/apache/fesod/releases). You can also find all +available versions in the [Maven Central Repository](https://mvnrepository.com/artifact/org.apache.fesod/fesod). ## Maven @@ -35,8 +35,8 @@ If you are using Maven for project building, add the following configuration in ```xml - cn.idev.excel - fastexcel + org.apache.fesod + fesod version ``` @@ -47,6 +47,6 @@ If you are using Gradle for project building, add the following configuration in ```gradle dependencies { - implementation 'cn.idev.excel:fastexcel:version' + implementation 'org.apache.fesod:fesod:version' } ``` diff --git a/website/docs/read/csv.md b/website/docs/read/csv.md deleted file mode 100644 index 08b65ada2..000000000 --- a/website/docs/read/csv.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: 'csv' -title: 'CSV' ---- - -# Reading CSV Files - -This chapter introduces how to use FastExcel to read custom CSV files. - -## Overview - -FastExcel reads CSV files through different parameter configurations. It uses [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) as the underlying implementation and also supports direct configuration through [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) settings to achieve reading objectives. - -The main parameters are as follows: - -| Name | Default Value | Description | -| :--- | :--- | :--- | -| `delimiter` | `,` (comma) | Field delimiter. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.AT`(`@`), `CsvConstant.TAB`, etc. | -| `quote` | `"` (double quote) | Field quote character. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.DOUBLE_QUOTE`(`"`). | -| `recordSeparator` | `CRLF` | Record (line) separator. Varies by operating system, such as `CsvConstant.CRLF`(Windows) or `CsvConstant.LF`(Unix/Linux). | -| `nullString` | `null` | String used to represent `null` values. Note this is different from an empty string `""`. | -| `escape` | `null` | Escape character used to escape quote characters themselves. | - ---- - -## Parameter Details and Examples - -The following sections will explain each parameter in detail with code examples. - -### delimiter - -`delimiter` specifies the field separator in CSV files. The default value is a comma `,`. -Additionally, FastExcel provides constants in `CsvConstant` to simplify usage. - -#### Code Example - -If the CSV file uses `\u0000` as the separator, you can configure it as follows: - -```java -@Test -public void delimiterDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .delimiter(CsvConstant.UNICODE_EMPTY) - .doReadSync(); -} -``` - -### quote - -`quote` specifies the quote character that wraps fields. The default value is double quote `"`. -This should be set when field content contains delimiters or line breaks. - -> Note: This cannot be the same as the `recordSeparator` setting. It's recommended to use in combination with `QuoteMode`. - -#### Code Example - -```java -@Test -public void quoteDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .quote(CsvConstant.DOUBLE_QUOTE, QuoteMode.MINIMAL) - .doReadSync(); -} -``` - -### recordSeparator - -`recordSeparator` specifies the line separator in the file. Different operating systems may use different line separators (for example, Windows uses `CRLF`, while Unix/Linux uses `LF`). - -#### Code Example - -```java -@Test -public void recordSeparatorDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .recordSeparator(CsvConstant.LF) - .doReadSync(); -} -``` - -### nullString - -`nullString` defines a specific string in the file that represents `null` values. For example, you can parse the string `"N/A"` as a `null` object. - -#### Code Example - -```java -@Test -public void nullStringDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .nullString("N/A") - .doReadSync(); -} -``` - -### escape - -`escape` specifies an escape character that can be used when quote characters (`quote`) appear within field values. - -#### Code Example - -```java -@Test -public void escapeDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .escape(CsvConstant.BACKSLASH) - .doReadSync(); -} -``` - -## CSVFormat Configuration Details and Examples - -Supports directly building a `CSVFormat` object. -> FastExcel currently still supports this approach, but it's not the most recommended usage method. - -### Code Example - -```java -@Test -public void csvFormatDemo() { - - CSVFormat csvFormat = CSVFormat.DEFAULT.builder().setDelimiter(CsvConstant.AT).build(); - String csvFile = "path/to/your.csv"; - - try (ExcelReader excelReader = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()).build()) { - ReadWorkbookHolder readWorkbookHolder = excelReader.analysisContext().readWorkbookHolder(); - // Check if it's an instance of CsvReadWorkbookHolder - if (readWorkbookHolder instanceof CsvReadWorkbookHolder) { - CsvReadWorkbookHolder csvReadWorkbookHolder = (CsvReadWorkbookHolder) readWorkbookHolder; - csvReadWorkbookHolder.setCsvFormat(csvFormat); - } - - ReadSheet readSheet = FastExcel.readSheet(0).build(); - excelReader.read(readSheet); - } -} -``` diff --git a/website/docs/read/num-rows.md b/website/docs/read/num-rows.md deleted file mode 100644 index 470534211..000000000 --- a/website/docs/read/num-rows.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: 'num-rows' -title: 'Rows' ---- - -# Reading Rows - -This chapter introduces how to read a specified number of rows. - -## Overview - -During data analysis and processing, quickly viewing the first few rows of an Excel file can help us better understand the data structure and content. -By default, FastExcel reads all data from the entire Excel file. -However, by setting the `numRows` parameter, you can limit the number of rows to read. 0 means no limit on the number of rows, i.e., read all rows. The row count includes header rows. - -## All Sheets - -### Code Example - -```java -@Test -public void allSheetRead() { - // Read the first 100 rows - FastExcel.read(fileName, DemoData.class, new PageReadListener(dataList -> { - for (DemoData demoData : dataList) { - log.info("Read one record: {}", JSON.toJSONString(demoData)); - } - })).numRows(100).sheet().doRead(); -} -``` - ---- - -## Single Sheet - -### Code Example - -```java -@Test -public void singleSheetRead() { - try (ExcelReader excelReader = FastExcel.read(fileName, DemoData.class, new DemoDataListener()).build()) { - ReadSheet readSheet = FastExcel.readSheet(0).build(); - readSheet.setNumRows(100); // Read the first 100 rows - excelReader.read(readSheet); - } -} -``` diff --git a/website/docs/read/sheet.md b/website/docs/read/sheet.md deleted file mode 100644 index ba47a2343..000000000 --- a/website/docs/read/sheet.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: 'sheet' -title: 'Sheet' ---- - -# Sheet - -This chapter introduces how to configure Sheets to read data. - -## Reading Multiple Sheets - -### Overview - -You can read multiple Sheets from an Excel file, but the same Sheet cannot be read repeatedly. - -### Code Example - -#### Reading All Sheets - -```java -@Test -public void readAllSheet() { - String fileName = "path/to/demo.xlsx"; - - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).doReadAll(); -} -``` - ---- - -## Reading Specific Sheets - -### Overview - -You can read a specific Sheet from an Excel file, supporting specification by Sheet index or name. - -> **Note:** Sheet names are limited to 31 characters in Excel. When reading sheets by name, use the actual sheet name that appears in the Excel file. - -### Code Example - -```java -@Test -public void readSingleSheet() { - String fileName = "path/to/demo.xlsx"; - - try (ExcelReader excelReader = FastExcel.read(fileName).build()) { - // Sheet index - ReadSheet sheet1 = FastExcel.readSheet(0).head(DemoData.class).registerReadListener(new DemoDataListener()).build(); - // Sheet name - ReadSheet sheet2 = FastExcel.readSheet("Sheet2").head(DemoData.class).registerReadListener(new DemoDataListener()).build(); - excelReader.read(sheet1, sheet2); - } -} -``` - ---- - -## Ignoring Hidden Sheets - -### Overview - -By setting the `ignoreHiddenSheet` parameter to true, data from Sheets in "hidden" state will not be read. -This supports both **"normal hidden"** and **"very hidden"** states. - -### Code Example - -```java -@Test -public void exceptionRead() { - String fileName = "path/to/demo.xlsx"; - - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .ignoreHiddenSheet(Boolean.TRUE) - .sheet() - .doRead(); -} -``` - -> In Microsoft Excel, Sheets have two hidden states: "normal hidden (xlSheetHidden)" and "very hidden (xlSheetVeryHidden)". Very hidden can be set through `VBA`, and in this case, the hidden Sheet cannot be unhidden through the "Unhide" operation. diff --git a/website/docs/fill/fill.md b/website/docs/sheet/fill/fill.md similarity index 74% rename from website/docs/fill/fill.md rename to website/docs/sheet/fill/fill.md index f0c6f08fa..a5f2ef14f 100644 --- a/website/docs/fill/fill.md +++ b/website/docs/sheet/fill/fill.md @@ -5,17 +5,18 @@ title: 'Fill' # Fill -This section explains how to use FastExcel to fill data into files. +This section explains how to use Fesod to fill data into files. ## Simple Fill ### Overview -Fill data into Excel based on a template file using objects or Map. +Fill data into spreadsheet based on a template file using objects or Map. ### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -29,6 +30,7 @@ public class FillData { ### Code Example ```java + @Test public void simpleFill() { String templateFileName = "path/to/simple.xlsx"; @@ -37,19 +39,19 @@ public void simpleFill() { FillData fillData = new FillData(); fillData.setName("张三"); fillData.setNumber(5.2); - FastExcel.write("simpleFill.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(fillData); + FesodSheet.write("simpleFill.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(fillData); // Approach 2: Fill based on Map Map map = new HashMap<>(); map.put("name", "张三"); map.put("number", 5.2); - FastExcel.write("simpleFillMap.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(map); + FesodSheet.write("simpleFillMap.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(map); } ``` @@ -72,19 +74,20 @@ Fill multiple data items into a template list, supporting in-memory batch operat ### Code Example ```java + @Test public void listFill() { String templateFileName = "path/to/list.xlsx"; // Approach 1: Fill all data at once - FastExcel.write("listFill.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(data()); + FesodSheet.write("listFill.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(data()); // Approach 2: Batch filling - try (ExcelWriter writer = FastExcel.write("listFillBatch.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("listFillBatch.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); writer.fill(data(), writeSheet); writer.fill(data(), writeSheet); } @@ -110,12 +113,13 @@ Fill various data types in a template, including lists and regular variables. ### Code Example ```java + @Test public void complexFill() { String templateFileName = "path/to/complex.xlsx"; - try (ExcelWriter writer = FastExcel.write("complexFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("complexFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // Fill list data, with forceNewRow enabled FillConfig config = FillConfig.builder().forceNewRow(true).build(); @@ -144,17 +148,19 @@ public void complexFill() { ### Overview -Optimize performance for filling large data, ensuring the template list is at the last row, and subsequent data is filled using `WriteTable`. +Optimize performance for filling large data, ensuring the template list is at the last row, and subsequent data is +filled using `WriteTable`. ### Code Example ```java + @Test public void complexFillWithTable() { String templateFileName = "path/to/complexFillWithTable.xlsx"; - try (ExcelWriter writer = FastExcel.write("complexFillWithTable.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("complexFillWithTable.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // Fill list data writer.fill(data(), writeSheet); @@ -191,12 +197,13 @@ Fill list data horizontally, suitable for scenarios with dynamic column numbers. ### Code Example ```java + @Test public void horizontalFill() { String templateFileName = "path/to/horizontal.xlsx"; - try (ExcelWriter writer = FastExcel.write("horizontalFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("horizontalFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); FillConfig config = FillConfig.builder().direction(WriteDirectionEnum.HORIZONTAL).build(); writer.fill(data(), config, writeSheet); @@ -227,12 +234,13 @@ Support filling multiple lists simultaneously, with prefixes to differentiate be ### Code Example ```java + @Test public void compositeFill() { String templateFileName = "path/to/composite.xlsx"; - try (ExcelWriter writer = FastExcel.write("compositeFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("compositeFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // Use FillWrapper for filling multiple lists writer.fill(new FillWrapper("data1", data()), writeSheet); diff --git a/website/docs/help/annotation.md b/website/docs/sheet/help/annotation.md similarity index 51% rename from website/docs/help/annotation.md rename to website/docs/sheet/help/annotation.md index 975670458..288dddcf6 100644 --- a/website/docs/help/annotation.md +++ b/website/docs/sheet/help/annotation.md @@ -5,43 +5,46 @@ title: 'Annotation' # Annotation -This section describes how to read annotations provided in FastExcel. +This section describes how to read annotations provided in the project. ## Entity Class Annotations -Entity classes are the foundation of read and write operations. FastExcel provides various annotations to help developers easily define fields and formats. +Entity classes are the foundation of read and write operations. FesodSheet provides various annotations to help +developers easily define fields and formats. ### `@ExcelProperty` -Defines the column name in Excel and the field name to map. Specific parameters are as follows: +Defines the column name in spreadsheet and the field name to map. Specific parameters are as follows: -| Name | Default Value | Description | -|-----------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| value | Empty | Used to match the header in Excel, must be fully matched. If there are multiple header rows, it will match the last row header. | -| order | Integer.MAX_VALUE | Higher priority than `value`, will match the order of entities and data in Excel according to the order of `order`. | -| index | -1 | Higher priority than `value` and `order`, will directly specify which column in Excel to match based on `index`. | -| converter | Automatically selected | Specifies which converter the current field uses. By default, it will be automatically selected.
For reading, as long as the `cn.idev.excel.converters.Converter#convertToJavaData(com.idev.excel.converters.ReadConverterContext)` method is implemented, it is sufficient. | +| Name | Default Value | Description | +|-----------|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| value | Empty | Used to match the header in spreadsheet, must be fully matched. If there are multiple header rows, it will match the last row header. | +| order | Integer.MAX_VALUE | Higher priority than `value`, will match the order of entities and data in spreadsheet according to the order of `order`. | +| index | -1 | Higher priority than `value` and `order`, will directly specify which column in spreadsheet to match based on `index`. | +| converter | Automatically selected | Specifies which converter the current field uses. By default, it will be automatically selected.
For reading, as long as the `org.apache.fesod.sheet.converters.Converter#convertToJavaData(org.apache.fesod.sheet.converters.ReadConverterContext)` method is implemented, it is sufficient. | ### `@ExcelIgnore` -By default, all fields will match Excel. Adding this annotation will ignore the field. +By default, all fields will match spreadsheet. Adding this annotation will ignore the field. ### `@ExcelIgnoreUnannotated` -By default, all properties without the `@ExcelProperty` annotation are involved in read/write operations. Properties with this annotation are not involved in read/write operations. +By default, all properties without the `@ExcelProperty` annotation are involved in read/write operations. Properties +with this annotation are not involved in read/write operations. ### `@DateTimeFormat` -Date conversion: When using `String` to receive data in Excel date format, this annotation will be called. The parameters are as follows: +Date conversion: When using `String` to receive data in spreadsheet date format, this annotation will be called. The +parameters are as follows: -| Name | Default Value | Description | -|------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| value | Empty | Refer to `java.text.SimpleDateFormat` . | -| use1904windowing | Automatically selected | In Excel, time is stored as a double-precision floating-point number starting from 1900, but sometimes the default start date is 1904, so set this value to change the default start date to 1904. | +| Name | Default Value | Description | +|------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| value | Empty | Refer to `java.text.SimpleDateFormat` . | +| use1904windowing | Automatically selected | In spreadsheet, time is stored as a double-precision floating-point number starting from 1900, but sometimes the default start date is 1904, so set this value to change the default start date to 1904. | ### `@NumberFormat` -Number conversion, using `String` to receive data in Excel number format will trigger this annotation. +Number conversion, using `String` to receive data in spreadsheet number format will trigger this annotation. | Name | Default Value | Description | |--------------|----------------------|---------------------------------------| diff --git a/website/docs/help/core-class.md b/website/docs/sheet/help/core-class.md similarity index 69% rename from website/docs/help/core-class.md rename to website/docs/sheet/help/core-class.md index ce79b481d..d58a13f37 100644 --- a/website/docs/help/core-class.md +++ b/website/docs/sheet/help/core-class.md @@ -5,15 +5,15 @@ title: 'Core Class' # Core Classes -This section introduces the core classes in FastExcel. +This section introduces the core classes in the project. ## Overview -If you use FastExcel for custom read/write operations, you need to understand its important concepts and classes. +If you use this project for custom read/write operations, you need to understand its important concepts and classes. ## Core Concepts -### FastExcel +### FesodSheet Entry class used to start various operations @@ -21,8 +21,10 @@ Entry class used to start various operations There are corresponding Builder classes for read and write operations: -- **`ExcelReaderBuilder` and `ExcelWriterBuilder`**：Constructs a `ReadWorkbook` or `WriteWorkbook`, which can be understood as an Excel object; only one Excel needs to be constructed -- **`ExcelReaderSheetBuilder` and `ExcelWriterSheetBuilder`**：Constructs a `ReadSheet` or `WriteSheet` object, which can be understood as a page in Excel; each page needs to be constructed +- **`ExcelReaderBuilder` and `ExcelWriterBuilder`**：Constructs a `ReadWorkbook` or `WriteWorkbook`, which can be + understood as an spreadsheet object; only one spreadsheet needs to be constructed +- **`ExcelReaderSheetBuilder` and `ExcelWriterSheetBuilder`**：Constructs a `ReadSheet` or `WriteSheet` object, which can + be understood as a page in spreadsheet; each page needs to be constructed - **`CsvReaderBuilder` and `CsvWriterBuilder`**：Construct the CsvFormat required internally. ### ReadListener @@ -33,7 +35,9 @@ Called to handle data after each row is read Called to handle data for each operation, including creating cells, creating tables, etc. -All configurations are inherited. The configuration of `Workbook` will be inherited by `Sheet`, so when setting parameters in FastExcel, the scope is the entire sheet before the `FastExcel...sheet()` method, and the scope is the entire csv before the `FastExcel...csv()` method. +All configurations are inherited. The configuration of `Workbook` will be inherited by `Sheet`, so when setting +parameters in FesodSheet, the scope is the entire sheet before the `FesodSheet.sheet()` method, and the scope is the +entire csv before the `FesodSheet.csv()` method. --- @@ -41,11 +45,14 @@ All configurations are inherited. The configuration of `Workbook` will be inheri ### Overview -`WriteHandler` is an interface provided by FastExcel for intercepting the writing process when writing to an Excel file, allowing developers to customize operations such as setting cell styles, merging cells, adding hyperlinks, inserting comments, etc. By implementing `WriteHandler`, developers can have precise control over the writing process to meet complex business requirements. +`WriteHandler` is an interface provided by FesodSheet for intercepting the writing process when writing to a spreadsheet +file, allowing developers to customize operations such as setting cell styles, merging cells, adding hyperlinks, +inserting comments, etc. By implementing `WriteHandler`, developers can have precise control over the writing process to +meet complex business requirements. ### WriteHandler Interface Categories -FastExcel provides the following WriteHandler interfaces for handling different writing scenarios: +FesodSheet provides the following WriteHandler interfaces for handling different writing scenarios: | Interface Name | Description | |-----------------------|--------------------------------------------------------------------------------------------------------------------| @@ -60,7 +67,7 @@ FastExcel provides the following WriteHandler interfaces for handling different - Implement the methods in the interface, defining custom logic in the methods. 2. Register the WriteHandler： - - Register your custom WriteHandler when calling `FastExcel.write()` using `.registerWriteHandler()`. + - Register your custom WriteHandler when calling `FesodSheet.write()` using `.registerWriteHandler()`. ### Example @@ -71,6 +78,7 @@ Set the background color to yellow and font color to blue for all content cells. Customise a `CellWriteHandler` ```java + @Slf4j public class CustomCellStyleHandler implements CellWriteHandler { @@ -99,14 +107,15 @@ public class CustomCellStyleHandler implements CellWriteHandler { Register and Use ```java + @Test public void customCellStyleWrite() { String fileName = "customCellStyleWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CustomCellStyleHandler()) - .sheet("Custom Style") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CustomCellStyleHandler()) + .sheet("Custom Style") + .doWrite(data()); } ``` @@ -117,6 +126,7 @@ Insert a comment for the first row, second column of the header. Customise a `RowWriteHandler` ```java + @Slf4j public class CommentRowWriteHandler implements RowWriteHandler { @@ -140,14 +150,15 @@ public class CommentRowWriteHandler implements RowWriteHandler { Register and Use ```java + @Test public void commentWrite() { String fileName = "commentWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CommentRowWriteHandler()) - .sheet("Insert Comment") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CommentRowWriteHandler()) + .sheet("Insert Comment") + .doWrite(data()); } ``` @@ -158,6 +169,7 @@ Add a dropdown list for the first column of the first two rows. Customise a `SheetWriteHandler` ```java + @Slf4j public class DropdownSheetWriteHandler implements SheetWriteHandler { @@ -180,14 +192,15 @@ public class DropdownSheetWriteHandler implements SheetWriteHandler { Register and Use ```java + @Test public void dropdownWrite() { String fileName = "dropdownWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new DropdownSheetWriteHandler()) - .sheet("Add Dropdown") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new DropdownSheetWriteHandler()) + .sheet("Add Dropdown") + .doWrite(data()); } ``` @@ -197,18 +210,22 @@ public void dropdownWrite() { ### Overview -`ReadListener` is an interface provided by FastExcel for processing each row of data when reading an Excel file. It is one of the core components of FastExcel, allowing developers to implement custom logic to handle data rows, process headers, and even perform specific operations after reading is complete. +`ReadListener` is an interface provided by FesodSheet for processing each row of data when reading a spreadsheet file. +It is +one of the core components of FesodSheet, allowing developers to implement custom logic to handle data rows, process +headers, and even perform specific operations after reading is complete. ### Methods -`ReadListener` is a generic interface, where the generic type is the type of object to be read (e.g., `DemoData`). Its core methods are as follows: +`ReadListener` is a generic interface, where the generic type is the type of object to be read (e.g., `DemoData`). Its +core methods are as follows: | Method Name | Description | |------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| | `void invoke(T data, AnalysisContext context)` | Triggered when a line of data is read. `data` is the parsed current line object, and `context` contains the read context information. | | `void doAfterAllAnalysed(AnalysisContext context)` | Called after all data parsing is complete, it can be used for resource release or statistical data processing. | | `void onException(Exception exception, AnalysisContext context)` *(Optional)* | Capture exceptions during the reading process to facilitate error handling and analysis. | -| `void invokeHead(Map> headMap, AnalysisContext context)` *(Optional)* | Get Excel header information for dynamic header processing. | +| `void invokeHead(Map> headMap, AnalysisContext context)` *(Optional)* | Get header information for dynamic header processing. | ### Use Cases @@ -218,11 +235,11 @@ public void dropdownWrite() { ### Implementation Steps 1. Implement the `ReadListener` interface: - - Use an entity class as the generic type (e.g., `ReadListener`). - - Implement the core methods and add data processing logic as needed. + - Use an entity class as the generic type (e.g., `ReadListener`). + - Implement the core methods and add data processing logic as needed. 2. Register the custom `ReadListener` during reading: - - When calling the `FastExcel.read()` method, pass in the custom listener instance. + - When calling the `FesodSheet.read()` method, pass in the custom listener instance. ### Example @@ -231,6 +248,7 @@ public void dropdownWrite() { Customise a `ReadListener` ```java + @Slf4j public class DemoDataListener implements ReadListener { @@ -266,13 +284,14 @@ public class DemoDataListener implements ReadListener { Use ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() // Read the first sheet by default - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() // Read the first sheet by default + .doRead(); } ``` @@ -281,6 +300,7 @@ public void simpleRead() { Customise a `ReadListener` ```java + @Slf4j public class HeadDataListener implements ReadListener { @@ -304,13 +324,14 @@ public class HeadDataListener implements ReadListener { Use ```java + @Test public void readWithHead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new HeadDataListener()) - .sheet() // Read the first sheet by default - .doRead(); + FesodSheet.read(fileName, DemoData.class, new HeadDataListener()) + .sheet() // Read the first sheet by default + .doRead(); } ``` @@ -319,6 +340,7 @@ public void readWithHead() { Customise a `ReadListener` ```java + @Slf4j public class ExceptionHandlingListener implements ReadListener { @@ -332,46 +354,51 @@ public class ExceptionHandlingListener implements ReadListener { } @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } } ``` Use ```java + @Test public void readWithExceptionHandling() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ExceptionHandlingListener()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new ExceptionHandlingListener()) + .sheet() + .doRead(); } ``` #### Pagination ```java + @Test public void pageRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { - // Pagination batch processing - log.info("Read a batch of data: {}", JSON.toJSONString(dataList)); - // Implement data processing logic - })) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { + // Pagination batch processing + log.info("Read a batch of data: {}", JSON.toJSONString(dataList)); + // Implement data processing logic + })) + .sheet() + .doRead(); } ``` > **Note**： > -> - `PageReadListener` is a convenient utility class provided by FastExcel that supports batch processing based on pagination. +> - `PageReadListener` is a convenient utility class provided by FesodSheet that supports batch processing based on + pagination. > - The default page size is 1, which can be specified using the constructor. --- @@ -380,33 +407,45 @@ public void pageRead() { ### Overview -`AnalysisEventListener` is the core listener used in FastExcel for processing Excel data. It is based on an event-driven mechanism, allowing developers to perform custom operations when reading each row of data and to perform corresponding processing after all data has been parsed. It is typically used for streaming large amounts of data and is suitable for scenarios that require processing large data volumes and performing batch operations (such as batch insertion into a database). +`AnalysisEventListener` is the core listener used in FesodSheet for processing spreadsheet data. It is based on an +event-driven +mechanism, allowing developers to perform custom operations when reading each row of data and to perform corresponding +processing after all data has been parsed. It is typically used for streaming large amounts of data and is suitable for +scenarios that require processing large data volumes and performing batch operations (such as batch insertion into a +database). Core Features: -- **Line-by-line reading**: `AnalysisEventListener` reads data from Excel files line by line, executing the `invoke` method when reading each line of data, making it suitable for streaming processing. -- **Memory control**: You can set `BATCH_COUNT` to control the amount of data processed each time, preventing memory overflow. -- **Batch Processing**: You can cache a certain amount of data and process it in batches, suitable for scenarios with large data volumes. -- **Event-Driven**: The `invoke` method is called when reading each row of data; after all data has been read, the `doAfterAllAnalysed` method is called. +- **Line-by-line reading**: `AnalysisEventListener` reads data from spreadsheet files line by line, executing the + `invoke` + method when reading each line of data, making it suitable for streaming processing. +- **Memory control**: You can set `BATCH_COUNT` to control the amount of data processed each time, preventing memory + overflow. +- **Batch Processing**: You can cache a certain amount of data and process it in batches, suitable for scenarios with + large data volumes. +- **Event-Driven**: The `invoke` method is called when reading each row of data; after all data has been read, the + `doAfterAllAnalysed` method is called. ### Methods -| Method Name | Description | -|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| -| `invoke(T data, AnalysisContext context)` | Triggered when a line of data is read. `data` is the parsed current line object, and `context` contains the read context information. | -| `doAfterAllAnalysed(AnalysisContext context)` | Called after all data parsing is complete, used for resource cleanup or post-processing of batch operations. | -| `onException(Exception exception, AnalysisContext context)` *(Optional)* | Capture and handle exceptions thrown during parsing to facilitate error data handling. | -| `invokeHead(Map> headMap, AnalysisContext context)` *(Optional)* | Retrieve Excel header data, commonly used for dynamic header processing. | +| Method Name | Description | +|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `invoke(T data, AnalysisContext context)` | Triggered when a line of data is read. `data` is the parsed current line object, and `context` contains the read context information. | +| `doAfterAllAnalysed(AnalysisContext context)` | Called after all data parsing is complete, used for resource cleanup or post-processing of batch operations. | +| `onException(Exception exception, AnalysisContext context)` *(Optional)* | Capture and handle exceptions thrown during parsing to facilitate error data handling. | +| `invokeHead(Map> headMap, AnalysisContext context)` *(Optional)* | Retrieve header data, commonly used for dynamic header processing. | ### Use Cases -- **Streaming Data Processing**: For example, when reading large amounts of data, you can process the data as you read it, reducing memory consumption. -- **Batch insertion into a database**: For example, batch processing row data from Excel and storing it in a database. +- **Streaming Data Processing**: For example, when reading large amounts of data, you can process the data as you read + it, reducing memory consumption. +- **Batch insertion into a database**: For example, batch processing row data from spreadsheet and storing it in a + database. ### Implementation Steps 1. Inherit from `AnalysisEventListener` and implement its methods. -2. Pass in a custom listener during reading and register it using `FastExcel.read()`. +2. Pass in a custom listener during reading and register it using `FesodSheet.read()`. ### Example @@ -415,6 +454,7 @@ Core Features: Inherit `AnalysisEventListener` ```java + @Slf4j public class DemoDataListener extends AnalysisEventListener { @@ -458,23 +498,26 @@ public class DemoDataListener extends AnalysisEventListener { Use ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() // Read the first sheet by default - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() // Read the first sheet by default + .doRead(); } ``` #### Processing Table Headers -You can use the `invokeHead` method to obtain header information for handling dynamic header scenarios or for customising header data parsing. +You can use the `invokeHead` method to obtain header information for handling dynamic header scenarios or for +customising header data parsing. Inherit `AnalysisEventListener` ```java + @Slf4j public class DemoDataListenerWithHead extends AnalysisEventListener { @@ -503,23 +546,26 @@ public class DemoDataListenerWithHead extends AnalysisEventListener { Use ```java + @Test public void readWithHead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListenerWithHead()) - .sheet() // Read the first sheet by default - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListenerWithHead()) + .sheet() // Read the first sheet by default + .doRead(); } ``` #### Handling Exceptions -The `onException` method is provided so that developers can catch exceptions during reading and handle them (e.g., log errors, skip error lines, etc.). +The `onException` method is provided so that developers can catch exceptions during reading and handle them (e.g., log +errors, skip error lines, etc.). Inherit `AnalysisEventListener` ```java + @Slf4j public class ExceptionHandlingListener extends AnalysisEventListener { @@ -548,19 +594,22 @@ public class ExceptionHandlingListener extends AnalysisEventListener { Use ```java + @Test public void readWithExceptionHandling() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ExceptionHandlingListener()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new ExceptionHandlingListener()) + .sheet() + .doRead(); } ``` ### Compared to ReadListener -`AnalysisEventListener` and `ReadListener` are both interfaces provided by FastExcel, designed to allow developers to perform customised processing when reading Excel files. However, they have some key differences in terms of functionality and use cases. +`AnalysisEventListener` and `ReadListener` are both interfaces provided by FesodSheet, designed to allow developers to +perform customised processing when reading spreadsheet files. However, they have some key differences in terms of +functionality and use cases. #### Different @@ -576,41 +625,50 @@ public void readWithExceptionHandling() { Use `AnalysisEventListener`: -- If you need to control memory consumption, batch process data, or handle complex read logic (such as paginated reading or batch writing to a database). +- If you need to control memory consumption, batch process data, or handle complex read logic (such as paginated reading + or batch writing to a database). - Suitable for processing large datasets, offering greater flexibility. Use `ReadListener`: -- If you want to simplify your code and do not have complex memory control requirements, and only need to handle the logic for each row of data. -- Suitable for simple Excel data reading and exception handling scenarios. +- If you want to simplify your code and do not have complex memory control requirements, and only need to handle the + logic for each row of data. +- Suitable for simple spreadsheet data reading and exception handling scenarios. -In summary, `ReadListener` is a more simplified interface suitable for simpler scenarios, while `AnalysisEventListener` offers greater control and scalability, making it suitable for complex data processing requirements. Developers can choose the appropriate listener based on their actual needs. +In summary, `ReadListener` is a more simplified interface suitable for simpler scenarios, while `AnalysisEventListener` +offers greater control and scalability, making it suitable for complex data processing requirements. Developers can +choose the appropriate listener based on their actual needs. ## Converter ### Overview -`Converter` is an interface provided by FastExcel for converting data when processing Excel files. It allows developers to customise operations by implementing the `Converter` interface to define custom data conversion logic. +`Converter` is an interface provided by FesodSheet for converting data when processing spreadsheet files. It allows +developers +to customise operations by implementing the `Converter` interface to define custom data conversion logic. ### Methods -`Converter` is a generic interface, and the generic type is the object type to be converted (such as `Date`). Its core methods are as follows: +`Converter` is a generic interface, and the generic type is the object type to be converted (such as `Date`). Its core +methods are as follows: -| Method Name | Description | -|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| -| `Class supportJavaTypeKey()`*(Optional)* | Returns the supported Java object types. | -| `CellDataTypeEnum supportExcelTypeKey()`*(Optional)* | Returns the supported Excel cell types, enumerated as CellDataTypeEnum. | -| `T convertToJavaData(ReadCellData cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(Optional)* | Convert Excel cell data to Java objects | -| `WriteCellData convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(Optional)* | Convert Java objects to Excel cell data objects | -| `WriteCellData convertToExcelData(WriteConverterContext context)` *(Optional)* | Convert Java objects to Excel cell data objects | +| Method Name | Description | +|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| +| `Class supportJavaTypeKey()`*(Optional)* | Returns the supported Java object types. | +| `CellDataTypeEnum supportExcelTypeKey()`*(Optional)* | Returns the supported cell types, enumerated as CellDataTypeEnum. | +| `T convertToJavaData(ReadCellData cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(Optional)* | Convert cell data to Java objects | +| `WriteCellData convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(Optional)* | Convert Java objects to cell data objects | +| `WriteCellData convertToExcelData(WriteConverterContext context)` *(Optional)* | Convert Java objects to cell data objects | -FastExcel provides many commonly used type converters by default, which are already registered in `DefaultConverterLoader`. +FesodSheet provides many commonly used type converters by default, which are already registered in +`DefaultConverterLoader`. -You can customise converters, but the types must not overlap with the default types. When registering types, use `ConverterKeyBuild.buildKey(converter.supportJavaTypeKey(), converter.supportExcelTypeKey())` as the key value. +You can customise converters, but the types must not overlap with the default types. When registering types, use +`ConverterKeyBuild.buildKey(converter.supportJavaTypeKey(), converter.supportExcelTypeKey())` as the key value. ### Use Cases -- **Data Conversion**: Convert Excel data, such as converting dates to strings, converting strings to dates, etc. +- **Data Conversion**: Convert spreadsheet data, such as converting dates to strings, converting strings to dates, etc. ### Implementation Steps @@ -624,6 +682,7 @@ You can customise converters, but the types must not overlap with the default ty Implement `Converter` ```java + @Slf4j public class TimestampNumberConverter implements Converter { @Override @@ -653,20 +712,21 @@ public class TimestampNumberConverter implements Converter { Use ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; // Read - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .registerConverter(new TimestampNumberConverter()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .registerConverter(new TimestampNumberConverter()) + .sheet() + .doRead(); // Write - FastExcel.write(fileName) - .registerConverter(new TimestampNumberConverter()) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName) + .registerConverter(new TimestampNumberConverter()) + .sheet() + .doWrite(data()); } ``` diff --git a/website/docs/help/faq.md b/website/docs/sheet/help/faq.md similarity index 65% rename from website/docs/help/faq.md rename to website/docs/sheet/help/faq.md index ae990a555..5f672fa35 100644 --- a/website/docs/help/faq.md +++ b/website/docs/sheet/help/faq.md @@ -5,72 +5,94 @@ title: 'FAQ' # FAQ -This section describes common issues that may arise when using FastExcel. +This section describes common issues that may arise when using this project. ## Feature Limitations -- **Q:** What functions does FastExcel support? What functions are not supported? -- **A:** FastExcel supports efficient reading and writing operations for Excel files, including support for CSV format. Unsupported functions include concurrent writing to a single file, reading and writing image macros, etc. +- **Q:** What functions does FesodSheet support? What functions are not supported? +- **A:** FesodSheet supports efficient reading and writing operations for spreadsheet files, including support for CSV + format. + Unsupported functions include concurrent writing to a single file, reading and writing image macros, etc. ## Choosing Write Operations -- **Q:** When writing to Excel, when should I choose the fill mode and when should I choose direct writing? -- **A:** For complex export content, it is recommended to use template filling; for simple format scenarios, direct writing is more efficient. +- **Q:** When writing to spreadsheet, when should I choose the fill mode and when should I choose direct writing? +- **A:** For complex export content, it is recommended to use template filling; for simple format scenarios, direct + writing is more efficient. ## Lombok Annotations -- **Q:** What is the role of Lombok annotations in using FastExcel? -- **A:** Commonly used Lombok annotations in entity classes such as `@Getter`, `@Setter`, `@EqualsAndHashCode` are used to automatically generate getter, setter methods, equals, and hashCode methods. If you do not want to use these auto-generated methods, you can implement them yourself. +- **Q:** What is the role of Lombok annotations in using FesodSheet? +- **A:** Commonly used Lombok annotations in entity classes such as `@Getter`, `@Setter`, `@EqualsAndHashCode` are used + to automatically generate getter, setter methods, equals, and hashCode methods. If you do not want to use these + auto-generated methods, you can implement them yourself. ## Field Matching - **Q:** How to solve the problem of some fields not being read or written correctly? -- **A:** Ensure that the entity class fields follow the camel case naming convention, avoid using `@Accessors(chain = true)`, and recommend using `@Builder` instead. Also, ensure that the entity class uses the `@ExcelProperty` annotation to mark the fields participating in reading and writing. +- **A:** Ensure that the entity class fields follow the camel case naming convention, avoid using + `@Accessors(chain = true)`, and recommend using `@Builder` instead. Also, ensure that the entity class uses the + `@ExcelProperty` annotation to mark the fields participating in reading and writing. ## Compatibility Issues -- **Q:** What should I do if I encounter compatibility issues when using FastExcel? -- **A:** Common compatibility issues include `NoSuchMethodException`, `ClassNotFoundException`, `NoClassDefFoundError`, etc., usually caused by jar conflicts. It is recommended to check and clean up dependencies in the project to ensure that the version of FastExcel used is compatible with other libraries in the project. +- **Q:** What should I do if I encounter compatibility issues when using FesodSheet? +- **A:** Common compatibility issues include `NoSuchMethodException`, `ClassNotFoundException`, `NoClassDefFoundError`, + etc., usually caused by jar conflicts. It is recommended to check and clean up dependencies in the project to ensure + that the version of FesodSheet used is compatible with other libraries in the project. ## Online Deployment - **Q:** Why are there issues in the online environment when it runs fine locally? -- **A:** In most cases, this is due to the lack of necessary font libraries in the online environment. You can solve this problem by installing font libraries (such as `dejavu-sans-fonts` and `fontconfig`) or enabling memory processing mode. +- **A:** In most cases, this is due to the lack of necessary font libraries in the online environment. You can solve + this problem by installing font libraries (such as `dejavu-sans-fonts` and `fontconfig`) or enabling memory processing + mode. ## Concurrent Reading - **Q:** Why shouldn't the Listener be managed by Spring? -- **A:** Listeners should not be managed by Spring because this would cause the Listener to become a singleton, which may lead to data confusion when reading files concurrently. A new Listener instance should be created each time a file is read. +- **A:** Listeners should not be managed by Spring because this would cause the Listener to become a singleton, which + may lead to data confusion when reading files concurrently. A new Listener instance should be created each time a file + is read. ## Performance Optimization -- **Q:** For large files over 10M, what reading strategies does FastExcel provide? -- **A:** FastExcel supports default large file processing strategies, as well as customizable high-speed modes and optimization settings for high concurrency and super large files. +- **Q:** For large files over 10M, what reading strategies does FesodSheet provide? +- **A:** FesodSheet supports default large file processing strategies, as well as customizable high-speed modes and + optimization settings for high concurrency and super large files. ## Writing and Format Setting - **Q:** How to set cell formats? -- **A:** You can set cell formats by using annotations such as `@ContentStyle` on entity class properties, for example, numeric formats, date formats, etc. +- **A:** You can set cell formats by using annotations such as `@ContentStyle` on entity class properties, for example, + numeric formats, date formats, etc. ## Export Issues -- **Q:** How to resolve the issue of Excel files exported cannot be opened or prompt for repair? -- **A:** This is usually caused by frontend frameworks or backend interceptors modifying the file stream. It is recommended to test local exports first, ensure the backend logic is correct, and then investigate frontend and network-related issues. +- **Q:** How to resolve the issue of spreadsheet files exported cannot be opened or prompt for repair? +- **A:** This is usually caused by frontend frameworks or backend interceptors modifying the file stream. It is + recommended to test local exports first, ensure the backend logic is correct, and then investigate frontend and + network-related issues. ## Large File Reading Optimization -- **Q:** How does FastExcel optimize memory usage when reading large files? -- **A:** FastExcel automatically determines the processing method for large files. For files with shared strings exceeding 5MB, a file storage strategy is used to reduce memory usage. You can enable ultra-fast mode by setting the `readCache` parameter, but this will increase memory consumption. +- **Q:** How does FesodSheet optimize memory usage when reading large files? +- **A:** FesodSheet automatically determines the processing method for large files. For files with shared strings + exceeding 5MB, a file storage strategy is used to reduce memory usage. You can enable ultra-fast mode by setting the + `readCache` parameter, but this will increase memory consumption. ## Concurrent Processing -- **Q:** How to efficiently read Excel files in a high-concurrency environment? -- **A:** In a high-concurrency environment, you can optimize reading performance using `SimpleReadCacheSelector`. By setting the `maxUseMapCacheSize` and `maxCacheActivateBatchCount` parameters, you can control the cache strategy for shared strings, improve hit rates, and reduce file read delays. +- **Q:** How to efficiently read spreadsheet files in a high-concurrency environment? +- **A:** In a high-concurrency environment, you can optimize reading performance using `SimpleReadCacheSelector`. By + setting the `maxUseMapCacheSize` and `maxCacheActivateBatchCount` parameters, you can control the cache strategy for + shared strings, improve hit rates, and reduce file read delays. ## Field Mapping -- **Q:** How to handle cases where entity class fields do not match Excel column names? -- **A:** You can use the `@ExcelProperty` annotation to specify the correspondence between entity class fields and Excel column names. For example: +- **Q:** How to handle cases where entity class fields do not match spreadsheet column names? +- **A:** You can use the `@ExcelProperty` annotation to specify the correspondence between entity class fields and + spreadsheet column names. For example: ```java @ExcelProperty("Name") @@ -79,7 +101,7 @@ This section describes common issues that may arise when using FastExcel. ## Data Validation -- **Q:** How to validate data when reading Excel data? +- **Q:** How to validate data when reading spreadsheet data? - **A:** Data validation logic can be implemented in the `ReadListener`. For example: ```java @@ -117,7 +139,7 @@ This section describes common issues that may arise when using FastExcel. - **A:** Using the `inMemory(true)` parameter can ensure correct field replacement. For example: ```java - FastExcel.write(fileName, DemoData.class).inMemory(true).sheet("Template").doWrite(fillData()); + FesodSheet.write(fileName, DemoData.class).inMemory(true).sheet("Template").doWrite(fillData()); ``` ## Error Handling @@ -141,32 +163,34 @@ This section describes common issues that may arise when using FastExcel. ## Dependency Conflict - **Q:** How to resolve dependency conflict issues? -- **A:** Common dependency conflicts include POI, ehcache, commons-io, etc. It is recommended to check the dependency tree in the project, ensure that the versions used are compatible with FastExcel. You can use the Maven `dependency:tree` command to view the dependency tree. +- **A:** Common dependency conflicts include POI, ehcache, commons-io, etc. It is recommended to check the dependency + tree in the project, ensure that the versions used are compatible with FesodSheet. You can use the Maven + `dependency:tree` command to view the dependency tree. ## Performance Monitoring -- **Q:** How to monitor the performance of FastExcel? -- **A:** You can monitor the performance of FastExcel by enabling debug logging. For example: +- **Q:** How to monitor the performance of FesodSheet? +- **A:** You can monitor the performance of FesodSheet by enabling debug logging. For example: ```java LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - ch.qos.logback.classic.Logger logger = lc.getLogger("cn.idev.excel"); + ch.qos.logback.classic.Logger logger = lc.getLogger("org.apache.fesod"); logger.setLevel(Level.DEBUG); ``` ## Multi-Sheet Reading -- **Q:** How to monitor the performance of FastExcel? -- **A:** You can monitor the performance of FastExcel by enabling debug logging. For example: +- **Q:** How to monitor the performance of FesodSheet? +- **A:** You can monitor the performance of FesodSheet by enabling debug logging. For example: ```java - FastExcel.read(file, MultipleSheetsData.class, new MultipleSheetsListener()).doReadAll(); + FesodSheet.read(file, MultipleSheetsData.class, new MultipleSheetsListener()).doReadAll(); ``` Alternatively, you can get information on all sheets before reading: ```java - ExcelReader excelReader = FastExcel.read(file, MultipleSheetsData.class, multipleSheetsListener).build(); + ExcelReader excelReader = FesodSheet.read(file, MultipleSheetsData.class, multipleSheetsListener).build(); List sheets = excelReader.excelExecutor().sheetList(); for (ReadSheet readSheet : sheets) { excelReader.read(readSheet); @@ -174,10 +198,11 @@ This section describes common issues that may arise when using FastExcel. excelReader.finish(); ``` -## Get Total Rows in Excel +## Get Total Rows -- **Q:** How to get the total number of rows in an Excel file? -- **A:** You can use `analysisContext.readSheetHolder().getApproximateTotalRowNumber()` method in the listener to get an approximate number of rows. For example: +- **Q:** How to get the total number of rows in a spreadsheet file? +- **A:** You can use `analysisContext.readSheetHolder().getApproximateTotalRowNumber()` method in the listener to get an + approximate number of rows. For example: ```java @Override @@ -189,11 +214,12 @@ This section describes common issues that may arise when using FastExcel. ## Memory Mode -- **Q:** How to use memory mode to process Excel files? -- **A:** Memory mode is suitable for processing smaller files and can significantly improve processing speed. For example: +- **Q:** How to use memory mode to process spreadsheet files? +- **A:** Memory mode is suitable for processing smaller files and can significantly improve processing speed. For + example: ```java - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .inMemory(Boolean.TRUE) .sheet("Template") .doWrite(data()); @@ -205,7 +231,7 @@ This section describes common issues that may arise when using FastExcel. - **A:** You can modify the delimiter of CSV files by setting `CsvFormat`. For example: ```java - FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv().delimiter(CsvConstant.UNICODE_EMPTY).doReadSync(); ``` diff --git a/website/docs/sheet/help/large-data.md b/website/docs/sheet/help/large-data.md new file mode 100644 index 000000000..2118a4053 --- /dev/null +++ b/website/docs/sheet/help/large-data.md @@ -0,0 +1,79 @@ +--- +id: 'large-data' +title: 'Large Data' +--- + +# Big Data Files + +## Reading + +### Overview + +When reading files larger than 10 MB, Microsoft Excel 03 is unable to handle them and consumes significantly more +memory. Microsoft Excel 2007 introduces the concept +of [Shared Strings](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/working-with-the-shared-string-table), +which can consume a significant amount of memory. +If all shared strings are loaded into memory, the memory usage can be approximately 3 to 10 times the size of the Excel +file. Therefore, FesodSheet uses a strategy of first storing the file and then deserialising it to read the data, +thereby +saving memory. Of course, after deserialising the file, efficiency will decrease by approximately 30-50% (this is not +fixed and depends on the hit rate, which may exceed 100%). + +If the read efficiency is acceptable, use the default setting. The permanent memory usage (for the entire process of +reading a single Excel file) generally does not exceed 50MB (most likely around 30MB), and the remaining temporary +memory is quickly recycled by the garbage collector. + +### Default Policy + +By default, large file processing is automatically determined. Shared strings under 5M are stored in memory, which +occupies approximately 15-50M of memory. Strings over 5M are stored in files, and file storage also requires additional +memory to store temporary shared strings, with a default of 20M. Apart from the memory used by shared strings, other +memory usage is minimal, so it can be estimated at 10MB. Therefore, the default of approximately 30MB is sufficient to +read an extremely large file. + +### Configure Memory + +If you want to customise the settings, first determine how much memory you are willing to allocate for reading a very +large Excel file. +For example, if you want the Excel file to occupy a maximum of 100MB of memory during the reading process (this is the +permanent memory usage during reading, not including memory immediately reclaimed by the young generation), then set the +size of the shared string stored in the file to 20MB (less than 20MB is stored in memory, more than 20MB is stored in a +temporary file), and then set the memory size occupied by the temporary shared string when stored in the file to +approximately 90MB. + +If the maximum number of file entries is only a few hundred thousand, and the Excel file is only a few dozen megabytes, +and there is no high concurrency, and memory is sufficient, + +```java +// Force memory storage, so a 20M Excel file will use 150M of memory (many temporary objects, so 100M will be constantly GC'd). +// This will be much more efficient than the complex strategy above. +// Just to clarify, all I did was add the readCache(new MapCache()) parameter. For the rest, refer to other examples. +FesodSheet.read(). + +readCache(new MapCache()); +``` + +High concurrency requirements, and often involve extremely large files. + +```java +// The first parameter specifies how many MB of shared string data will be stored in the file (default is 5 MB). +// The second parameter specifies how many MB of cache data will be stored in memory when using file storage (default is 20 MB). +// For example, if you want to use 100 MB of memory (this refers to permanent memory usage during parsing, excluding temporary objects) to parse an Excel file, the calculation shows it to be approximately 20 MB + 90 MB, so set the parameters to: 20 and 90. +// Here's a clarification: the only addition is the readCacheSelector(new SimpleReadCacheSelector(5, 20)) parameter; the rest follows the examples provided. +FesodSheet.read(). + +readCacheSelector(new SimpleReadCacheSelector(5, 20)); +``` + +### About maxCacheActivateSize + +When using file storage, FesodSheet splits the shared string into batches of **1000** items and then stores them in file +storage. Excel typically reads shared strings in sequential order, so by default, 1000 entries (approximately 20MB) are +kept in memory. If a match is found, the data is returned directly; if not, the file is read. Therefore, the size should +not be set too small, as this makes it difficult to find a match and results in constant file reads. Conversely, setting +it too large can consume excessive memory. + +To determine whether `maxCacheActivateSize` needs adjustment, enabling `debug` logs will output `Already put :4000000` +as the last value, which can be estimated to be 4 million. Then, checking `Cache misses count:4001` yields a value of +4,000. `4 million / 4,000 = 1,000` indicates that `maxCacheActivateSize` is already very reasonable. If the value is +less than 500, there is a significant issue. Values between 500 and 1000 should be acceptable. diff --git a/website/docs/help/parameter.md b/website/docs/sheet/help/parameter.md similarity index 90% rename from website/docs/help/parameter.md rename to website/docs/sheet/help/parameter.md index c1a22b7e6..0bc847722 100644 --- a/website/docs/help/parameter.md +++ b/website/docs/sheet/help/parameter.md @@ -5,7 +5,7 @@ title: 'Parameter' # Parameter -This section introduces the parameters used in FastExcel. +This section introduces the parameters used in the project. ## Class Diagram @@ -108,7 +108,7 @@ All parameters inherit from `BasicParameter`. | clazz | Empty | Choose one of `head` or `clazz`. Reads the class corresponding to the file header, and annotations can also be used. If neither is specified, all data will be read. | | customConverterList | Empty | Many converters are loaded by default. You can add unsupported fields here. | | autoTrim | true | Automatically trims the header, reads data, etc. | -| use1904windowing | false | In Excel, time is stored as a double-precision floating-point number starting from 1900, but sometimes the default start date is 1904. So setting this value changes the default start date to 1904. | +| use1904windowing | false | Time is stored as a double-precision floating-point number starting from 1900, but sometimes the default start date is 1904. So setting this value changes the default start date to 1904. | | useScientificFormat | false | When converting numbers to text, whether to use scientific notation for large values. | | locale | Empty | DeepL Translate_ The world's most accurate translator | | filedCacheLocation | THREAD_LOCAL | Parsing the fields of the class will have a cache. Before, it was placed globally in a Map. After 3.3.0, it is placed in ThreadLocal by default, meaning that each read and write will reparse the class. You can reflectively modify the annotations of the class, and concurrent scenarios will not affect each other.
THREAD_LOCAL: Default, the cache will be cleared each time, but not the same time.
MEMORY: Placed in global memory, theoretically better performance, but cannot modify the exported object through reflection, exclusion, etc.
NONE: No caching, performance will degrade, consider using it when reading and writing at the same time, and you need to reflectively exclude, modify objects, etc. | @@ -117,33 +117,33 @@ All parameters inherit from `BasicParameter`. ### ReadBasicParameter -| Name | Default Value | Description | -|------------------------|---------------|----------------------------------------------------------------------------------------------------------| -| customReadListenerList | Empty | Can register multiple listeners. When reading Excel, the listener's methods will be continuously called. | -| headRowNumber | 1 | The number of rows in the header of Excel, default is 1 row. | +| Name | Default Value | Description | +|------------------------|---------------|----------------------------------------------------------------------------------------------------------------| +| customReadListenerList | Empty | Can register multiple listeners. When reading spreadsheet, the listener's methods will be continuously called. | +| headRowNumber | 1 | The number of rows in the header of spreadsheet, default is 1 row. | ### ReadWorkbook -| Name | Default Value | Description | -|--------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| excelType | Empty | The current type of Excel, supports XLS, XLSX, CSV. | -| inputStream | Empty | Choose between `file` and `inputStream`. Reads the file stream. If a stream is received, it is used directly. If not, it is recommended to use the `file` parameter. Using `inputStream` will help create temporary files, but in the end it is still `file`. | -| file | Empty | Choose between `inputStream` and `file`. Reads the file. | -| mandatoryUseInputStream | false | Forces the use of `inputStream` to create objects, which may degrade performance but will not create temporary files. | -| charset | Charset#defaultCharset | Only useful for CSV files, specifies the encoding used when reading the file. | -| autoCloseStream | true | Automatically closes the read stream. | -| readCache | Empty | For files smaller than 5MB, use memory. For files larger than 5MB, use `EhCache`. It is not recommended to use this parameter. | -| readCacheSelector | SimpleReadCacheSelector | Used to select when to use memory to store temporary data and when to use disk to store temporary data. | -| ignoreEmptyRow | true | Ignore empty rows. | -| password | Empty | Password for reading the file. | -| xlsxSAXParserFactoryName | Empty | Specifies the name of the class used for sax reading, for example: `com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl`. | -| useDefaultListener | true | By default, `ModelBuildEventListener` is added to help convert to the object passed in. Setting it to `false` will not assist in converting objects, and custom listeners will receive a `Map` object. If you still want to receive `class` objects, call the `readListener` method and add custom `beforeListener`, `ModelBuildEventListener`, and custom `afterListener`. | -| extraReadSet | Empty | Set of additional content to be read, which is not read by default. | -| readDefaultReturn | STRING | STRING: Returns an array of `Map`, the return value is the content you see in the Excel cell without clicking on it.
ACTUAL_DATA: Returns an array of `Map`, the actual data stored, will automatically convert types, `Object` type can be `BigDecimal`, `Boolean`, `String`, `LocalDateTime`, `null`, one of them.
READ_CELL_DATA: Returns an array of `Map>`, where `?` type refers to ACTUAL_DATA. | -| customObject | STRING | STRING: Returns an array of `Map`, the return value is the content you see in the Excel cell without clicking on it.
ACTUAL_DATA: Returns an array of `Map`, the actual data stored, will automatically convert types, `Object` type can be `BigDecimal`, `Boolean`, `String`, `LocalDateTime`, `null`, one of them.
READ_CELL_DATA: Returns an array of `Map>`, where `?` type refers to ACTUAL_DATA. | -| numRows | 0 | Read the specified number of rows. 0 means no limit on the number of rows, i.e. read all rows. | -| ignoreHiddenSheet | true | `@since 1.3.0`
Ignore hidden sheets. | -| csvFormat | CSVFormat.DEFAULT | `@since 1.3.0`
Set the CSVFormat object, which is only valid for csv files. | +| Name | Default Value | Description | +|--------------------------|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| excelType | Empty | The current type of spreadsheet, supports XLS, XLSX, CSV. | +| inputStream | Empty | Choose between `file` and `inputStream`. Reads the file stream. If a stream is received, it is used directly. If not, it is recommended to use the `file` parameter. Using `inputStream` will help create temporary files, but in the end it is still `file`. | +| file | Empty | Choose between `inputStream` and `file`. Reads the file. | +| mandatoryUseInputStream | false | Forces the use of `inputStream` to create objects, which may degrade performance but will not create temporary files. | +| charset | Charset#defaultCharset | Only useful for CSV files, specifies the encoding used when reading the file. | +| autoCloseStream | true | Automatically closes the read stream. | +| readCache | Empty | For files smaller than 5MB, use memory. For files larger than 5MB, use `EhCache`. It is not recommended to use this parameter. | +| readCacheSelector | SimpleReadCacheSelector | Used to select when to use memory to store temporary data and when to use disk to store temporary data. | +| ignoreEmptyRow | true | Ignore empty rows. | +| password | Empty | Password for reading the file. | +| xlsxSAXParserFactoryName | Empty | Specifies the name of the class used for sax reading, for example: `com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl`. | +| useDefaultListener | true | By default, `ModelBuildEventListener` is added to help convert to the object passed in. Setting it to `false` will not assist in converting objects, and custom listeners will receive a `Map` object. If you still want to receive `class` objects, call the `readListener` method and add custom `beforeListener`, `ModelBuildEventListener`, and custom `afterListener`. | +| extraReadSet | Empty | Set of additional content to be read, which is not read by default. | +| readDefaultReturn | STRING | STRING: Returns an array of `Map`, the return value is the content you see in the cell without clicking on it.
ACTUAL_DATA: Returns an array of `Map`, the actual data stored, will automatically convert types, `Object` type can be `BigDecimal`, `Boolean`, `String`, `LocalDateTime`, `null`, one of them.
READ_CELL_DATA: Returns an array of `Map>`, where `?` type refers to ACTUAL_DATA. | +| customObject | STRING | STRING: Returns an array of `Map`, the return value is the content you see in the cell without clicking on it.
ACTUAL_DATA: Returns an array of `Map`, the actual data stored, will automatically convert types, `Object` type can be `BigDecimal`, `Boolean`, `String`, `LocalDateTime`, `null`, one of them.
READ_CELL_DATA: Returns an array of `Map>`, where `?` type refers to ACTUAL_DATA. | +| numRows | 0 | Read the specified number of rows. 0 means no limit on the number of rows, i.e. read all rows. | +| ignoreHiddenSheet | true | `@since 1.3.0`
Ignore hidden sheets. | +| csvFormat | CSVFormat.DEFAULT | `@since 1.3.0`
Set the CSVFormat object, which is only valid for csv files. | ### ReadSheet @@ -200,7 +200,7 @@ FastExcel.write(fileName) | Name | Default Value | Description | |-------------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| -| excelType | Empty | The current type of Excel, supports XLS, XLSX, CSV. | +| excelType | Empty | The current type of spreadsheet, supports XLS, XLSX, CSV. | | outputStream | Empty | Choose between `file` and `outputStream`. Writes the file stream. | | file | Empty | Choose between `outputStream` and `file`. Writes the file. | | templateInputStream | Empty | Template file stream. | @@ -209,7 +209,7 @@ FastExcel.write(fileName) | autoCloseStream | true | Automatically closes the write stream. | | password | Empty | Password for reading the file. | | inMemory | false | Whether to process in memory, by default, a temporary file will be generated to save memory. Memory mode is more efficient, but prone to OOM. | -| writeExcelOnException | false | If an exception occurs during writing, whether to try to write the data to Excel. | +| writeExcelOnException | false | If an exception occurs during writing, whether to try to write the data to spreadsheet. | | withBom | true | Set the encoding prefix in the CSV file, otherwise Office software may display garbled characters. | | mandatoryUseInputStream | false | Forces the use of `inputStream` to create objects, which may degrade performance but will not create temporary files. | | csvFormat | CSVFormat.DEFAULT | `@since 1.3.0`
Set the CSVFormat object, which is only valid for csv files. | diff --git a/website/docs/read/converter.md b/website/docs/sheet/read/converter.md similarity index 81% rename from website/docs/read/converter.md rename to website/docs/sheet/read/converter.md index 6d7af2215..e8eaed518 100644 --- a/website/docs/read/converter.md +++ b/website/docs/sheet/read/converter.md @@ -5,17 +5,19 @@ title: 'Converter' # Format Conversion -FastExcel supports date, number, and custom format conversions. +Fesod supports date, number, and custom format conversions. ## Overview -During usage, we may need to convert read or written data into specific formats. FastExcel provides a flexible converter mechanism that allows users to define custom data conversion rules to meet various business requirements. +During usage, we may need to convert read or written data into specific formats. Fesod provides a flexible converter +mechanism that allows users to define custom data conversion rules to meet various business requirements. ## Example ### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -60,11 +62,12 @@ public class CustomStringStringConverter implements Converter { ### Code Example ```java + @Test public void converterRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, ConverterData.class, new DemoDataListener()) + FesodSheet.read(fileName, ConverterData.class, new DemoDataListener()) .registerConverter(new CustomStringStringConverter()) // Register custom converter .sheet() .doRead(); diff --git a/website/docs/sheet/read/csv.md b/website/docs/sheet/read/csv.md new file mode 100644 index 000000000..a0663f6f6 --- /dev/null +++ b/website/docs/sheet/read/csv.md @@ -0,0 +1,160 @@ +--- +id: 'csv' +title: 'CSV' +--- + +# Reading CSV Files + +This chapter introduces how to use Fesod to read custom CSV files. + +## Overview + +Fesod reads CSV files through different parameter configurations. It +uses [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) as the underlying implementation and also +supports direct configuration +through [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) +settings to achieve reading objectives. + +The main parameters are as follows: + +| Name | Default Value | Description | +|:------------------|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------| +| `delimiter` | `,` (comma) | Field delimiter. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.AT`(`@`), `CsvConstant.TAB`, etc. | +| `quote` | `"` (double quote) | Field quote character. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.DOUBLE_QUOTE`(`"`). | +| `recordSeparator` | `CRLF` | Record (line) separator. Varies by operating system, such as `CsvConstant.CRLF`(Windows) or `CsvConstant.LF`(Unix/Linux). | +| `nullString` | `null` | String used to represent `null` values. Note this is different from an empty string `""`. | +| `escape` | `null` | Escape character used to escape quote characters themselves. | + +--- + +## Parameter Details and Examples + +The following sections will explain each parameter in detail with code examples. + +### delimiter + +`delimiter` specifies the field separator in CSV files. The default value is a comma `,`. +Additionally, Fesod provides constants in `CsvConstant` to simplify usage. + +#### Code Example + +If the CSV file uses `\u0000` as the separator, you can configure it as follows: + +```java + +@Test +public void delimiterDemo() { + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .delimiter(CsvConstant.UNICODE_EMPTY) + .doReadSync(); +} +``` + +### quote + +`quote` specifies the quote character that wraps fields. The default value is double quote `"`. +This should be set when field content contains delimiters or line breaks. + +> Note: This cannot be the same as the `recordSeparator` setting. It's recommended to use in combination with +`QuoteMode`. + +#### Code Example + +```java + +@Test +public void quoteDemo() { + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .quote(CsvConstant.DOUBLE_QUOTE, QuoteMode.MINIMAL) + .doReadSync(); +} +``` + +### recordSeparator + +`recordSeparator` specifies the line separator in the file. Different operating systems may use different line +separators (for example, Windows uses `CRLF`, while Unix/Linux uses `LF`). + +#### Code Example + +```java + +@Test +public void recordSeparatorDemo() { + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .recordSeparator(CsvConstant.LF) + .doReadSync(); +} +``` + +### nullString + +`nullString` defines a specific string in the file that represents `null` values. For example, you can parse the string +`"N/A"` as a `null` object. + +#### Code Example + +```java + +@Test +public void nullStringDemo() { + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .nullString("N/A") + .doReadSync(); +} +``` + +### escape + +`escape` specifies an escape character that can be used when quote characters (`quote`) appear within field values. + +#### Code Example + +```java + +@Test +public void escapeDemo() { + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .escape(CsvConstant.BACKSLASH) + .doReadSync(); +} +``` + +## CSVFormat Configuration Details and Examples + +Supports directly building a `CSVFormat` object. +> Fesod currently still supports this approach, but it's not the most recommended usage method. + +### Code Example + +```java + +@Test +public void csvFormatDemo() { + + CSVFormat csvFormat = CSVFormat.DEFAULT.builder().setDelimiter(CsvConstant.AT).build(); + String csvFile = "path/to/your.csv"; + + try (ExcelReader excelReader = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()).build()) { + ReadWorkbookHolder readWorkbookHolder = excelReader.analysisContext().readWorkbookHolder(); + // Check if it's an instance of CsvReadWorkbookHolder + if (readWorkbookHolder instanceof CsvReadWorkbookHolder) { + CsvReadWorkbookHolder csvReadWorkbookHolder = (CsvReadWorkbookHolder) readWorkbookHolder; + csvReadWorkbookHolder.setCsvFormat(csvFormat); + } + + ReadSheet readSheet = FesodSheet.readSheet(0).build(); + excelReader.read(readSheet); + } +} +``` diff --git a/website/docs/read/exception.md b/website/docs/sheet/read/exception.md similarity index 92% rename from website/docs/read/exception.md rename to website/docs/sheet/read/exception.md index 87c0b2e3b..98b75e8ca 100644 --- a/website/docs/read/exception.md +++ b/website/docs/sheet/read/exception.md @@ -40,7 +40,7 @@ public class DemoExceptionListener extends AnalysisEventListener { public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoCommentExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoCommentExtraListener()) .extraRead(CellExtraTypeEnum.COMMENT) .sheet() .doRead(); @@ -84,7 +84,7 @@ public class DemoHyperLinkExtraListener implements ReadListener { public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoHyperLinkExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoHyperLinkExtraListener()) .extraRead(CellExtraTypeEnum.HYPERLINK) .sheet() .doRead(); @@ -127,7 +127,7 @@ public class DemoMergeExtraListener implements ReadListener { public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoMergeExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoMergeExtraListener()) .extraRead(CellExtraTypeEnum.MERGE) .sheet() .doRead(); diff --git a/website/docs/read/head.md b/website/docs/sheet/read/head.md similarity index 69% rename from website/docs/read/head.md rename to website/docs/sheet/read/head.md index 6f4815ce7..418e4ceba 100644 --- a/website/docs/read/head.md +++ b/website/docs/sheet/read/head.md @@ -5,7 +5,7 @@ title: 'Head' # Headers -This chapter introduces how to read header data from Excel files. +This chapter introduces how to read header data from the spreadsheet files. ## Reading Header Data @@ -16,6 +16,7 @@ You can obtain header information by overriding the `invokeHead` method in the l ### Data Listener ```java + @Slf4j public class DemoHeadDataListener extends AnalysisEventListener { @Override @@ -24,21 +25,24 @@ public class DemoHeadDataListener extends AnalysisEventListener { } @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } } ``` ### Code Example ```java + @Test public void headerRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoHeadDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoHeadDataListener()) .sheet() .doRead(); } @@ -50,20 +54,22 @@ public void headerRead() { ### Overview -Parse multi-row headers by setting the `headRowNumber` parameter or automatically based on header annotations in entity classes. +Parse multi-row headers by setting the `headRowNumber` parameter or automatically based on header annotations in entity +classes. ### Code Example ```java + @Test public void complexHeaderRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() - // Set the number of header rows, default is 1 - .headRowNumber(2) - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() + // Set the number of header rows, default is 1 + .headRowNumber(2) + .doRead(); } ``` @@ -78,11 +84,12 @@ Set header POJO using the `head()` method. ### Code Example ```java + @Test public void headerPojoRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, new DemoDataListener()) + FesodSheet.read(fileName, new DemoDataListener()) .head(DemoData.class) .sheet() .doRead(); diff --git a/website/docs/sheet/read/num-rows.md b/website/docs/sheet/read/num-rows.md new file mode 100644 index 000000000..d77d3cc5e --- /dev/null +++ b/website/docs/sheet/read/num-rows.md @@ -0,0 +1,51 @@ +--- +id: 'num-rows' +title: 'Rows' +--- + +# Reading Rows + +This chapter introduces how to read a specified number of rows. + +## Overview + +During data analysis and processing, quickly viewing the first few rows of a spreadsheet file can help us better +understand the data structure and content. +By default, Fesod reads all data from the entire spreadsheet file. +However, by setting the `numRows` parameter, you can limit the number of rows to read. 0 means no limit on the number of +rows, i.e., read all rows. The row count includes header rows. + +## All Sheets + +### Code Example + +```java + +@Test +public void allSheetRead() { + // Read the first 100 rows + FesodSheet.read(fileName, DemoData.class, new PageReadListener(dataList -> { + for (DemoData demoData : dataList) { + log.info("Read one record: {}", JSON.toJSONString(demoData)); + } + })).numRows(100).sheet().doRead(); +} +``` + +--- + +## Single Sheet + +### Code Example + +```java + +@Test +public void singleSheetRead() { + try (ExcelReader excelReader = FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).build()) { + ReadSheet readSheet = FesodSheet.readSheet(0).build(); + readSheet.setNumRows(100); // Read the first 100 rows + excelReader.read(readSheet); + } +} +``` diff --git a/website/docs/read/pojo.md b/website/docs/sheet/read/pojo.md similarity index 78% rename from website/docs/read/pojo.md rename to website/docs/sheet/read/pojo.md index 54ca7ee55..75cb62da4 100644 --- a/website/docs/read/pojo.md +++ b/website/docs/sheet/read/pojo.md @@ -11,13 +11,15 @@ This chapter introduces how to read data by configuring POJO classes. ### Overview -You can read Excel data by specifying **column names** or **column indexes**. This makes interaction with dynamically generated Excel files more flexible. +You can read spreadsheet data by specifying **column names** or **column indexes**. This makes interaction with +dynamically generated spreadsheet files more flexible. ### Example Code #### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -36,11 +38,12 @@ public class IndexOrNameData { #### 代码示例 ```java + @Test public void indexOrNameRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, IndexOrNameData.class, new DemoDataListener()) + FesodSheet.read(fileName, IndexOrNameData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -57,6 +60,7 @@ Use the `CellData` type to receive cell data to support formulas and various cel ### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -71,11 +75,12 @@ public class CellDataReadDemoData { ### Code Example ```java + @Test public void cellDataRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, CellDataReadDemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, CellDataReadDemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -87,11 +92,14 @@ public void cellDataRead() { ### Overview -FastExcel supports reading Excel files directly without defining POJO classes, using `Map` to read data directly. +Fesod supports reading spreadsheet files directly without defining POJO classes, using `Map` to read +data +directly. ### Data Listener ```java + @Slf4j public class NoModelDataListener extends AnalysisEventListener> { diff --git a/website/docs/sheet/read/sheet.md b/website/docs/sheet/read/sheet.md new file mode 100644 index 000000000..f553eab3d --- /dev/null +++ b/website/docs/sheet/read/sheet.md @@ -0,0 +1,88 @@ +--- +id: 'sheet' +title: 'Sheet' +--- + +# Sheet + +This chapter introduces how to configure Sheets to read data. + +## Reading Multiple Sheets + +### Overview + +You can read multiple sheets from a spreadsheet file, but the same sheet cannot be read repeatedly. + +### Code Example + +#### Reading All Sheets + +```java + +@Test +public void readAllSheet() { + String fileName = "path/to/demo.xlsx"; + + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).doReadAll(); +} +``` + +--- + +## Reading Specific Sheets + +### Overview + +You can read a specific sheet from a spreadsheet file, supporting specification by sheet index or name. + +> **Note:** Sheet names are limited to 31 characters in Microsoft Excel. When reading sheets by name, use the actual +> sheet name that appears in the Microsoft Excel file. + +### Code Example + +```java + +@Test +public void readSingleSheet() { + String fileName = "path/to/demo.xlsx"; + + try (ExcelReader excelReader = FesodSheet.read(fileName).build()) { + // Sheet index + ReadSheet sheet1 = FesodSheet.readSheet(0).head(DemoData.class) + .registerReadListener(new DemoDataListener()).build(); + // Sheet name + ReadSheet sheet2 = FesodSheet.readSheet("Sheet2").head(DemoData.class) + .registerReadListener(new DemoDataListener()).build(); + excelReader.read(sheet1, sheet2); + } +} +``` + +--- + +## Ignoring Hidden Sheets + +### Overview + +By setting the `ignoreHiddenSheet` parameter to true, data from sheets in "hidden" state will not be read. +This supports both **"normal hidden"** and **"very hidden"** states. + +### Code Example + +```java + +@Test +public void exceptionRead() { + String fileName = "path/to/demo.xlsx"; + + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .ignoreHiddenSheet(Boolean.TRUE) + .sheet() + .doRead(); +} +``` + +> In Microsoft Excel, Sheets have two hidden states: "normal hidden (xlSheetHidden)" and "very hidden ( +> xlSheetVeryHidden)". Very hidden can be set through `VBA`, and in this case, the hidden sheet cannot be unhidden +> through +> the "Unhide" operation. diff --git a/website/docs/read/simple.md b/website/docs/sheet/read/simple.md similarity index 68% rename from website/docs/read/simple.md rename to website/docs/sheet/read/simple.md index 2d1950d6a..1458e756c 100644 --- a/website/docs/read/simple.md +++ b/website/docs/sheet/read/simple.md @@ -5,13 +5,13 @@ title: 'Simple' # Simple Reading -This chapter introduces how to use FastExcel to perform simple Excel reading operations. +This chapter introduces how to use this project to perform simple spreadsheet reading operations. ## Data Listeners ### Overview -FastExcel provides a listener mechanism for processing each row of data while reading Excel files. +Fesod provides a listener mechanism for processing each row of data while reading spreadsheet files. ### Usage @@ -19,16 +19,17 @@ Data listeners need to be instantiated and support various usage patterns. #### Instantiation -Listeners cannot be managed by Spring and must be re-instantiated each time an Excel file is read. +Listeners cannot be managed by Spring and must be re-instantiated each time a spreadsheet file is read. #### `Lambda` Expressions ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { + FesodSheet.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { for (DemoData demoData : dataList) { log.info("Read one record: {}", JSON.toJSONString(demoData)); } @@ -39,14 +40,15 @@ public void simpleRead() { #### Anonymous Inner Classes ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ReadListener() { + FesodSheet.read(fileName, DemoData.class, new ReadListener() { @Override public void invoke(DemoData data, AnalysisContext context) { - log.info("Read one record: {}", JSON.toJSONString(data)); + log.info("Read one record: {}", JSON.toJSONString(data)); } @Override @@ -60,11 +62,12 @@ public void simpleRead() { #### Data Listeners ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -76,13 +79,15 @@ public void simpleRead() { ### Overview -FastExcel provides a simple way to read Excel files. Users only need to define a POJO class to represent the data structure, then read data through FastExcel's listener mechanism. +Fesod provides a simple way to read spreadsheet files. Users only need to define a POJO class to represent the data +structure, then read data through Fesod's listener mechanism. ### POJO Class -The `DemoData` POJO class corresponding to the Excel structure: +The `DemoData` POJO class corresponding to the spreadsheet structure: ```java + @Getter @Setter @EqualsAndHashCode @@ -95,9 +100,10 @@ public class DemoData { ### Data Listener -`DemoDataListener` is a custom listener used to process data read from Excel. +`DemoDataListener` is a custom listener used to process data read from spreadsheet. ```java + @Slf4j public class DemoDataListener implements ReadListener { @@ -116,11 +122,12 @@ public class DemoDataListener implements ReadListener { ### Code Example ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -132,11 +139,13 @@ public void simpleRead() { ### Overview -FastExcel supports reading Excel files directly without defining POJO classes, using `Map` to read data directly, where the key is the **column index** and the value is the **cell data**. +Fesod supports reading spreadsheet files directly without defining POJO classes, using `Map` to read +data directly, where the key is the **column index** and the value is the **cell data**. ### Data Listener ```java + @Slf4j public class NoModelDataListener extends AnalysisEventListener> { @@ -158,13 +167,15 @@ public class NoModelDataListener extends AnalysisEventListener list = FastExcel.read(fileName) + List list = FesodSheet.read(fileName) .head(DemoData.class) .sheet() .doReadSync(); @@ -198,15 +210,17 @@ public void synchronousReadToObjectList() { #### Reading as Map List -When not using POJOs, each row can be read as a Map, where the key is the column index and the value is the cell content. +When not using POJOs, each row can be read as a Map, where the key is the column index and the value is the cell +content. ```java + @Test public void synchronousReadToMapList() { String fileName = "path/to/demo.xlsx"; // Map List - List> list = FastExcel.read(fileName) + List> list = FesodSheet.read(fileName) .sheet() .doReadSync(); diff --git a/website/docs/read/spring.md b/website/docs/sheet/read/spring.md similarity index 80% rename from website/docs/read/spring.md rename to website/docs/sheet/read/spring.md index 0d25d158c..f1c4d5a46 100644 --- a/website/docs/read/spring.md +++ b/website/docs/sheet/read/spring.md @@ -5,11 +5,13 @@ title: 'Spring' # Spring Integration Guide -This chapter introduces how to integrate and use FastExcel in the Spring framework to handle Excel files uploaded by users. +This chapter introduces how to integrate and use Fesod in the Spring framework to handle spreadsheet files uploaded by +users. ## Overview -By creating RESTful API endpoints, users can upload Excel files using HTTP requests, and the server uses FastExcel to parse the data. +By creating RESTful API endpoints, users can upload spreadsheet files using HTTP requests, and the server uses Fesod to +parse the data. ## Environment Dependencies @@ -18,9 +20,10 @@ By creating RESTful API endpoints, users can upload Excel files using HTTP reque Ensure the necessary dependencies are included in your pom.xml file: ```xml + - cn.idev.excel - fastexcel + org.apache.fesod + fesod {version.number} @@ -37,9 +40,10 @@ Ensure the necessary dependencies are included in your pom.xml file: ### POJO Class -First, define a POJO class for mapping Excel data: +First, define a POJO class for mapping spreadsheet data: ```java + @Getter @Setter @ToString @@ -55,6 +59,7 @@ public class UploadData { Create a listener to handle each row of data: ```java + @Slf4j public class UploadDataListener extends AnalysisEventListener { private final List list = new ArrayList<>(); @@ -78,6 +83,7 @@ public class UploadDataListener extends AnalysisEventListener { Create a controller to handle file upload requests: ```java + @RestController @RequestMapping("/excel") public class ExcelController { @@ -89,7 +95,7 @@ public class ExcelController { } try { - FastExcel.read(file.getInputStream(), UploadData.class, new UploadDataListener()) + FesodSheet.read(file.getInputStream(), UploadData.class, new UploadDataListener()) .sheet() .doRead(); return ResponseEntity.ok("File uploaded and processed successfully!"); @@ -105,11 +111,13 @@ public class ExcelController { ### Multi-Template Parsing -By defining multiple different model classes and processing methods within the same listener, you can extend support for multi-template parsing as needed. +By defining multiple different model classes and processing methods within the same listener, you can extend support for +multi-template parsing as needed. ### Exception Handling -To improve user experience and ensure program robustness, exception handling logic needs to be added during data processing. +To improve user experience and ensure program robustness, exception handling logic needs to be added during data +processing. You can override the `onException` method in custom listeners for detailed exception handling. ### Practical Applications diff --git a/website/docs/write/csv.md b/website/docs/sheet/write/csv.md similarity index 51% rename from website/docs/write/csv.md rename to website/docs/sheet/write/csv.md index 4b0fbce8d..4ecf0a2f9 100644 --- a/website/docs/write/csv.md +++ b/website/docs/sheet/write/csv.md @@ -5,21 +5,25 @@ title: 'CSV' # Writing CSV Files -This chapter introduces how to use FastExcel to write custom CSV files. +This chapter introduces how to use Fesod to write custom CSV files. ## Overview -FastExcel writes CSV files through different parameter configurations. It uses [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) as the underlying implementation and also supports direct configuration through [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) settings to achieve writing objectives. +Fesod writes CSV files through different parameter configurations. It +uses [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) as the underlying implementation and also +supports direct configuration +through [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) +settings to achieve writing objectives. The main parameters are as follows: -| Name | Default Value | Description | -| :--- | :--- | :--- | -| `delimiter` | `,` (comma) | Field delimiter. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.AT` (`@`), `CsvConstant.TAB`, etc. | -| `quote` | `"` (double quote) | Field quote character. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.DOUBLE_QUOTE` (`"`). | -| `recordSeparator` | `CRLF` | Record (line) separator. Varies by operating system, such as `CsvConstant.CRLF` (Windows) or `CsvConstant.LF` (Unix/Linux). | -| `nullString` | `null` | String used to represent `null` values. Note this is different from an empty string `""`. | -| `escape` | `null` | Escape character, determines whether to escape special characters. | +| Name | Default Value | Description | +|:------------------|:-------------------|:------------------------------------------------------------------------------------------------------------------------------------------| +| `delimiter` | `,` (comma) | Field delimiter. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.AT` (`@`), `CsvConstant.TAB`, etc. | +| `quote` | `"` (double quote) | Field quote character. It's recommended to use predefined constants from `CsvConstant`, such as `CsvConstant.DOUBLE_QUOTE` (`"`). | +| `recordSeparator` | `CRLF` | Record (line) separator. Varies by operating system, such as `CsvConstant.CRLF` (Windows) or `CsvConstant.LF` (Unix/Linux). | +| `nullString` | `null` | String used to represent `null` values. Note this is different from an empty string `""`. | +| `escape` | `null` | Escape character, determines whether to escape special characters. | --- @@ -29,17 +33,19 @@ The following sections will explain each parameter in detail with code examples. ### delimiter -`delimiter` specifies the field separator in CSV files. The default value is a comma `,`. Additionally, FastExcel provides constants in `CsvConstant` to simplify usage. +`delimiter` specifies the field separator in CSV files. The default value is a comma `,`. Additionally, Fesod +provides constants in `CsvConstant` to simplify usage. #### Code Example If the CSV file uses `\u0000` as the separator, you can configure it as follows: ```java + @Test public void delimiterDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .delimiter(CsvConstant.UNICODE_EMPTY) .doWrite(data()); @@ -48,16 +54,19 @@ public void delimiterDemo() { ### quote -`quote` specifies the quote character that wraps fields. The default value is double quote `"`. This should be set when field content contains delimiters or line breaks. -> Note: This cannot be the same as the `recordSeparator` setting. It's recommended to use in combination with `QuoteMode`. +`quote` specifies the quote character that wraps fields. The default value is double quote `"`. This should be set when +field content contains delimiters or line breaks. +> Note: This cannot be the same as the `recordSeparator` setting. It's recommended to use in combination with +`QuoteMode`. #### Code Example ```java + @Test public void quoteDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .quote(CsvConstant.DOUBLE_QUOTE, QuoteMode.MINIMAL) .doWrite(data()); @@ -66,15 +75,17 @@ public void quoteDemo() { ### recordSeparator -`recordSeparator` specifies the line separator in the file. Different operating systems may use different line separators (for example, Windows uses `CRLF`, while Unix/Linux uses `LF`). +`recordSeparator` specifies the line separator in the file. Different operating systems may use different line +separators (for example, Windows uses `CRLF`, while Unix/Linux uses `LF`). #### Code Example ```java + @Test public void recordSeparatorDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .recordSeparator(CsvConstant.LF) .doWrite(data()); @@ -89,10 +100,11 @@ For example, you can replace `null` objects with the string `"N/A"`. #### Code Example ```java + @Test public void nullStringDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .nullString("N/A") .doWrite(data()); @@ -106,10 +118,11 @@ public void nullStringDemo() { #### Code Example ```java + @Test public void escapeDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .escape(CsvConstant.BACKSLASH) .doWrite(data()); @@ -119,17 +132,18 @@ public void escapeDemo() { ## CSVFormat Configuration Details and Examples Supports directly building a `CSVFormat` object. -> FastExcel currently still supports this approach, but it's not the most recommended usage method. +> Fesod currently still supports this approach, but it's not the most recommended usage method. ### Code Example ```java + @Test public void csvFormatDemo() { CSVFormat csvFormat = CSVFormat.DEFAULT.builder().setDelimiter(CsvConstant.AT).build(); String csvFile = "path/to/your.csv"; - try (ExcelWriter excelWriter = FastExcel.write(csvFile, DemoData.class).excelType(ExcelTypeEnum.CSV).build()) { + try (ExcelWriter excelWriter = FesodSheet.write(csvFile, DemoData.class).excelType(ExcelTypeEnum.CSV).build()) { WriteWorkbookHolder writeWorkbookHolder = excelWriter.writeContext().writeWorkbookHolder(); Workbook workbook = writeWorkbookHolder.getWorkbook(); // Check if it's an instance of CsvWorkbook @@ -138,7 +152,7 @@ public void csvFormatDemo() { csvWorkbook.setCsvFormat(csvFormat); writeWorkbookHolder.setWorkbook(csvWorkbook); } - WriteSheet writeSheet = FastExcel.writerSheet(0).build(); + WriteSheet writeSheet = FesodSheet.writerSheet(0).build(); excelWriter.write(data(), writeSheet); } } diff --git a/website/docs/write/extra.md b/website/docs/sheet/write/extra.md similarity index 94% rename from website/docs/write/extra.md rename to website/docs/sheet/write/extra.md index ead7baf9a..af117988b 100644 --- a/website/docs/write/extra.md +++ b/website/docs/sheet/write/extra.md @@ -43,7 +43,7 @@ Usage public void commentWrite() { String fileName = "commentWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .inMemory(Boolean.TRUE) // Comments must enable in-memory mode .registerWriteHandler(new CommentWriteHandler()) .sheet("批注示例") @@ -82,7 +82,7 @@ public void writeHyperlinkDataWrite() { // Set hyperlink data.setHyperlink(new WriteCellData<>("点击访问").hyperlink("https://example.com")); - FastExcel.write(fileName, WriteCellDemoData.class) + FesodSheet.write(fileName, WriteCellDemoData.class) .sheet() .doWrite(Collections.singletonList(data)); } @@ -119,7 +119,7 @@ public void writeFormulaDataWrite() { // Set formula data.setFormulaData(new WriteCellData<>("=SUM(A1:A10)")); - FastExcel.write(fileName, WriteCellDemoData.class) + FesodSheet.write(fileName, WriteCellDemoData.class) .sheet() .doWrite(Collections.singletonList(data)); } @@ -145,7 +145,7 @@ public void templateWrite() { String templateFileName = "path/to/template.xlsx"; String fileName = "templateWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .withTemplate(templateFileName) .sheet() .doWrite(data()); @@ -205,12 +205,12 @@ public void mergeWrite() { String fileName = "mergeWrite" + System.currentTimeMillis() + ".xlsx"; // Annotation approach - FastExcel.write(fileName, DemoMergeData.class) + FesodSheet.write(fileName, DemoMergeData.class) .sheet("合并示例") .doWrite(data()); // Custom merge strategy - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .registerWriteHandler(new CustomMergeStrategy()) .sheet("自定义合并") .doWrite(data()); diff --git a/website/docs/write/format.md b/website/docs/sheet/write/format.md similarity index 94% rename from website/docs/write/format.md rename to website/docs/sheet/write/format.md index 195a079df..4eb045210 100644 --- a/website/docs/write/format.md +++ b/website/docs/sheet/write/format.md @@ -39,7 +39,7 @@ public class ConverterData { @Test public void converterWrite() { String fileName = "converterWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, ConverterData.class) + FesodSheet.write(fileName, ConverterData.class) .sheet() .doWrite(data()); } diff --git a/website/docs/write/head.md b/website/docs/sheet/write/head.md similarity index 85% rename from website/docs/write/head.md rename to website/docs/sheet/write/head.md index 55e044413..f73b83f91 100644 --- a/website/docs/write/head.md +++ b/website/docs/sheet/write/head.md @@ -5,7 +5,7 @@ title: 'Head' # Headers -This chapter introduces how to write header data in Excel. +This chapter introduces how to write header data in spreadsheet. ## Complex Header Writing @@ -16,6 +16,7 @@ Supports setting multi-level headers by specifying main titles and subtitles thr ### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -32,12 +33,13 @@ public class ComplexHeadData { ### Code Example ```java + @Test public void complexHeadWrite() { String fileName = "complexHeadWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, ComplexHeadData.class) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, ComplexHeadData.class) + .sheet() + .doWrite(data()); } ``` @@ -56,19 +58,20 @@ Generate dynamic headers in real-time, suitable for scenarios where header conte ### Code Example ```java + @Test public void dynamicHeadWrite() { String fileName = "dynamicHeadWrite" + System.currentTimeMillis() + ".xlsx"; List> head = Arrays.asList( - Collections.singletonList("动态字符串标题"), - Collections.singletonList("动态数字标题"), - Collections.singletonList("动态日期标题")); - - FastExcel.write(fileName) - .head(head) - .sheet() - .doWrite(data()); + Collections.singletonList("动态字符串标题"), + Collections.singletonList("动态数字标题"), + Collections.singletonList("动态日期标题")); + + FesodSheet.write(fileName) + .head(head) + .sheet() + .doWrite(data()); } ``` diff --git a/website/docs/write/image.md b/website/docs/sheet/write/image.md similarity index 95% rename from website/docs/write/image.md rename to website/docs/sheet/write/image.md index c0ddfcebd..6e40bd0f9 100644 --- a/website/docs/write/image.md +++ b/website/docs/sheet/write/image.md @@ -16,6 +16,7 @@ Supports exporting images through various methods including files, streams, byte #### POJO Class ```java + @Getter @Setter @EqualsAndHashCode @@ -46,7 +47,7 @@ public void imageWrite() throws Exception { data.setUrl(new URL("https://example.com/image.jpg")); list.add(data); - FastExcel.write(fileName, ImageDemoData.class) + FesodSheet.write(fileName, ImageDemoData.class) .sheet() .doWrite(list); } diff --git a/website/docs/write/pojo.md b/website/docs/sheet/write/pojo.md similarity index 91% rename from website/docs/write/pojo.md rename to website/docs/sheet/write/pojo.md index 6342680c1..841b2a1e5 100644 --- a/website/docs/write/pojo.md +++ b/website/docs/sheet/write/pojo.md @@ -11,7 +11,8 @@ This chapter introduces how to write data by configuring POJO classes. ### Overview -Dynamically select columns to export by setting a collection of column names, supporting ignoring columns or exporting only specific columns. +Dynamically select columns to export by setting a collection of column names, supporting ignoring columns or exporting +only specific columns. ### Code Examples @@ -23,7 +24,7 @@ public void excludeOrIncludeWrite() { String fileName = "excludeColumnFieldWrite" + System.currentTimeMillis() + ".xlsx"; Set excludeColumns = Set.of("date"); - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .excludeColumnFieldNames(excludeColumns) .sheet() .doWrite(data()); @@ -38,7 +39,7 @@ public void excludeOrIncludeWrite() { String fileName = "includeColumnFiledWrite" + System.currentTimeMillis() + ".xlsx"; Set includeColumns = Set.of("date"); - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .includeColumnFiledNames(includeColumns) .sheet() .doWrite(data()); @@ -79,7 +80,7 @@ public class IndexData { @Test public void indexWrite() { String fileName = "indexWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, IndexData.class) + FesodSheet.write(fileName, IndexData.class) .sheet() .doWrite(data()); } @@ -104,7 +105,7 @@ Write data directly using `List>` to define headers and data withou public void noModelWrite() { String fileName = "noModelWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName) + FesodSheet.write(fileName) .head(head()) // Dynamic headers .sheet("无对象写入") .doWrite(dataList()); diff --git a/website/docs/write/sheet.md b/website/docs/sheet/write/sheet.md similarity index 70% rename from website/docs/write/sheet.md rename to website/docs/sheet/write/sheet.md index 83f3751af..8f20051b1 100644 --- a/website/docs/write/sheet.md +++ b/website/docs/sheet/write/sheet.md @@ -18,12 +18,13 @@ Write data in batches to the same Sheet. ### Code Example ```java + @Test public void writeSingleSheet() { String fileName = "repeatedWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Sheet1").build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Sheet1").build(); for (int i = 0; i < 5; i++) { excelWriter.write(data(), writeSheet); } @@ -46,13 +47,14 @@ Write data in batches to multiple Sheets, enabling paginated writing for large d ### Code Example ```java + @Test public void writeMultiSheet() { String fileName = "repeatedWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { for (int i = 0; i < 5; i++) { - WriteSheet writeSheet = FastExcel.writerSheet(i, "Sheet" + i).build(); + WriteSheet writeSheet = FesodSheet.writerSheet(i, "Sheet" + i).build(); excelWriter.write(data(), writeSheet); } } @@ -74,14 +76,15 @@ Supports using multiple Tables within a single Sheet for segmented writing. ### Code Example ```java + @Test public void tableWrite() { String fileName = "tableWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Table示例").build(); - WriteTable table1 = FastExcel.writerTable(0).build(); - WriteTable table2 = FastExcel.writerTable(1).build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Table示例").build(); + WriteTable table1 = FesodSheet.writerTable(0).build(); + WriteTable table2 = FesodSheet.writerTable(1).build(); excelWriter.write(data(), writeSheet, table1); excelWriter.write(data(), writeSheet, table2); diff --git a/website/docs/write/simple.md b/website/docs/sheet/write/simple.md similarity index 64% rename from website/docs/write/simple.md rename to website/docs/sheet/write/simple.md index 1e665fec9..5e80fad20 100644 --- a/website/docs/write/simple.md +++ b/website/docs/sheet/write/simple.md @@ -5,20 +5,21 @@ title: 'Simple' # Simple Writing -This chapter introduces how to use FastExcel to perform simple Excel writing operations. +This chapter introduces how to use Fesod to perform simple spreadsheet writing operations. ## Overview -Use FastExcel for simple Excel data writing to quickly write entity objects to Excel files. +Use Fesod for simple spreadsheet data writing to quickly write entity objects to spreadsheet files. This is the most basic and commonly used writing approach. ## Code Examples ### POJO Class -The `DemoData` POJO class corresponding to the Excel structure: +The `DemoData` POJO class corresponding to the spreadsheet structure: ```java + @Getter @Setter @EqualsAndHashCode @@ -52,43 +53,46 @@ private List data() { ### Writing Methods -FastExcel provides multiple writing methods, including `Lambda` expressions, data lists, `ExcelWriter` objects, etc. +Fesod provides multiple writing methods, including `Lambda` expressions, data lists, `ExcelWriter` objects, etc. #### `Lambda` Expression ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .sheet("Sheet1") - .doWrite(() -> data()); + FesodSheet.write(fileName, DemoData.class) + .sheet("Sheet1") + .doWrite(() -> data()); } ``` #### Data List ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .sheet("Sheet1") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .sheet("Sheet1") + .doWrite(data()); } ``` #### `ExcelWriter` Object ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Sheet1").build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Sheet1").build(); excelWriter.write(data(), writeSheet); } } diff --git a/website/docs/write/spring.md b/website/docs/sheet/write/spring.md similarity index 57% rename from website/docs/write/spring.md rename to website/docs/sheet/write/spring.md index 66a9d507e..3f5097354 100644 --- a/website/docs/write/spring.md +++ b/website/docs/sheet/write/spring.md @@ -5,17 +5,19 @@ title: 'Spring' # Spring Integration Guide -This chapter introduces how to integrate and use FastExcel in the Spring framework to generate Excel files. +This chapter introduces how to integrate and use Fesod in the Spring framework to generate spreadsheet files. ## Spring Controller Example ### Overview -In Spring Boot projects, you can generate Excel files and provide download functionality through HTTP interfaces, making it convenient to use FastExcel in web environments. +In Spring Boot projects, you can generate spreadsheet files and provide download functionality through HTTP interfaces, +making it convenient to use Fesod in web environments. ### Code Example ```java + @GetMapping("download") public void download(HttpServletResponse response) throws IOException { response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); @@ -23,8 +25,8 @@ public void download(HttpServletResponse response) throws IOException { String fileName = URLEncoder.encode("demo", "UTF-8").replaceAll("\\+", "%20"); response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx"); - FastExcel.write(response.getOutputStream(), DemoData.class) - .sheet("Sheet1") - .doWrite(data()); + FesodSheet.write(response.getOutputStream(), DemoData.class) + .sheet("Sheet1") + .doWrite(data()); } ``` diff --git a/website/docs/write/style.md b/website/docs/sheet/write/style.md similarity index 94% rename from website/docs/write/style.md rename to website/docs/sheet/write/style.md index 3b6ff5692..8a4c1c5e7 100644 --- a/website/docs/write/style.md +++ b/website/docs/sheet/write/style.md @@ -47,13 +47,14 @@ public class DemoStyleData { ### Code Example ```java + @Test public void annotationStyleWrite() { String fileName = "annotationStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoStyleData.class) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, DemoStyleData.class) + .sheet() + .doWrite(data()); } ``` @@ -95,7 +96,7 @@ public void handlerStyleWrite() { HorizontalCellStyleStrategy styleStrategy = new HorizontalCellStyleStrategy(headStyle, contentStyle); - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .registerWriteHandler(styleStrategy) .sheet("样式模板") .doWrite(data()); @@ -112,7 +113,8 @@ public void handlerStyleWrite() { ### Overview -If existing strategies cannot meet requirements, you can implement the `CellWriteHandler` interface for complete custom control over styling. +If existing strategies cannot meet requirements, you can implement the `CellWriteHandler` interface for complete custom +control over styling. ### Code Example @@ -152,7 +154,7 @@ Usage public void customCellStyleWrite() { String fileName = "customCellStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .registerWriteHandler(new CustomCellStyleWriteHandler()) .sheet("自定义样式") .doWrite(data()); @@ -174,7 +176,7 @@ Directly manipulate POI's `CellStyle`, suitable for precise style control. public void poiStyleWrite() { String fileName = "poiStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .registerWriteHandler(new CellWriteHandler() { @Override public void afterCellDispose(CellWriteHandlerContext context) { @@ -232,7 +234,7 @@ public class WidthAndHeightData { public void widthAndHeightWrite() { String fileName = "widthAndHeightWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, WidthAndHeightData.class) + FesodSheet.write(fileName, WidthAndHeightData.class) .sheet() .doWrite(data()); } diff --git a/website/i18n/en/code.json b/website/i18n/en/code.json index 51ad6d8d6..bf056e01d 100644 --- a/website/i18n/en/code.json +++ b/website/i18n/en/code.json @@ -364,5 +364,40 @@ }, "team.thanks": { "message": "Thanks to all wonderful contributor, who already contributed to Apache Fesod (Incubating)." + }, + "theme.SearchBar.noResultsText": { + "message": "No results" + }, + "theme.SearchBar.seeAllOutsideContext": { + "message": "See all results outside \"{context}\"" + }, + "theme.SearchBar.searchInContext": { + "message": "See all results within \"{context}\"" + }, + "theme.SearchBar.seeAll": { + "message": "See all results" + }, + "theme.SearchBar.label": { + "message": "Search", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "Search results for \"{query}\"", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "Search the documentation", + "description": "The search page title for empty query" + }, + "theme.SearchPage.searchContext.everywhere": { + "message": "Everywhere" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "1 document found|{count} documents found", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.noResultsText": { + "message": "No documents were found", + "description": "The paragraph for empty search result" } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs-community/current.json b/website/i18n/en/docusaurus-plugin-content-docs-community/current.json index dd30528de..3a041ecbd 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs-community/current.json +++ b/website/i18n/en/docusaurus-plugin-content-docs-community/current.json @@ -2,5 +2,21 @@ "version.label": { "message": "Next", "description": "The label for version current" + }, + "sidebar.community.category.Contribution": { + "message": "Contribution", + "description": "The label for category Contribution in sidebar community" + }, + "sidebar.community.category.Committers": { + "message": "Committers", + "description": "The label for category Committers in sidebar community" + }, + "sidebar.community.category.PPMC Members": { + "message": "PPMC Members", + "description": "The label for category PPMC Members in sidebar community" + }, + "sidebar.community.category.Release": { + "message": "Release", + "description": "The label for category Release in sidebar community" } } diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current.json b/website/i18n/en/docusaurus-plugin-content-docs/current.json index 59def22d6..ef464759c 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current.json @@ -22,5 +22,9 @@ "sidebar.docs.category.help": { "message": "Help", "description": "The label for category help in sidebar docs" + }, + "sidebar.docs.category.fesod-sheet": { + "message": "Fesod Sheet", + "description": "The label for category fesod-sheet in sidebar docs" } } diff --git a/website/i18n/en/docusaurus-theme-classic/navbar.json b/website/i18n/en/docusaurus-theme-classic/navbar.json index c4e146cff..3789faa75 100644 --- a/website/i18n/en/docusaurus-theme-classic/navbar.json +++ b/website/i18n/en/docusaurus-theme-classic/navbar.json @@ -50,5 +50,9 @@ "item.label.Code of Conduct": { "message": "Code of Conduct", "description": "Navbar item with label Code of Conduct" + }, + "item.label.Team": { + "message": "Team", + "description": "Navbar item with label Team" } } diff --git a/website/i18n/zh-cn/code.json b/website/i18n/zh-cn/code.json index fbbeee00c..e65d040dc 100644 --- a/website/i18n/zh-cn/code.json +++ b/website/i18n/zh-cn/code.json @@ -1,6 +1,6 @@ { "site.description": { - "message": "快速、简洁、解决大文件内存溢出的 Java 处理 Excel 工具" + "message": "快速、简洁、解决大文件内存溢出的 Java 处理电子表格工具" }, "quickstart": { "message": "快速开始" @@ -12,13 +12,13 @@ "message": "快速" }, "homepage.feature.quick.description": { - "message": "专注于性能优化，能够高效处理大规模的 Excel 数据。相比一些传统的 Excel 处理库，它能显著降低内存占用" + "message": "专注于性能优化，能够高效处理大规模的电子表格数据。相比一些传统的电子表格处理库，它能显著降低内存占用" }, "homepage.feature.simple.title": { "message": "简洁" }, "homepage.feature.simple.description": { - "message": "提供了简洁直观的 API，使得开发者可以轻松集成到项目中，无论是简单的 Excel 操作还是复杂的数据处理都能快速上手" + "message": "提供了简洁直观的 API，使得开发者可以轻松集成到项目中，无论是简单的电子表格操作还是复杂的数据处理都能快速上手" }, "homepage.feature.bigdata": { "message": "大文件" diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json index 56c6ef499..e24d98d4b 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current.json @@ -22,5 +22,9 @@ "sidebar.docs.category.help": { "message": "帮助", "description": "The label for category help in sidebar docs" + }, + "sidebar.docs.category.fesod-sheet": { + "message": "Fesod Sheet", + "description": "The label for category fesod-sheet in sidebar docs" } } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/annotation.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/annotation.md deleted file mode 100644 index 9ede6f9b5..000000000 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/annotation.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -id: 'annotation' -title: '注解' ---- - -# 注解 - -本章节介绍读取 FastExcel 中提供的注解。 - -## 实体类注解 - -实体类是读写操作的基础。FastExcel 提供了多种注解，帮助开发者轻松定义字段和格式。 - -### **`@ExcelProperty`** - -定义 Excel 列名和映射的字段名。 具体参数如下： - -| 名称 | 默认值 | 描述 | -|-----------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| -| value | 空 | 用于匹配 excel 中的头，必须全匹配,如果有多行头，会匹配最后一行头 | -| order | Integer.MAX_VALUE | 优先级高于 `value`，会根据 `order` 的顺序来匹配实体和 excel 中数据的顺序 | -| index | -1 | 优先级高于 `value` 和 `order`，会根据 `index` 直接指定到 excel 中具体的哪一列 | -| converter | 自动选择 | 指定当前字段用什么转换器，默认会自动选择。读的情况下只要实现 `cn.idev.excel.converters.Converter#convertToJavaData(com.idev.excel.converters.ReadConverterContext)` 方法即可 | - -### `@ExcelIgnore` - -默认所有字段都会和 Excel 去匹配，加了这个注解会忽略该字段。 - -### `@ExcelIgnoreUnannotated` - -默认不加 `@ExcelProperty` 的注解的都会参与读写，加了不会参与读写。 - -### **`@DateTimeFormat`** - -日期转换，用 `String` 去接收 excel 日期格式的数据会调用这个注解,参数如下： - -| 名称 | 默认值 | 描述 | -|------------------|------|----------------------------------------------------------------------| -| value | 空 | 参照 `java.text.SimpleDateFormat` 书写即可 | -| use1904windowing | 自动选择 | excel 中时间是存储 1900 年起的一个双精度浮点数，但是有时候默认开始日期是 1904，所以设置这个值改成默认 1904 年开始 | - -### **`@NumberFormat`** - -数字转换，用 `String` 去接收 excel 数字格式的数据会调用这个注解。 - -| 名称 | 默认值 | 描述 | -|--------------|----------------------|-----------------------------------| -| value | 空 | 参照 `java.text.DecimalFormat` 书写即可 | -| roundingMode | RoundingMode.HALF_UP | 格式化的时候设置舍入模式 | - -### **`@ColumnWidth`** - -指定列宽。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/large-data.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/large-data.md deleted file mode 100644 index e1cf7a63f..000000000 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/large-data.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: 'large-data' -title: '大数据量文件' ---- - -# 大数据量文件 - -## 读取 - -### 概述 - -当需要读取 10M 大小以上的文件时，Excel 03 没有办法处理，相对内存占用大很多。Excel 07 版本有个[共享字符串](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/working-with-the-shared-string-table)的概念，这个会非常占用内存，如果全部读取到内存的话，大概是 Excel 文件的大小的 3-10 倍，所以 FastExcel 用先存储文件的，然后再反序列化去读取的策略来节约内存。当然需要通过文件反序列化以后，效率会降低，大概降低 30-50%（不一定，也看命中率，可能会超过100%）。 - -如果对读取效率感觉还能接受，就用默认的，永久占用（单个 Excel 读取整个过程）一般不会超过 50M (大概率就 30M)，剩下临时的 GC 会很快回收。 - -### 默认策略 - -默认大文件处理会自动判断，共享字符串 5M 以下会使用内存存储，大概占用 15-50M 的内存，超过 5M 则使用文件存储，然后文件存储也要设置多内存用来存放临时的共享字符串，默认 20M。除了共享字符串占用内存外，其他占用较少，所以可以预估 10M，所以默认大概 30M 就能读取一个超级大的文件。 - -### 配置内存 - -如果想自定义设置，首先要确定大概愿意花多少内存来读取一个超级大的 Excel，比如希望读取 Excel 最多占用 100M 内存（是读取过程中永久占用，新生代马上回收的不算），那就设置使用文件来存储共享字符串的大小判断为 20M (小于 20M 存内存，大于存临时文件)，然后设置文件存储时临时共享字符串占用内存大小 90M 差不多。 - -如果最大文件条数也就十几二十万，然后 Excel 也就是十几二十M，而且不会有很高的并发，内存也较大 - -```java -// 强制使用内存存储，这样大概一个 20M 的 Excel 使用 150M（很多临时对象，所以 100M 会一直 GC）的内存 -// 这样效率会比上面的复杂的策略高很多 -// 这里再说明下 就是加了个readCache(new MapCache()) 参数而已，其他的参照其他示例写 -FastExcel.read().readCache(new MapCache()); -``` - -对并发要求较高，而且都是经常有超级大文件 - -```java -// 第一个参数的意思是多少M共享字符串以后，采用文件存储（单位 MB，默认 5M） -// 第二个参数 文件存储时，内存存放多少M缓存数据，默认 20M -// 比如 你希望用 100M 内存(这里说的是解析过程中的永久占用，临时对象不算)来解析excel，前面算过了，大概是 20M+90M，所以设置参数为：20 和 90 -// 这里再说明下 就是加了个 readCacheSelector(new SimpleReadCacheSelector(5, 20)) 参数而已，其他的参照其他示例写 -FastExcel.read().readCacheSelector(new SimpleReadCacheSelector(5, 20)); -``` - -### 关于 maxCacheActivateSize - -FastExcel 在使用文件存储的时候，会把共享字符串拆分成 **1000** 条一批，然后放到文件存储。然后 Excel 来读取共享字符串大概率是按照顺序的，所以默认 20M 的 1000 条的数据放在内存，命中后直接返回，没命中去读文件。所以不能设置太小，太小了，很难命中，一直去读取文件，太大了的话会占用过多的内存。 - -判断 maxCacheActivateSize 是否需要调整，开启 `debug` 日志会输出 `Already put :4000000` 最后一次输出，大概可以得出值为 400W，然后看`Cache misses count:4001`得到值为 4K，`400W/4K=1000` 这代表已经 `maxCacheActivateSize` 已经非常合理了。如果小于 500 问题就非常大了，500 到 1000 应该都还行。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/introduce.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/introduce.md index bd2918523..0dff96ea2 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/introduce.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/introduce.md @@ -8,23 +8,24 @@ slug: / ## 介绍 -**Apache Fesod (Incubating)** 是一款高性能且内存高效的Java库，用于读写Excel文件，旨在简化开发并确保可靠性。 +**Apache Fesod (Incubating)** 是一款高性能且内存高效的 Java 库，用于读写电子表格文件，旨在简化开发并确保可靠性。 -Apache Fesod (Incubating)）能为开发者和企业提供极大的自由度与灵活性。我们计划在未来引入更多新功能，持续提升用户体验与工具实用性。Apache Fesod (Incubating) 致力于成为您处理Excel文件的最佳选择。 +Apache Fesod (Incubating)）能为开发者和企业提供极大的自由度与灵活性。我们计划在未来引入更多新功能，持续提升用户体验与工具实用性。Apache +Fesod (Incubating) 致力于成为您处理电子表格文件的最佳选择。 项目名称fesod（发音`/ˈfɛsɒd/`）是“fast easy spreadsheet and other documents”的缩写，体现了项目的起源、背景与愿景。 ## 特性 -- **高性能读写**：专注于性能优化，能够高效处理大规模Excel数据。相较于某些传统Excel处理库，它能显著降低内存消耗。 -- **简单易用**：提供简单直观的API，无论进行基础Excel操作还是复杂数据处理，开发者均可轻松集成至项目中。 +- **高性能读写**：专注于性能优化，能够高效处理大规模电子表格数据。相较于某些传统电子表格处理库，它能显著降低内存消耗。 +- **简单易用**：提供简单直观的API，无论进行基础电子表格操作还是复杂数据处理，开发者均可轻松集成至项目中。 - **流式操作**：支持流式读取，有效规避一次性加载海量数据的瓶颈。此设计在处理数十万乃至数百万行数据时尤为关键。 ## 示例 ### 读取 -下面是读取 Excel 文档的例子： +下面是读取电子表格文档的例子： ```java // 实现 ReadListener 接口，设置读取数据的操作 @@ -42,14 +43,14 @@ public class DemoDataListener implements ReadListener { public static void main(String[] args) { String fileName = "demo.xlsx"; - // 读取 Excel 文件 - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); + // 读取文件 + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); } ``` ### 写入 -下面是一个创建 Excel 文档的简单例子： +下面是一个创建电子表格文档的简单例子： ```java // 示例数据类 @@ -80,6 +81,6 @@ private static List data() { public static void main(String[] args) { String fileName = "demo.xlsx"; // 创建一个名为“模板”的 sheet 页，并写入数据 - FastExcel.write(fileName, DemoData.class).sheet("模板").doWrite(data()); + FesodSheet.write(fileName, DemoData.class).sheet("模板").doWrite(data()); } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/example.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/example.md index e37c7efce..0d2049bbb 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/example.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/example.md @@ -3,11 +3,11 @@ id: 'simple-example' title: '简单示例' --- -# 简单示例 +## Fesod Sheet 示例 -## 读取 +### 读取 -下面是读取 Excel 文件的例子： +下面是读取电子表格文件的例子： ```java // 实现 ReadListener 接口，设置读取数据的操作 @@ -25,14 +25,14 @@ public class DemoDataListener implements ReadListener { public static void main(String[] args) { String fileName = "demo.xlsx"; - // 读取 Excel 文件 - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); + // 读取文件 + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).sheet().doRead(); } ``` -## 写入 +### 写入 -下面是一个创建 Excel 文档的简单例子： +下面是一个创建电子表格文档的简单例子： ```java // 示例数据类 @@ -63,6 +63,6 @@ private static List data() { public static void main(String[] args) { String fileName = "demo.xlsx"; // 创建一个名为“模板”的 sheet 页，并写入数据 - FastExcel.write(fileName, DemoData.class).sheet("模板").doWrite(data()); + FesodSheet.write(fileName, DemoData.class).sheet("模板").doWrite(data()); } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/guide.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/guide.md index 267585cd9..026cbc081 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/guide.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/quickstart/guide.md @@ -7,7 +7,7 @@ title: '指南' ## 兼容说明 -下表列出了各版本 FastExcel 基础库对 Java 语言版本最低要求的情况： +下表列出了各版本 Fesod 基础库对 Java 语言版本最低要求的情况： | 版本 | jdk版本支持范围 | 备注 | |-------|--------------|----| @@ -16,14 +16,14 @@ title: '指南' | 1.1.x | jdk8 - jdk21 | | | 1.0.x | jdk8 - jdk21 | | -我们强烈建议您使用最新版本的 FastExcel，因为最新版本中的性能优化、BUG 修复和新功能都会让您的使用更加方便。 +我们强烈建议您使用最新版本的 Fesod，因为最新版本中的性能优化、BUG 修复和新功能都会让您的使用更加方便。 -> 当前 FastExcel 底层使用 poi 作为基础包，如果您的项目中已经有 poi 相关组件，需要您手动排除 poi 的相关 jar 包。 +> 当前 Fesod 底层使用 poi 作为基础包，如果您的项目中已经有 poi 相关组件，需要您手动排除 poi 的相关 jar 包。 ## 版本更新 -您可以在 [版本升级详情](https://github.com/fast-excel/fastexcel/blob/main/CHANGELOG.md) -中查询到具体的版本更新细节。您也可以在 [Maven 中心仓库](https://mvnrepository.com/artifact/cn.idev.excel/fastexcel) +您可以在 [版本发布](https://github.com/apache/fesod/releases) +中查询到具体的版本更新细节。您也可以在 [Maven 中心仓库](https://mvnrepository.com/artifact/org.apache.fesod/fesod) 中查询到所有的版本。 ## Maven @@ -33,8 +33,8 @@ title: '指南' ```xml - cn.idev.excel - fastexcel + org.apache.fesod + fesod 版本号 ``` @@ -45,6 +45,6 @@ title: '指南' ```gradle dependencies { - implementation 'cn.idev.excel:fastexcel:版本号' + implementation 'org.apache.fesod:fesod:版本号' } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/num-rows.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/num-rows.md deleted file mode 100644 index 20c756d4a..000000000 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/num-rows.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -id: 'num-rows' -title: '行数' ---- - -# 读取行 - -本章节将介绍读取指定的行数。 - -## 概述 - -在数据分析和处理过程中，快速查看 Excel 文件的前几行内容可以帮助我们更好地理解数据结构和内容。默认情况下，FastExcel 会读取整个 Excel 文件的所有数据，通过设置 `numRows` 参数可以限制读取的行数。0 表示不限制行数，即读取所有行，行数包括表头行。 - -## 所有的 Sheet - -### 代码示例 - -```java -@Test -public void allSheetRead() { - // 读取前100行 - FastExcel.read(fileName, DemoData.class, new PageReadListener(dataList -> { - for (DemoData demoData : dataList) { - log.info("读取到一条数据{}", JSON.toJSONString(demoData)); - } - })).numRows(100).sheet().doRead(); -} -``` - ---- - -## 单个 sheet - -### 代码示例 - -```java -@Test -public void singleSheetRead() { - try (ExcelReader excelReader = FastExcel.read(fileName, DemoData.class, new DemoDataListener()).build()) { - ReadSheet readSheet = FastExcel.readSheet(0).build(); - readSheet.setNumRows(100); // 读取前100行 - excelReader.read(readSheet); - } -} -``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/fill/fill.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md similarity index 75% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/fill/fill.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md index e0bb3743b..950d7c9f0 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/fill/fill.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md @@ -5,17 +5,18 @@ title: '填充' # 填充 -本章节介绍如何使用 FastExcel 来填充数据到文件中。 +本章节介绍如何使用 Fesod 来填充数据到文件中。 ## 简单填充 ### 概述 -基于模板文件，通过对象或 Map 填充数据到 Excel 中。 +基于模板文件，通过对象或 Map 填充数据到电子表格中。 ### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -29,6 +30,7 @@ public class FillData { ### 代码示例 ```java + @Test public void simpleFill() { String templateFileName = "path/to/simple.xlsx"; @@ -37,19 +39,19 @@ public void simpleFill() { FillData fillData = new FillData(); fillData.setName("张三"); fillData.setNumber(5.2); - FastExcel.write("simpleFill.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(fillData); + FesodSheet.write("simpleFill.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(fillData); // 方案2：基于 Map 填充 Map map = new HashMap<>(); map.put("name", "张三"); map.put("number", 5.2); - FastExcel.write("simpleFillMap.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(map); + FesodSheet.write("simpleFillMap.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(map); } ``` @@ -72,19 +74,20 @@ public void simpleFill() { ### 代码示例 ```java + @Test public void listFill() { String templateFileName = "path/to/list.xlsx"; // 方案1：一次性填充所有数据 - FastExcel.write("listFill.xlsx") - .withTemplate(templateFileName) - .sheet() - .doFill(data()); + FesodSheet.write("listFill.xlsx") + .withTemplate(templateFileName) + .sheet() + .doFill(data()); // 方案2：分批填充 - try (ExcelWriter writer = FastExcel.write("listFillBatch.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("listFillBatch.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); writer.fill(data(), writeSheet); writer.fill(data(), writeSheet); } @@ -110,12 +113,13 @@ public void listFill() { ### 代码示例 ```java + @Test public void complexFill() { String templateFileName = "path/to/complex.xlsx"; - try (ExcelWriter writer = FastExcel.write("complexFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("complexFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // 填充列表数据，开启 forceNewRow FillConfig config = FillConfig.builder().forceNewRow(true).build(); @@ -149,12 +153,13 @@ public void complexFill() { ### 代码示例 ```java + @Test public void complexFillWithTable() { String templateFileName = "path/to/complexFillWithTable.xlsx"; - try (ExcelWriter writer = FastExcel.write("complexFillWithTable.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("complexFillWithTable.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // 填充列表数据 writer.fill(data(), writeSheet); @@ -191,12 +196,13 @@ public void complexFillWithTable() { ### 代码示例 ```java + @Test public void horizontalFill() { String templateFileName = "path/to/horizontal.xlsx"; - try (ExcelWriter writer = FastExcel.write("horizontalFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("horizontalFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); FillConfig config = FillConfig.builder().direction(WriteDirectionEnum.HORIZONTAL).build(); writer.fill(data(), config, writeSheet); @@ -227,12 +233,13 @@ public void horizontalFill() { ### 代码示例 ```java + @Test public void compositeFill() { String templateFileName = "path/to/composite.xlsx"; - try (ExcelWriter writer = FastExcel.write("compositeFill.xlsx").withTemplate(templateFileName).build()) { - WriteSheet writeSheet = FastExcel.writerSheet().build(); + try (ExcelWriter writer = FesodSheet.write("compositeFill.xlsx").withTemplate(templateFileName).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet().build(); // 使用 FillWrapper 进行多列表填充 writer.fill(new FillWrapper("data1", data()), writeSheet); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/annotation.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/annotation.md new file mode 100644 index 000000000..9b4617766 --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/annotation.md @@ -0,0 +1,53 @@ +--- +id: 'annotation' +title: '注解' +--- + +# 注解 + +本章节介绍读取 FesodSheet 中提供的注解。 + +## 实体类注解 + +实体类是读写操作的基础。FesodSheet 提供了多种注解，帮助开发者轻松定义字段和格式。 + +### **`@ExcelProperty`** + +定义电子表格列名和映射的字段名。 具体参数如下： + +| 名称 | 默认值 | 描述 | +|-----------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| value | 空 | 用于匹配电子表格中的头，必须全匹配,如果有多行头，会匹配最后一行头 | +| order | Integer.MAX_VALUE | 优先级高于 `value`，会根据 `order` 的顺序来匹配实体和电子表格中数据的顺序 | +| index | -1 | 优先级高于 `value` 和 `order`，会根据 `index` 直接指定到电子表格中具体的哪一列 | +| converter | 自动选择 | 指定当前字段用什么转换器，默认会自动选择。读的情况下只要实现 `org.apache.fesod.sheet.converters.Converter#convertToJavaData(org.apache.fesod.sheet.converters.ReadConverterContext)` 方法即可 | + +### `@ExcelIgnore` + +默认所有字段都会和电子表格去匹配，加了这个注解会忽略该字段。 + +### `@ExcelIgnoreUnannotated` + +默认不加 `@ExcelProperty` 的注解的都会参与读写，加了不会参与读写。 + +### **`@DateTimeFormat`** + +日期转换，用 `String` 去接收电子表格日期格式的数据会调用这个注解,参数如下： + +| 名称 | 默认值 | 描述 | +|------------------|------|--------------------------------------------------------------------| +| value | 空 | 参照 `java.text.SimpleDateFormat` 书写即可 | +| use1904windowing | 自动选择 | 电子表格中时间是存储 1900 年起的一个双精度浮点数，但是有时候默认开始日期是 1904，所以设置这个值改成默认 1904 年开始 | + +### **`@NumberFormat`** + +数字转换，用 `String` 去接收电子表格数字格式的数据会调用这个注解。 + +| 名称 | 默认值 | 描述 | +|--------------|----------------------|-----------------------------------| +| value | 空 | 参照 `java.text.DecimalFormat` 书写即可 | +| roundingMode | RoundingMode.HALF_UP | 格式化的时候设置舍入模式 | + +### **`@ColumnWidth`** + +指定列宽。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/core-class.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/core-class.md similarity index 75% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/core-class.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/core-class.md index f6d8fac7f..b1d1d9f5e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/core-class.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/core-class.md @@ -5,15 +5,15 @@ title: '核心类' # 核心类 -本章节介绍读取 FastExcel 中的核心类。 +本章节介绍读取 FesodSheet 中的核心类。 ## 概述 -如果使用 FastExcel 进行自定义读写操作，需要理解其重要的概念和类。 +如果使用 FesodSheet 进行自定义读写操作，需要理解其重要的概念和类。 ## 核心概念 -### FastExcel +### FesodSheet 入口类，用于构建开始各种操作。 @@ -21,8 +21,10 @@ title: '核心类' 对读和写操作分别有对应的 Builder 类： -- **`ExcelReaderBuilder` 和 `ExcelWriterBuilder`**：分别为构建出一个 ReadWorkbook 和 WriteWorkbook，可以理解成一个 excel 对象，一个 excel 只要构建一个。 -- **`ExcelReaderSheetBuilder` 和 `ExcelWriterSheetBuilder`**：分别构建出一个 ReadSheet 和 WriteSheet 对象，可以理解成 excel 里面的一页,每一页都要构建一个。 +- **`ExcelReaderBuilder` 和 `ExcelWriterBuilder`**：分别为构建出一个 ReadWorkbook 和 WriteWorkbook，可以理解成一个电子表格对象，一个 + 电子表格只能构建一个。 +- **`ExcelReaderSheetBuilder` 和 `ExcelWriterSheetBuilder`**：分别构建出一个 ReadSheet 和 WriteSheet 对象，可以理解成 + 电子表格里面的一页,每一页都要构建一个。 - **`CsvReaderBuilder` 和 `CsvWriterBuilder`**：构建内部所需的 CsvFormat。 ### ReadListener @@ -33,7 +35,8 @@ title: '核心类' 在每一个操作包括创建单元格、创建表格等都会调用 WriteHandler 来处理数据。 -所有配置都是继承的，Workbook 的配置会被 Sheet 继承，所以在用 FastExcel 设置参数的时候，在 FastExcel...sheet() 方法之前作用域是整个 sheet,在 FastExcel...csv() 方法之前作用域是整个 csv。 +所有配置都是继承的，Workbook 的配置会被 Sheet 继承，所以在用 FesodSheet 设置参数的时候，在 FesodSheet.sheet() 方法之前作用域是整个 +sheet,在 FesodSheet.csv() 方法之前作用域是整个 csv。 --- @@ -41,12 +44,12 @@ title: '核心类' ### 概述 -`WriteHandler` 是 FastExcel 提供的接口，用于在写入 Excel 文件时拦截写入过程，允许开发者自定义操作，如设置单元格样式、合并单元格、添加超链接、插入批注等。 +`WriteHandler` 是 FesodSheet 提供的接口，用于在写入电子表格文件时拦截写入过程，允许开发者自定义操作，如设置单元格样式、合并单元格、添加超链接、插入批注等。 通过实现 `WriteHandler`，开发者可以深入控制写入流程，以满足复杂的业务需求。 ### 分类 -FastExcel 提供了以下几种 WriteHandler 接口，分别用于处理不同的写入场景： +FesodSheet 提供了以下几种 WriteHandler 接口，分别用于处理不同的写入场景： | 接口名 | 描述 | |-----------------------|-------------------------------------| @@ -61,7 +64,7 @@ FastExcel 提供了以下几种 WriteHandler 接口，分别用于处理不同 - 实现接口中的方法，在方法中定义自定义逻辑。 2. 注册 WriteHandler： - - 在调用 `FastExcel.write()` 时通过 `.registerWriteHandler()` 注册自定义的 WriteHandler。 + - 在调用 `FesodSheet.write()` 时通过 `.registerWriteHandler()` 注册自定义的 WriteHandler。 ### 示例 @@ -72,6 +75,7 @@ FastExcel 提供了以下几种 WriteHandler 接口，分别用于处理不同 自定义 `CellWriteHandler` ```java + @Slf4j public class CustomCellStyleHandler implements CellWriteHandler { @@ -100,14 +104,15 @@ public class CustomCellStyleHandler implements CellWriteHandler { 注册并使用 ```java + @Test public void customCellStyleWrite() { String fileName = "customCellStyleWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CustomCellStyleHandler()) - .sheet("自定义样式") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CustomCellStyleHandler()) + .sheet("自定义样式") + .doWrite(data()); } ``` @@ -118,6 +123,7 @@ public void customCellStyleWrite() { 自定义 `RowWriteHandler` ```java + @Slf4j public class CommentRowWriteHandler implements RowWriteHandler { @@ -141,14 +147,15 @@ public class CommentRowWriteHandler implements RowWriteHandler { 注册并使用 ```java + @Test public void commentWrite() { String fileName = "commentWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CommentRowWriteHandler()) - .sheet("插入批注") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CommentRowWriteHandler()) + .sheet("插入批注") + .doWrite(data()); } ``` @@ -159,6 +166,7 @@ public void commentWrite() { 自定义 `SheetWriteHandler` ```java + @Slf4j public class DropdownSheetWriteHandler implements SheetWriteHandler { @@ -181,14 +189,15 @@ public class DropdownSheetWriteHandler implements SheetWriteHandler { 注册并使用 ```java + @Test public void dropdownWrite() { String fileName = "dropdownWrite.xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new DropdownSheetWriteHandler()) - .sheet("添加下拉框") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new DropdownSheetWriteHandler()) + .sheet("添加下拉框") + .doWrite(data()); } ``` @@ -198,8 +207,8 @@ public void dropdownWrite() { ### 概述 -`ReadListener` 是 FastExcel 提供的接口，用于在读取 Excel 文件时对每一行数据进行处理。 -它是 FastExcel 核心组件之一，允许开发者实现自定义逻辑来处理数据行、处理表头，甚至在读取完成后执行特定操作。 +`ReadListener` 是 FesodSheet 提供的接口，用于在读取电子表格文件时对每一行数据进行处理。 +它是 FesodSheet 核心组件之一，允许开发者实现自定义逻辑来处理数据行、处理表头，甚至在读取完成后执行特定操作。 ### 方法 @@ -210,7 +219,7 @@ public void dropdownWrite() { | `void invoke(T data, AnalysisContext context)` | 当读取到一行数据时触发，`data` 是解析后的当前行对象，`context` 包含读取的上下文信息。 | | `void doAfterAllAnalysed(AnalysisContext context)` | 在所有数据解析完成后调用，可用于资源释放或统计数据处理。 | | `void onException(Exception exception, AnalysisContext context)` *(可选)* | 捕获读取过程中的异常，方便处理解析错误。 | -| `void invokeHead(Map> headMap, AnalysisContext context)` *(可选)* | 获取 Excel 表头信息，用于动态处理表头。 | +| `void invokeHead(Map> headMap, AnalysisContext context)` *(可选)* | 获取表头信息，用于动态处理表头。 | ### 使用场景 @@ -224,7 +233,7 @@ public void dropdownWrite() { - 实现核心方法，根据需要添加数据处理逻辑。 2. 在读取时注册自定义 `ReadListener`： - - 调用 `FastExcel.read()` 方法时，传入自定义监听器实例。 + - 调用 `FesodSheet.read()` 方法时，传入自定义监听器实例。 ### 示例 @@ -233,6 +242,7 @@ public void dropdownWrite() { 自定义 `ReadListener` ```java + @Slf4j public class DemoDataListener implements ReadListener { @@ -268,13 +278,14 @@ public class DemoDataListener implements ReadListener { 使用 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() // 默认读取第一个 Sheet - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() // 默认读取第一个 Sheet + .doRead(); } ``` @@ -283,6 +294,7 @@ public void simpleRead() { 自定义 `ReadListener` ```java + @Slf4j public class HeadDataListener implements ReadListener { @@ -306,13 +318,14 @@ public class HeadDataListener implements ReadListener { 使用 ```java + @Test public void readWithHead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new HeadDataListener()) - .sheet() // 默认读取第一个 Sheet - .doRead(); + FesodSheet.read(fileName, DemoData.class, new HeadDataListener()) + .sheet() // 默认读取第一个 Sheet + .doRead(); } ``` @@ -321,6 +334,7 @@ public void readWithHead() { 自定义 `ReadListener` ```java + @Slf4j public class ExceptionHandlingListener implements ReadListener { @@ -334,46 +348,50 @@ public class ExceptionHandlingListener implements ReadListener { } @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } } ``` 使用 ```java + @Test public void readWithExceptionHandling() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ExceptionHandlingListener()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new ExceptionHandlingListener()) + .sheet() + .doRead(); } ``` #### 分页处理 ```java + @Test public void pageRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { - // 分页批量处理 - log.info("读取到一批数据: {}", JSON.toJSONString(dataList)); - // 实现数据处理逻辑 - })) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { + // 分页批量处理 + log.info("读取到一批数据: {}", JSON.toJSONString(dataList)); + // 实现数据处理逻辑 + })) + .sheet() + .doRead(); } ``` > **说明**： > -> - `PageReadListener` 是 FastExcel 提供的便捷工具类，支持基于分页的批量处理。 +> - `PageReadListener` 是 FesodSheet 提供的便捷工具类，支持基于分页的批量处理。 > - 默认每页大小为 1，可通过构造器指定。 --- @@ -382,11 +400,12 @@ public void pageRead() { ### 概述 -`AnalysisEventListener` 是 FastExcel 中用于处理读取 Excel 数据的核心监听器。它基于事件驱动机制，允许开发者在读取每一行数据时执行自定义操作，并在所有数据解析完成后进行相应处理。它通常用于流式读取大量数据，适合需要处理大数据量、进行批量操作（如批量插入数据库）的场景。 +`AnalysisEventListener` 是 FesodSheet +中用于处理读取数据的核心监听器。它基于事件驱动机制，允许开发者在读取每一行数据时执行自定义操作，并在所有数据解析完成后进行相应处理。它通常用于流式读取大量数据，适合需要处理大数据量、进行批量操作（如批量插入数据库）的场景。 核心特性: -- **逐行读取**：`AnalysisEventListener` 按行读取 Excel 文件的数据，在读取每行数据时执行 `invoke` 方法，适合流式处理。 +- **逐行读取**：`AnalysisEventListener` 按行读取文件的数据，在读取每行数据时执行 `invoke` 方法，适合流式处理。 - **内存控制**：可以设置 `BATCH_COUNT` 来控制每次处理的数据量，避免内存溢出。 - **批量处理**：可以缓存一定数量的数据并批量处理，适用于大数据量场景。 - **事件驱动**：当读取每一行数据时，调用 `invoke` 方法；所有数据读取完毕后，调用 `doAfterAllAnalysed` 方法。 @@ -400,17 +419,17 @@ public void pageRead() { | `invoke(T data, AnalysisContext context)` | 当读取到一行数据时触发，`data` 为解析后的当前行数据，`context` 为读取上下文。 | | `doAfterAllAnalysed(AnalysisContext context)` | 在所有数据解析完成后调用，用于资源清理或批量操作后处理。 | | `onException(Exception exception, AnalysisContext context)` *(可选)* | 捕获并处理解析过程中抛出的异常，方便处理错误数据。 | -| `invokeHead(Map> headMap, AnalysisContext context)` *(可选)* | 获取 Excel 表头数据，常用于动态表头处理。 | +| `invokeHead(Map> headMap, AnalysisContext context)` *(可选)* | 获取表头数据，常用于动态表头处理。 | ### 使用场景 - **流式数据处理**：比如读取大量数据时，可以边读取边处理，减少内存消耗。 -- **批量插入数据库**：如批量处理 Excel 中的行数据并存储到数据库。 +- **批量插入数据库**：如批量处理电子表格中的行数据并存储到数据库。 ### 实现步骤 1. 继承 `AnalysisEventListener` 并实现其方法。 -2. 在读取时传入自定义监听器，通过 `FastExcel.read()` 注册。 +2. 在读取时传入自定义监听器，通过 `FesodSheet.read()` 注册。 ### 示例 @@ -419,6 +438,7 @@ public void pageRead() { 继承 `AnalysisEventListener` ```java + @Slf4j public class DemoDataListener extends AnalysisEventListener { @@ -462,13 +482,14 @@ public class DemoDataListener extends AnalysisEventListener { 使用 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() // 默认读取第一个 Sheet - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() // 默认读取第一个 Sheet + .doRead(); } ``` @@ -479,6 +500,7 @@ public void simpleRead() { 继承 `AnalysisEventListener` ```java + @Slf4j public class DemoDataListenerWithHead extends AnalysisEventListener { @@ -507,13 +529,14 @@ public class DemoDataListenerWithHead extends AnalysisEventListener { 使用 ```java + @Test public void readWithHead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListenerWithHead()) - .sheet() // 默认读取第一个 Sheet - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListenerWithHead()) + .sheet() // 默认读取第一个 Sheet + .doRead(); } ``` @@ -524,6 +547,7 @@ public void readWithHead() { 继承 `AnalysisEventListener` ```java + @Slf4j public class ExceptionHandlingListener extends AnalysisEventListener { @@ -552,19 +576,20 @@ public class ExceptionHandlingListener extends AnalysisEventListener { 使用 ```java + @Test public void readWithExceptionHandling() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ExceptionHandlingListener()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new ExceptionHandlingListener()) + .sheet() + .doRead(); } ``` ### 与 `ReadListener` 比较 -`AnalysisEventListener` 和 `ReadListener` 都是 FastExcel 提供的接口，目的是为了让开发者在读取 Excel 时进行自定义处理，但它们在功能和使用场景上有一些关键的区别。 +`AnalysisEventListener` 和 `ReadListener` 都是 FesodSheet 提供的接口，目的是为了让开发者在读取电子表格时进行自定义处理，但它们在功能和使用场景上有一些关键的区别。 #### 区别 @@ -584,34 +609,37 @@ public void readWithExceptionHandling() { - 使用 `ReadListener`： - 如果你希望简化代码，并且没有复杂的内存控制需求，只需处理每一行数据的逻辑。 - - 适合简单的 Excel 数据读取和异常捕获场景。 - 总的来说，`ReadListener` 是更为简化的接口，适用于较为简单的场景，而 `AnalysisEventListener` 提供了更强的控制力和扩展性，适合复杂的数据处理需求。开发者可以根据实际需求选择合适的监听器。 + - 适合简单的电子表格数据读取和异常捕获场景。 + 总的来说，`ReadListener` 是更为简化的接口，适用于较为简单的场景，而 `AnalysisEventListener` + 提供了更强的控制力和扩展性，适合复杂的数据处理需求。开发者可以根据实际需求选择合适的监听器。 ## Converter ### 概述 -`Converter` 是 FastExcel 提供的接口，用于在处理 Excel 文件时对数据进行转换。允许开发者自定义操作，通过实现 `Converter` 接口，自定义数据转换逻辑。 +`Converter` 是 FesodSheet 提供的接口，用于在处理电子表格文件时对数据进行转换。允许开发者自定义操作，通过实现 `Converter` +接口，自定义数据转换逻辑。 ### 方法 `Converter` 是一个泛型接口，泛型类型是需要被转换的对象类型（如 `Date`)。其核心方法如下： -| 方法名 | 描述 | -|---------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| -| `Class supportJavaTypeKey()`*(可选)* | 返回支持的 Java 对象类型 | -| `CellDataTypeEnum supportExcelTypeKey()`*(可选)* | 返回支持的 Excel 单元格类型，枚举类为 CellDataTypeEnum | -| `T convertToJavaData(ReadCellData cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(可选)* | 将 Excel 单元格数据转换为 Java 对象 | -| `WriteCellData convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(可选)* | 将 Java 对象转换为 Excel 单元格数据对象 | -| `WriteCellData convertToExcelData(WriteConverterContext context)` *(可选)* | 将 Java 对象转换为 Excel 单元格数据对象 | +| 方法名 | 描述 | +|---------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| +| `Class supportJavaTypeKey()`*(可选)* | 返回支持的 Java 对象类型 | +| `CellDataTypeEnum supportExcelTypeKey()`*(可选)* | 返回支持的单元格类型，枚举类为 CellDataTypeEnum | +| `T convertToJavaData(ReadCellData cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(可选)* | 将单元格数据转换为 Java 对象 | +| `WriteCellData convertToExcelData(T value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)` *(可选)* | 将 Java 对象转换为单元格数据对象 | +| `WriteCellData convertToExcelData(WriteConverterContext context)` *(可选)* | 将 Java 对象转换为单元格数据对象 | -FastExcel 默认提供了很多常用类型的转换器， 并已默认在 `DefaultConverterLoader` 中注册。 +FesodSheet 默认提供了很多常用类型的转换器， 并已默认在 `DefaultConverterLoader` 中注册。 -您可以自定义转换器，但类型不能与默认的类型重复。类型注册时，使用的 `ConverterKeyBuild.buildKey(converter.supportJavaTypeKey(), converter.supportExcelTypeKey())` 作为 key 值。 +您可以自定义转换器，但类型不能与默认的类型重复。类型注册时，使用的 +`ConverterKeyBuild.buildKey(converter.supportJavaTypeKey(), converter.supportExcelTypeKey())` 作为 key 值。 ### 使用场景 -- **数据转换**：对 Excel 数据进行转换，如将日期转换为字符串、将字符串转换为日期等。 +- **数据转换**：对电子表格数据进行转换，如将日期转换为字符串、将字符串转换为日期等。 ### 实现步骤 @@ -625,6 +653,7 @@ FastExcel 默认提供了很多常用类型的转换器， 并已默认在 `Defa 实现 `Converter` ```java + @Slf4j public class TimestampNumberConverter implements Converter { @Override @@ -654,20 +683,21 @@ public class TimestampNumberConverter implements Converter { 使用 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; // 读取 - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .registerConverter(new TimestampNumberConverter()) - .sheet() - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .registerConverter(new TimestampNumberConverter()) + .sheet() + .doRead(); // 写入 - FastExcel.write(fileName) - .registerConverter(new TimestampNumberConverter()) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName) + .registerConverter(new TimestampNumberConverter()) + .sheet() + .doWrite(data()); } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/faq.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/faq.md similarity index 68% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/faq.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/faq.md index 58ee5ee81..d4cde4ebc 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/faq.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/faq.md @@ -5,47 +5,52 @@ title: '常见问题' # 常见问题 -本章节介绍使用 FastExcel 时可能遇到的常见问题。 +本章节介绍使用 FesodSheet 时可能遇到的常见问题。 ## 功能限制 -- **Q:** FastExcel支持哪些功能？有哪些不支持的功能？ -- **A:** FastExcel支持Excel文件的高效读写操作，包括CSV格式的支持。不支持的功能包括单个文件的并发写入、读取图片宏等。 +- **Q:** FesodSheet 支持哪些功能？有哪些不支持的功能？ +- **A:** FesodSheet 支持电子表格文件的高效读写操作，包括CSV格式的支持。不支持的功能包括单个文件的并发写入、读取图片宏等。 ## 写操作的选择 -- **Q:** 在写Excel时，何时选择填充方式，何时选择直接写入？ +- **Q:** 在写电子表格时，何时选择填充方式，何时选择直接写入？ - **A:** 对于格式复杂的导出内容，推荐使用模板填充；对于格式简单的场景，直接写入更为高效。 ## Lombok注解 -- **Q:** 使用FastExcel时，实体类中的Lombok注解有何作用？ -- **A:** 实体类中常用的Lombok注解如`@Getter`、`@Setter`、`@EqualsAndHashCode`用于自动生成getter、setter方法及equals和hashCode方法。如果不想使用这些自动生成的方法，可以自行实现。 +- **Q:** 使用 FesodSheet 时，实体类中的Lombok注解有何作用？ +- **A:** 实体类中常用的 Lombok 注解如`@Getter`、`@Setter`、`@EqualsAndHashCode` + 用于自动生成 getter、setter 方法及 equals 和 hashCode 方法。如果不想使用这些自动生成的方法，可以自行实现。 ## 字段匹配 - **Q:** 如何解决部分字段无法正确读取或写入的问题？ -- **A:** 确保实体类字段遵循驼峰命名规则，避免使用`@Accessors(chain = true)`，推荐使用`@Builder`替代。另外，确保实体类中使用了`@ExcelProperty`注解标记参与读写的字段。 +- **A:** 确保实体类字段遵循驼峰命名规则，避免使用`@Accessors(chain = true)`，推荐使用`@Builder`替代。另外，确保实体类中使用了 + `@ExcelProperty`注解标记参与读写的字段。 ## 兼容性问题 -- **Q:** 使用FastExcel时遇到兼容性问题怎么办？ -- **A:** 常见的兼容性问题包括`NoSuchMethodException`、`ClassNotFoundException`、`NoClassDefFoundError`等，通常是由jar包冲突引起。建议检查并清理项目中的依赖，确保使用的FastExcel版本与项目中的其他库兼容。 +- **Q:** 使用 FesodSheet 时遇到兼容性问题怎么办？ +- **A:** 常见的兼容性问题包括`NoSuchMethodException`、`ClassNotFoundException`、`NoClassDefFoundError` + 等，通常是由jar包冲突引起。建议检查并清理项目中的依赖，确保使用的 FesodSheet 版本与项目中的其他库兼容。 ## 线上部署 - **Q:** 本地运行正常，为何线上环境出现问题？ -- **A:** 大多数情况下是由于线上环境缺少必要的字体库导致。可以通过安装字体库（如`dejavu-sans-fonts`和`fontconfig`）或启用内存处理模式来解决问题。 +- **A:** 大多数情况下是由于线上环境缺少必要的字体库导致。可以通过安装字体库（如`dejavu-sans-fonts`和`fontconfig` + ）或启用内存处理模式来解决问题。 ## 并发读取 -- **Q:** 为何不能将Listener交给Spring管理？ -- **A:** Listener不应被Spring管理，因为这会导致Listener变成单例模式，在并发读取文件时可能引发数据混淆问题。每次读取文件时应新建一个Listener实例。 +- **Q:** 为何不能将 Listener 交给 Spring 管理？ +- **A:** Listener 不应被 Spring 管理，因为这会导致 Listener 变成单例模式，在并发读取文件时可能引发数据混淆问题。每次读取文件时应新建一个 + Listener 实例。 ## 性能优化 -- **Q:** 对于10M以上的大型文件，FastExcel提供了哪些读取策略？ -- **A:** FastExcel支持默认的大文件处理策略，以及可以自定义的高速模式和针对高并发、超大文件的优化设置。 +- **Q:** 对于10M以上的大型文件，FesodSheet 提供了哪些读取策略？ +- **A:** FesodSheet 支持默认的大文件处理策略，以及可以自定义的高速模式和针对高并发、超大文件的优化设置。 ## 写入与格式设置 @@ -54,23 +59,25 @@ title: '常见问题' ## 导出问题 -- **Q:** 导出的Excel文件无法打开或提示需要修复，如何解决？ +- **Q:** 导出的电子表格文件无法打开或提示需要修复，如何解决？ - **A:** 这通常是由于前端框架或后端拦截器修改了文件流导致。建议先测试本地导出，确保后端逻辑无误后再排查前端和网络相关的问题。 ## 大文件读取优化 -- **Q:** FastExcel在读取大文件时如何优化内存使用？ -- **A:** FastExcel默认会自动判断大文件的处理方式。对于共享字符串超过5MB的文件，会使用文件存储策略，减少内存占用。可以通过设置`readCache`参数来开启极速模式，但这会增加内存消耗。 +- **Q:** FesodSheet 在读取大文件时如何优化内存使用？ +- **A:** FesodSheet 默认会自动判断大文件的处理方式。对于共享字符串超过 5MB 的文件，会使用文件存储策略，减少内存占用。可以通过设置 + `readCache`参数来开启极速模式，但这会增加内存消耗。 ## 并发处理 -- **Q:** 如何在高并发环境下高效读取Excel文件？ -- **A:** 在高并发环境下，可以使用`SimpleReadCacheSelector`来优化读取性能。通过设置`maxUseMapCacheSize`和`maxCacheActivateBatchCount`参数，可以控制共享字符串的缓存策略，提高命中率，减少文件读取的延迟。 +- **Q:** 如何在高并发环境下高效读取电子表格文件？ +- **A:** 在高并发环境下，可以使用`SimpleReadCacheSelector`来优化读取性能。通过设置`maxUseMapCacheSize`和 + `maxCacheActivateBatchCount`参数，可以控制共享字符串的缓存策略，提高命中率，减少文件读取的延迟。 ## 字段映射 -- **Q:** 如何处理实体类字段与Excel列名不一致的情况？ -- **A:** 可以使用`@ExcelProperty`注解来指定实体类字段与Excel列名的对应关系。例如： +- **Q:** 如何处理实体类字段与电子表格列名不一致的情况？ +- **A:** 可以使用`@ExcelProperty`注解来指定实体类字段与电子表格列名的对应关系。例如： ```java @ExcelProperty("姓名") @@ -79,7 +86,7 @@ title: '常见问题' ## 数据校验 -- **Q:** 如何在读取Excel数据时进行校验？ +- **Q:** 如何在读取电子表格数据时进行校验？ - **A:** 可以在`ReadListener`中实现数据校验逻辑。例如： ```java @@ -117,7 +124,7 @@ title: '常见问题' - **A:** 使用`inMemory(true)`参数可以确保字段正确替换。例如： ```java - FastExcel.write(fileName, DemoData.class).inMemory(true).sheet("模板").doWrite(fillData()); + FesodSheet.write(fileName, DemoData.class).inMemory(true).sheet("模板").doWrite(fillData()); ``` ## 错误处理 @@ -141,32 +148,34 @@ title: '常见问题' ## 依赖冲突 - **Q:** 如何解决依赖冲突问题？ -- **A:** 常见的依赖冲突包括POI、ehcache和commons-io等。建议检查项目中的依赖树，确保使用的版本与FastExcel兼容。可以通过Maven的`dependency:tree`命令查看依赖树。 +- **A:** 常见的依赖冲突包括 POI、ehcache 和 commons-io 等。建议检查项目中的依赖树，确保使用的版本与 FesodSheet 兼容。可以通过 + Maven 的 + `dependency:tree`命令查看依赖树。 ## 性能监控 -- **Q:** 如何监控FastExcel的性能？ -- **A:** 可以通过开启调试日志来监控FastExcel的性能。例如： +- **Q:** 如何监控 FesodSheet 的性能？ +- **A:** 可以通过开启调试日志来监控 FesodSheet 的性能。例如： ```java LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - ch.qos.logback.classic.Logger logger = lc.getLogger("cn.idev.excel"); + ch.qos.logback.classic.Logger logger = lc.getLogger("org.apache.fesod"); logger.setLevel(Level.DEBUG); ``` ## 多Sheet读取 -- **Q:** 如何读取包含多个Sheet的Excel文件？ -- **A:** 可以使用`MultipleSheetsListener`来处理多Sheet的读取。例如： +- **Q:** 如何读取包含多个 Sheet 的电子表格文件？ +- **A:** 可以使用`MultipleSheetsListener`来处理多 Sheet 的读取。例如： ```java - FastExcel.read(file, MultipleSheetsData.class, new MultipleSheetsListener()).doReadAll(); + FesodSheet.read(file, MultipleSheetsData.class, new MultipleSheetsListener()).doReadAll(); ``` 或者，可以在读取前获取所有Sheet的信息： ```java - ExcelReader excelReader = FastExcel.read(file, MultipleSheetsData.class, multipleSheetsListener).build(); + ExcelReader excelReader = FesodSheet.read(file, MultipleSheetsData.class, multipleSheetsListener).build(); List sheets = excelReader.excelExecutor().sheetList(); for (ReadSheet readSheet : sheets) { excelReader.read(readSheet); @@ -174,9 +183,9 @@ title: '常见问题' excelReader.finish(); ``` -## 获取Excel总行数 +## 获取总行数 -- **Q:** 如何获取Excel文件的总行数？ +- **Q:** 如何获取电子表格文件的总行数？ - **A:** 可以在监听器中使用`analysisContext.readSheetHolder().getApproximateTotalRowNumber()`方法获取大致的行数。例如： ```java @@ -189,11 +198,11 @@ title: '常见问题' ## 内存模式 -- **Q:** 如何使用内存模式处理Excel文件？ +- **Q:** 如何使用内存模式处理电子表格文件？ - **A:** 内存模式适合处理较小的文件，可以显著提高处理速度。例如： ```java - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .inMemory(Boolean.TRUE) .sheet("模板") .doWrite(data()); @@ -201,11 +210,11 @@ title: '常见问题' ## 读取CSV文件 -- **Q:** 如何读取CSV文件并修改分隔符？ -- **A:** 可以通过设置`csv()`中的分隔符来读取CSV文件。例如： +- **Q:** 如何读取 CSV 文件并修改分隔符？ +- **A:** 可以通过设置`csv()`中的分隔符来读取 CSV 文件。例如： ```java - FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv().delimiter(CsvConstant.UNICODE_EMPTY).doReadSync(); ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/large-data.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/large-data.md new file mode 100644 index 000000000..dccdb5dce --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/large-data.md @@ -0,0 +1,63 @@ +--- +id: 'large-data' +title: '大数据量文件' +--- + +# 大数据量文件 + +## 读取 + +### 概述 + +当需要读取 10M 大小以上的文件时，微软 Excel 03 没有办法处理，相对内存占用大很多。微软 Excel 07 +版本有个[共享字符串](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/working-with-the-shared-string-table) +的概念，这个会非常占用内存，如果全部读取到内存的话，大概是电子表格文件的大小的 3-10 倍，所以 FesodSheet +用先存储文件的，然后再反序列化去读取的策略来节约内存。当然需要通过文件反序列化以后，效率会降低，大概降低 +30-50%（不一定，也看命中率，可能会超过100%）。 + +如果对读取效率感觉还能接受，就用默认的，永久占用（单个电子表格读取整个过程）一般不会超过 50M (大概率就 30M)，剩下临时的 GC +会很快回收。 + +### 默认策略 + +默认大文件处理会自动判断，共享字符串 5M 以下会使用内存存储，大概占用 15-50M 的内存，超过 5M +则使用文件存储，然后文件存储也要设置多内存用来存放临时的共享字符串，默认 20M。除了共享字符串占用内存外，其他占用较少，所以可以预估 +10M，所以默认大概 30M 就能读取一个超级大的文件。 + +### 配置内存 + +如果想自定义设置，首先要确定大概愿意花多少内存来读取一个超级大的电子表格，比如希望读取电子表格最多占用 100M +内存（是读取过程中永久占用，新生代马上回收的不算），那就设置使用文件来存储共享字符串的大小判断为 20M (小于 20M +存内存，大于存临时文件)，然后设置文件存储时临时共享字符串占用内存大小 90M 差不多。 + +如果最大文件条数也就十几二十万，然后电子表格也就是十几二十M，而且不会有很高的并发，内存也较大 + +```java +// 强制使用内存存储，这样大概一个 20M 的电子表格使用 150M（很多临时对象，所以 100M 会一直 GC）的内存 +// 这样效率会比上面的复杂的策略高很多 +// 这里再说明下 就是加了个readCache(new MapCache()) 参数而已，其他的参照其他示例写 +FesodSheet.read(). + +readCache(new MapCache()); +``` + +对并发要求较高，而且都是经常有超级大文件 + +```java +// 第一个参数的意思是多少M共享字符串以后，采用文件存储（单位 MB，默认 5M） +// 第二个参数 文件存储时，内存存放多少M缓存数据，默认 20M +// 比如 你希望用 100M 内存(这里说的是解析过程中的永久占用，临时对象不算)来解析电子表格，前面算过了，大概是 20M+90M，所以设置参数为：20 和 90 +// 这里再说明下 就是加了个 readCacheSelector(new SimpleReadCacheSelector(5, 20)) 参数而已，其他的参照其他示例写 +FesodSheet.read(). + +readCacheSelector(new SimpleReadCacheSelector(5, 20)); +``` + +### 关于 maxCacheActivateSize + +FesodSheet 在使用文件存储的时候，会把共享字符串拆分成 **1000** 条一批，然后放到文件存储。然后电子表格来读取共享字符串大概率是按照顺序的，所以默认 +20M 的 1000 条的数据放在内存，命中后直接返回，没命中去读文件。所以不能设置太小，太小了，很难命中，一直去读取文件，太大了的话会占用过多的内存。 + +判断 maxCacheActivateSize 是否需要调整，开启 `debug` 日志会输出 `Already put :4000000` 最后一次输出，大概可以得出值为 +400W，然后看`Cache misses count:4001`得到值为 4K，`400W/4K=1000` 这代表已经 `maxCacheActivateSize` 已经非常合理了。如果小于 +500 问题就非常大了，500 到 1000 应该都还行。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/parameter.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/parameter.md similarity index 89% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/parameter.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/parameter.md index 17c449dae..63aa01934 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/parameter.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/help/parameter.md @@ -5,7 +5,7 @@ title: '参数' # 参数 -本章节介绍使用 FastExcel 中的参数。 +本章节介绍使用 FesodSheet 中的参数。 ## 类图 @@ -108,7 +108,7 @@ WriteWorkbook --|> WriteBasicParameter | clazz | 空 | 与 `head` 二选一。读取文件的头对应的class，也可以使用注解。如果两个都不指定，则会读取全部数据 | | customConverterList | 空 | 默认加载了很多转换器，这里可以加入不支持的字段 | | autoTrim | true | 会对表头、读取数据等进行自动去除前后空格 | -| use1904windowing | false | excel 中时间是存储 1900 年起的一个双精度浮点数，但是有时候默认开始日期是 1904，所以设置这个值改成默认 1904 年开始 | +| use1904windowing | false | 电子表格中时间是存储 1900 年起的一个双精度浮点数，但是有时候默认开始日期是 1904，所以设置这个值改成默认 1904 年开始 | | useScientificFormat | false | 数字转文本的时候在较大的数值的是否是否采用科学计数法 | | locale | 空 | 此参数用于格式化日期和数字 | | filedCacheLocation | THREAD_LOCAL | 解析 class 的 field 会有缓存，默认放到 ThreadLocal ，也就是说每次读写都会重新解析 class，可以反射修改 class 的注解，并发场景不会相互影响
THREAD_LOCAL：默认，每次读写都会缓存，但是不是同一次不会影响
MEMORY：放到全局的内存里面，理论上性能会更好，但是无法通过反射、排除等方法修改导出的对象
NONE：不缓存，性能会变差，涉及到读的同时要写，而且还要反射、排除等方法去修改对象的情况下可以考虑使用。 | @@ -117,33 +117,33 @@ WriteWorkbook --|> WriteBasicParameter ### ReadBasicParameter 通用参数 -| 名称 | 默认值 | 描述 | -|------------------------|-----|-------------------------------------| -| customReadListenerList | 空 | 可以注册多个监听器，读取 excel 的时候会不断的回调监听器中的方法 | -| headRowNumber | 1 | excel 中头的行数，默认 1 行 | +| 名称 | 默认值 | 描述 | +|------------------------|-----|----------------------------------| +| customReadListenerList | 空 | 可以注册多个监听器，读取电子表格的时候会不断的回调监听器中的方法 | +| headRowNumber | 1 | 电子表格中头的行数，默认 1 行 | ### ReadWorkbook 参数 -| 名称 | 默认值 | 描述 | -|--------------------------|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| excelType | 空 | 当前 excel 的类型,支持 XLS、XLSX、CSV | -| inputStream | 空 | 与 `file` 二选一。读取文件的流，如果接收到的是流就只用，不用流建议使用 `file` 参数。因为使用了 `inputStream`，FastExcel 会帮忙创建临时文件，最终还是 `file` | -| file | 空 | 与 `inputStream` 二选一。读取文件的文件。 | -| mandatoryUseInputStream | false | 强制使用 `inputStream` 来创建对象，性能会变差，但是不会创建临文件。 | -| charset | Charset#defaultCharset | 只有csv文件有用，读取文件的时候使用的编码 | -| autoCloseStream | true | 自动关闭读取的流。 | -| readCache | 空 | 默认小于 5M 用 内存，超过 5M 会使用 `EhCache`,这里不建议使用这个参数。 | -| readCacheSelector | SimpleReadCacheSelector | 用于选择什么时候用内存去存储临时数据，什么时候用磁盘存储临时数据 | -| ignoreEmptyRow | true | 忽略空的行 | -| password | 空 | 读取文件的密码 | -| xlsxSAXParserFactoryName | 空 | 指定 sax 读取使用的 class 的名称，例如：`com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl` | -| useDefaultListener | true | 默认会加入 `ModelBuildEventListener` 来帮忙转换成传入 `class` 的对象，设置成 `false` 后将不会协助转换对象，自定义的监听器会接收到 `Map` 对象，如果还想继续接听到 `class` 对象，请调用 `readListener` 方法，加入自定义的 `beforeListener`、`ModelBuildEventListener`、`afterListener` 即可。 | -| extraReadSet | 空 | 额外需要读取内容的 set，默认不读取这些数据 | -| readDefaultReturn | STRING | STRING：会返回一个 Map<Integer, String> 的数组，返回值就是你在 excel 里面不点击单元格看到的内容
ACTUAL_DATA：会返回一个 Map<Integer, Object> 的数组，返回实际上存储的数据，会帮自动转换类型，Object 类型为 `BigDecimal`、`Boolean`、`String`、`LocalDateTime`、null，中的一个，
READ_CELL_DATA: 会返回一个Map<Integer,ReadCellData<?>>的数组,其中`?`类型参照 ACTUAL_DATA的 | -| customObject | STRING | STRING：会返回一个 Map<Integer, String> 的数组，返回值就是你在 excel 里面不点击单元格看到的内容
ACTUAL_DATA：会返回一个 Map<Integer, Object> 的数组，返回实际上存储的数据，会帮自动转换类型，Object 类型为 `BigDecimal`、`Boolean`、`String`、`LocalDateTime`、null，中的一个，
READ_CELL_DATA: 会返回一个Map<Integer,ReadCellData<?>>的数组,其中`?`类型参照 ACTUAL_DATA的 | -| numRows | 0 | 读取指定的行数，0 表示不限制行数，即读取所有行 | -| ignoreHiddenSheet | true | `@since 1.3.0`
忽略隐藏的 sheet | -| csvFormat | CSVFormat.DEFAULT | `@since 1.3.0`
设置 CSVFormat 对象，仅对 csv 文件有效 | +| 名称 | 默认值 | 描述 | +|--------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| excelType | 空 | 当前电子表格的类型,支持 XLS、XLSX、CSV | +| inputStream | 空 | 与 `file` 二选一。读取文件的流，如果接收到的是流就只用，不用流建议使用 `file` 参数。因为使用了 `inputStream`，FesodSheet 会帮忙创建临时文件，最终还是 `file` | +| file | 空 | 与 `inputStream` 二选一。读取文件的文件。 | +| mandatoryUseInputStream | false | 强制使用 `inputStream` 来创建对象，性能会变差，但是不会创建临文件。 | +| charset | Charset#defaultCharset | 只有csv文件有用，读取文件的时候使用的编码 | +| autoCloseStream | true | 自动关闭读取的流。 | +| readCache | 空 | 默认小于 5M 用 内存，超过 5M 会使用 `EhCache`,这里不建议使用这个参数。 | +| readCacheSelector | SimpleReadCacheSelector | 用于选择什么时候用内存去存储临时数据，什么时候用磁盘存储临时数据 | +| ignoreEmptyRow | true | 忽略空的行 | +| password | 空 | 读取文件的密码 | +| xlsxSAXParserFactoryName | 空 | 指定 sax 读取使用的 class 的名称，例如：`com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl` | +| useDefaultListener | true | 默认会加入 `ModelBuildEventListener` 来帮忙转换成传入 `class` 的对象，设置成 `false` 后将不会协助转换对象，自定义的监听器会接收到 `Map` 对象，如果还想继续接听到 `class` 对象，请调用 `readListener` 方法，加入自定义的 `beforeListener`、`ModelBuildEventListener`、`afterListener` 即可。 | +| extraReadSet | 空 | 额外需要读取内容的 set，默认不读取这些数据 | +| readDefaultReturn | STRING | STRING：会返回一个 Map<Integer, String> 的数组，返回值就是你在电子表格里面不点击单元格看到的内容
ACTUAL_DATA：会返回一个 Map<Integer, Object> 的数组，返回实际上存储的数据，会帮自动转换类型，Object 类型为 `BigDecimal`、`Boolean`、`String`、`LocalDateTime`、null，中的一个，
READ_CELL_DATA: 会返回一个Map<Integer,ReadCellData<?>>的数组,其中`?`类型参照 ACTUAL_DATA的 | +| customObject | STRING | STRING：会返回一个 Map<Integer, String> 的数组，返回值就是你在电子表格里面不点击单元格看到的内容
ACTUAL_DATA：会返回一个 Map<Integer, Object> 的数组，返回实际上存储的数据，会帮自动转换类型，Object 类型为 `BigDecimal`、`Boolean`、`String`、`LocalDateTime`、null，中的一个，
READ_CELL_DATA: 会返回一个Map<Integer,ReadCellData<?>>的数组,其中`?`类型参照 ACTUAL_DATA的 | +| numRows | 0 | 读取指定的行数，0 表示不限制行数，即读取所有行 | +| ignoreHiddenSheet | true | `@since 1.3.0`
忽略隐藏的 sheet | +| csvFormat | CSVFormat.DEFAULT | `@since 1.3.0`
设置 CSVFormat 对象，仅对 csv 文件有效 | ### ReadSheet 参数 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/converter.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/converter.md similarity index 82% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/converter.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/converter.md index 0e0b81337..33ef36437 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/converter.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/converter.md @@ -5,17 +5,18 @@ title: '格式转换' # 格式转换 -FastExcel 支持日期、数字、自定义格式转换。 +Fesod 支持日期、数字、自定义格式转换。 ## 概述 -在使用过程中，我们可能需要对读取或写入的数据进行特定格式的转换。FastExcel 提供了灵活的转换器机制，允许用户自定义数据转换规则，以满足各种业务需求。 +在使用过程中，我们可能需要对读取或写入的数据进行特定格式的转换。Fesod 提供了灵活的转换器机制，允许用户自定义数据转换规则，以满足各种业务需求。 ## 示例 ### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -60,11 +61,12 @@ public class CustomStringStringConverter implements Converter { ### 代码示例 ```java + @Test public void converterRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, ConverterData.class, new DemoDataListener()) + FesodSheet.read(fileName, ConverterData.class, new DemoDataListener()) .registerConverter(new CustomStringStringConverter()) // 注册自定义转换器 .sheet() .doRead(); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/csv.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/csv.md similarity index 52% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/csv.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/csv.md index 7693d955c..bc0b3c9e3 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/csv.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/csv.md @@ -5,21 +5,24 @@ title: 'CSV' # 读取 CSV 文件 -本章节介绍如何使用 FastExcel 来读取自定义 CSV 文件。 +本章节介绍如何使用 Fesod 来读取自定义 CSV 文件。 ## 概述 -FastExcel 通过不同的参数设计进行 CSV 的读取。其底层使用了 [Apache Commons CSV](https://commons.apache.org/proper/commons-csv)，也支持通过直接设置 [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) 进行设定来达成读取的目标。 +Fesod 通过不同的参数设计进行 CSV +的读取。其底层使用了 [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) +，也支持通过直接设置 [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) +进行设定来达成读取的目标。 主要的参数如下： -| 名称 | 默认值 | 描述 | -| :--- | :--- | :--- | -| `delimiter` | `,` (逗号) | 字段分隔符。推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.AT` (`@`)、`CsvConstant.TAB` 等。 | -| `quote` | `"` (双引号) | 字段引用符号，推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.DOUBLE_QUOTE` (`"`)。 | -| `recordSeparator` | `CRLF` | 记录（行）分隔符。根据操作系统不同而变化，例如 `CsvConstant.CRLF` (Windows) 或 `CsvConstant.LF` (Unix/Linux)。 | -| `nullString` | `null` | 用于表示 `null` 值的字符串。注意这与空字符串 `""` 不同。 | -| `escape` | `null` | 转义字符，用于转义引用符号自身。 | +| 名称 | 默认值 | 描述 | +|:------------------|:----------|:--------------------------------------------------------------------------------------| +| `delimiter` | `,` (逗号) | 字段分隔符。推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.AT` (`@`)、`CsvConstant.TAB` 等。 | +| `quote` | `"` (双引号) | 字段引用符号，推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.DOUBLE_QUOTE` (`"`)。 | +| `recordSeparator` | `CRLF` | 记录（行）分隔符。根据操作系统不同而变化，例如 `CsvConstant.CRLF` (Windows) 或 `CsvConstant.LF` (Unix/Linux)。 | +| `nullString` | `null` | 用于表示 `null` 值的字符串。注意这与空字符串 `""` 不同。 | +| `escape` | `null` | 转义字符，用于转义引用符号自身。 | --- @@ -29,20 +32,21 @@ FastExcel 通过不同的参数设计进行 CSV 的读取。其底层使用了 [ ### delimiter -`delimiter` 用于指定 CSV 文件中的字段分隔符。默认值为英文逗号 `,`。同时，FastExcel 提供了一些常量 `CsvConstant`，用于简化使用。 +`delimiter` 用于指定 CSV 文件中的字段分隔符。默认值为英文逗号 `,`。同时，Fesod 提供了一些常量 `CsvConstant`，用于简化使用。 #### 代码示例 如果 CSV 文件使用 `\u0000` 作为分隔符，可以如下设置： ```java + @Test public void delimiterDemo() { - String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) - .csv() - .delimiter(CsvConstant.UNICODE_EMPTY) - .doReadSync(); + String csvFile = "path/to/your.csv"; + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) + .csv() + .delimiter(CsvConstant.UNICODE_EMPTY) + .doReadSync(); } ``` @@ -55,10 +59,11 @@ public void delimiterDemo() { #### 代码示例 ```java + @Test public void quoteDemo() { String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv() .quote(CsvConstant.DOUBLE_QUOTE, QuoteMode.MINIMAL) .doReadSync(); @@ -72,10 +77,11 @@ public void quoteDemo() { #### 代码示例 ```java + @Test public void recordSeparatorDemo() { String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv() .recordSeparator(CsvConstant.LF) .doReadSync(); @@ -89,10 +95,11 @@ public void recordSeparatorDemo() { #### 代码示例 ```java + @Test public void nullStringDemo() { String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv() .nullString("N/A") .doReadSync(); @@ -106,10 +113,11 @@ public void nullStringDemo() { #### 代码示例 ```java + @Test public void escapeDemo() { String csvFile = "path/to/your.csv"; - List dataList = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()) + List dataList = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()) .csv() .escape(CsvConstant.BACKSLASH) .doReadSync(); @@ -119,18 +127,19 @@ public void escapeDemo() { ## CSVFormat 设置详解与示例 支持直接构建一个 `CSVFormat` 对象。 -> 目前 FastExcel 仍然支持，但并非最推荐的使用方法。 +> 目前 Fesod 仍然支持，但并非最推荐的使用方法。 ### 代码示例 ```java + @Test public void csvFormatDemo() { CSVFormat csvFormat = CSVFormat.DEFAULT.builder().setDelimiter(CsvConstant.AT).build(); String csvFile = "path/to/your.csv"; - try (ExcelReader excelReader = FastExcel.read(csvFile, DemoData.class, new DemoDataListener()).build()) { + try (ExcelReader excelReader = FesodSheet.read(csvFile, DemoData.class, new DemoDataListener()).build()) { ReadWorkbookHolder readWorkbookHolder = excelReader.analysisContext().readWorkbookHolder(); // 判断是否为CsvReadWorkbookHolder实例 if (readWorkbookHolder instanceof CsvReadWorkbookHolder) { @@ -138,7 +147,7 @@ public void csvFormatDemo() { csvReadWorkbookHolder.setCsvFormat(csvFormat); } - ReadSheet readSheet = FastExcel.readSheet(0).build(); + ReadSheet readSheet = FesodSheet.readSheet(0).build(); excelReader.read(readSheet); } } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/exception.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/exception.md similarity index 85% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/exception.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/exception.md index b80dc89bc..38c53352b 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/exception.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/exception.md @@ -14,6 +14,7 @@ title: '异常处理' ## 数据监听器 ```java + @Slf4j public class DemoExceptionListener extends AnalysisEventListener { @Override @@ -26,21 +27,24 @@ public class DemoExceptionListener extends AnalysisEventListener { @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } @Override public void extra(CellExtra extra, AnalysisContext context) { log.info("读取到额外信息: {}", JSON.toJSONString(extra)); - if(CellExtraTypeEnum.COMMENT == extra.getType()) { + if (CellExtraTypeEnum.COMMENT == extra.getType()) { log.info("批注信息: {}", extra.getText()); } } @@ -37,11 +40,12 @@ public class DemoCommentExtraListener implements ReadListener { ### 代码示例 ```java + @Test public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoCommentExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoCommentExtraListener()) .extraRead(CellExtraTypeEnum.COMMENT) .sheet() .doRead(); @@ -59,18 +63,21 @@ public void extraRead() { ### 数据监听器 ```java + @Slf4j public class DemoHyperLinkExtraListener implements ReadListener { @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } @Override public void extra(CellExtra extra, AnalysisContext context) { log.info("读取到额外信息: {}", JSON.toJSONString(extra)); - if(CellExtraTypeEnum.HYPERLINK == extra.getType()) { + if (CellExtraTypeEnum.HYPERLINK == extra.getType()) { log.info("超链接信息: {}", extra.getText()); } } @@ -80,11 +87,12 @@ public class DemoHyperLinkExtraListener implements ReadListener { ### 代码示例 ```java + @Test public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoHyperLinkExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoHyperLinkExtraListener()) .extraRead(CellExtraTypeEnum.HYPERLINK) .sheet() .doRead(); @@ -102,18 +110,21 @@ public void extraRead() { ### 数据监听器 ```java + @Slf4j public class DemoMergeExtraListener implements ReadListener { @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } @Override public void extra(CellExtra extra, AnalysisContext context) { log.info("读取到额外信息: {}", JSON.toJSONString(extra)); - if(CellExtraTypeEnum.MERGE == extra.getType()) { + if (CellExtraTypeEnum.MERGE == extra.getType()) { log.info("合并单元格范围: {} - {}", extra.getFirstRowIndex(), extra.getLastRowIndex()); } } @@ -123,11 +134,12 @@ public class DemoMergeExtraListener implements ReadListener { ### 代码示例 ```java + @Test public void extraRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoMergeExtraListener()) + FesodSheet.read(fileName, DemoData.class, new DemoMergeExtraListener()) .extraRead(CellExtraTypeEnum.MERGE) .sheet() .doRead(); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/head.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/head.md similarity index 72% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/head.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/head.md index 140f82c5f..64fcd0325 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/head.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/head.md @@ -5,7 +5,7 @@ title: '表头' # 表头 -本章节将介绍读取 Excel 中的表头数据。 +本章节将介绍读取电子表格中的表头数据。 ## 读取表头数据 @@ -16,6 +16,7 @@ title: '表头' ### 数据监听器 ```java + @Slf4j public class DemoHeadDataListener extends AnalysisEventListener { @Override @@ -24,21 +25,24 @@ public class DemoHeadDataListener extends AnalysisEventListener { } @Override - public void invoke(DemoData data, AnalysisContext context) {} + public void invoke(DemoData data, AnalysisContext context) { + } @Override - public void doAfterAllAnalysed(AnalysisContext context) {} + public void doAfterAllAnalysed(AnalysisContext context) { + } } ``` ### 代码示例 ```java + @Test public void headerRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoHeadDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoHeadDataListener()) .sheet() .doRead(); } @@ -55,15 +59,16 @@ public void headerRead() { ### 代码示例 ```java + @Test public void complexHeaderRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) - .sheet() - // 设置多行表头的行数，默认为 1 - .headRowNumber(2) - .doRead(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) + .sheet() + // 设置多行表头的行数，默认为 1 + .headRowNumber(2) + .doRead(); } ``` @@ -78,11 +83,12 @@ public void complexHeaderRead() { ### 代码示例 ```java + @Test public void headerPojoRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, new DemoDataListener()) + FesodSheet.read(fileName, new DemoDataListener()) .head(DemoData.class) .sheet() .doRead(); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/num-rows.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/num-rows.md new file mode 100644 index 000000000..78138e55d --- /dev/null +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/num-rows.md @@ -0,0 +1,48 @@ +--- +id: 'num-rows' +title: '行数' +--- + +# 读取行 + +本章节将介绍读取指定的行数。 + +## 概述 + +在数据分析和处理过程中，快速查看电子表格文件的前几行内容可以帮助我们更好地理解数据结构和内容。默认情况下，Fesod +会读取整个文件的所有数据，通过设置 `numRows` 参数可以限制读取的行数。0 表示不限制行数，即读取所有行，行数包括表头行。 + +## 所有的 Sheet + +### 代码示例 + +```java + +@Test +public void allSheetRead() { + // 读取前100行 + FesodSheet.read(fileName, DemoData.class, new PageReadListener(dataList -> { + for (DemoData demoData : dataList) { + log.info("读取到一条数据{}", JSON.toJSONString(demoData)); + } + })).numRows(100).sheet().doRead(); +} +``` + +--- + +## 单个 sheet + +### 代码示例 + +```java + +@Test +public void singleSheetRead() { + try (ExcelReader excelReader = FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).build()) { + ReadSheet readSheet = FesodSheet.readSheet(0).build(); + readSheet.setNumRows(100); // 读取前100行 + excelReader.read(readSheet); + } +} +``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/pojo.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/pojo.md similarity index 79% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/pojo.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/pojo.md index e45a53b01..5fd008aa5 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/pojo.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/pojo.md @@ -11,13 +11,14 @@ title: '实体类' ### 概述 -您可以通过指定**列名**或**列下标**来读取 Excel 数据。这使得与动态生成的 Excel 文件交互更加灵活。 +您可以通过指定**列名**或**列下标**来读取电子表格数据。这使得与动态生成的电子表格文件交互更加灵活。 ### 示例代码 #### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -36,11 +37,12 @@ public class IndexOrNameData { #### 代码示例 ```java + @Test public void indexOrNameRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, IndexOrNameData.class, new DemoDataListener()) + FesodSheet.read(fileName, IndexOrNameData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -57,6 +59,7 @@ public void indexOrNameRead() { ### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -71,11 +74,12 @@ public class CellDataReadDemoData { ### 代码示例 ```java + @Test public void cellDataRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, CellDataReadDemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, CellDataReadDemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -87,11 +91,12 @@ public void cellDataRead() { ### 概述 -FastExcel 支持不定义 POJO 类直接读取 Excel 文件，通过 `Map` 直接读取数据。 +Fesod 支持不定义 POJO 类直接读取电子表格文件，通过 `Map` 直接读取数据。 ### 数据监听器 ```java + @Slf4j public class NoModelDataListener extends AnalysisEventListener> { diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/sheet.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/sheet.md similarity index 53% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/sheet.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/sheet.md index 5971e81ca..368668f7b 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/sheet.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/sheet.md @@ -11,18 +11,19 @@ title: 'Sheet' ### 概述 -可以读取 Excel 文件中的多个 Sheet，且同一个 Sheet 不可重复读取。 +可以读取电子表格文件中的多个 Sheet，且同一个 Sheet 不可重复读取。 ### 代码示例 #### 读取全部 Sheet ```java + @Test public void readAllSheet() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()).doReadAll(); + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()).doReadAll(); } ``` @@ -32,22 +33,23 @@ public void readAllSheet() { ### 概述 -可以读取 Excel 文件具体的某个 Sheet，支持指定 Sheet 的索引或名称 +可以读取电子表格文件具体的某个 Sheet，支持指定 Sheet 的索引或名称 -> **注意：** Excel 中 Sheet 名称最多为 31 个字符。按名称读取时，请使用文件中实际显示的 Sheet 名称。 +> **注意：** 微软 Excel 中 Sheet 名称最多为 31 个字符。按名称读取时，请使用文件中实际显示的 Sheet 名称。 ### 代码示例 ```java + @Test public void readSingleSheet() { String fileName = "path/to/demo.xlsx"; - try (ExcelReader excelReader = FastExcel.read(fileName).build()) { + try (ExcelReader excelReader = FesodSheet.read(fileName).build()) { // Sheet 索引 - ReadSheet sheet1 = FastExcel.readSheet(0).head(DemoData.class).registerReadListener(new DemoDataListener()).build(); + ReadSheet sheet1 = FesodSheet.readSheet(0).head(DemoData.class).registerReadListener(new DemoDataListener()).build(); // Sheet 名 - ReadSheet sheet2 = FastExcel.readSheet("Sheet2").head(DemoData.class).registerReadListener(new DemoDataListener()).build(); + ReadSheet sheet2 = FesodSheet.readSheet("Sheet2").head(DemoData.class).registerReadListener(new DemoDataListener()).build(); excelReader.read(sheet1, sheet2); } } @@ -64,15 +66,17 @@ public void readSingleSheet() { ### 代码示例 ```java + @Test public void exceptionRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) .ignoreHiddenSheet(Boolean.TRUE) .sheet() .doRead(); } ``` -> 微软 Excel 中，Sheet 有“普通隐藏(xlSheetHidden)”和“绝对隐藏(xlSheetVeryHidden)”两种状态，绝对隐藏可通过 `VBA` 来设置，此时隐藏的 Sheet 无法通过“取消隐藏”的操作来取消。 +> 微软 Excel 中，Sheet 有“普通隐藏(xlSheetHidden)”和“绝对隐藏(xlSheetVeryHidden)”两种状态，绝对隐藏可通过 `VBA` 来设置，此时隐藏的 +> Sheet 无法通过“取消隐藏”的操作来取消。 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/simple.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/simple.md similarity index 69% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/simple.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/simple.md index baa233642..cbe4fa45c 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/simple.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/simple.md @@ -5,13 +5,13 @@ title: '简单读取' # 简单读取 -本章节介绍如何使用 FastExcel 完成简单 Excel 读取 +本章节介绍如何使用 Fesod 完成简单电子表格读取 ## 数据监听器 ### 概述 -FastExcel 提供监听器机制，用于在读取 Excel 文件时对每一行数据进行处理。 +Fesod 提供监听器机制，用于在读取电子表格文件时对每一行数据进行处理。 ### 使用 @@ -19,16 +19,17 @@ FastExcel 提供监听器机制，用于在读取 Excel 文件时对每一行数 #### 实例化 -监听器不能被 Spring 管理，每次读取 Excel 文件时需要重新实例化。 +监听器不能被 Spring 管理，每次读取电子表格文件时需要重新实例化。 #### `Lambda` 表达式 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { + FesodSheet.read(fileName, DemoData.class, new PageReadListener<>(dataList -> { for (DemoData demoData : dataList) { log.info("读取到一条数据: {}", JSON.toJSONString(demoData)); } @@ -39,14 +40,15 @@ public void simpleRead() { #### 匿名内部类 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new ReadListener() { + FesodSheet.read(fileName, DemoData.class, new ReadListener() { @Override public void invoke(DemoData data, AnalysisContext context) { - log.info("读取到一条数据: {}", JSON.toJSONString(data)); + log.info("读取到一条数据: {}", JSON.toJSONString(data)); } @Override @@ -60,11 +62,12 @@ public void simpleRead() { #### 数据监听器 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -76,13 +79,14 @@ public void simpleRead() { ### 概述 -FastExcel 提供了一种简单的方式来读取 Excel 文件。用户只需定义一个 POJO 类来表示数据结构，然后通过 FastExcel 的监听器机制读取数据。 +Fesod 提供了一种简单的方式来读取电子表格文件。用户只需定义一个 POJO 类来表示数据结构，然后通过 Fesod 的监听器机制读取数据。 ### POJO 类 -与 Excel 结构对应的 POJO 类 `DemoData` +与电子表格结构对应的 POJO 类 `DemoData` ```java + @Getter @Setter @EqualsAndHashCode @@ -95,9 +99,10 @@ public class DemoData { ### 数据监听器 -`DemoDataListener` 是一个自定义监听器，用于处理从 Excel 中读取的数据。 +`DemoDataListener` 是一个自定义监听器，用于处理从电子表格中读取的数据。 ```java + @Slf4j public class DemoDataListener implements ReadListener { @@ -116,11 +121,12 @@ public class DemoDataListener implements ReadListener { ### 代码示例 ```java + @Test public void simpleRead() { String fileName = "path/to/demo.xlsx"; - FastExcel.read(fileName, DemoData.class, new DemoDataListener()) + FesodSheet.read(fileName, DemoData.class, new DemoDataListener()) .sheet() .doRead(); } @@ -132,11 +138,13 @@ public void simpleRead() { ### 概述 -FastExcel 支持不定义 POJO 类直接读取 Excel 文件，通过 `Map` 直接读取数据，其中的键为**列索引**，值为**单元格数据**。 +Fesod 支持不定义 POJO 类直接读取电子表格文件，通过 `Map` 直接读取数据，其中的键为**列索引**，值为* +*单元格数据**。 ### 数据监听器 ```java + @Slf4j public class NoModelDataListener extends AnalysisEventListener> { @@ -158,13 +166,16 @@ public class NoModelDataListener extends AnalysisEventListener list = FastExcel.read(fileName) + List list = FesodSheet.read(fileName) .head(DemoData.class) .sheet() .doReadSync(); @@ -201,12 +213,13 @@ public void synchronousReadToObjectList() { 在不使用 POJO 情况下，可以将每一行读取为 Map，键为列索引，值为单元格内容。 ```java + @Test public void synchronousReadToMapList() { String fileName = "path/to/demo.xlsx"; // Map 列表 - List> list = FastExcel.read(fileName) + List> list = FesodSheet.read(fileName) .sheet() .doReadSync(); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/spring.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/spring.md similarity index 84% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/spring.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/spring.md index f914109cc..47e03b82c 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/read/spring.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/spring.md @@ -5,11 +5,11 @@ title: '与 Spring 集成' # 与 Spring 集成指南 -本章节介绍如何在 Spring 框架中集成和使用 FastExcel 来处理用户上传的 Excel 文件。 +本章节介绍如何在 Spring 框架中集成和使用 Fesod 来处理用户上传的电子表格文件。 ## 概述 -通过创建 RESTful API 接口，用户可以使用 HTTP 请求上传 Excel 文件，服务器端使用 FastExcel 解析数据。 +通过创建 RESTful API 接口，用户可以使用 HTTP 请求上传电子表格文件，服务器端使用 Fesod 解析数据。 ## 环境依赖 @@ -18,9 +18,10 @@ title: '与 Spring 集成' 确保在 pom.xml 文件中包括必要的依赖项： ```xml + - cn.idev.excel - fastexcel + org.apache.fesod + fesod 版本号 @@ -37,9 +38,10 @@ title: '与 Spring 集成' ### POJO类 -首先，定义一个用于映射 Excel 数据的 POJO 类： +首先，定义一个用于映射电子表格数据的 POJO 类： ```java + @Getter @Setter @ToString @@ -55,6 +57,7 @@ public class UploadData { 创建一个监听器来处理每一行数据： ```java + @Slf4j public class UploadDataListener extends AnalysisEventListener { private final List list = new ArrayList<>(); @@ -78,6 +81,7 @@ public class UploadDataListener extends AnalysisEventListener { 创建一个控制器来处理文件上传请求： ```java + @RestController @RequestMapping("/excel") public class ExcelController { @@ -89,7 +93,7 @@ public class ExcelController { } try { - FastExcel.read(file.getInputStream(), UploadData.class, new UploadDataListener()) + FesodSheet.read(file.getInputStream(), UploadData.class, new UploadDataListener()) .sheet() .doRead(); return ResponseEntity.ok("文件上传并处理成功！"); @@ -109,7 +113,8 @@ public class ExcelController { ### 异常处理 -为了改善用户体验并保证程序健壮性，需要在数据处理过程中加入异常处理逻辑，可以在自定义监听器中重写 `onException` 方法进行详细的异常处理。 +为了改善用户体验并保证程序健壮性，需要在数据处理过程中加入异常处理逻辑，可以在自定义监听器中重写 `onException` +方法进行详细的异常处理。 ### 实际应用 diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/csv.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/csv.md similarity index 57% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/csv.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/csv.md index 4ccc060d1..9cbe268e2 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/csv.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/csv.md @@ -5,21 +5,24 @@ title: 'CSV' # 写入 CSV 文件 -本章节介绍如何使用 FastExcel 来写入自定义 CSV 文件。 +本章节介绍如何使用 Fesod 来写入自定义 CSV 文件。 ## 概述 -FastExcel 通过不同的参数设计进行 CSV 的写入。其底层使用了 [Apache Commons CSV](https://commons.apache.org/proper/commons-csv)，也支持通过直接设置 [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) 进行设定来达成写入的目标。 +Fesod 通过不同的参数设计进行 CSV +的写入。其底层使用了 [Apache Commons CSV](https://commons.apache.org/proper/commons-csv) +，也支持通过直接设置 [CSVFormat](https://commons.apache.org/proper/commons-csv/apidocs/org/apache/commons/csv/CSVFormat.html) +进行设定来达成写入的目标。 主要的参数如下： -| 名称 | 默认值 | 描述 | -| :--- | :--- | :--- | -| `delimiter` | `,` (逗号) | 字段分隔符。推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.AT` (`@`)、`CsvConstant.TAB` 等。 | -| `quote` | `"` (双引号) | 字段引用符号，推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.DOUBLE_QUOTE` (`"`)。 | -| `recordSeparator` | `CRLF` | 记录（行）分隔符。根据操作系统不同而变化，例如 `CsvConstant.CRLF` (Windows) 或 `CsvConstant.LF` (Unix/Linux)。 | -| `nullString` | `null` | 用于表示 `null` 值的字符串。注意这与空字符串 `""` 不同。 | -| `escape` | `null` | 转义字符，确认是否进行特殊符号的转义。 | +| 名称 | 默认值 | 描述 | +|:------------------|:----------|:--------------------------------------------------------------------------------------| +| `delimiter` | `,` (逗号) | 字段分隔符。推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.AT` (`@`)、`CsvConstant.TAB` 等。 | +| `quote` | `"` (双引号) | 字段引用符号，推荐使用 `CsvConstant` 中预定义的常量，例如 `CsvConstant.DOUBLE_QUOTE` (`"`)。 | +| `recordSeparator` | `CRLF` | 记录（行）分隔符。根据操作系统不同而变化，例如 `CsvConstant.CRLF` (Windows) 或 `CsvConstant.LF` (Unix/Linux)。 | +| `nullString` | `null` | 用于表示 `null` 值的字符串。注意这与空字符串 `""` 不同。 | +| `escape` | `null` | 转义字符，确认是否进行特殊符号的转义。 | --- @@ -29,17 +32,18 @@ FastExcel 通过不同的参数设计进行 CSV 的写入。其底层使用了 [ ### delimiter -`delimiter` 用于指定 CSV 文件中的字段分隔符。默认值为英文逗号 `,`。同时，FastExcel 提供了一些常量 `CsvConstant`，用于简化使用。 +`delimiter` 用于指定 CSV 文件中的字段分隔符。默认值为英文逗号 `,`。同时，Fesod 提供了一些常量 `CsvConstant`，用于简化使用。 #### 代码示例 如果 CSV 文件使用 `\u0000` 作为分隔符，可以如下设置： ```java + @Test public void delimiterDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .delimiter(CsvConstant.UNICODE_EMPTY) .doWrite(data()); @@ -54,10 +58,11 @@ public void delimiterDemo() { #### 代码示例 ```java + @Test public void quoteDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .quote(CsvConstant.DOUBLE_QUOTE, QuoteMode.MINIMAL) .doWrite(data()); @@ -71,10 +76,11 @@ public void quoteDemo() { #### 代码示例 ```java + @Test public void recordSeparatorDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .recordSeparator(CsvConstant.LF) .doWrite(data()); @@ -88,10 +94,11 @@ public void recordSeparatorDemo() { #### 代码示例 ```java + @Test public void nullStringDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .nullString("N/A") .doWrite(data()); @@ -105,10 +112,11 @@ public void nullStringDemo() { #### 代码示例 ```java + @Test public void escapeDemo() { String csvFile = "path/to/your.csv"; - FastExcel.write(csvFile, DemoData.class) + FesodSheet.write(csvFile, DemoData.class) .csv() .escape(CsvConstant.BACKSLASH) .doWrite(data()); @@ -118,17 +126,18 @@ public void escapeDemo() { ## CSVFormat 设置详解与示例 支持直接构建一个 `CSVFormat` 对象。 -> 目前 FastExcel 仍然支持，但并非最推荐的使用方法。 +> 目前 Fesod 仍然支持，但并非最推荐的使用方法。 ### 代码示例 ```java + @Test public void csvFormatDemo() { CSVFormat csvFormat = CSVFormat.DEFAULT.builder().setDelimiter(CsvConstant.AT).build(); String csvFile = "path/to/your.csv"; - try (ExcelWriter excelWriter = FastExcel.write(csvFile, DemoData.class).excelType(ExcelTypeEnum.CSV).build()) { + try (ExcelWriter excelWriter = FesodSheet.write(csvFile, DemoData.class).excelType(ExcelTypeEnum.CSV).build()) { WriteWorkbookHolder writeWorkbookHolder = excelWriter.writeContext().writeWorkbookHolder(); Workbook workbook = writeWorkbookHolder.getWorkbook(); // 判断是否为CsvWorkbook实例 @@ -137,7 +146,7 @@ public void csvFormatDemo() { csvWorkbook.setCsvFormat(csvFormat); writeWorkbookHolder.setWorkbook(csvWorkbook); } - WriteSheet writeSheet = FastExcel.writerSheet(0).build(); + WriteSheet writeSheet = FesodSheet.writerSheet(0).build(); excelWriter.write(data(), writeSheet); } } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/extra.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/extra.md similarity index 93% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/extra.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/extra.md index 5a4d434d2..31224c5e9 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/extra.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/extra.md @@ -43,7 +43,7 @@ public class CommentWriteHandler implements RowWriteHandler { public void commentWrite() { String fileName = "commentWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .inMemory(Boolean.TRUE) // 批注必须启用内存模式 .registerWriteHandler(new CommentWriteHandler()) .sheet("批注示例") @@ -82,7 +82,7 @@ public void writeHyperlinkDataWrite() { // 设置超链接 data.setHyperlink(new WriteCellData<>("点击访问").hyperlink("https://example.com")); - FastExcel.write(fileName, WriteCellDemoData.class) + FesodSheet.write(fileName, WriteCellDemoData.class) .sheet() .doWrite(Collections.singletonList(data)); } @@ -112,6 +112,7 @@ public class WriteCellDemoData { ### 代码示例 ```java + @Test public void writeFormulaDataWrite() { String fileName = "writeCellDataWrite" + System.currentTimeMillis() + ".xlsx"; @@ -119,9 +120,9 @@ public void writeFormulaDataWrite() { // 设置公式 data.setFormulaData(new WriteCellData<>("=SUM(A1:A10)")); - FastExcel.write(fileName, WriteCellDemoData.class) - .sheet() - .doWrite(Collections.singletonList(data)); + FesodSheet.write(fileName, WriteCellDemoData.class) + .sheet() + .doWrite(Collections.singletonList(data)); } ``` @@ -145,7 +146,7 @@ public void templateWrite() { String templateFileName = "path/to/template.xlsx"; String fileName = "templateWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .withTemplate(templateFileName) .sheet() .doWrite(data()); @@ -205,12 +206,12 @@ public void mergeWrite() { String fileName = "mergeWrite" + System.currentTimeMillis() + ".xlsx"; // 注解方式 - FastExcel.write(fileName, DemoMergeData.class) + FesodSheet.write(fileName, DemoMergeData.class) .sheet("合并示例") .doWrite(data()); // 自定义合并策略 - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .registerWriteHandler(new CustomMergeStrategy()) .sheet("自定义合并") .doWrite(data()); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/format.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/format.md similarity index 94% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/format.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/format.md index d35089eb7..2f27f7f33 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/format.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/format.md @@ -39,7 +39,7 @@ public class ConverterData { @Test public void converterWrite() { String fileName = "converterWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, ConverterData.class) + FesodSheet.write(fileName, ConverterData.class) .sheet() .doWrite(data()); } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/head.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/head.md similarity index 84% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/head.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/head.md index 0ad2d85c9..32d89edab 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/head.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/head.md @@ -5,7 +5,7 @@ title: '表头' # 表头 -本章节将介绍写入 Excel 中的表头数据。 +本章节将介绍写入电子表格中的表头数据。 ## 复杂头写入 @@ -16,6 +16,7 @@ title: '表头' ### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -32,12 +33,13 @@ public class ComplexHeadData { ### 代码示例 ```java + @Test public void complexHeadWrite() { String fileName = "complexHeadWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, ComplexHeadData.class) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, ComplexHeadData.class) + .sheet() + .doWrite(data()); } ``` @@ -56,19 +58,20 @@ public void complexHeadWrite() { ### 代码示例 ```java + @Test public void dynamicHeadWrite() { String fileName = "dynamicHeadWrite" + System.currentTimeMillis() + ".xlsx"; List> head = Arrays.asList( - Collections.singletonList("动态字符串标题"), - Collections.singletonList("动态数字标题"), - Collections.singletonList("动态日期标题")); - - FastExcel.write(fileName) - .head(head) - .sheet() - .doWrite(data()); + Collections.singletonList("动态字符串标题"), + Collections.singletonList("动态数字标题"), + Collections.singletonList("动态日期标题")); + + FesodSheet.write(fileName) + .head(head) + .sheet() + .doWrite(data()); } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/image.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/image.md similarity index 95% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/image.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/image.md index a46b2c695..028138032 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/image.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/image.md @@ -46,7 +46,7 @@ public void imageWrite() throws Exception { data.setUrl(new URL("https://example.com/image.jpg")); list.add(data); - FastExcel.write(fileName, ImageDemoData.class) + FesodSheet.write(fileName, ImageDemoData.class) .sheet() .doWrite(list); } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/pojo.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/pojo.md similarity index 89% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/pojo.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/pojo.md index fd674a33d..dbe92ba25 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/pojo.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/pojo.md @@ -18,15 +18,16 @@ title: '实体类' 忽略指定列 ```java + @Test public void excludeOrIncludeWrite() { String fileName = "excludeColumnFieldWrite" + System.currentTimeMillis() + ".xlsx"; Set excludeColumns = Set.of("date"); - FastExcel.write(fileName, DemoData.class) - .excludeColumnFieldNames(excludeColumns) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .excludeColumnFieldNames(excludeColumns) + .sheet() + .doWrite(data()); } ``` @@ -38,7 +39,7 @@ public void excludeOrIncludeWrite() { String fileName = "includeColumnFiledWrite" + System.currentTimeMillis() + ".xlsx"; Set includeColumns = Set.of("date"); - FastExcel.write(fileName, DemoData.class) + FesodSheet.write(fileName, DemoData.class) .includeColumnFiledNames(includeColumns) .sheet() .doWrite(data()); @@ -60,6 +61,7 @@ public void excludeOrIncludeWrite() { ### POJO 类 ```java + @Getter @Setter @EqualsAndHashCode @@ -79,7 +81,7 @@ public class IndexData { @Test public void indexWrite() { String fileName = "indexWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, IndexData.class) + FesodSheet.write(fileName, IndexData.class) .sheet() .doWrite(data()); } @@ -104,7 +106,7 @@ public void indexWrite() { public void noModelWrite() { String fileName = "noModelWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName) + FesodSheet.write(fileName) .head(head()) // 动态头 .sheet("无对象写入") .doWrite(dataList()); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/sheet.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/sheet.md similarity index 63% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/sheet.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/sheet.md index bec171524..f4604f460 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/sheet.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/sheet.md @@ -7,7 +7,7 @@ title: 'Sheet 页' 本章节将介绍设置 Sheet 来写入数据的使用。 -> **注意：** Excel 中 Sheet 名称最多为 31 个字符。超过此长度的名称将被自动截断，并记录警告日志。 +> **注意：** 微软 Excel 中 Sheet 名称最多为 31 个字符。超过此长度的名称将被自动截断，并记录警告日志。 ## 写入同一个 Sheet @@ -18,12 +18,13 @@ title: 'Sheet 页' ### 代码示例 ```java + @Test public void writeSingleSheet() { String fileName = "repeatedWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Sheet1").build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Sheet1").build(); for (int i = 0; i < 5; i++) { excelWriter.write(data(), writeSheet); } @@ -46,13 +47,14 @@ public void writeSingleSheet() { ### 代码示例 ```java + @Test public void writeMultiSheet() { String fileName = "repeatedWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { for (int i = 0; i < 5; i++) { - WriteSheet writeSheet = FastExcel.writerSheet(i, "Sheet" + i).build(); + WriteSheet writeSheet = FesodSheet.writerSheet(i, "Sheet" + i).build(); excelWriter.write(data(), writeSheet); } } @@ -74,14 +76,15 @@ public void writeMultiSheet() { ### 代码示例 ```java + @Test public void tableWrite() { String fileName = "tableWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Table示例").build(); - WriteTable table1 = FastExcel.writerTable(0).build(); - WriteTable table2 = FastExcel.writerTable(1).build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Table示例").build(); + WriteTable table1 = FesodSheet.writerTable(0).build(); + WriteTable table2 = FesodSheet.writerTable(1).build(); excelWriter.write(data(), writeSheet, table1); excelWriter.write(data(), writeSheet, table2); diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/simple.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/simple.md similarity index 62% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/simple.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/simple.md index b011acd84..6e8afc928 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/simple.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/simple.md @@ -5,19 +5,20 @@ title: '简单写入' # 简单写入 -本章节介绍如何使用 FastExcel 完成简单 Excel 写入 +本章节介绍如何使用 Fesod 完成简单电子表格写入 ## 概述 -使用 FastExcel 进行简单的 Excel 数据写入，可以快速地将实体对象写入 Excel 文件，是最基本、最常用的写入方式。 +使用 Fesod 进行简单的电子表格数据写入，可以快速地将实体对象写入电子表格文件，是最基本、最常用的写入方式。 ## 代码示例 ### POJO 类 -与 Excel 结构对应的 POJO 类 `DemoData` +与电子表格结构对应的 POJO 类 `DemoData` ```java + @Getter @Setter @EqualsAndHashCode @@ -51,43 +52,46 @@ private List data() { ### 写入方式 -FastExcel 提供了多种写入方式，包括 `Lambda` 表达式、数据列表、`ExcelWriter` 对象等。 +Fesod 提供了多种写入方式，包括 `Lambda` 表达式、数据列表、`ExcelWriter` 对象等。 #### `Lambda` 表达式 ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .sheet("Sheet1") - .doWrite(() -> data()); + FesodSheet.write(fileName, DemoData.class) + .sheet("Sheet1") + .doWrite(() -> data()); } ``` #### 数据列表 ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .sheet("Sheet1") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .sheet("Sheet1") + .doWrite(data()); } ``` #### `ExcelWriter` 对象 ```java + @Test public void simpleWrite() { String fileName = "simpleWrite" + System.currentTimeMillis() + ".xlsx"; - try (ExcelWriter excelWriter = FastExcel.write(fileName, DemoData.class).build()) { - WriteSheet writeSheet = FastExcel.writerSheet("Sheet1").build(); + try (ExcelWriter excelWriter = FesodSheet.write(fileName, DemoData.class).build()) { + WriteSheet writeSheet = FesodSheet.writerSheet("Sheet1").build(); excelWriter.write(data(), writeSheet); } } diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/spring.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/spring.md similarity index 61% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/spring.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/spring.md index ce2ce3047..8c685db0e 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/spring.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/spring.md @@ -5,17 +5,18 @@ title: '与 Spring 集成' # 与 Spring 集成指南 -本章节介绍如何在 Spring 框架中集成和使用 FastExcel 来生成 Excel 文件。 +本章节介绍如何在 Spring 框架中集成和使用 Fesod 来生成电子表格文件。 ## Spring 控制器示例 ### 概述 -Spring Boot 项目中可以通过 HTTP 接口生成 Excel 文件并提供下载功能，便于在 Web 环境下使用 FastExcel。 +Spring Boot 项目中可以通过 HTTP 接口生成电子表格文件并提供下载功能，便于在 Web 环境下使用 Fesod。 ### 代码示例 ```java + @GetMapping("download") public void download(HttpServletResponse response) throws IOException { response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); @@ -23,8 +24,8 @@ public void download(HttpServletResponse response) throws IOException { String fileName = URLEncoder.encode("demo", "UTF-8").replaceAll("\\+", "%20"); response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx"); - FastExcel.write(response.getOutputStream(), DemoData.class) - .sheet("Sheet1") - .doWrite(data()); + FesodSheet.write(response.getOutputStream(), DemoData.class) + .sheet("Sheet1") + .doWrite(data()); } ``` diff --git a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/style.md b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/style.md similarity index 76% rename from website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/style.md rename to website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/style.md index 562cc9c79..8d2a33bb0 100644 --- a/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/write/style.md +++ b/website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/style.md @@ -47,13 +47,14 @@ public class DemoStyleData { ### 代码示例 ```java + @Test public void annotationStyleWrite() { String fileName = "annotationStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoStyleData.class) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, DemoStyleData.class) + .sheet() + .doWrite(data()); } ``` @@ -72,6 +73,7 @@ public void annotationStyleWrite() { ### 代码示例 ```java + @Test public void handlerStyleWrite() { String fileName = "handlerStyleWrite" + System.currentTimeMillis() + ".xlsx"; @@ -93,12 +95,12 @@ public void handlerStyleWrite() { // 使用策略设置样式 HorizontalCellStyleStrategy styleStrategy = - new HorizontalCellStyleStrategy(headStyle, contentStyle); + new HorizontalCellStyleStrategy(headStyle, contentStyle); - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(styleStrategy) - .sheet("样式模板") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(styleStrategy) + .sheet("样式模板") + .doWrite(data()); } ``` @@ -148,14 +150,15 @@ public class CustomCellStyleWriteHandler implements CellWriteHandler { 使用 ```java + @Test public void customCellStyleWrite() { String fileName = "customCellStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CustomCellStyleWriteHandler()) - .sheet("自定义样式") - .doWrite(data()); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CustomCellStyleWriteHandler()) + .sheet("自定义样式") + .doWrite(data()); } ``` @@ -170,28 +173,29 @@ public void customCellStyleWrite() { ### 代码示例 ```java + @Test public void poiStyleWrite() { String fileName = "poiStyleWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, DemoData.class) - .registerWriteHandler(new CellWriteHandler() { - @Override - public void afterCellDispose(CellWriteHandlerContext context) { - if (BooleanUtils.isNotTrue(context.getHead())) { - Cell cell = context.getCell(); - Workbook workbook = context.getWriteWorkbookHolder().getWorkbook(); - - // 创建并设置样式 - CellStyle cellStyle = workbook.createCellStyle(); - cellStyle.setFillForegroundColor(IndexedColors.LIGHT_ORANGE.getIndex()); - cellStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); - cell.setCellStyle(cellStyle); + FesodSheet.write(fileName, DemoData.class) + .registerWriteHandler(new CellWriteHandler() { + @Override + public void afterCellDispose(CellWriteHandlerContext context) { + if (BooleanUtils.isNotTrue(context.getHead())) { + Cell cell = context.getCell(); + Workbook workbook = context.getWriteWorkbookHolder().getWorkbook(); + + // 创建并设置样式 + CellStyle cellStyle = workbook.createCellStyle(); + cellStyle.setFillForegroundColor(IndexedColors.LIGHT_ORANGE.getIndex()); + cellStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); + cell.setCellStyle(cellStyle); + } } - } - }) - .sheet("POI样式") - .doWrite(data()); + }) + .sheet("POI样式") + .doWrite(data()); } ``` @@ -228,13 +232,14 @@ public class WidthAndHeightData { ### 代码示例 ```java + @Test public void widthAndHeightWrite() { String fileName = "widthAndHeightWrite" + System.currentTimeMillis() + ".xlsx"; - FastExcel.write(fileName, WidthAndHeightData.class) - .sheet() - .doWrite(data()); + FesodSheet.write(fileName, WidthAndHeightData.class) + .sheet() + .doWrite(data()); } ``` diff --git a/website/sidebars.js b/website/sidebars.js index e2e8c5ac9..c7c88fd50 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -37,63 +37,67 @@ const sidebars = { { id: "introduce", type: "doc", - }, - { + }, { type: 'category', label: 'quickstart', items: [ 'quickstart/guide', 'quickstart/simple-example' ] - }, - { - type: 'category', - label: 'read', - items: [ - 'read/simple', - 'read/sheet', - 'read/num-rows', - 'read/csv', - 'read/head', - 'read/extra', - 'read/exception', - 'read/pojo', - 'read/converter', - 'read/spring' - ] - }, - { - type: 'category', - label: 'write', - items: [ - 'write/simple', - 'write/sheet', - 'write/image', - 'write/csv', - 'write/head', - 'write/extra', - 'write/format', - 'write/pojo', - 'write/style', - 'write/spring' - ] - }, - { - type: 'category', - label: 'fill', - items: [ - 'fill/fill' - ] - }, - { + }, { type: 'category', - label: 'help', + label: 'fesod-sheet', items: [ - 'help/annotation', - 'help/core-class', - 'help/parameter', - 'help/large-data', - "help/faq" + { + type: 'category', + label: 'read', + items: [ + 'sheet/read/simple', + 'sheet/read/sheet', + 'sheet/read/num-rows', + 'sheet/read/csv', + 'sheet/read/head', + 'sheet/read/extra', + 'sheet/read/exception', + 'sheet/read/pojo', + 'sheet/read/converter', + 'sheet/read/spring' + ], + }, + { + type: 'category', + label: 'write', + items: [ + 'sheet/write/simple', + 'sheet/write/sheet', + 'sheet/write/image', + 'sheet/write/csv', + 'sheet/write/head', + 'sheet/write/extra', + 'sheet/write/format', + 'sheet/write/pojo', + 'sheet/write/style', + 'sheet/write/spring' + ] + }, + { + type: 'category', + label: 'fill', + items: [ + 'sheet/fill/fill' + ] + }, + { + type: 'category', + label: 'help', + items: [ + 'sheet/help/annotation', + 'sheet/help/core-class', + 'sheet/help/parameter', + 'sheet/help/large-data', + "sheet/help/faq" + ] + } ] } ] diff --git a/website/src/css/custom.css b/website/src/css/custom.css index a0371fd9c..1285023a3 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -83,4 +83,20 @@ article header h2 { .footer__copyright p { text-align: justify; +} + +.theme-announcement-bar { + font-size: 20px; + + --site-announcement-bar-stripe-color1: var(--ifm-color-primary); + --site-announcement-bar-stripe-color2: var(--ifm-color-primary-lighter); + + background: repeating-linear-gradient( + 35deg, + var(--site-announcement-bar-stripe-color1), + var(--site-announcement-bar-stripe-color1) 20px, + var(--site-announcement-bar-stripe-color2) 10px, + var(--site-announcement-bar-stripe-color2) 40px + ); + font-weight: bold; } \ No newline at end of file diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 0d674cf30..9e980856b 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -47,7 +47,7 @@ function HomepageHeader() { + to="https://github.com/apache/fesod">