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"

「Hang」

「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"

「Mend」

"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()

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

清除此擴充功能設定的預設固定字型大小 (如有)。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

clearDefaultFontSize()

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

清除此擴充功能設定的預設字型大小 (如有)。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

clearFont()

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

清除這個擴充功能設定的字型 (如有)。

參數

  • 詳細資料

    物件

    • genericFamily

      GenericFamily

      應清除字型的一般字型系列。

    • 文字

      ScriptCode 選填

      要清除字型的指令碼。如果省略，系統會清除全域字幕字型設定。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

clearMinimumFontSize()

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

清除此擴充功能設定的字型大小下限 (如果有)。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getDefaultFixedFontSize()

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

取得固定寬度字型的預設大小。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。

傳回

  • Promise<object>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getDefaultFontSize()

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

取得預設的字型大小。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。

傳回

  • Promise<object>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getFont()

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

取得指定文字和通用字型系列的字型。

參數

  • 詳細資料

    物件

    • genericFamily

      GenericFamily

      應擷取字型的一般字型系列。

    • 文字

      ScriptCode 選填

      應擷取字型的指令碼。如果省略，系統會擷取全球字元的字型設定 (字元代碼「Zyyy」)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • fontId

        字串

        字型 ID。這不是字型 ID 偏好設定值的常值，而是系統將偏好設定值解析為的字型 ID。因此，如果系統中沒有可用的字型，fontId 可能會與傳遞至 setFont 的字型不同。空字串表示會改用全域字體設定。

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

傳回

  • Promise<object>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getFontList()

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

取得系統上的字型清單。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (results: FontName[]) => void

傳回

  • Promise<FontName[]>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getMinimumFontSize()

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

取得最小字型大小。

參數

  • 詳細資料

    物件 選填

    這個參數目前未使用。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。

傳回

  • Promise<object>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setDefaultFixedFontSize()

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

設定固定寬度字型的預設大小。

參數

  • 詳細資料

    物件

    • pixelSize

      數字

      字型大小 (以像素為單位)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setDefaultFontSize()

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

設定預設的字型大小。

參數

  • 詳細資料

    物件

    • pixelSize

      數字

      字型大小 (以像素為單位)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setFont()

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

設定特定文字和一般字型系列的字型。

參數

  • 詳細資料

    物件

    • fontId

      字串

      字型 ID。空白字串表示會改用全域指令碼字型設定。

    • genericFamily

      GenericFamily

      應設定字型的通用字型系列。

    • 文字

      ScriptCode 選填

      應設定字型的指令碼。如果省略，系統會設定全域字元的字型設定 (字元程式碼「Zyyy」)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setMinimumFontSize()

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

設定字型大小下限。

參數

  • 詳細資料

    物件

    • pixelSize

      數字

      字型大小 (以像素為單位)。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 96 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onDefaultFixedFontSizeChanged

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

當預設的固定字型大小設定變更時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。

onDefaultFontSizeChanged

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

當預設字型大小設定變更時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。

onFontChanged

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

在字型設定變更時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • fontId

        字串

        字型 ID。請參閱 getFont 中的說明。

      • genericFamily

        GenericFamily

        字型設定已變更的一般字型系列。

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • 文字

        ScriptCode 選填

        字型設定已變更的指令碼。

onMinimumFontSizeChanged

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

當字型大小下限設定變更時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (details: object) => void

    • 詳細資料

      物件

      • levelOfControl

        LevelOfControl

        這項擴充功能對設定的控制層級。

      • pixelSize

        數字

        字型大小 (以像素為單位)。