public class DataFormatter
extends java.lang.Object
Internally, formats will be implemented using subclasses of Format
such as DecimalFormat
and SimpleDateFormat
. Therefore the formats used by this class must obey the same pattern rules as these Format subclasses. This means that only legal number pattern characters ("0", "#", ".", "," etc.) may appear in number formats. Other characters can be inserted before or after the number pattern to form a prefix or suffix.
For example the Excel pattern "$#,##0.00 "USD"_);($#,##0.00 "USD")"
will be correctly formatted as "$1,000.00 USD" or "($1,000.00 USD)". However the pattern "00-00-00"
is incorrectly formatted by DecimalFormat as "000000--". For Excel formats that are not compatible with DecimalFormat, you can provide your own custom Format
implementation via DataFormatter.addFormat(String,Format)
. The following custom formats are already provided by this class:
If the Excel format pattern cannot be parsed successfully, then a default format will be used. The default number format will mimic the Excel General format: "#" for whole numbers and "#.##########" for decimal numbers. You can override the default format pattern with DataFormatter.setDefaultNumberFormat(Format)
. Note: the default format will only be used when a Format cannot be created from the cell's data format string.
Note that by default formatted numeric values are trimmed. Excel formats can contain spacers and padding and the default behavior is to strip them off.
Example:
Consider a numeric cell with a value 12.343
and format "##.##_ "
. The trailing underscore and space ("_ ") in the format adds a space to the end and Excel formats this cell as "12.34 "
, but DataFormatter
trims the formatted value and returns "12.34"
.
emulateCSV=true
flag in the
DateFormatter
cosntructor. If set to true, then the output tries to conform to what you get when you take an xls or xlsx in Excel and Save As CSV file:
DataFormatter
will output "0". Some formats are automatically "localized" by Excel, eg show as mm/dd/yyyy when loaded in Excel in some Locales but as dd/mm/yyyy in others. These are always returned in the "default" (US) format, as stored in the file. Some format strings request an alternate locale, eg [$-809]d/m/yy h:mm AM/PM
which explicitly requests UK locale. These locale directives are (currently) ignored. You can use DateFormatConverter
to do some of this localisation if you need it.
Constructor and Description |
---|
DataFormatter()
Creates a formatter using the
default locale .
|
DataFormatter(boolean emulateCSV)
Creates a formatter using the
default locale .
|
DataFormatter(java.util.Locale locale)
Creates a formatter using the given locale.
|
DataFormatter(java.util.Locale locale, boolean emulateCSV)
Creates a formatter using the given locale.
|
DataFormatter(java.util.Locale locale, boolean localeIsAdapting, boolean emulateCSV)
Creates a formatter using the given locale.
|
Modifier and Type | Method and Description |
---|---|
void |
addFormat(java.lang.String excelFormatStr, java.text.Format format)
Adds a new format to the available formats.
(向可用格式添加新格式。)
|
java.text.Format |
createFormat(Cell cell)
Create and return a Format based on the format string from a cell's style.
(根据单元格样式中的格式字符串创建并返回格式。)
|
java.lang.String |
formatCellValue(Cell cell)
Returns the formatted value of a cell as a
String regardless of the cell type.
(无论单元格类型如何,都将单元格的格式化值作为字符串返回。)
|
java.lang.String |
formatCellValue(Cell cell, FormulaEvaluator evaluator)
Returns the formatted value of a cell as a
String regardless of the cell type.
(无论单元格类型如何,都将单元格的格式化值作为字符串返回。)
|
java.lang.String |
formatCellValue(Cell cell, FormulaEvaluator evaluator, ConditionalFormattingEvaluator cfEvaluator)
Returns the formatted value of a cell as a
String regardless of the cell type.
(无论单元格类型如何,都将单元格的格式化值作为字符串返回。)
|
java.lang.String |
formatRawCellContents(double value, int formatIndex, java.lang.String formatString)
Formats the given raw cell value, based on the supplied format index and string, according to excel style rules.
(根据 excel 样式规则,根据提供的格式索引和字符串格式化给定的原始单元格值。)
|
java.lang.String |
formatRawCellContents(double value, int formatIndex, java.lang.String formatString, boolean use1904Windowing)
Formats the given raw cell value, based on the supplied format index and string, according to excel style rules.
(根据 excel 样式规则,根据提供的格式索引和字符串格式化给定的原始单元格值。)
|
java.text.Format |
getDefaultFormat(Cell cell)
Returns a default format for a cell.
(返回单元格的默认格式。)
|
java.beans.PropertyChangeSupport |
getLocaleChangedObservable()
If the Locale has been changed via
LocaleUtil.setUserLocale(Locale) the stored formats need to be refreshed.
(如果通过 LocaleUtil.setUserLocale(Locale) 更改了区域设置,则需要刷新存储的格式。)
|
void |
setDefaultNumberFormat(java.text.Format format)
Sets a default number format to be used when the Excel format cannot be parsed successfully.
(设置无法成功解析 Excel 格式时使用的默认数字格式。)
|
static void |
setExcelStyleRoundingMode(java.text.DecimalFormat format)
Enables excel style rounding mode (round half up) on the Decimal Format given.
(在给定的十进制格式上启用 excel 样式舍入模式(四舍五入)。)
|
static void |
setExcelStyleRoundingMode(java.text.DecimalFormat format, java.math.RoundingMode roundingMode)
Enables custom rounding mode on the given Decimal Format.
(在给定的十进制格式上启用自定义舍入模式。)
|
void |
updateLocale(java.util.Locale newLocale)
Update formats when locale has been changed
(更改语言环境时更新格式)
|
public DataFormatter()
default locale
.
(使用默认语言环境创建格式化程序。)
public DataFormatter(boolean emulateCSV)
default locale
.
(使用默认语言环境创建格式化程序。)
emulateCSV
- whether to emulate CSV output.
(emulateCSV - 是否模拟 CSV 输出。)
public DataFormatter(java.util.Locale locale)
public DataFormatter(java.util.Locale locale, boolean emulateCSV)
emulateCSV
- whether to emulate CSV output.
(emulateCSV - 是否模拟 CSV 输出。)
public DataFormatter(java.util.Locale locale, boolean localeIsAdapting, boolean emulateCSV)
localeIsAdapting
- (true only if locale is not user-specified)
(localeIsAdapting -(仅当区域设置不是用户指定时才为真))
emulateCSV
- whether to emulate CSV output.
(emulateCSV - 是否模拟 CSV 输出。)
public java.text.Format createFormat(Cell cell)
cell
- The Excel cell
(单元格 - Excel 单元格)
public java.text.Format getDefaultFormat(Cell cell)
cell
- The cell
(细胞——细胞)
public java.lang.String formatRawCellContents(double value, int formatIndex, java.lang.String formatString)
formatCellValue(Cell)
public java.lang.String formatRawCellContents(double value, int formatIndex, java.lang.String formatString, boolean use1904Windowing)
formatCellValue(Cell)
public java.lang.String formatCellValue(Cell cell)
Returns the formatted value of a cell as a String regardless of the cell type. If the Excel format pattern cannot be parsed then the cell value will be formatted using a default format.
When passed a null or blank cell, this method will return an empty String (""). Formulas in formula type cells will not be evaluated.
(无论单元格类型如何,都将单元格的格式化值作为字符串返回。如果无法解析 Excel 格式模式,则单元格值将使用默认格式进行格式化。当传递一个空或空白单元格时,此方法将返回一个空字符串 ("")。不会计算公式类型单元格中的公式。)cell
- The cell
(细胞——细胞)
public java.lang.String formatCellValue(Cell cell, FormulaEvaluator evaluator)
Returns the formatted value of a cell as a String regardless of the cell type. If the Excel number format pattern cannot be parsed then the cell value will be formatted using a default format.
When passed a null or blank cell, this method will return an empty String (""). Formula cells will be evaluated using the given FormulaEvaluator
if the evaluator is non-null. If the evaluator is null, then the formula String will be returned. The caller is responsible for setting the currentRow on the evaluator
cell
- The cell (can be null)
(cell - 单元格(可以为空))
evaluator
- The FormulaEvaluator (can be null)
(evaluator - FormulaEvaluator(可以为空))
public java.lang.String formatCellValue(Cell cell, FormulaEvaluator evaluator, ConditionalFormattingEvaluator cfEvaluator)
Returns the formatted value of a cell as a String regardless of the cell type. If the Excel number format pattern cannot be parsed then the cell value will be formatted using a default format.
When passed a null or blank cell, this method will return an empty String (""). Formula cells will be evaluated using the given FormulaEvaluator
if the evaluator is non-null. If the evaluator is null, then the formula String will be returned. The caller is responsible for setting the currentRow on the evaluator
When a ConditionalFormattingEvaluator is present, it is checked first to see if there is a number format to apply. If multiple rules apply, the last one is used. If no ConditionalFormattingEvaluator is present, no rules apply, or the applied rules do not define a format, the cell's style format is used.
The two evaluators should be from the same context, to avoid inconsistencies in cached values.
(无论单元格类型如何,都将单元格的格式化值作为字符串返回。如果无法解析 Excel 数字格式模式,则单元格值将使用默认格式进行格式化。当传递一个空或空白单元格时,此方法将返回一个空字符串 ("")。如果评估器不为空,则将使用给定的 FormulaEvaluator 评估公式单元格。如果求值器为空,则返回公式字符串。调用者负责在评估器上设置 currentRow 当存在 ConditionalFormattingEvaluator 时,首先检查它是否有要应用的数字格式。如果应用多个规则,则使用最后一个。如果不存在 ConditionalFormattingEvaluator、不应用任何规则或应用的规则未定义格式,则使用单元格的样式格式。两个评估者应该来自相同的上下文,以避免缓存值的不一致。)cell
- The cell (can be null)
(cell - 单元格(可以为空))
evaluator
- The FormulaEvaluator (can be null)
(evaluator - FormulaEvaluator(可以为空))
cfEvaluator
- ConditionalFormattingEvaluator (can be null)
(cfEvaluator - ConditionalFormattingEvaluator(可以为空))
public void setDefaultNumberFormat(java.text.Format format)
Sets a default number format to be used when the Excel format cannot be parsed successfully. Note: This is a fall back for when an error occurs while parsing an Excel number format pattern. This will not affect cells with the General format.
The value that will be passed to the Format's format method (specified by java.text.Format#format
) will be a double value from a numeric cell. Therefore the code in the format method should expect a Number
value.
format
- A Format instance to be used as a default
(format - 用作默认值的 Format 实例)
Format.format(java.lang.Object)
public void addFormat(java.lang.String excelFormatStr, java.text.Format format)
The value that will be passed to the Format's format method (specified by java.text.Format#format
) will be a double value from a numeric cell. Therefore the code in the format method should expect a Number
value.
excelFormatStr
- The data format string
(excelFormatStr - 数据格式字符串)
format
- A Format instance
(format - 一个 Format 实例)
public static void setExcelStyleRoundingMode(java.text.DecimalFormat format)
public static void setExcelStyleRoundingMode(java.text.DecimalFormat format, java.math.RoundingMode roundingMode)
format
- DecimalFormat
(格式 - 十进制格式)
roundingMode
- RoundingMode
(roundingMode - RoundingMode)
public java.beans.PropertyChangeSupport getLocaleChangedObservable()
LocaleUtil.setUserLocale(Locale)
the stored formats need to be refreshed. All formats which aren't originated from DataFormatter itself, i.e. all Formats added via
addFormat(String, Format)
and
setDefaultNumberFormat(Format)
, need to be added again. To notify callers, the returned
PropertyChangeSupport
should be used. The Locale in
updateLocale(Locale)
is the new Locale.
(如果通过 LocaleUtil.setUserLocale(Locale) 更改了区域设置,则需要刷新存储的格式。所有不是源自DataFormatter 本身的格式,即所有通过addFormat(String, Format) 和setDefaultNumberFormat(Format) 添加的格式,都需要重新添加。要通知调用者,应使用返回的 PropertyChangeSupport。 updateLocale(Locale) 中的 Locale 是新的 Locale。)
public void updateLocale(java.util.Locale newLocale)
newLocale
- the new locale
(newLocale - 新的语言环境)
Copyright 2021 The Apache Software Foundation or its licensors, as applicable.