@sheetxl/models
Version:
Models - A Headless javascript spreadsheet library.
201 lines • 8.14 kB
TypeScript
import { ICellModel, CellType, ICellValue } from "../cell";
import { AdjustedColor } from "../color";
export interface ParseNumberFormatCharPlaceHolder {
offset: number;
char: string;
}
export declare enum ParseNumberFormatRunType {
Text = "text",
Repeat = "repeat",
Spacing = "spacing"
}
export interface ParseNumberFormatRun {
type: ParseNumberFormatRunType;
width: number;
text: string;
}
export interface ParseNumberFormatRuns {
runs: readonly ParseNumberFormatRun[];
readonly length: number;
readonly width: number;
readonly lastRepeatIndex: number;
}
/**
* This interface returns rendering information about the formatted text based on the numberFormat
*
* https://customformats.com/
* https://exceljet.net/custom-number-formats
* https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1
*/
export interface ParsedNumberFormat {
/**
* Never null
*/
readonly displayText: string;
/**
* If there is a conditional color then this is the color to use.
*/
readonly conditionalColor: AdjustedColor | null;
/**
* From the '*' formatChar.
* A single character (usually a ' ' but can be anything)
*
* Repeats the next character in the format enough times to fill the column to its current width.
* There shall not be more than one asterisk in one section of the format. If more than one asterisk
* appears in one section of the format, all but the last asterisk shall be ignored.
* [Example: if the number format is 0*x, and the value 3 is in the cell, the value 3xxxxxx is displayed.
* The number of x characters that are displayed in the cell varies based on the width of the column. end example]
*/
readonly repeatChars: ParseNumberFormatCharPlaceHolder[];
/**
* If this is not null then the character should be displayed this many times.
* This is is used if the text does not fit or if the value doesn't render against
* the type correctly (for example a negative date)
* @remarks
* This is different than repeatChars in that it will only display the value
* and not any additional .
*/
readonly repeatPlaceholder: string | null;
/**
* From the '_' formatChar.
* An array of single characters.
*
* Skips the width of the next character.
* This is useful for lining up negative and positive values in different cells of the same column.
* [Example: The number format _(0.0_);(0.0) aligns the numbers 2.3 and the column even though the
* negative number is enclosed by parentheses. end example]
*/
readonly spacingChars: ParseNumberFormatCharPlaceHolder[];
/**
* The displayText broken down into runs. This is useful for more complex layouts.
*/
readonly formattedRuns: ParseNumberFormatRuns;
/**
* If true then the text could wrap if it doesn't fit.
*/
readonly canWrap: boolean;
/**
* If the format is a date format then this is true.
*/
readonly isDateFormat: boolean;
/**
* If the format is a time format then this is true.
*/
readonly isTimeFormat: boolean;
/**
* Return the value as a javascript date if possible. Will
* return null if not possible.
*/
readonly asDate: Date | null;
}
/**
* Return a legacy color as an rgb value
*/
export declare const convertToLegacyColor: (color: string) => string;
export interface NumberFormatOptions {
/**
* Is date 1904
*/
date1904?: boolean;
/**
* Parse a string of m/d/yy as date. We don't use as we do this using localization
*/
dateNF?: boolean;
/**
* Call when a repeat char
*/
onRepeatChar?: (offset: number, character: string) => void;
/**
* The character to add to the formatted string when a spacing character is
* introduced.
*
* @defaultValue ' '
*/
spacingCharacter?: string;
/**
* When '_' is encountered this is called.
*/
onSpacingChar?: (offset: number, character: string) => void;
/**
* When '?' this encountered this is called.
* @defaultValue ' '
*/
digitCharacter?: string;
onDigitChar?: (offset: number) => void;
locale?: string;
table?: any;
}
/**
* Language Code Identifier (LCIDs) are 'embedded' within numberFormat.
*
* There is the original (being deprecated) format and the new 'locale names' format.
* The original format (most widely used at time of writing but being deprecated). Is an 8 digit hex number (xxyyzzzz). If the number is less than this then it is assumed to have
* leading 0s. The hex is broken down into 3 parts.
* xx - appearance of the number (see)
*
* Also modern Excel 365 now allows this syntax: [$-lg-CN,xxyy] where lg-CN is the language and country of the locale (replacing zzzz), and xxyy are as defined in the prior answer. Leading zeros are not needed and the whole ,xxyy part is optional.
* In addition, a gannen suffix -x-gannen is allowed on Japanese locale codes, which replaces a 1 value (first year of emperor reign) for e formats with 元. For example:
*/
export declare const formatValue: (format: string, value: any, options: NumberFormatOptions) => string;
export declare const parseNumberFormat: (numberFormat: string, cell: ICellModel, resolveColor: (val: any) => AdjustedColor, date1904: boolean) => ParsedNumberFormat;
export interface UnformattedTextOptions {
date1904: boolean;
}
/**
* Note - Even in the case of unformatted text we do a 'minimum' amount. For example we convert dates and percentages
*/
export declare const unformattedTextFromCell: (value: ICellValue, type: CellType, numberFormat: string, options: UnformattedTextOptions) => string;
/**
* Colors, spacing, column width adjustments (turning a long number into scientific notation)
*
* https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1
*
* Rules to accommodate.
* 1. Defaults Formatting rules (based on # of parts 1 - 4)
* a. (4) >0;<0;=0; text
* b. (3) >0;<0;=0; (General for text)
* c. (2) >=0;<0; (General for text)
* d. (1) Value is not considered
* 2. Custom formatting rules specified with brackets []
* If custom formatting rules are applied then only 1 -3 parts
a. 1-2 parts can contain custom rules. last part (if 3rd part can be a default format.
b. If a custom eval is used no default and value doesn't match then returns overflow ([Red][<=100]General;[Blue][>100]General)
* 3. Color rules
* a. color definition
* i. 8 standard colors [Black],[Blue],[Cyan],[Green],[Magenta],[Red],[White],[Yellow]
* ii. and legacy colors codes - default legacy color palette values are listed in §18.8.27
* 4. Adjusting for width
* a. padding should only add the number of characters viewable
* b. Overflow (support for drawing ### when column width is too small)
*/
declare enum Operator {
Equal = "=",
NotEqual = "<>",
GreaterThan = ">",
LessThan = "<",
GreaterThanOrEqual = ">=",
LessThanOrEqual = "<="
}
type FormatCondition = {
op: Operator;
comp: number;
};
type ColorAndCondition = {
color: string | null;
condition: FormatCondition | null;
};
type FormatPart = {
format: string;
colorAndCondition: ColorAndCondition;
};
export declare const getConditionAndColor: (format: string, defaultCondition: FormatCondition) => ColorAndCondition;
export declare const getFormatParts: (format: string) => FormatPart[];
export declare const getConditionalColor: (value: any, format: string, type: CellType, resolveColor: (val: any) => AdjustedColor) => AdjustedColor;
export declare const isFractionFormatter: (fmt: string) => boolean;
/**
* Adjust the decimal in a format.
* @param type Optional but is checked to see if it's a number for the General use case.
*/
export declare const adjustDecimalPlaces: (format: string, amount: number, type?: CellType) => string;
export {};
//# sourceMappingURL=NumberFormatParser.d.ts.map