Module java.desktop
Package java.awt.font

Class TextAttribute

java.lang.Object
java.text.AttributedCharacterIterator.Attribute
java.awt.font.TextAttribute
所有已实现的接口:
Serializable
public final class TextAttribute extends AttributedCharacterIterator.Attribute
TextAttribute类定义了用于文本渲染的属性键和属性值。

TextAttribute实例被用作属性键，用于识别在Font、TextLayout、AttributedCharacterIterator和其他处理文本属性的类中的属性。此类中定义的其他常量可用作属性值。

对于每个文本属性，文档提供了：

  • 其值的类型，
  • 相关的预定义常量（如果有的话），
  • 如果属性不存在，则默认效果，
  • 如果有限制，则有效值，
  • 效果的描述。

值

  • 属性的值必须始终是不可变的。
  • 如果给出值的限制，则该集合之外的任何值都保留供将来使用；该值将被视为默认值。
  • 值null被视为与默认值相同，并导致默认行为。
  • 如果值不是正确的类型，则将忽略该属性。
  • 值的身份并不重要，只有实际值重要。例如，TextAttribute.WEIGHT_BOLD和Float.valueOf(2.0f)表示相同的WEIGHT。
  • 类型为Number的属性值（用于WEIGHT、WIDTH、POSTURE、SIZE、JUSTIFICATION和TRACKING）可以沿其自然范围变化，并不限于预定义常量。Number.floatValue()用于从Number获取实际值。
  • WEIGHT、WIDTH和POSTURE的值由系统插值，系统可以选择“最接近可用”的字体或使用其他技术来近似用户的请求。

属性摘要

