目錄 / Table of Contents

Class OdfFontContext

Namespace
OdfKit.Styles
Assembly
OdfKit.dll

Provides an isolated font registration, fallback, and segmentation context. 提供隔離的字型註冊、遞補與分段情境。

public sealed class OdfFontContext
Inheritance
OdfFontContext
Inherited Members

Remarks

Each instance owns its font registrations, fallback mappings, plane font mappings, and subsetter, so independent contexts (for example per tenant) never observe each other's state. Precedence at the high-level text entry points is per-call options, then the owning document's context, then Default. All members are thread-safe; lookup hot paths read immutable snapshots without locks. 每個執行個體擁有自己的字型註冊、替代對照、平面字型對應與子集化器，彼此獨立的情境（例如各租戶） 不會觀察到對方的狀態。高階文字入口的優先序為：每次呼叫的選項、所屬文件的情境、最後才是 Default。所有成員皆為執行緒安全；查詢熱路徑以不可變快照無鎖讀取。

Constructors

OdfFontContext()

Initializes a new isolated font context. 初始化新的隔離字型情境。

public OdfFontContext()

Properties

Default

Gets the process-wide default font context. 取得處理程序層級的預設字型情境。

public static OdfFontContext Default { get; }

Property Value

OdfFontContext

Methods

EmbedFontSubsets(OdfPackage, OdfNode, OdfNode)

Embeds subset fonts for private-use code points when a subsetter is registered. 若已註冊字型子集化實作，掃描文件中的 PUA 自造字並將對應子集字型嵌入封裝。

public void EmbedFontSubsets(OdfPackage package, OdfNode contentRoot, OdfNode stylesRoot)

Parameters

package OdfPackage

The ODF package. / ODF 套件。

contentRoot OdfNode

The content XML root. / 內容 XML 的根節點。

stylesRoot OdfNode

The styles XML root. / 樣式 XML 的根節點。

EmbedFonts(OdfPackage, OdfNode, OdfNode)

Embeds all fonts declared in the document into the package. 掃描並將文件中定義的所有字型內嵌至套件中。

public void EmbedFonts(OdfPackage package, OdfNode contentRoot, OdfNode stylesRoot)

Parameters

package OdfPackage

The ODF package. / ODF 套件。

contentRoot OdfNode

The content XML root. / 內容 XML 的根節點。

stylesRoot OdfNode

The styles XML root. / 樣式 XML 的根節點。

GetFontFallbackCandidates(string)

Gets the ordered fallback candidates for a font name. 取得指定字型的解析候選序列，依序包含原始名稱、使用者註冊替代字型與內建跨平台替代字型。

public IReadOnlyList<string> GetFontFallbackCandidates(string fontName)

Parameters

fontName string

The font name. / 字型名稱。

Returns

IReadOnlyList<string>

The de-duplicated candidates in priority order. / 依優先順序排列且已去除重複項目的字型候選序列。

GetSupplementaryPlaneFontName(string, int)

Gets the font name for a base font family and Unicode plane. 依據基礎字型名稱與 Unicode 平面，取得對應的字型名稱（自訂註冊規則優先，其後為內建的全字庫、花園明朝與字雲等對應）。

public string GetSupplementaryPlaneFontName(string baseFontFamily, int plane)

Parameters

baseFontFamily string

The base font family name. / 基礎字型名稱。

plane int

The Unicode plane. / Unicode 平面（Plane）。

Returns

string

The mapped font name. / 對應的字型名稱。

IsTrueTypeCollection(string)

Returns whether the file is a TrueType Collection. 檢查指定字型檔案是否為 TrueType Collection（.ttc）格式。PDFsharp 等部分渲染後端不支援直接讀取。

public static bool IsTrueTypeCollection(string filePath)

Parameters

filePath string

The font file path. / 字型檔案路徑。

Returns

bool

Whether the file starts with the TTC signature. / 若檔案以 TTC 簽章（'ttcf'）開頭則為 true。

MapFont(string)

Maps a font name through the registered substitution rules. 取得指定字型的實質替代字型名稱。若無替代規則則傳回原名稱。

public string MapFont(string fontName)

Parameters

fontName string

The font name. / 字型名稱。

Returns

string

The substituted or original font name. / 替代後或原字型名稱。

RegisterEmbeddedFonts(OdfDocument, int, long)

Registers fonts embedded through ODF font-face URI declarations. 註冊透過 ODF font-face URI 宣告內嵌的字型。

public int RegisterEmbeddedFonts(OdfDocument document, int maximumFonts, long maximumTotalBytes)

Parameters

document OdfDocument

The source document. / 來源文件。

maximumFonts int

The maximum embedded font count. / 內嵌字型數上限。

maximumTotalBytes long

The maximum total embedded font bytes. / 內嵌字型總位元組上限。

Returns

int

The registered font count. / 已註冊的字型數。

RegisterFallback(string, string)

Registers a font substitution rule. 註冊字型替代對照規則（例如在無微軟字型之 Linux/Docker 上將 "MS YaHei" 對照至 "Noto Sans CJK TC"）。

public void RegisterFallback(string targetFont, string replacementFont)

Parameters

targetFont string

The font name to substitute. / 要替代的目標字型名稱。

replacementFont string

The replacement font name. / 用來替代的字型名稱。

Exceptions

ArgumentNullException

當參數為空時拋出

