Тип QML Text

Определяет способ добавления форматированного текста в сцену Подробнее...

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

Свойства

• baseUrl : url
• bottomPadding : real
• clip : bool
• color : color
• contentHeight : real
• contentWidth : real
• effectiveHorizontalAlignment : перечисление
• elide : перечисление
• font.bold : bool
• font.capitalization : перечисление
• font.family : строка
• font.italic : bool
• font.letterSpacing : real
• font.pixelSize : int
• font.pointSize : real
• font.strikeout : bool
• font.styleName : строка
• font.underline : bool
• font.weight : перечисление
• font.wordSpacing : real
• fontSizeMode : перечисление
• horizontalAlignment : перечисление
• hoveredLink : строка
• leftPadding : real
• lineCount : int
• lineHeight : real
• lineHeightMode : перечисление
• linkColor : цвет
• maximumLineCount : int
• minimumPixelSize : int
• minimumPointSize : int
• padding : real
• renderType : перечисление
• rightPadding : real
• style : перечисление
• styleColor : цвет
• text : строка
• textFormat : перечисление
• topPadding : real
• truncated : bool
• verticalAlignment : перечисление
• wrapMode : перечисление

Сигналы

• lineLaidOut(объект line)
• linkActivated(строка link)
• linkHovered(строка link)

Методы

• doLayout()
• linkAt(real x, real y)

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

Элементы Text могут отображать как обычный, так и форматированный текст. Например, красный текст с определённым шрифтом и размером может быть определён так:

Text {
    text: "Hello World!"
    font.family: "Helvetica"
    font.pointSize: 24
    color: "red"
}

Форматированный текст определяется с использованием разметки в стиле HTML:

Text {
    text: "<b>Hello</b> <i>World!</i>"
}

Если высота и ширина не заданы явно, Text попытается определить необходимое пространство и установить его соответственно. Если wrapMode не задан, он всегда отдаёт предпочтение ширине высоте (весь текст будет помещён на одной строке).

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

Обратите внимание, что поддерживаемый подмножество HTML ограничено. Кроме того, если текст содержит теги HTML img, загружающие удалённые изображения, текст перезагружается.

Text предоставляет только чтение текста. Для редактирования текста см. TextEdit.

См. также Пример шрифтов.

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

baseUrl : url

Это свойство указывает базовый URL, который используется для разрешения относительных URL в тексте.

URL разрешаются, чтобы находиться в той же директории, что и целевой базовый URL, что означает, что любая часть пути после последнего '/' будет проигнорирована.

Значение по умолчанию — URL файла QML, создающего элемент Text.

bottomPadding : real

Эти свойства содержат отступы вокруг содержимого. Это пространство зарезервировано в дополнение к contentWidth и contentHeight.

Это свойство QML было добавлено в Qt 5.6.

clip : bool

Это свойство содержит значение, указывающее, обрезается ли текст.

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

Если вы хотите отобразить потенциально длинный текст в ограниченном пространстве, вам, вероятно, следует использовать elide вместо этого.

color : color

Цвет текста.

Пример зелёного текста, определённого с использованием шестнадцатеричного обозначения:

Text {
    color: "#00FF00"
    text: "green text"
}

Пример сине-стального текста, определённого с использованием имени цвета SVG:

Text {
    color: "steelblue"
    text: "blue text"
}

contentHeight : real

Возвращает высоту текста, включая высоту, превышающую высоту, которая покрыта из-за того, что текст больше, чем помещается в заданную высоту.

contentWidth : real

Возвращает ширину текста, включая ширину, превышающую ширину, которая покрыта из-за недостаточной обёртки, если WrapMode установлен.

effectiveHorizontalAlignment : перечисление

Устанавливает горизонтальное и вертикальное выравнивание текста в пределах ширины и высоты элементов Text. По умолчанию текст выравнивается по верхнему краю. Горизонтальное выравнивание следует естественному выравниванию текста, например, текст, который читается слева направо, выравнивается по левому краю.

Допустимые значения для horizontalAlignment являются Text.AlignLeft, Text.AlignRight, Text.AlignHCenter и Text.AlignJustify. Допустимые значения для verticalAlignment являются Text.AlignTop, Text.AlignBottom и Text.AlignVCenter.

