字体

摘要

枚举
`匿名枚举 26{ AFONT_WEIGHT_MIN = 0, AFONT_WEIGHT_THIN = 100, AFONT_WEIGHT_EXTRA_LIGHT = 200, AFONT_WEIGHT_LIGHT = 300, AFONT_WEIGHT_NORMAL = 400, AFONT_WEIGHT_MEDIUM = 500, AFONT_WEIGHT_SEMI_BOLD = 600, AFONT_WEIGHT_BOLD = 700, AFONT_WEIGHT_EXTRA_BOLD = 800, AFONT_WEIGHT_BLACK = 900, AFONT_WEIGHT_MAX = 1000 }`	enum
`匿名枚举 27{ AFAMILY_VARIANT_DEFAULT = 0, AFAMILY_VARIANT_COMPACT = 1, AFAMILY_VARIANT_ELEGANT = 2 }`	enum

类型定义
`AFont`	typedef `结构体 AFont` AFont 提供单个字体配置的信息。
`AFontMatcher`	typedef `结构体 AFontMatcher` AFontMatcher 对给定参数和可用字体文件执行匹配操作。
`ASystemFontIterator`	typedef `结构体 ASystemFontIterator` ASystemFontIterator 提供对系统字体配置的访问。

函数
`AFontMatcher_create()`	`AFontMatcher *_Nonnull` 从给定参数中选择最佳字体。
`AFontMatcher_destroy(AFontMatcher *_Nonnull matcher)`	`void` 销毁匹配器对象。
`AFontMatcher_match(const AFontMatcher _Nonnull matcher, const char _Nonnull familyName, const uint16_t _Nonnull text, const uint32_t textLength, uint32_t _Nullable runLengthOut)`	`AFont *_Nonnull` 从文本的通用字体系列中执行匹配并选择一种字体。
`AFontMatcher_setFamilyVariant(AFontMatcher *_Nonnull matcher, uint32_t familyVariant)`	`void` 为匹配器设置字体系列变体。
`AFontMatcher_setLocales(AFontMatcher _Nonnull matcher, const char _Nonnull languageTags)`	`void` 为匹配器设置字体区域设置。
`AFontMatcher_setStyle(AFontMatcher *_Nonnull matcher, uint16_t weight, bool italic)`	`void` 为匹配器设置字体样式。
`AFont_close(AFont *_Nullable font)`	`void` 关闭一个 AFont。
`AFont_getAxisCount(const AFont *_Nonnull font)`	`size_t` 返回与当前字体关联的字体变体设置计数。
`AFont_getAxisTag(const AFont *_Nonnull font, uint32_t axisIndex)`	`uint32_t` 返回与当前字体关联的 OpenType 轴标签。
`AFont_getAxisValue(const AFont *_Nonnull font, uint32_t axisIndex)`	`float` 返回与当前字体关联的 OpenType 轴值。
`AFont_getCollectionIndex(const AFont *_Nonnull font)`	`size_t` 返回与当前字体关联的字体集索引值。
`AFont_getFontFilePath(const AFont *_Nonnull font)`	`const char *_Nonnull` 返回当前字体文件的绝对路径。
`AFont_getLocale(const AFont *_Nonnull font)`	`const char *_Nullable` 返回与当前字体关联的符合 IETF BCP47 标准的语言标签。
`AFont_getWeight(const AFont *_Nonnull font)`	`uint16_t` 返回与当前字体关联的粗细值。
`AFont_isItalic(const AFont *_Nonnull font)`	`bool` 如果当前字体是斜体，则返回 true；否则返回 false。
`ASystemFontIterator_close(ASystemFontIterator *_Nullable iterator)`	`void` 关闭已打开的系统字体迭代器，释放所有相关资源。
`ASystemFontIterator_next(ASystemFontIterator *_Nonnull iterator)`	`AFont *_Nullable` 移至下一个系统字体。
`ASystemFontIterator_open()`	`ASystemFontIterator *_Nullable` 创建一个系统字体迭代器。

枚举

匿名枚举 26

声明于 android/font.h

 Anonymous Enum 26

