Тип QML Text

Указывает, как добавить форматированный текст в сцену. Подробнее...

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

Свойства

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

Сигналы

• lineLaidOut(объект строка)
• linkActivated(строка ссылка)
• linkHovered(строка ссылка)

Методы

• forceLayout()
• linkAt(вещественное число x, вещественное число y)

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

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

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 ограничено. Кроме того, если текст содержит теги HTML img, загружающие удаленные изображения, текст перегружается.

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

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

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

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

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

Устанавливает выравнивание текста по горизонтали и вертикали в пределах ширины и высоты элементов 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.

advance : размер

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

Обратите внимание, что отступ может быть отрицательным, если текст течет справа налево.

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

antialiasing : bool

Используется для определения, следует ли использовать Text сглаживание или нет. Только Text с renderType Text.NativeRendering может отключить сглаживание.

Значение по умолчанию — true.

baseUrl : url

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

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

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

clip : bool

Этот параметр указывает, обрезается ли текст.

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

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

color : color

Цвет текста.

Пример зеленого текста, заданного в шестнадцатеричном формате:

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

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

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

contentHeight : real

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

contentWidth : real

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

elide : enumeration

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

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

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

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

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

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

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

font.bold : bool

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

font.capitalization : enumeration

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

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

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

font.family : string

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

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

font.hintingPreference : enumeration

Устанавливает предпочтительный способ подбора шрифта. Это подсказка для системы рендеринга текста использовать определённый уровень подбора, и поддержка зависит от платформы. Более подробную информацию см. в таблице документации для QFont::HintingPreference.

Примечание: Этот параметр имеет эффект только при использовании вместе с типом рендеринга Text.NativeRendering.

Font.PreferDefaultHinting — использовать уровень подбора по умолчанию для целевой платформы.

Font.PreferNoHinting — если возможно, рендерить текст без подбора контуров глифов. Макет текста будет типографически точным, используя те же метрики, что используются, например, при печати.

Font.PreferVerticalHinting — если возможно, рендерить текст без горизонтального подбора, но выравнивать глифы по пиксельной сетке в вертикальном направлении. Текст будет выглядеть более чётко на дисплеях с низкой плотностью пикселей, недостаточной для точного отображения глифов. Но поскольку горизонтальные метрики глифов не подбираются, макет текста будет масштабируемым для устройств с высокой плотностью пикселей (например, принтеров) без влияния на детали, такие как переносы строк.

Font.PreferFullHinting — если возможно, рендерить текст с подбором в горизонтальном и вертикальном направлениях. Текст будет изменён для повышения удобочитаемости на целевом устройстве, но поскольку метрики будут зависеть от целевого размера текста, позиции глифов, переносы строк и другие типографические детали не будут масштабироваться, что означает, что макет текста может выглядеть по-разному на устройствах с различной плотностью пикселей.

Text { text: "Hello"; renderType: Text.NativeRendering; font.hintingPreference: Font.PreferVerticalHinting }

Этот параметр был добавлен в Qt 5.8.

font.italic : bool

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

font.kerning : bool

Включает или выключает функцию кернинга OpenType при формировании текста. Отключение может улучшить производительность при создании или изменении текста в ущерб некоторым косметическим элементам. Значение по умолчанию — true.

Text { text: "OATS FLAVOUR WAY"; font.kerning: false }

Этот параметр был добавлен в Qt 5.10.

font.letterSpacing : real

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

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

font.pixelSize : int

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

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

font.pointSize : real

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

font.preferShaping : bool

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

Значение по умолчанию — true.

Text { text: "Some text"; font.preferShaping: false }

Этот параметр был добавлен в Qt 5.10.

font.strikeout : bool

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

font.styleName : string

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

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

Этот параметр был добавлен в Qt 5.6.

font.underline : bool

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

font.weight : enumeration

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

Вес может быть одним из следующих:

• 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 : real

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

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

fontInfo.bold : bool

Состояние полужирности информации о шрифте, разрешённой для текущего шрифта и fontSizeMode. Это true, если вес разрешённого шрифта полужирный или выше.

Этот параметр был добавлен в Qt 5.9.

fontInfo.family : string

Имя семейства шрифта, которое было определено для текущего шрифта и fontSizeMode.

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

fontInfo.italic : bool

Состояние курсива шрифта в информации о шрифте, которая была определена для текущего шрифта и fontSizeMode.

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

fontInfo.pixelSize : строка

Размер шрифта в пикселях из информации о шрифте, которая была определена для текущего шрифта и fontSizeMode.

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

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

Размер шрифта в пунктах из информации о шрифте, которая была определена для текущего шрифта и fontSizeMode.

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

fontInfo.styleName : строка

Имя стиля шрифта из информации о шрифте, которая была определена для текущего шрифта и fontSizeMode.

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

fontInfo.weight : целое

Вес шрифта из информации о шрифте, которая была определена для текущего шрифта и fontSizeMode.

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

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.

Если свойство textFormat установлено в Text.RichText, это свойство не будет иметь никакого эффекта, так как оно будет полностью проигнорировано. Если textFormat установлено в Text.StyledText, то свойство будет учитываться, если в тексте нет тегов размера шрифта. Если теги размера шрифта есть, свойство по-прежнему будет учитывать их. Это может привести к тому, что свойство fontSizeMode не будет полностью соблюдаться.

hoveredLink : строка

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

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

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

lineCount : целое

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

Это свойство не поддерживается для rich text.

См. также maximumLineCount.

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

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

Значение по умолчанию — множитель 1,0. Высота строки должна быть положительным значением.

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

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

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

linkColor : цвет

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

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

maximumLineCount : целое

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

Это свойство не поддерживается для rich text.

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

minimumPixelSize : целое

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

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

minimumPointSize : целое

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

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

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

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

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

• Text.QtRendering
• Text.NativeRendering

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

Тип рендеринга по умолчанию определяется QQuickWindow::textRenderType().

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

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

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

• 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 : цвет

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

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

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

См. также style.

text : строка

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

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

См. также textFormat.

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

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

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

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

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

<b></b> - bold
<del></del> - strike out (removed content)
<s></s> - strike out (no longer accurate or no longer relevant content)
<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 {
        font.pointSize: 24
        textFormat: Text.MarkdownText
        text: "**Hello** *World!*"
    }
}

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

Примечание: С Text.MarkdownText, и с поддерживаемым подмножеством HTML, некоторые декоративные элементы не отображаются так, как они бы отображались в веб-браузере:

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

truncated : bool

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

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

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

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

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

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

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

lineLaidOut(объект line)

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

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

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

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

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

Следующий пример позволит вам разместить элемент в конце последней строки:

onLineLaidOut: {
    if (line.isLast) {
        lastLineMarker.x = line.x + line.implicitWidth
        lastLineMarker.y = line.y + (line.height - lastLineMarker.height) / 2
    }
}

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

linkActivated(строка 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(строка link)

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

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

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

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

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

forceLayout()

Вызывает повторный макет отображаемого текста.

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

linkAt(вещественное x, вещественное y)

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

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

См. также hoveredLink.