Обратите внимание, что для одной строки текста размер текста — это площадь текста. В этом общем случае все выравнивания эквивалентны. Если вы хотите выровнять текст по центру в родительском элементе, вам нужно либо изменить Item::anchors, либо установить horizontalAlignment на Text.AlignHCenter и связать ширину с шириной родительского элемента.

При использовании присоединённого свойства LayoutMirroring::enabled для отражения макетов приложения, горизонтальное выравнивание текста также будет отражено. Однако свойство horizontalAlignment останется без изменений. Для запроса эффективного горизонтального выравнивания Text используйте только для чтения свойство effectiveHorizontalAlignment.

elide : перечисление

Установите это свойство для обрезания частей текста, не умещающихся по ширине элемента Text. Текст будет обрезан только при явном указании ширины.

Это свойство нельзя использовать с форматированным текстом.

Обрезка может быть:

• Text.ElideNone - значение по умолчанию
• Text.ElideLeft
• Text.ElideMiddle
• Text.ElideRight

Если это свойство установлено в Text.ElideRight, оно может использоваться с переносимым текстом. Текст будет обрезан только если maximumLineCount, или height было установлено. Если оба maximumLineCount и height установлены, maximumLineCount будет применено, если строки не помещаются в разрешённую высоту.

Если текст является строкой с несколькими длинами, и режим не Text.ElideNone, будет использована первая строка, которая подходит, в противном случае будет обрезан последний элемент.

Строки с несколькими длинами упорядочены от длинной к короткой, разделенные символом Unicode «String Terminator» U009C (запишите это в QML с "\u009C" или "\x9C").

font.bold : bool

Устанавливает, является ли вес шрифта полужирным.

font.capitalization : перечисление

Устанавливает регистр текста.

• Font.MixedCase - это нормальный вариант отображения текста, где не применяются изменения регистра.
• Font.AllUppercase - изменяет текст на прописные буквы.
• Font.AllLowercase - изменяет текст на строчные буквы.
• Font.SmallCaps - изменяет текст на полужирные малые буквы.
• Font.Capitalize - изменяет текст, чтобы первая буква каждого слова была заглавной.

Text { text: "Hello"; font.capitalization: Font.AllLowercase }

font.family : строка

Устанавливает имя семейства шрифта.

Имя семейства нечувствительно к регистру и может необязательно включать имя типографии, например, «Helvetica [Cronyx]». Если семейство доступно более чем от одной типографии, и типография не указана, произвольно выбирается типография. Если семейство недоступно, семейство будет установлено с использованием алгоритма подбора шрифтов.

font.italic : bool

Устанавливает, имеет ли шрифт курсивный стиль.

font.letterSpacing : вещественное

Устанавливает интерлиньяж для шрифта.

Изменение интерлиньяжа изменяет стандартное расстояние между отдельными буквами в шрифте. Положительное значение увеличивает расстояние между буквами на соответствующее количество пикселей; отрицательное значение уменьшает расстояние.

font.pixelSize : целое число

Устанавливает размер шрифта в пикселях.

Использование этой функции делает шрифт зависящим от устройства. Используйте pointSize для установки размера шрифта независимо от устройства.

font.pointSize : вещественное

Устанавливает размер шрифта в пунктах. Размер пункта должен быть больше нуля.

font.strikeout : bool

Устанавливает, имеет ли шрифт стиль зачёркивания.

font.styleName : строка

Устанавливает имя стиля шрифта.

Имя стиля нечувствительно к регистру. Если установлено, шрифт будет сопоставлен с именем стиля вместо свойств шрифта font.weight, font.bold и font.italic.

Это свойство QML было добавлено в Qt 5.6.

font.underline : bool

Устанавливает, подчёркивается ли текст.

font.weight : перечисление

Устанавливает вес шрифта.

Вес может быть одним из:

• Font.Thin
• Font.Light
• Font.ExtraLight
• Font.Normal - значение по умолчанию
• Font.Medium
• Font.DemiBold
• Font.Bold
• Font.ExtraBold
• Font.Black

Text { text: "Hello"; font.weight: Font.DemiBold }

font.wordSpacing : вещественное

Устанавливает интервалы между словами для шрифта.

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

fontSizeMode : перечисление

Это свойство определяет, как определяется размер шрифта отображаемого текста. Возможные значения:

• Text.FixedSize (по умолчанию) - используется размер, указанный в font.pixelSize или font.pointSize.
• Text.HorizontalFit - используется наибольший размер до указанного, который помещается в ширину элемента без переноса строк.
• Text.VerticalFit - используется наибольший размер до указанного, который помещается по высоте элемента.
• Text.Fit - используется наибольший размер до указанного, который помещается в ширину и высоту элемента.

Размер шрифта при подгонке имеет минимальную границу, заданную свойством minimumPointSize или minimumPixelSize, и максимальную границу, заданную либо свойством font.pointSize, либо font.pixelSize.

Text { text: "Hello"; fontSizeMode: Text.Fit; minimumPixelSize: 10; font.pixelSize: 72 }

Если текст не помещается в границы элемента с минимальным размером шрифта, текст будет обрезан в соответствии со свойством elide.

horizontalAlignment : перечисление

Устанавливает горизонтальное и вертикальное выравнивание текста по ширине и высоте элемента Text. По умолчанию текст выравнивается по верху. Горизонтальное выравнивание соответствует естественному выравниванию текста, например, текст, читаемый слева направо, будет выровнен по левому краю.

Допустимые значения для horizontalAlignment являются Text.AlignLeft, Text.AlignRight, Text.AlignHCenter и Text.AlignJustify. Допустимые значения для verticalAlignment являются Text.AlignTop, Text.AlignBottom и Text.AlignVCenter.

Обратите внимание, что для одной строки текста размер текста — это площадь текста. В этом распространённом случае все выравнивания эквивалентны. Если вы хотите, чтобы текст, например, был центрирован в своём родителе, вам необходимо либо изменить Item::anchors, либо установить horizontalAlignment в Text.AlignHCenter и привязать ширину к ширине родителя.

При использовании присоединённого свойства LayoutMirroring::enabled для отражения макетов приложения, горизонтальное выравнивание текста также будет отражено. Однако свойство horizontalAlignment останется без изменений. Для запроса эффективного горизонтального выравнивания Text используйте только для чтения свойство effectiveHorizontalAlignment.

hoveredLink : строка

Это свойство содержит строку ссылки, когда пользователь наводит указатель мыши на ссылку, встроенную в текст. Ссылка должна быть в формате форматированного текста или HTML, и строка hoveredLink обеспечивает доступ к конкретной ссылке.

Это свойство QML было добавлено в Qt 5.2.

См. такжеlinkHovered и linkAt().

leftPadding : вещественное

Эти свойства содержат отступы вокруг содержимого. Это пространство зарезервировано в дополнение к contentWidth и contentHeight.

Это свойство QML было добавлено в Qt 5.6.

lineCount : целое число

Возвращает количество видимых строк в элементе текста.

Это свойство не поддерживается для форматированного текста.

См. такжеmaximumLineCount.

lineHeight : вещественное

Устанавливает интерлиньяж для текста. Значение может быть в пикселях или в множителе, в зависимости от lineHeightMode.

Значение по умолчанию — множитель 1.0. Интерлиньяж должен быть положительным значением.

lineHeightMode : перечисление

Это свойство определяет, как задаётся интерлиньяж. Возможные значения:

• Text.ProportionalHeight (по умолчанию) - задаёт интерлиньяж пропорционально строке (как множитель). Например, установлено в 2 для двойного интервала.
• Text.FixedHeight - устанавливает интерлиньяж с фиксированной высотой (в пикселях).

linkColor : цвет

Цвет ссылок в тексте.

Это свойство работает с форматированным текстом textFormat, но не с RichText. Цвет ссылок в RichText можно указать, включив теги стиля CSS в текст.

maximumLineCount : целое число

Установите это свойство для ограничения количества строк, которое будет отображать элемент текста. Если elide установлено в Text.ElideRight, текст будет обрезан соответствующим образом. По умолчанию это значение максимального целого числа.

Это свойство не поддерживается для форматированного текста.

См. также lineCount и elide.

minimumPixelSize : целое число

Данное свойство задаёт минимальный размер шрифта в пикселях, масштабируемый свойством fontSizeMode.

Если свойство fontSizeMode равно Text.FixedSize или свойство font.pixelSize равно -1, то это свойство игнорируется.