属性
`AFONT_WEIGHT_BLACK`	一个表示 Black 粗细的字体粗细值。
`AFONT_WEIGHT_BOLD`	一个表示 Bold 粗细的字体粗细值。
`AFONT_WEIGHT_EXTRA_BOLD`	一个表示 Extra-bold 粗细的字体粗细值。
`AFONT_WEIGHT_EXTRA_LIGHT`	一个表示 Extra-light 粗细的字体粗细值。
`AFONT_WEIGHT_LIGHT`	一个表示 Light 粗细的字体粗细值。
`AFONT_WEIGHT_MAX`	字体粗细值的最大值。
`AFONT_WEIGHT_MEDIUM`	一个表示 Medium 粗细的字体粗细值。
`AFONT_WEIGHT_MIN`	字体粗细值的最小值。
`AFONT_WEIGHT_NORMAL`	一个表示 Normal 粗细的字体粗细值。
`AFONT_WEIGHT_SEMI_BOLD`	一个表示 Semi-bold 粗细的字体粗细值。
`AFONT_WEIGHT_THIN`	一个表示 Thin 粗细的字体粗细值。

匿名枚举 27

声明于 android/font_matcher.h

 Anonymous Enum 27

属性

属性
`AFAMILY_VARIANT_COMPACT`	一个表示 Compact 字体系列变体的系列变体值。紧凑字体系列具有基于拉丁文的垂直指标。
`AFAMILY_VARIANT_DEFAULT`	一个表示系统默认变体的系列变体值。
`AFAMILY_VARIANT_ELEGANT`	一个表示 Elegant 字体系列变体的系列变体值。 Elegant 字体系列的垂直指标可能大于拉丁文字体。

AFAMILY_VARIANT_COMPACT

一个表示 Compact 字体系列变体的系列变体值。

紧凑字体系列具有基于拉丁文的垂直指标。

AFAMILY_VARIANT_DEFAULT

一个表示系统默认变体的系列变体值。

AFAMILY_VARIANT_ELEGANT

一个表示 Elegant 字体系列变体的系列变体值。

Elegant 字体系列的垂直指标可能大于拉丁文字体。

类型定义

AFont

声明于 android/font.h

struct AFont AFont

AFont 提供单个字体配置的信息。

AFontMatcher

声明于 android/font_matcher.h

struct AFontMatcher AFontMatcher

AFontMatcher 对给定参数和可用字体文件执行匹配操作。

此匹配器不是线程安全对象。请勿将此匹配器传递给其他线程。

ASystemFontIterator

声明于 android/system_fonts.h

struct ASystemFontIterator ASystemFontIterator

ASystemFontIterator 提供对系统字体配置的访问。

ASystemFontIterator 是一个用于迭代所有可用系统字体设置的迭代器。此迭代器不是线程安全对象。请勿将此迭代器传递给其他线程。

函数

AFontMatcher_create

声明于 android/font_matcher.h

AFontMatcher *_Nonnull AFontMatcher_create()

从给定参数中选择最佳字体。

创建一个新的 AFontMatcher 对象。

自 API 级别 29 起可用。

AFontMatcher_destroy

声明于 android/font_matcher.h

void AFontMatcher_destroy(
  AFontMatcher *_Nonnull matcher
)

销毁匹配器对象。

自 API 级别 29 起可用。

详情

参数

matcher

匹配器对象。不允许传递 NULL。

AFontMatcher_match

声明于 android/font_matcher.h

AFont *_Nonnull AFontMatcher_match(
  const AFontMatcher *_Nonnull matcher,
  const char *_Nonnull familyName,
  const uint16_t *_Nonnull text,
  const uint32_t textLength,
  uint32_t *_Nullable runLengthOut
)

从文本的通用字体系列中执行匹配并选择一种字体。

有关通用字体系列的更多信息，请阅读 W3C 规范

即使没有字体可以渲染给定的文本，此函数也会返回一个非空结果用于绘制 Tofu 字符。

自 API 级别 29 起可用。

详情

参数

`matcher`	匹配器对象。不允许传递 NULL。
`familyName`	以 null 字符结尾的字体系列名称
`text`	待渲染的 UTF-16 编码文本缓冲区。请勿传递空字符串。
`textLength`	给定文本缓冲区的长度。不能为零。
`runLengthOut`	如果不为 null，则将填充字体运行长度。

返回值

用于给定文本和参数的字体。不再需要时，您需要通过 AFont_close 释放返回的字体。

