chrome.fontSettings

说明

使用 chrome.fontSettings API 管理 Chrome 的字体设置。

权限

fontSettings

如需使用 Font Settings API，您必须在扩展程序清单中声明 "fontSettings" 权限。例如：

{
  "name": "My Font Settings Extension",
  "description": "Customize your fonts",
  "version": "0.2",
  "permissions": [
    "fontSettings"
  ],
  ...
}

概念和用法

Chrome 允许某些字体设置取决于某些通用字体系列和语言脚本。例如，用于 sans-serif 简体中文的字体可能与用于 serif 日语的字体不同。

Chrome 支持的通用字体系列基于 CSS 通用字体系列，并在 GenericReference 下列出。当网页指定通用字体系列时，Chrome 会根据相应设置选择字体。如果未指定通用字体系列，Chrome 将使用“标准”通用字体系列的设置。

当网页指定一种语言时，Chrome 会根据相应语言脚本的设置选择字体。如果未指定语言，Chrome 将使用默认脚本（或全局脚本）的设置。

支持的语言脚本由 ISO 15924 脚本代码指定，并在 ScriptCode 下列出。从技术层面讲，Chrome 设置并非完全按脚本设置，还取决于语言。例如，当网页指定俄语时，Chrome 会选择西里尔字体（ISO 15924 脚本代码“Cyrl”），并且不仅会将此字体用于西里尔字符，还会将其用于该字体涵盖的所有内容，例如拉丁字符。

示例

以下代码会获取适用于阿拉伯语的标准字体。

chrome.fontSettings.getFont(
  { genericFamily: 'standard', script: 'Arab' },
  function(details) { console.log(details.fontId); }
);

以下代码段为日语设置了无衬线字体。

chrome.fontSettings.setFont(
  { genericFamily: 'sansserif', script: 'Jpan', fontId: 'MS PGothic' }
);

如需试用此 API，请从 chrome-extension-samples 代码库安装 fontSettings API 示例。

类型

FontName

表示字体名称。

属性

• displayName

  字符串

  字体的显示名称。

• fontId

  字符串

  字体 ID。

GenericFamily

CSS 通用字体系列。

枚举

"standard"

"sansserif"

"serif"

"fixed"

"cursive"

"fantasy"

"math"

LevelOfControl

以下各项之一：not\_controllable：无法由任何扩展程序控制 controlled\_by\_other\_extensions：由优先级更高的扩展程序控制 controllable\_by\_this\_extension：可由此扩展程序控制 controlled\_by\_this\_extension：由此扩展程序控制

枚举

"not_controllable"

"controlled_by_other_extensions"

"controllable_by_this_extension"

"controlled_by_this_extension"

ScriptCode

ISO 15924 脚本代码。默认脚本（或全局脚本）由脚本代码“Zyyy”表示。

枚举

“Afak”

“Arab”

"Armi"

"Armn"

“Avst”

“Bali”

“Bamu”

“Bass”

“Batk”

“Beng”

“Blis”

“Bopo”

“Brah”

“Brai”

“Bugi”

"Buhd"

"Cakm"

“Cans”

“Cari”

“Cham”

“Cher”

“Cirt”

"Copt"

"Cprt"

"Cyrl"

“Cyrs”

“Deva”

"Dsrt"

“Dupl”

“Egyd”

"Egyh"

“Egyp”

“Elba”

“Ethi”

“Geor”

“Geok”

“Glag”

“Goth”

“Gran”

“Grek”

“Gujr”

“Guru”

“挂起”

“Hani”

“Hano”

“Hans”

“Hant”

"Hebr"

“Hluw”

“Hmng”

“Hung”

"Inds"

“Ital”

“Java”

“Jpan”

“Jurc”

“Kali”

“Khar”

"Khmr"

“Khoj”

“Knda”

“Kpel”

“Kthi”

“Lana”

“Laoo”

“Latf”

"Latg"

“Latn”

"Lepc"

“Limb”

“Lina”

“Linb”

“Lisu”

“Loma”

“Lyci”

“Lydi”

“Mand”

“Mani”

“Maya”

“修复”

“Merc”

“Mero”

“Mlym”

“Moon”

“Mong”

“Mroo”

“Mtei”

“Mymr”

“Narb”

“Nbat”

"Nkgb"

“Nkoo”

“Nshu”

“Ogam”

“Olck”

“Orkh”

“Orya”

"Osma"

“Palm”

“Perm”

“Phag”

“Phli”

“Phlp”

"Phlv"

“Phnx”

“Plrd”

“Prti”

“Rjng”

“Roro”

“Runr”

“Samr”

“Sara”

“Sarb”

“Saur”

"Sgnw"

“Shaw”

"Shrd"

“Sind”

“Sinh”

“Sora”

“Sund”

“Sylo”

“Syrc”

“Syre”

"Syrj"

“Syrn”

“Tagb”

“Takr”

“Tale”

“Talu”

“Taml”

“Tang”

“Tavt”

“Telu”

“Teng”

“Tfng”

“Tglg”

“Thaa”

“泰语”

“Tibt”

“Tirh”

“Ugar”

“Vaii”

“Visp”

“Wara”

“Wole”

“Xpeo”

"Xsux"

“Yiii”

"Zmth"