minimumPointSize : int

Данное свойство задаёт минимальный размер шрифта в пунктах, масштабируемый свойством fontSizeMode.

Если свойство fontSizeMode равно Text.FixedSize или свойство font.pointSize равно -1, то это свойство игнорируется.

padding : real

Эти свойства задают отступы вокруг содержимого. Это пространство зарезервировано дополнительно к contentWidth и contentHeight.

Это свойство QML было введено в Qt 5.6.

renderType : enumeration

Переопределяет тип рендеринга по умолчанию для этого компонента.

Поддерживаемые типы рендеринга:

• Text.QtRendering - значение по умолчанию
• Text.NativeRendering

Выберите Text.NativeRendering, если вы предпочитаете, чтобы текст выглядел естественно на целевой платформе и вам не требуются расширенные функции, такие как преобразование текста. Использование таких функций в сочетании с типом рендеринга NativeRendering приведёт к плохим, а иногда и размытым результатам.

rightPadding : real

Эти свойства задают отступы вокруг содержимого. Это пространство зарезервировано дополнительно к contentWidth и contentHeight.

Это свойство QML было введено в Qt 5.6.

style : enumeration

Устанавливает дополнительный стиль текста.

Поддерживаемые стили текста:

• Text.Normal - значение по умолчанию
• Text.Outline
• Text.Raised
• Text.Sunken

Row {
    Text { font.pointSize: 24; text: "Normal" }
    Text { font.pointSize: 24; text: "Raised"; style: Text.Raised; styleColor: "#AAAAAA" }
    Text { font.pointSize: 24; text: "Outline";style: Text.Outline; styleColor: "red" }
    Text { font.pointSize: 24; text: "Sunken"; style: Text.Sunken; styleColor: "#AAAAAA" }
}

styleColor : color

Определяет вторичный цвет, используемый стилями текста.

styleColor используется в качестве цвета контура для контурного текста и как цвет тени для поднятого или опущенного текста. Если стиль не установлен, он вообще не используется.

Text { font.pointSize: 18; text: "hello"; style: Text.Raised; styleColor: "gray" }

См. также style.

text : string

Текст для отображения. Текст поддерживает как обычный, так и форматированный текст.

Элемент попытается автоматически определить, должен ли текст обрабатываться как форматированный текст. Это определение выполняется с помощью Qt::mightBeRichText().

textFormat : enumeration

Способ отображения свойства text.

Поддерживаемые форматы текста:

• Text.AutoText (по умолчанию)
• Text.PlainText
• Text.StyledText
• Text.RichText

Если формат текста равен Text.AutoText элемент Text автоматически определяет, должен ли текст обрабатываться как форматированный текст. Это определение выполняется с помощью Qt::mightBeRichText(), которая использует быстрый и, следовательно, простой эвристический подход. В основном проверяется, есть ли что-то, что выглядит как тег, перед первой строкой перевода. Хотя результат может быть верным для распространённых случаев, гарантии нет.

Text.StyledText — это оптимизированный формат, поддерживающий некоторые базовые форматирования текста, в стиле HTML 3.2:

<b></b> - bold
<strong></strong> - bold
<i></i> - italic
<br> - new line
<p> - paragraph
<u> - underlined text
<font color="color_name" size="1-7"></font>
<h1> to <h6> - headers
<a href=""> - anchor
<img src="" align="top,middle,bottom" width="" height=""> - inline images
<ol type="">, <ul type=""> and <li> - ordered and unordered lists
<pre></pre> - preformatted
&gt; &lt; &amp;

Text.StyledText анализатор строгий, требующий правильного вложенности тегов.

Column {
    Text {
        font.pointSize: 24
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.RichText
        text: "<b>Hello</b> <i>World!</i>"
    }
    Text {
        font.pointSize: 24
        textFormat: Text.PlainText
        text: "<b>Hello</b> <i>World!</i>"
    }
}

Text.RichText поддерживает более широкий набор функций HTML 4, как описано на странице Поддерживаемый подмножество HTML. Вы должны предпочесть использование Text.PlainText или Text.StyledText, поскольку они обеспечивают лучшую производительность.

topPadding : real

Эти свойства задают отступы вокруг содержимого. Это пространство зарезервировано дополнительно к contentWidth и contentHeight.