AFontMatcher_setFamilyVariant

声明于 android/font_matcher.h

void AFontMatcher_setFamilyVariant(
  AFontMatcher *_Nonnull matcher,
  uint32_t familyVariant
)

为匹配器设置字体系列变体。

如果未调用此函数，匹配器将使用 AFAMILY_VARIANT_DEFAULT 执行操作。

自 API 级别 29 起可用。

详情

参数

`matcher`	匹配器对象。不允许传递 NULL。
`familyVariant`	必须是 AFAMILY_VARIANT_DEFAULT、AFAMILY_VARIANT_COMPACT 或 AFAMILY_VARIANT_ELEGANT 之一。

AFontMatcher_setLocales

声明于 android/font_matcher.h

void AFontMatcher_setLocales(
  AFontMatcher *_Nonnull matcher,
  const char *_Nonnull languageTags
)

为匹配器设置字体区域设置。

如果未调用此函数，匹配器将使用空的区域设置列表执行操作。

自 API 级别 29 起可用。

详情

参数

`matcher`	匹配器对象。不允许传递 NULL。
`languageTags`	以 null 字符结尾的逗号分隔的符合 IETF BCP47 标准的语言标签。

AFontMatcher_setStyle

声明于 android/font_matcher.h

void AFontMatcher_setStyle(
  AFontMatcher *_Nonnull matcher,
  uint16_t weight,
  bool italic
)

为匹配器设置字体样式。

如果未调用此函数，匹配器将使用 AFONT_WEIGHT_NORMAL（非斜体样式）执行操作。

自 API 级别 29 起可用。

详情

参数

`matcher`	匹配器对象。不允许传递 NULL。
`weight`	字体粗细值。仅接受 0 到 1000 的值。
`italic`	如果为斜体则为 true，否则为 false。

AFont_close

声明于 android/font.h

void AFont_close(
  AFont *_Nullable font
)

关闭一个 AFont。

自 API 级别 29 起可用。

详情

参数

font

ASystemFontIterator_next 或 AFontMatchert_match 返回的字体。如果传递 NULL 则不执行任何操作。

AFont_getAxisCount

声明于 android/font.h

size_t AFont_getAxisCount(
  const AFont *_Nonnull font
)

返回与当前字体关联的字体变体设置计数。

字体变体设置以多个标签-值对的形式提供。

例如，粗斜体字体可能具有以下字体变体设置：“wght”700，“slnt”-12。在这种情况下，AFont_getAxisCount 返回 2，并且 AFont_getAxisTag 和 AFont_getAxisValue 将返回以下值。

AFont* font = ASystemFontIterator_next(ite);

// Returns the number of axes
AFont_getAxisCount(font);  // Returns 2

// Returns the tag-value pair for the first axis.
AFont_getAxisTag(font, 0);  // Returns 'wght'(0x77676874)
AFont_getAxisValue(font, 0);  // Returns 700.0

// Returns the tag-value pair for the second axis.
AFont_getAxisTag(font, 1);  // Returns 'slnt'(0x736c6e74)
AFont_getAxisValue(font, 1);  // Returns -12.0

有关字体变体设置的更多信息，请阅读字体变体表

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

字体变体设置的数量。

AFont_getAxisTag

声明于 android/font.h

uint32_t AFont_getAxisTag(
  const AFont *_Nonnull font,
  uint32_t axisIndex
)

返回与当前字体关联的 OpenType 轴标签。

有关更多详情，请参阅 AFont_getAxisCount。

自 API 级别 29 起可用。

详情

参数

`font`	字体对象。不允许传递 NULL。
`axisIndex`	字体变体设置的索引。不允许传递大于或等于 AFont_getAxisCount 的值。

返回值

给定字体变体设置的 OpenType 轴标签值。

AFont_getAxisValue

声明于 android/font.h

float AFont_getAxisValue(
  const AFont *_Nonnull font,
  uint32_t axisIndex
)

返回与当前字体关联的 OpenType 轴值。

有关更多详情，请参阅 AFont_getAxisCount。

自 API 级别 29 起可用。

详情

参数

`font`	字体对象。不允许传递 NULL。
`axisIndex`	字体变体设置的索引。不允许传递大于或等于 AFont_getAxisCount 的值。

