Тип QML Text

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

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

Свойства

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

Сигналы

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

Методы

• forceLayout()
• linkAt(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.

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

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

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

Данная документация была добавлена в 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 : size

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

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

Это свойство было добавлено в 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 : string

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

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

fontInfo.pointSize : real

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

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

fontInfo.styleName : string

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

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

fontInfo.weight : int

Вес шрифта, определённый для текущего шрифта и fontSizeMode.

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

fontSizeMode : enumeration

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

• 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.

hoveredLink : string

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

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

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

lineCount : int

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

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

См. также maximumLineCount.

lineHeight : real

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

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

lineHeightMode : enumeration

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

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

linkColor : color

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

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

maximumLineCount : int

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

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

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

minimumPixelSize : int

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

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

minimumPointSize : int

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

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

renderType : enumeration

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

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

• Text.QtRendering
• Text.NativeRendering

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

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

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(). Однако распознавание Markdown не выполняется автоматически.

См. также textFormat.

textFormat : enumeration

Способ отображения свойства 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:

• 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(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, real y)

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

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

См. также hoveredLink.