RegisterFont(string, string)

Registers a font file for the specified font name. 為指定字型名稱註冊字型檔案。

public void RegisterFont(string fontName, string filePath)

Parameters

fontName string

The font name. / 字型名稱。

filePath string

The font file path. / 字型檔案的路徑。

Exceptions

ArgumentNullException

當 fontName 或 filePath 為 null 時拋出

FileNotFoundException

當找不到指定的字型檔案時拋出

RegisterFontData(string, byte[])

Registers an in-memory font for precise layout without creating a temporary file. 註冊記憶體中字型，供精確排版使用且不建立暫存檔。

public void RegisterFontData(string fontName, byte[] fontData)

Parameters

fontName string

The font name. / 字型名稱。

fontData byte[]

The OpenType or TrueType bytes, copied by this method. / OpenType 或 TrueType 位元組；本方法會複製內容。

RegisterFontDirectory(string)

Registers a directory scanned for font files. 註冊用於搜尋字型檔案的目錄。

public void RegisterFontDirectory(string directoryPath)

Parameters

directoryPath string

The font directory path. / 字型目錄的路徑。

Exceptions

ArgumentNullException

當 directoryPath 為 null 時拋出

DirectoryNotFoundException

當找不到指定的字型目錄時拋出

RegisterFontSubsetter(IFontSubsetter)

Registers a font subsetter extension. 註冊字型子集化擴充實作。

public IDisposable RegisterFontSubsetter(IFontSubsetter subsetter)

Parameters

subsetter IFontSubsetter

The font subsetter. / 字型子集化實作。

Returns

IDisposable

A handle restoring the previous registration when disposed. / 可用於還原先前註冊狀態的資源控制代碼。

Exceptions

ArgumentNullException

當 subsetter 為 null 時擲出

RegisterSupplementaryPlaneFontMapping(string, IReadOnlyDictionary<int, string>)

Registers a custom supplementary-plane font mapping that takes precedence over the built-in rules. 註冊自訂的增補平面字型對應規則，查詢時優先於內建對應規則。

public IDisposable RegisterSupplementaryPlaneFontMapping(string baseFontPattern, IReadOnlyDictionary<int, string> planeFontNames)

Parameters

baseFontPattern string

The substring matched against the base font family name. / 用於比對基礎字型家族名稱的子字串。

planeFontNames IReadOnlyDictionary<int, string>

The mapping from Unicode plane number (1 to 16) to the font name to use. / Unicode 平面編號（1 至 16）對應至所用字型名稱的對照表。

Returns

IDisposable

A handle that removes the registration when disposed. / 釋放時移除此註冊的資源控制代碼。

Remarks

Later registrations are consulted first. When baseFontPattern matches the base font family (ordinal, case-insensitive substring comparison), the mapping exclusively decides the result: planes missing from planeFontNames keep the base font family and the built-in rules are not consulted. 後註冊的規則優先比對。當 baseFontPattern 與基礎字型家族名稱相符（不分大小寫的序數子字串比對）時， 該規則獨占決定結果：未列於 planeFontNames 的平面維持基礎字型家族，且不再套用內建規則。

Exceptions

ArgumentNullException

當 baseFontPattern 為空或 planeFontNames 為 null 時擲出

ArgumentOutOfRangeException

當平面編號不在 1 至 16 範圍內時擲出

ArgumentException

當任一平面對應的字型名稱為空白時擲出

ResolveFontFallback(string, Func<string, bool>)

Resolves the first usable fallback candidate using the specified probe. 依指定可用性探針解析第一個可使用的字型候選名稱。

public string? ResolveFontFallback(string fontName, Func<string, bool> isAvailable)

Parameters

fontName string

The font name. / 字型名稱。

isAvailable Func<string, bool>

The availability probe. / 用來判斷字型候選是否可使用的探針。

Returns

string

The first usable candidate, or null. / 第一個可使用的候選字型名稱，若沒有候選符合則為 null。

Exceptions

ArgumentNullException

當 isAvailable 為 null 時擲出

ResolveFontPath(string)

Resolves the absolute file path for a font family name. 依字型家族名稱解析字型的絕對路徑。

public string? ResolveFontPath(string fontName)

Parameters

fontName string

The font name. / 字型名稱。

Returns

string

The absolute font file path, or null. / 字型檔案的絕對路徑，若無法解析則為 null。

SegmentText(string, string)

Segments text and assigns font names per Unicode plane. 將文字依照 Unicode 字面拆分為多個文字片段，並指派適當的字型名稱。

public List<(string Text, string FontName)> SegmentText(string text, string defaultFontName)

Parameters

text string

The source text. / 要分段的來源文字。

defaultFontName string

The default font name. / 預設的字型名稱。

Returns

List<(string Text, string FontName)>

The text segments with font names. / 文字片段與字型名稱的 Tuple 集合。

WarnIfUnresolvable(string, string)

Warns once when a font name cannot be resolved to a file. 檢查指定字型名稱是否能成功解析出實際字型檔案；若找不到則發出一次性警告（同一名稱不重複記錄）。

public bool WarnIfUnresolvable(string fontName, string context)

Parameters

fontName string

The font name. / 字型名稱。

context string

The warning context description. / 用於警告訊息的情境描述（例如觸發此字型查詢的功能名稱）。

Returns

bool

Whether the font resolves successfully. / 若該字型可成功解析則為 true。