Перейти к основному содержимому

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

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

Выпадающий список форматов чисел в DHTMLX Spreadsheet с вариантами Common, Number, Currency, Percent, Date, Time и Text

Примечание

Руководство пользователя поможет вашим пользователям легко работать со 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(). Он принимает два параметра:

Например:

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

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

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

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

События​

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

  • beforeAction — срабатывает перед выполнением действия setCellFormat
  • afterAction — срабатывает после выполнения действия setCellFormat
Need more help?Contact Support