Форматирование чисел

DHTMLX Spreadsheet поддерживает форматирование чисел, которое можно применять к числовым значениям в ячейках.

Примечание

Руководство пользователя поможет вашим пользователям легко работать со Spreadsheet.

Форматы чисел по умолчанию

Формат числа — это объект, включающий набор свойств:

• id - идентификатор формата, используемый для задания формата ячейки методом setFormat()
• mask - маска числового формата. Список доступных в маске символов приведён ниже
• name - название формата, отображаемое в выпадающих списках панели инструментов и меню
• example - пример того, как выглядит отформатированное число. По умолчанию для примеров форматов используется число 2702.31

Форматы чисел по умолчанию:

defaultFormats = [
    { name: "Common", id: "common", mask: "", example: "1500.31" },
    { name: "Number", id: "number", mask: "#,##0.00", example: "1,500.31" },
    { name: "Percent", id: "percent", mask: "#,##0.00%", example: "1,500.31%" },
    { name: "Currency", id: "currency", mask: "$#,##0.00", example: "$1,500.31" },
    { name: "Date", id: "date", mask: "mm-dd-yy", example: "28/12/2021" },
    { 
        name: "Time",
           id: "time",
           mask: hh:mm:ss am/pm || hh:mm:ss, // depending on the localization.timeFormat config
           example: "13:30:00"
    },
    { name: "Text", id: "text", mask: "@", example: "'1500.31'" },
    { name: "Scientific", id: "scientific", mask: "0.00E+00", example: "1.50E+03" }
];

Вот как выглядит таблица с данными в различных числовых форматах:

Формат даты

Формат отображения дат в таблице можно задать с помощью опции dateFormat свойства localization. Формат по умолчанию — "%d/%m/%Y".

const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {
    localization: {
        dateFormat: "%D/%M/%Y",
    }
});

spreadsheet.parse({
    styles: {
        // a set of styles
    },
    data: [
        {cell: "B1", value: "03/10/2022", format: "date"},
        {cell: "B2", value: new Date(), format: "date"},
    ]
});

Ознакомьтесь с полным списком доступных символов для создания форматов.

Формат времени

Чтобы задать формат отображения времени в ячейках таблицы, используйте опцию timeFormat свойства localization:

const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {
    localization: {
        timeFormat: 24,
    }
});

spreadsheet.parse({
    styles: {
        // a set of styles
    },
    data: [
        { cell: "A1", value: "18:30", format: "time" },
        { cell: "A2", value: 44550.5625, format: "time" },
        { cell: "A3", value: new Date(), format: "time" },
    ]
});

Локализация числа, даты, времени, валюты

С помощью параметров конфигурации Spreadsheet можно локализовать время и дату, указать нужный знак валюты, а также задать желаемые разделители десятичной части и тысяч. Все эти настройки доступны в свойстве localization. Это объект со следующими свойствами:

• decimal - (необязательный) символ, используемый в качестве десятичного разделителя, по умолчанию "." (точка)
  Возможные значения: "." | ","
• thousands - (необязательный) символ, используемый в качестве разделителя тысяч, по умолчанию "," (запятая)
  Возможные значения: "." | "," | " " | ""
• currency - (необязательный) знак валюты, по умолчанию "$"
• dateFormat - (необязательный) формат отображения дат в виде строки, по умолчанию "%d/%m/%Y". Подробнее на странице API localization
• timeFormat - (необязательный) формат отображения времени: 12 или 24, по умолчанию 12

Например, настройки локализации по умолчанию можно изменить следующим образом:

const spreadsheet = new dhx.Spreadsheet("spreadsheet", {
    localization: {
        decimal: ",", 
        thousands: " ", 
        currency: "¥",  
        dateFormat: "%D/%M/%Y",
        timeFormat: 24
    }
});

spreadsheet.parse(dataset);

Вот результат настройки объекта localization для Spreadsheet:

Научный числовой формат

Научная (экспоненциальная) запись доступна как формат по умолчанию и удобна для краткого представления очень больших или очень маленьких чисел. Встроенный формат "scientific" использует маску 0.00E+00, которая отображает, например, 1500.31 как 1.50E+03.

Чтобы применить его к ячейке, используйте метод setFormat():

spreadsheet.setFormat("A1", "scientific");

Также можно задать пользовательский научный формат с другой маской через параметр конфигурации formats. Например, маска 0.###E+0 даёт более компактный результат:

const spreadsheet = new dhx.Spreadsheet("spreadsheet_container", {
    formats: [
        { id: "scientific_compact", mask: "0.###E+0", name: "Scientific (compact)", example: "1.5E+3" }
    ]
});

Настройка форматов

Вы не ограничены форматами чисел по умолчанию. Форматы можно настраивать двумя способами:

• изменять настройки стандартных числовых форматов
• добавлять пользовательские числовые форматы в таблицу

Все эти изменения выполняются с помощью параметра конфигурации formats. Это массив объектов форматов, каждый из которых содержит набор свойств:

• id - (string) обязательный, идентификатор формата, используемый для задания формата ячейки методом setFormat()
• mask - (string) обязательный, маска числового формата. Список доступных в маске символов приведён ниже
• name - (string) необязательный, название формата, отображаемое в выпадающих списках панели инструментов и меню
• example - (string) необязательный, пример того, как выглядит отформатированное число

Структура маски

Маска может содержать набор стандартных синтаксических символов, включая заполнители цифр, разделители, знаки процента и валюты, допустимые символы:

• 0 - цифра числа. Используется для отображения незначащих нулей, если цифр в числе меньше, чем нулей в формате. Например, чтобы отобразить 2 как 2.0, используйте формат 0.0.
• # - цифра числа. Используется для отображения только значащих цифр (незначащие нули будут опущены, если цифр в числе меньше, чем символов # в формате).
• $ - форматирует числа как денежное значение в долларах. Чтобы использовать другой знак валюты, его нужно определить в маске как [$ your_currency_sign]#,##0.00, например, [$ €]#,##0.00.

Примечание

Обратите внимание, что все символы между [$ и ] будут интерпретированы как знак валюты.

• .(точка) - добавляет десятичную точку к числам.
• ,(запятая) - добавляет разделитель тысяч к числам.
• символы для задания формата даты - используются для создания маски даты и времени. Например, чтобы отобразить 27.09.2023 как 27, Sep 2023, используйте формат "%d, %M %Y".
• E+ / E- - форматирует числа в научной (экспоненциальной) записи. Цифры после E задают минимальное количество разрядов показателя степени. E+ всегда показывает знак показателя; E- показывает его только для отрицательных показателей. Например, маска 0.00E+00 отображает 1500.31 как 1.50E+03.

Установка формата

Чтобы применить нужный формат к числовому значению, используйте метод setFormat(). Он принимает два параметра:

• cell - (string) идентификатор ячейки, значение которой нужно отформатировать
• format - (string) название стандартного числового формата, применяемого к значению ячейки

Например:

// применяет процентный формат к ячейке A1
spreadsheet.setFormat("A1","percent");

Получение формата

Числовой формат, применённый к значению ячейки, можно получить методом getFormat(). Метод принимает идентификатор ячейки в качестве параметра.

var format = spreadsheet.getFormat("A1"); 
// ->"percent"

События

Для контроля изменений формата ячейки можно использовать пару событий:

• beforeAction - срабатывает перед выполнением действия setCellFormat
• afterAction - срабатывает после выполнения действия setCellFormat