Тип QML Date

Предоставляет функции работы с датой. Подробнее...

• Список всех членов, включая унаследованные

Методы

• строка fromLocaleDateString(locale, dateString, format)
• строка fromLocaleString(locale, dateTimeString, format)
• строка fromLocaleTimeString(locale, timeString, format)
• строка timeZoneUpdated()
• строка toLocaleDateString(locale, format)
• строка toLocaleString(locale, format)
• строка toLocaleTimeString(locale, format)

Подробное описание

Объект QML Date расширяет объект JS Date с функциями, учитывающими локаль.

Функции, принимающие аргумент format, принимают значения перечисления Locale.LongFormat, Locale.ShortFormat, Locale.NarrowFormat или строку, определяющую формат.

Значения перечисления формата

Используйте значения перечисления, когда вам нужен формат, соответствующий настройкам локали.

Формат, представленный перечислениями, будет зависеть от вашей локали, а также от метода, для которого используется перечисление.

Например, для локали en_US, используются эти строки формата:

Строки формата

Вы также можете указать строку формата напрямую.

Эти выражения могут быть использованы для форматирования дат:

Все остальные символы ввода будут проигнорированы. Любая последовательность символов, заключенная в одинарные кавычки, будет обрабатываться как текст и не будет использоваться как выражение. Две последовательные одинарные кавычки ("''") заменяются одной одинарной кавычкой в выводе.

Примеры строк формата (предполагается, что дата — 20 июля 1969 года):

Эти выражения могут использоваться для форматирования времени:

Все остальные символы ввода будут проигнорированы. Любая последовательность символов, заключенная в одинарные кавычки, будет обрабатываться как текст и не будет использоваться как выражение. Две последовательные одинарные кавычки ("''") заменяются одной одинарной кавычкой в выводе.

Примеры строк формата (предполагается, что время — 14:13:09.042):

Если дата недействительна, возвращается пустая строка.

Дополнительные заметки

Использование функций, учитывающих локаль, для форматирования даты или времени может привести к некорректному формату времени из-за несоответствия в спецификации между Qt и JS. ECMA-262 определяет, что исторические даты должны интерпретироваться путём проектирования текущих правил перехода на летнее время на прошлые годы, в то время как Qt использует исторические данные (если они доступны) для определения того, было ли летнее время в действии для данной даты. Поэтому построение значения Date в JS и преобразование его в строку с помощью функций, учитывающих локаль, может привести к результату, ошибочному на один час, если DST сейчас в действии, а не было в то время, указанное, или наоборот.

Существуют различные форматы дат с разным пониманием отрицательных годов. В обычном человеческом языке нет года 0. Год после 1 до н. э. — 1 н. э. Это понимание отражается при печати или анализе дат в одном из форматов, не стандартизованных ECMAScript. То есть: toString(), toLocaleString(), toUTCString() и т. п. ECMAScript стандартизирует только один формат: ISO 8601. Это то, что вы получаете при вызове toISOString(). Этот формат включает год 0, который в других форматах — 1 до н. э. Таким образом, при печати отрицательных дат с toISOString() и toString() получаются разные годы.

При установке года с помощью конструктора Date или set(UTC)FullYear(), используется соглашение, заданное ISO 8601, и 0 — допустимый год. Это означает, что отрицательные годы, установленные с помощью конструктора или set(UTC)FullYear(), основаны на нуле, и, следовательно, смещены на один год от того, что печатается с помощью toString() и т. п. Анализ вывода любого из методов to*String() вернёт то же значение даты, что и выведенное вами. Date.parse() распознает различные форматы и их соглашения о существовании года 0.

Обратите внимание, что всё это отличается от того, что вы получаете в других реализациях JavaScript, которые обычно рассматривают год 0 как допустимый во всех строковых представлениях. Поскольку форматы дат являются «зависимыми от реализации» в стандарте ECMAScript, это всё ещё допустимо.

См. также Locale.

Документация методов

строка fromLocaleDateString(locale, dateString, format)

Преобразует строку даты dateString в объект Date с использованием locale и format.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример демонстрирует, как текущая дата сначала форматируется как строка даты с использованием локали и формата по умолчанию, а затем анализируется обратно аналогичным образом:

import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property date currentDate: new Date()
    property string dateString

    Component.onCompleted: {
        dateString = currentDate.toLocaleDateString();
        print(Date.fromLocaleDateString(dateString));
    }
}

строка fromLocaleString(locale, dateTimeString, format)

Преобразует строку даты и времени dateTimeString в объект Date с использованием locale и format.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример показывает преобразование строки даты и времени в определённом формате с использованием локале по умолчанию:

import QtQml 2.0

QtObject {
    property var locale: Qt.locale()
    property string dateTimeString: "Tue 2013-09-17 10:56:06"

    Component.onCompleted: {
        print(Date.fromLocaleString(locale, dateTimeString, "ddd yyyy-MM-dd hh:mm:ss"));
    }
}

string fromLocaleTimeString(locale, timeString, format)

Преобразует строку времени timeString в объект Date с использованием locale и format.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример демонстрирует, как текущее время сначала форматируется как строка времени с использованием локали по умолчанию и короткого формата, а затем преобразуется обратно аналогичным образом:

import QtQml 2.2

QtObject {
    property var locale: Qt.locale()
    property date currentTime: new Date()
    property string timeString

    Component.onCompleted: {
        timeString = currentTime.toLocaleTimeString(locale, Locale.ShortFormat);
        print(Date.fromLocaleTimeString(locale, timeString, Locale.ShortFormat));
    }
}

string timeZoneUpdated()

Сообщает движку JS, что часовой пояс системы был изменён, что необходимо для корректной обработки данных даты и времени.

JS хранит объекты Date в формате UTC; все операции доступа к компонентам даты и времени в местном времени включают применение текущего смещения от UTC. Если текущее смещение изменяется из-за обновления часового пояса, движку JS необходимо сообщить об этом, чтобы он мог пересчитать смещение.

Эта функция должна вызываться после обновления часового пояса системы.

Например, приложение, изменяющее часовой пояс, вызвало бы timeZoneUpdated() после установки нового часового пояса:

property string selectedTimeZone

onSelectedTimeZoneChanged: {
    MyFunctions.setSystemTimeZone(selectedTimeZone)
    Date.timeZoneUpdated()
}

string toLocaleDateString(locale, format)

Преобразует дату в строку, содержащую дату, подходящую для указанной locale в указанном формате.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример демонстрирует форматирование текущей даты для немецкой локали:

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleDateString(Qt.locale("de_DE"))
}

string toLocaleString(locale, format)

Преобразует дату в строку, содержащую дату и время, подходящую для указанной locale в указанном формате.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример демонстрирует форматирование текущей даты и времени для немецкой локали:

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleString(Qt.locale("de_DE"))
}

string toLocaleTimeString(locale, format)

Преобразует дату в строку, содержащую время, подходящую для указанной locale в указанном формате.

Если format не указан, используется Locale.LongFormat.

Если locale не указан, используется локаль по умолчанию.

Следующий пример демонстрирует форматирование текущего времени для немецкой локали:

import QtQuick 2.0

Text {
    text: "The date is: " + new Date().toLocaleTimeString(Qt.locale("de_DE"))
}