“Zsym”

“Zyyy”

方法

clearDefaultFixedFontSize()

prometido

chrome.fontSettings.clearDefaultFixedFontSize(
  details?: object,
  callback?: function,
)

清除此扩展程序设置的默认固定字号（如果有）。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

clearDefaultFontSize()

prometido

chrome.fontSettings.clearDefaultFontSize(
  details?: object,
  callback?: function,
)

清除此扩展程序设置的默认字号（如果有）。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

clearFont()

prometido

chrome.fontSettings.clearFont(
  details: object,
  callback?: function,
)

清除此扩展程序设置的字体（如果有）。

参数

• 详细信息

  对象

  • genericFamily

    GenericFamily

    应为其清除字体的通用字体系列。

  • 文字

    ScriptCode（可选）

    应清除字体的脚本。如果省略，系统会清除全局脚本字体设置。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

clearMinimumFontSize()

prometido

chrome.fontSettings.clearMinimumFontSize(
  details?: object,
  callback?: function,
)

清除此扩展程序设置的最小字号（如果有）。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getDefaultFixedFontSize()

prometido

chrome.fontSettings.getDefaultFixedFontSize(
  details?: object,
  callback?: function,
)

获取固定宽度字体的默认大小。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。

返回

• Promise<object>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getDefaultFontSize()

prometido

chrome.fontSettings.getDefaultFontSize(
  details?: object,
  callback?: function,
)

获取默认字号。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。

返回

• Promise<object>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getFont()

prometido

chrome.fontSettings.getFont(
  details: object,
  callback?: function,
)

获取给定脚本和通用字体系列的字体。

参数

• 详细信息

  对象

  • genericFamily

    GenericFamily

    应为其检索字体的通用字体系列。

  • 文字

    ScriptCode（可选）

    应为其检索字体的脚本。如果省略，则会检索全局脚本（脚本代码“Zyyy”）的字体设置。

• callback

  函数（可选）

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • fontId

      字符串

      字体 ID。这可能不是字面量字体 ID 偏好设置值，而是系统解析偏好设置值所对应的字体的 ID。因此，如果系统上不提供字体，fontId 可能会与传递给 setFont 的字体不同。空字符串表示回退到全局脚本字体设置。

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

返回

• Promise<object>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getFontList()

prometido

chrome.fontSettings.getFontList(
  callback?: function,
)

获取系统中的字体列表。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (results: FontName[]) => void

  • 结果

    FontName[]

返回

• Promise<FontName[]>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getMinimumFontSize()

prometido

chrome.fontSettings.getMinimumFontSize(
  details?: object,
  callback?: function,
)

获取最小字体大小。

参数

• 详细信息

  对象（可选）

  此参数目前尚未使用。

• callback

  函数（可选）

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。

返回

• Promise<object>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setDefaultFixedFontSize()

prometido

chrome.fontSettings.setDefaultFixedFontSize(
  details: object,
  callback?: function,
)

设置固定宽度字体的默认大小。

参数

• 详细信息

  对象

  • pixelSize

    数值

    字体大小（以像素为单位）。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setDefaultFontSize()

prometido

chrome.fontSettings.setDefaultFontSize(
  details: object,
  callback?: function,
)

设置默认字体大小。

参数

• 详细信息

  对象

  • pixelSize

    数值

    字体大小（以像素为单位）。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setFont()

prometido

chrome.fontSettings.setFont(
  details: object,
  callback?: function,
)

为给定脚本和通用字体系列设置字体。

参数

• 详细信息

  对象

  • fontId

    字符串

    字体 ID。空字符串表示回退到全局脚本字体设置。

  • genericFamily

    GenericFamily

    应为其设置字体的通用字体系列。

  • 文字

    ScriptCode（可选）

    应设置字体的脚本代码。如果省略，则系统会设置全局脚本（脚本代码为“Zyyy”）的字体设置。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

setMinimumFontSize()

prometido

chrome.fontSettings.setMinimumFontSize(
  details: object,
  callback?: function,
)

设置最小字体大小。

参数

• 详细信息

  对象

  • pixelSize

    数值

    字体大小（以像素为单位）。

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 96 及更高版本

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

事件

onDefaultFixedFontSizeChanged

chrome.fontSettings.onDefaultFixedFontSizeChanged.addListener(
  callback: function,
)

在默认的固定字号设置发生变化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。

onDefaultFontSizeChanged

chrome.fontSettings.onDefaultFontSizeChanged.addListener(
  callback: function,
)

在默认字号设置发生变化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。

onFontChanged

chrome.fontSettings.onFontChanged.addListener(
  callback: function,
)

在字体设置发生变化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • fontId

      字符串

      字体 ID。请参阅 getFont 中的说明。

    • genericFamily

      GenericFamily

      字体设置已更改的通用字体系列。

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • 文字

      ScriptCode（可选）

      字体设置已更改的脚本代码。

onMinimumFontSizeChanged

chrome.fontSettings.onMinimumFontSizeChanged.addListener(
  callback: function,
)

当最小字号设置发生变化时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (details: object) => void

  • 详细信息

    对象

    • levelOfControl

      LevelOfControl

      此扩展程序对相应设置的控制级别。

    • pixelSize

      数值

      字体大小（以像素为单位）。