返回值

给定字体变体设置的浮点值。

AFont_getCollectionIndex

声明于 android/font.h

size_t AFont_getCollectionIndex(
  const AFont *_Nonnull font
)

返回与当前字体关联的字体集索引值。

如果目标字体文件是字体集（例如 .ttc 或 .otc），则此函数返回一个非负值作为字体在集中的偏移量。如果目标字体文件是常规字体，则始终返回 0。

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

字体集索引。

AFont_getFontFilePath

声明于 android/font.h

const char *_Nonnull AFont_getFontFilePath(
  const AFont *_Nonnull font
)

返回当前字体文件的绝对路径。

此方法返回的字体格式列表如下：

OpenType
OpenType 字体集
TrueType
TrueType 字体集

文件扩展名可以是 *.otf、*.ttf、*.otc 或 *.ttc 之一。

返回的字体文件保证使用 O_RDONLY 打开。请注意，返回的指针在对给定字体调用 AFont_close() 之前一直有效。

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

字体文件路径字符串。

AFont_getLocale

声明于 android/font.h

const char *_Nullable AFont_getLocale(
  const AFont *_Nonnull font
)

返回与当前字体关联的符合 IETF BCP47 标准的语言标签。

有关 IETF BCP47 的信息，请阅读 Locale.forLanguageTag(java.lang.String)

请注意，返回的指针在调用 AFont_close() 之前一直有效。

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

符合 IETF BCP47 标准的语言标签；如果不可用，则为 nullptr。

AFont_getWeight

声明于 android/font.h

uint16_t AFont_getWeight(
  const AFont *_Nonnull font
)

返回与当前字体关联的粗细值。

粗细值为正且小于或等于 1000。以下是常用名称及其对应值的列表：

值	名称	NDK 定义
100	极细体 (Thin)	AFONT_WEIGHT_THIN
200	特细体 (Extra Light)	AFONT_WEIGHT_EXTRA_LIGHT
300	细体 (Light)	AFONT_WEIGHT_LIGHT
400	常规体 (Normal)	AFONT_WEIGHT_NORMAL
500	中等体 (Medium)	AFONT_WEIGHT_MEDIUM
600	半粗体 (Semi Bold)	AFONT_WEIGHT_SEMI_BOLD
700	粗体 (Bold)	AFONT_WEIGHT_BOLD
800	特粗体 (Extra Bold)	AFONT_WEIGHT_EXTRA_BOLD
900	极粗体 (Black)	AFONT_WEIGHT_BLACK

请注意，粗细值可能介于上述值之间，例如 250 粗细。

有关字体粗细的更多信息，请阅读 OpenType usWeightClass

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

返回一个小于或等于 AFONT_WEIGHT_MAX 的正整数。

AFont_isItalic

声明于 android/font.h

bool AFont_isItalic(
  const AFont *_Nonnull font
)

如果当前字体是斜体，则返回 true；否则返回 false。

自 API 级别 29 起可用。

详情

参数

font

字体对象。不允许传递 NULL。

返回值

如果为斜体则为 true，否则为 false。

ASystemFontIterator_close

声明于 android/system_fonts.h

void ASystemFontIterator_close(
  ASystemFontIterator *_Nullable iterator
)

关闭已打开的系统字体迭代器，释放所有相关资源。

自 API 级别 29 起可用。

详情

参数

iterator

系统字体迭代器的指针。如果传递 NULL 则不执行任何操作。

ASystemFontIterator_next

声明于 android/system_fonts.h

AFont *_Nullable ASystemFontIterator_next(
  ASystemFontIterator *_Nonnull iterator
)

移至下一个系统字体。

自 API 级别 29 起可用。

详情

参数

iterator

系统字体的迭代器。不允许传递 NULL。

返回值

字体。如果没有更多字体可用，则返回 nullptr。不再需要时，您需要通过 AFont_close() 释放返回的字体。

ASystemFontIterator_open

声明于 android/system_fonts.h

ASystemFontIterator *_Nullable ASystemFontIterator_open()

创建一个系统字体迭代器。

使用 ASystemFontIterator_close() 关闭迭代器。

自 API 级别 29 起可用。

详情
返回值	新分配的迭代器指针；失败时为 nullptr。