Это свойство QML было введено в Qt 5.6.

truncated : bool

Возвращает true, если текст был усечён из-за maximumLineCount или elide.

Это свойство не поддерживается для форматированного текста.

См. также maximumLineCount и elide.

verticalAlignment : enumeration

Устанавливает горизонтальное и вертикальное выравнивание текста внутри ширины и высоты элементов Text. По умолчанию текст выравнивается по верху. Горизонтальное выравнивание соответствует естественному выравниванию текста, например, текст, читаемый слева направо, будет выровнен по левому краю.

Допустимые значения для horizontalAlignment являются Text.AlignLeft, Text.AlignRight, Text.AlignHCenter и Text.AlignJustify. Допустимые значения для verticalAlignment являются Text.AlignTop, Text.AlignBottom и Text.AlignVCenter.

Обратите внимание, что для одной строки текста размер текста соответствует области текста. В этом распространённом случае все выравнивания эквивалентны. Если вы хотите, чтобы текст, например, был центрирован в родительском элементе, вам нужно либо изменить Item::anchors, либо установить horizontalAlignment на Text.AlignHCenter и связать ширину с шириной родительского элемента.

При использовании присоединённого свойства LayoutMirroring::enabled для зеркального отображения макета приложения, горизонтальное выравнивание текста также будет зеркально отображено. Однако свойство horizontalAlignment останется неизменным. Для запроса эффективного горизонтального выравнивания Text используйте только для чтения свойство effectiveHorizontalAlignment.

wrapMode : enumeration

Установите это свойство для перевода текста на ширину элемента Text. Текст будет переноситься только при явном указании ширины. wrapMode может быть одним из:

• Text.NoWrap (по умолчанию) — перенос не будет выполняться. Если текст содержит недостаточно символов новой строки, то contentWidth превысит заданную ширину.
• Text.WordWrap — перенос выполняется только по границам слов. Если слово слишком длинное, то contentWidth превысит заданную ширину.
• Text.WrapAnywhere — перенос выполняется в любой точке строки, даже если это происходит посреди слова.
• Text.Wrap — если возможно, перенос выполняется по границам слов; в противном случае он выполняется в соответствующей точке строки, даже посреди слова.

Документация сигналов

lineLaidOut(object line)

Этот сигнал испускается для каждой строки текста, которая выкладывается во время процесса выкладки. Указанный объект line предоставляет более подробную информацию о строке, которая в настоящее время выкладывается.

Это даёт возможность позиционировать и изменять размер строки по мере её выкладки. Например, это можно использовать для создания столбцов или выкладки текста вокруг объектов.

Свойства указанного объекта line:

• number (только для чтения)
• x
• y
• width
• height

Например, это сместит первые 5 строк элемента Text на 100 пикселей вправо:

onLineLaidOut: {
    if (line.number < 5) {
        line.x = line.x + 100
        line.width = line.width - 100
    }
}

Соответствующий обработчик — onLineLaidOut.

linkActivated(string link)

Этот сигнал испускается, когда пользователь нажимает на ссылку, встроенную в текст. Ссылка должна быть в формате форматированного или HTML-текста, и строка link обеспечивает доступ к конкретной ссылке.

    Text {
            textFormat: Text.RichText
            text: "See the <a href=\"http://qt-project.org\">Qt Project website</a>."
            onLinkActivated: console.log(link + " link activated")
    }

Пример кода отобразит текст "Посетите сайт Qt Project".

Нажатие на выделенную ссылку выведет http://qt-project.org link activated в консоль.

Соответствующий обработчик — onLinkActivated.

linkHovered(string link)

Этот сигнал испускается, когда пользователь наводит указатель на ссылку, встроенную в текст. Ссылка должна быть в формате форматированного или HTML-текста, и строка link обеспечивает доступ к конкретной ссылке.

Соответствующий обработчик — onLinkHovered.

Этот сигнал QML был введён в Qt 5.2.

См. также hoveredLink и linkAt().

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

doLayout()

Вызывает повторную выкладку отображаемого текста.

linkAt(real x, real y)

Возвращает строку ссылки в точке x, y в координатах содержимого или пустую строку, если в этой точке ссылки нет.

Этот метод QML был введён в Qt 5.3.

См. также hoveredLink.