所有TextAttributes的键、值类型、主要常量和默认值行为
键 值类型 主要常量 默认值
FAMILY String 参见Font DIALOG、DIALOG_INPUT、
SERIF、SANS_SERIF和MONOSPACED。		 "默认"（使用平台默认值）
WEIGHT Number WEIGHT_REGULAR, WEIGHT_BOLD WEIGHT_REGULAR
WIDTH Number WIDTH_CONDENSED, WIDTH_REGULAR,
WIDTH_EXTENDED		 WIDTH_REGULAR
POSTURE Number POSTURE_REGULAR, POSTURE_OBLIQUE POSTURE_REGULAR
SIZE Number none 12.0
TRANSFORM TransformAttribute 参见TransformAttribute IDENTITY TransformAttribute.IDENTITY
SUPERSCRIPT Integer SUPERSCRIPT_SUPER, SUPERSCRIPT_SUB 0（使用标准字形和度量）
FONT Font none null（不覆盖字体分辨率）
CHAR_REPLACEMENT GraphicAttribute none null（使用字体字形绘制文本）
FOREGROUND Paint none null（使用当前图形画笔）
BACKGROUND Paint none null（不渲染背景）
UNDERLINE Integer UNDERLINE_ON -1（不渲染下划线）
STRIKETHROUGH Boolean STRIKETHROUGH_ON false（不渲染删除线）
RUN_DIRECTION Boolean RUN_DIRECTION_LTR
RUN_DIRECTION_RTL		 null（使用Bidi标准默认值）
BIDI_EMBEDDING Integer none 0（使用基线方向）
JUSTIFICATION Number JUSTIFICATION_FULL JUSTIFICATION_FULL
INPUT_METHOD_HIGHLIGHT InputMethodHighlight,
Annotation		 (参见类) null（不应用输入高亮）
INPUT_METHOD_UNDERLINE Integer UNDERLINE_LOW_ONE_PIXEL,
UNDERLINE_LOW_TWO_PIXEL		 -1（不渲染下划线）
SWAP_COLORS Boolean SWAP_COLORS_ON false（不交换颜色）
NUMERIC_SHAPING NumericShaper none null（不形状数字）
KERNING Integer KERNING_ON 0（不请求字距调整）
LIGATURES Integer LIGATURES_ON 0（不形成可选连字）
TRACKING Number TRACKING_LOOSE, TRACKING_TIGHT 0（不添加跟踪）
参见:

  • Field Details

    • FAMILY

      public static final TextAttribute FAMILY
      字体名称的属性键。值为String的实例。默认值为"Default"，这将使用平台默认字体系列。

      Font类为逻辑字体名称DIALOG、DIALOG_INPUT、SANS_SERIF、SERIF和MONOSPACED定义了常量。

      这定义了传递给Font构造函数的name值。允许使用逻辑和物理字体名称。如果找不到请求的名称的字体，则使用默认字体。

      注意：此属性的命名不幸地错误，因为它指定了面名而不仅仅是系列。因此，诸如"Lucida Sans Bold"之类的值将选择该面（如果存在）。但请注意，如果请求的面不存在，则将使用默认字体，并带有regular重量。名称中的"Bold"是面名的一部分，而不是字体重量为粗体的单独请求。

    • WEIGHT

      public static final TextAttribute WEIGHT
      字体重量的属性键。值为Number的实例。默认值为WEIGHT_REGULAR。

      提供了几个常量值，请参见WEIGHT_EXTRA_LIGHT、WEIGHT_LIGHT、WEIGHT_DEMILIGHT、WEIGHT_REGULAR、WEIGHT_SEMIBOLD、WEIGHT_MEDIUM、WEIGHT_DEMIBOLD、WEIGHT_BOLD、WEIGHT_HEAVY、WEIGHT_EXTRABOLD和WEIGHT_ULTRABOLD。值WEIGHT_BOLD对应于传递给Font构造函数的样式值Font.BOLD。

      该值大致是干线宽度与常规重量干线宽度之比。

      系统可以插值提供的值。

    • WEIGHT_EXTRA_LIGHT

      public static final Float WEIGHT_EXTRA_LIGHT
      最轻的预定义重量。
      参见：

    • WEIGHT_LIGHT

      public static final Float WEIGHT_LIGHT
      标准轻重量。
      参见：

    • WEIGHT_DEMILIGHT

      public static final Float WEIGHT_DEMILIGHT
      介于WEIGHT_LIGHT和WEIGHT_STANDARD之间的中等重量。
      参见：

    • WEIGHT_REGULAR

      public static final Float WEIGHT_REGULAR
      标准重量。这是WEIGHT的默认值。
      参见：

    • WEIGHT_SEMIBOLD

      public static final Float WEIGHT_SEMIBOLD
      比WEIGHT_REGULAR略重的重量。
      参见：

    • WEIGHT_MEDIUM

      public static final Float WEIGHT_MEDIUM
      介于WEIGHT_REGULAR和WEIGHT_BOLD之间的中等重量。
      参见：

    • WEIGHT_DEMIBOLD

      public static final Float WEIGHT_DEMIBOLD
      比WEIGHT_BOLD略轻的重量。
      参见：

    • WEIGHT_BOLD

      public static final Float WEIGHT_BOLD
      标准粗体重量。
      参见：

    • WEIGHT_HEAVY

      public static final Float WEIGHT_HEAVY
      比WEIGHT_BOLD略重的重量。
      参见：

    • WEIGHT_EXTRABOLD

      public static final Float WEIGHT_EXTRABOLD
      额外的重型重量。
      参见：

    • WEIGHT_ULTRABOLD

      public static final Float WEIGHT_ULTRABOLD
      最重的预定义重量。
      参见：

    • WIDTH

      public static final TextAttribute WIDTH
      字体宽度的属性键。值为Number的实例。默认值为WIDTH_REGULAR。

      提供了几个常量值，请参见WIDTH_CONDENSED、WIDTH_SEMI_CONDENSED、WIDTH_REGULAR、WIDTH_SEMI_EXTENDED、WIDTH_EXTENDED。

      该值大致是进度宽度与常规宽度进度宽度之比。

      系统可以插值提供的值。

    • WIDTH_CONDENSED

      public static final Float WIDTH_CONDENSED
      最紧凑的预定义宽度。
      参见：

    • WIDTH_SEMI_CONDENSED

      public static final Float WIDTH_SEMI_CONDENSED
      适度紧凑的宽度。
      参见：

    • WIDTH_REGULAR

      public static final Float WIDTH_REGULAR
      标准宽度。这是WIDTH的默认值。
      参见：

    • WIDTH_SEMI_EXTENDED

      public static final Float WIDTH_SEMI_EXTENDED
      适度扩展的宽度。
      参见：

    • WIDTH_EXTENDED

      public static final Float WIDTH_EXTENDED
      最扩展的预定义宽度。
      参见：

    • POSTURE

      public static final TextAttribute POSTURE
      字体姿势的属性键。值为Number的实例。默认值为POSTURE_REGULAR。

      提供了两个常量值，POSTURE_REGULAR和POSTURE_OBLIQUE。值POSTURE_OBLIQUE对应于传递给Font构造函数的样式值Font.ITALIC。

      该值大致是字体干线的斜率，表示为横向距离与纵向距离的比值。正值向右倾斜。

      系统可以插值提供的值。

      这将影响字体的斜体角度，如Font.getItalicAngle返回的那样。

      参见：

    • POSTURE_REGULAR

      public static final Float POSTURE_REGULAR
      标准姿势，直立。这是POSTURE的默认值。
      参见：

    • POSTURE_OBLIQUE

      public static final Float POSTURE_OBLIQUE
      标准斜体姿势。
      参见：

    • SIZE

      public static final TextAttribute SIZE
      字体大小的属性键。值为Number的实例。默认值为12pt。

      这对应于传递给Font构造函数的size参数。

      非常大或非常小的大小会影响渲染性能，渲染系统可能不会以这些大小呈现文本。负大小是非法的，并导致使用默认大小。

      请注意，具有2倍变换的12pt字体的外观和度量可能与没有变换的24pt字体不同。

    • TRANSFORM

      public static final TextAttribute TRANSFORM
      字体变换的属性键。值为TransformAttribute的实例。默认值为TransformAttribute.IDENTITY。

      TransformAttribute类定义了常量IDENTITY。

      这对应于传递给Font.deriveFont(AffineTransform)的变换。由于该变换是可变的，而TextAttribute值必须不可变，因此使用了TransformAttribute包装类。

      主要意图是支持缩放和倾斜，尽管可能存在其他效果。

      一些变换会导致基线旋转和/或移位。文本和基线一起变换，以使文本遵循新基线。例如，在水平基线上的文本，新基线遵循通过变换传递的单位x向量的方向。文本度量根据这个新基线进行测量。因此，例如，在其他条件相同的情况下，使用旋转的TRANSFORM和未旋转的TRANSFORM呈现的文本将被测量为具有相同的上升、下降和前进。

      在样式化文本中，每个运行的基线依次对齐，以可能创建整个文本运行的非线性基线。有关更多信息，请参见TextLayout.getLayoutPath()。

      参见：

    • SUPERSCRIPT

      public static final TextAttribute SUPERSCRIPT
      上标和下标的属性键。值为Integer的实例。默认值为0，表示不使用上标或下标。

      提供了两个常量值，参见SUPERSCRIPT_SUPER和SUPERSCRIPT_SUB。它们的值分别为1和-1。绝对值越大的值定义了更高级别的上标或下标，例如，2对应于超级上标，3对应于超级超级上标，以此类推，负值和下标类似，最高级别为7（或-7）。超出此范围的值被保留；行为取决于平台。

      SUPERSCRIPT可以影响字体的上升和下降。但上升和下降永远不会变为负值。

    • SUPERSCRIPT_SUPER

      public static final Integer SUPERSCRIPT_SUPER
      标准上标。
      参见:

    • SUPERSCRIPT_SUB

      public static final Integer SUPERSCRIPT_SUB
      标准下标。
      参见:

    • FONT

      public static final TextAttribute FONT
      用于提供用于呈现文本的字体的属性键。值为Font的实例。默认值为null，表示应执行从属性到Font的正常解析。

      TextLayout和AttributedCharacterIterator使用TextAttributes的Maps。通常，所有属性都会被检查并用于选择和配置Font实例。但是，如果存在FONT属性，那么将使用其关联的Font。这为用户提供了一种覆盖将字体属性解析为Font或强制使用特定Font实例的方式。这还允许用户在可以对Font进行子类化的情况下指定Font的子类。

      FONT用于客户端已经拥有Font实例但仍需要使用基于Map的API的特殊情况。通常，Map为除FONT属性外不包含其他属性。使用基于Map的API的常见情况是单独指定所有属性，因此不需要或不希望使用FONT。

      但是，如果Map中同时存在FONT和其他属性，则呈现系统将合并Font中定义的属性与附加属性。此合并过程将TextAttributes分类为两组。一组是“主要”组，被认为是字体的选择和度量行为的基础。这些属性包括FAMILY、WEIGHT、WIDTH、POSTURE、SIZE、TRANSFORM、SUPERSCRIPT和TRACKING。另一组是“次要”组，包括所有其他定义的属性，除了FONT本身。

      为生成新的Map，首先从FONT属性获取Font，并将其所有属性提取到新的Map中。然后，仅将原始Map中的“次要”属性添加到新Map中。因此，主要属性的值完全来自Font，而次要属性的值来自Font，但可以被Map中的其他值覆盖。

      注意:Font的基于Map的构造函数和deriveFont方法不处理FONT属性，因为这些方法用于创建新的Font对象。相反，应使用Font.getFont(Map)来处理FONT属性。

      参见:

    • CHAR_REPLACEMENT

      public static final TextAttribute CHAR_REPLACEMENT
      用于显示字符的字体的标准字形之外的用户定义字形的属性键。值为GraphicAttribute的实例。默认值为null，表示应使用字体提供的标准字形。

      此属性用于为文本行中嵌入的图形或其他组件保留空间。在执行双向重新排序（参见Bidi）时，正确定位文本行内的“内联”组件是必需的。每个字符（Unicode代码点）将使用提供的GraphicAttribute进行呈现。通常，应用此属性的字符应为\uFFFC。

      GraphicAttribute确定文本的逻辑和视觉边界；实际的字体值将被忽略。

      参见:

    • FOREGROUND

      public static final TextAttribute FOREGROUND
      用于呈现文本的画笔的属性键。值为Paint的实例。默认值为null，表示在呈现时使用Graphics2D上设置的Paint。 Graphics上设置的 Paint值如何，字形都将使用此 Paint进行呈现（但请参见 SWAP_COLORS）。

      参见:

    • BACKGROUND

      public static final TextAttribute BACKGROUND
      用于呈现文本背景的画笔的属性键。值为Paint的实例。默认值为null，表示不应呈现背景。 Paint填充，然后文本将在其上进行呈现（但请参见 SWAP_COLORS）。

      参见:

    • UNDERLINE

      public static final TextAttribute UNDERLINE
      下划线的属性键。值为Integer的实例。默认值为-1，表示没有下划线。 UNDERLINE_ON。

    • UNDERLINE_ON

      public static final Integer UNDERLINE_ON
      标准下划线。
      参见:

    • STRIKETHROUGH

      public static final TextAttribute STRIKETHROUGH
      删除线的属性键。值为Boolean的实例。默认值为false，表示没有删除线。 STRIKETHROUGH_ON。

    • STRIKETHROUGH_ON

      public static final Boolean STRIKETHROUGH_ON
      单个删除线。
      参见:

    • RUN_DIRECTION

      public static final TextAttribute RUN_DIRECTION
      文本行的运行方向的属性键。值为Boolean的实例。默认值为null，表示应使用确定运行方向的标准Bidi算法，其值为Bidi.DIRECTION_DEFAULT_LEFT_TO_RIGHT。 RUN_DIRECTION_RTL和 RUN_DIRECTION_LTR。

      Bidi构造函数。

      注意:此属性应对段落中的所有文本具有相同的值，否则行为是不确定的。
      参见:

    • RUN_DIRECTION_LTR

      public static final Boolean RUN_DIRECTION_LTR
      从左到右的运行方向。
      参见:

    • RUN_DIRECTION_RTL

      public static final Boolean RUN_DIRECTION_RTL
      从右到左的运行方向。
      参见:

    • BIDI_EMBEDDING

      public static final TextAttribute BIDI_EMBEDDING
      文本的嵌入级别的属性键。值为Integer的实例。默认值为null，表示应在没有显式嵌入的情况下运行Bidirectional算法。 嵌入级别，负值-1到-61是 覆盖级别。值0表示使用基线方向。这些级别将在嵌入级别数组中传递给 Bidi构造函数。

      注意:当此属性在段落中的任何位置存在时，段落中的任何Unicode双向控制字符（RLO、LRO、RLE、LRE和PDF）将被忽略，并且将处理未出现此属性的文本运行，就好像它存在并且值为0。
      参见:

    • JUSTIFICATION

      public static final TextAttribute JUSTIFICATION
      段落对齐的属性键。值为Number的实例。默认值为1，表示对齐应使用提供的完整宽度。值被固定在范围[0..1]内。 JUSTIFICATION_FULL和 JUSTIFICATION_NONE。

      TextLayout上进行对齐时要使用的额外空间的分数。例如，如果行宽为50点，要求将其对齐到70点，值为0.75将填充使用剩余空间的四分之三，或15点，以便最终行长为65点。

      注意:此属性应对段落中的所有文本具有相同的值，否则行为是不确定的。
      参见:

    • JUSTIFICATION_FULL

      public static final Float JUSTIFICATION_FULL
      将行调整为完整请求的宽度。这是JUSTIFICATION的默认值。
      参见:

    • JUSTIFICATION_NONE

      public static final Float JUSTIFICATION_NONE
      不允许行进行调整。
      参见:

    • INPUT_METHOD_HIGHLIGHT

      public static final TextAttribute INPUT_METHOD_HIGHLIGHT
      输入法高亮样式的属性键。

      值是InputMethodHighlight的实例或Annotation的实例。默认值为null，这意味着在呈现之前不应用输入法样式。

      如果需要单独呈现具有相同InputMethodHighlight的相邻文本运行，则InputMethodHighlights应该包装在Annotation实例中。

      输入法高亮在文本由输入法组成时使用。文本编辑组件应保留它们，即使它们通常只处理无样式的文本，并使它们可用于绘图例程。

      参见:

    • INPUT_METHOD_UNDERLINE

      public static final TextAttribute INPUT_METHOD_UNDERLINE
      输入法下划线的属性键。值是Integer的实例。默认值为-1，表示没有下划线。

      提供了几个常量值，请参见UNDERLINE_LOW_ONE_PIXEL、UNDERLINE_LOW_TWO_PIXEL、UNDERLINE_LOW_DOTTED、UNDERLINE_LOW_GRAY和UNDERLINE_LOW_DASHED。

      如果需要，可以与UNDERLINE一起使用。主要目的是供输入法使用。其他用途的下划线可能会使用户感到困惑。

      输入法下划线会影响文本的视觉边界和轮廓。

      自 JDK 1.3 起

    • UNDERLINE_LOW_ONE_PIXEL

      public static final Integer UNDERLINE_LOW_ONE_PIXEL
      单像素实线低下划线。
      自 JDK 1.3 起
      1.3
      参见:

    • UNDERLINE_LOW_TWO_PIXEL

      public static final Integer UNDERLINE_LOW_TWO_PIXEL
      双像素实线低下划线。
      自 JDK 1.3 起
      1.3
      参见:

    • UNDERLINE_LOW_DOTTED

      public static final Integer UNDERLINE_LOW_DOTTED
      单像素点状低下划线。
      自 JDK 1.3 起
      1.3
      参见:

    • UNDERLINE_LOW_GRAY

      public static final Integer UNDERLINE_LOW_GRAY
      双像素灰色低下划线。
      自 JDK 1.3 起
      1.3
      参见:

    • UNDERLINE_LOW_DASHED

      public static final Integer UNDERLINE_LOW_DASHED
      单像素虚线低下划线。
      自 JDK 1.3 起
      1.3
      参见:

    • SWAP_COLORS

      public static final TextAttribute SWAP_COLORS
      交换前景和背景Paints的属性键。值是Boolean的实例。默认值为false，表示不交换颜色。

      定义了常量值SWAP_COLORS_ON。

      如果设置了FOREGROUND属性，则其Paint将用作背景，否则将使用当前Graphics上的Paint。如果设置了BACKGROUND属性，则其Paint将用作前景，否则系统将找到与（解析后的）背景形成对比的颜色，以便文本可见。

      参见:

    • SWAP_COLORS_ON

      public static final Boolean SWAP_COLORS_ON
      交换前景和背景。
      自 JDK 1.3 起

    • NUMERIC_SHAPING

      public static final TextAttribute NUMERIC_SHAPING
      将ASCII十进制数字转换为其他十进制范围的属性键。值是NumericShaper的实例。默认值为null，表示不执行数字形状。

      当定义了数字形状时，文本首先由形状器处理，然后执行文本的任何其他分析。

      注意: 对于段落中的所有文本，此值应该相同，否则行为是不确定的。

      自 JDK 1.4 起
      1.4
      参见:

    • KERNING

      public static final TextAttribute KERNING
      请求字距调整的属性键。值是Integer的实例。默认值为0，不请求字距调整。

      提供了常量值KERNING_ON。

      单个字符的默认前进值对于某些字符序列不合适，例如"To"或"AWAY"。没有字距调整时，相邻字符看起来被分隔得太远。字距调整导致选择的字符序列以不同的间距排列，以获得更令人愉悦的视觉外观。

      自 JDK 1.6 起

    • KERNING_ON

      public static final Integer KERNING_ON
      请求标准字距调整。
      自 JDK 1.6 起
      1.6
      参见:

    • LIGATURES

      public static final TextAttribute LIGATURES
      启用可选连字的属性键。值是Integer的实例。默认值为0，表示不使用可选连字。

      定义了常量值LIGATURES_ON。

      写系统需要的连字始终是启用的。

      自 JDK 1.6 起

    • LIGATURES_ON

      public static final Integer LIGATURES_ON
      请求标准可选连字。
      自 JDK 1.6 起
      1.6
      参见:

    • TRACKING

      public static final TextAttribute TRACKING
      控制字距的属性键。值是Number的实例。默认值为0，表示没有额外的字距。

      提供了常量值TRACKING_TIGHT和TRACKING_LOOSE。

      字距值乘以字体点大小，并通过字体变换传递，以确定要添加到每个字形簇的前进量。正字距值将抑制可选连字的形成。字距值通常在-0.1和0.3之间；此范围之外的值通常不理想。

      自 JDK 1.6 起

    • TRACKING_TIGHT

      public static final Float TRACKING_TIGHT
      执行紧密字距。
      自 JDK 1.6 起
      1.6
      参见:

    • TRACKING_LOOSE

      public static final Float TRACKING_LOOSE
      执行宽松字距。
      自 JDK 1.6 起
      1.6
      参见:

  • Constructor Details

    • TextAttribute

      protected TextAttribute(String name)
      使用指定名称构造TextAttribute。
      参数:
      name - 要分配给此TextAttribute的属性名称

  • Method Details