ScriptItemizeOpenType 函式 (usp10.h)

發行項
03/03/2024

將 Unicode 字串分成個別可塑造的專案，併為 OpenType 處理的每個可成形專案提供功能標記數位。

語法

HRESULT ScriptItemizeOpenType(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          OPENTYPE_TAG         *pScriptTags,
  [out]          int                  *pcItems
);

參數

[in] pwcInChars

要進行專案化之 Unicode 字串的指標。

[in] cInChars

pwcInChars 中要分項的字元數。

[in] cMaxItems

定義要處理之專案的 SCRIPT_ITEM 結構數目上限。

[in, optional] psControl

SCRIPT_CONTROL 結構的指標，指出要執行的專案化類型。

或者，如果不需要任何SCRIPT_CONTROL屬性，應用程式可以將此參數設定為 NULL。如需詳細資訊，請參閱＜備註＞一節。

[in, optional] psState

指出初始雙向演算法狀態之SCRIPT_STATE 結構的指標。

或者，如果不需要腳本狀態，應用程式可以將此參數設定為 NULL 。如需詳細資訊，請參閱＜備註＞一節。

[out] pItems

函式擷取 SCRIPT_ITEM 結構的緩衝區指標，代表已處理的專案。緩衝區長度應為 (cMaxItems + 1) * sizeof(SCRIPT_ITEM) 位元組。使用處理少於兩 個SCRIPT_ITEM 結構的緩衝區來呼叫此函式無效。函式一律會將終端機專案加入至專案分析陣列，讓以零起始索引「i」的項目長度一律可供使用：

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pScriptTags

緩衝區的指標，函式會擷取代表腳本標記之OPENTYPE_TAG 結構的陣列。緩衝區長度應為 cMaxItems * sizeof(OPENTYPE_TAG) 位元組。

注意當專案中的所有字元都是中性字元時，此參數的值會SCRIPT_TAG_UNKNOWN (0x00000000) 。例如，如果專案完全由標點符號所組成，就會發生這種情況。

[out] pcItems

已處理之SCRIPT_ITEM 結構的指標。

傳回值

若成功，即傳回 0。如果函式未成功，函式會傳回非零 HRESULT 值。在所有錯誤情況下，不會完全處理任何專案，而且輸出中沒有任何部分包含定義的值。應用程式可以使用 SUCCEEDED 和 FAILED 宏來測試傳回值。

如果 cMaxItems 所指示的大小太小，則函式會傳回E_OUTOFMEMORY。應用程式可以使用較大的緩衝區再次嘗試呼叫函式。

如果發生下列一或多個狀況，函式會傳回E_INVALIDARG：

pwcInChars 設定為 NULL
cInChars 為 0
pItems 設定為 NULL
pScriptTags 設定為 NULL
cMaxItems< 2

備註

ScriptItemizeOpenType 優先於較舊的 ScriptItemize 函式。 ScriptItemizeOpenType 的其中一個優點是每個可成形專案的功能標記可用性。

如需通常呼叫此函式的內容討論，請參閱使用 Uniscribe 顯示文字。

函式會以成形引擎的變更或方向變更來分隔專案。

應用程式可以從 ScriptItemizeOpenType 所擷取的每個SCRIPT_ITEM結構，建立多個範圍或完全落在單一專案中。不過，它不應該將多個項目合併成單一執行。測量或轉譯時，應用程式可以針對每個回合呼叫 ScriptShapeOpenType，而且必須在 ScriptItemizeOpenType 所擷取的SCRIPT_ITEM結構中傳遞對應的SCRIPT_ANALYSIS結構。

如果應用程式所處理的文字可以包含任何由右至左的內容，則應用程式會使用呼叫 ScriptItemizeOpenType 中的 psControl 和 psState 參數。不過，應用程式不需要這麼做，而且可以處理雙向文字本身，而不是依賴 Uniscribe 來執行此動作。 psControl 和 psState 參數在某些嚴格由左至右的案例中很有用，例如，當 SCRIPT_CONTROL 的 fLinkStringBefore 成員不是由右至左腳本特有的時。應用程式會將 psControl 和 psState 設定為 NULL ，讓 ScriptItemizeOpenType 完全以字元碼中斷 Unicode 字串。

應用程式可以將所有參數設定為非 NULL 值，讓函式執行完整的 Unicode 雙向分析。若要允許正確的 Unicode 雙向分析，應該根據段落開頭的讀取順序初始化 SCRIPT_STATE 結構，而且應該傳遞整個段落的 ScriptItemizeOpenType 。特別是， uBidiLevel 成員應該針對從左至右初始化為0，而從右至左為1。

SCRIPT_ITEM中會參考SCRIPT_ANALYSIS的 fRTL成員。 scriptGetProperties 會擷取SCRIPT_PROPERTIES的 fNumeric 成員。這些成員會一起提供與 GetCharacterPlacement 中 lpResults 所參考之 GCP_RESULTS 的 lpClass 成員相同的分類。

歐洲數位U+0030到U+0039可以轉譯為國家數位，如下表所示。

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	Unicode U+0030 到 U+0039 所顯示的數位圖形
FALSE	任何	歐洲數位
TRUE	FALSE	如 SCRIPT_CONTROL 的 uDefaultLanguage 成員所指定。
TRUE	TRUE	如同先前的強文字，預設為 SCRIPT_CONTROL 的 uDefaultLanguage 成員。

在內容數位模式中，會發生下列其中一個動作：

如果 uDefaultLanguage 指定的腳本方向與輸出相同，則會以 uDefaultLanguage 所指示的語言呈現第一個字母之前遇到的所有數位。
如果 uDefaultLanguage 指定的腳本與輸出相反方向，則會以歐洲數位轉譯第一個字母之前遇到的所有數位。

例如，如果 uDefaultLanguage 指出LANG_ARABIC，則初始數位會在由右至左內嵌的 Arabic-Indic 中。不過，它們位於由左至右內嵌的歐洲數位中。

如需詳細資訊，請參閱數位圖形。

下表提供 Unicode 控制字元和定義及其對SCRIPT_STATE 成員的影響。如需 Unicode 控制字元的詳細資訊，請參閱 Unicode 標準。

Unicode 控制字元	意義	對SCRIPT_STATE的影響
NADS	使用國家數位圖形覆寫歐洲數位 (NODS) 。	設定 fDigitSubstitute。
點頭	使用標準數位圖形，否則稱為歐洲數位。請參閱 NADS。	清除 fDigitSubstitute。
屁股	啟用對稱配對的交換，例如括弧。針對這些字元，左和右會解譯為開頭和結尾。此為預設值。請參閱 ISS。	清除 fInhibitSymSwap。
ISS	禁止對稱配對交換。請參閱 ASS。	設定 fInhibitSymSwap。
AAFS	啟用阿拉伯文簡報表單的阿拉伯文窗體成形。請參閱IAFS。	設定 fCharShape。
IAFS	禁止阿拉伯文表單成形，也就是阿拉伯文簡報表單的連字和標籤連接。不受影響之阿拉伯文字元。此為預設值。請參閱AAFS。	清除 fCharShape。

SCRIPT_STATE的 fArabicNumContext 成員支援阿拉伯文腳本文字中數字的區分內容顯示。它指出數位是否使用原生阿拉伯文腳本數字圖形或歐洲數位來轉譯。在段落開頭，此成員通常應該針對阿拉伯文地區設定初始化為 TRUE ，或針對任何其他地區設定初始化 為 FALSE 。函式會在處理強文字時更新腳本狀態。

輸出參數 pScriptTags 表示專案平行的陣列。針對每個專案，此函式會擷取應該用於所有後續作業中成形的腳本標籤。

腳本標籤通常是由 ScriptItemizeOpenType 從輸入字元決定。如果函式擷取特定的腳本標籤，應用程式應該將它傳遞至其他函式，而不需要變更。不過，例如，當字元為中性 (時，無法判斷數位) 和腳本時，應用程式應該根據與文字相關聯的字型和語言，選擇適當的腳本標籤。

重要從 Windows 8 開始：若要維護在 Windows 7 上執行的能力，使用 Uniscribe 的模組必須在其連結庫清單中指定 gdi32.lib 之前指定 Usp10.lib。

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	usp10.h
程式庫	Usp10.lib
Dll	Usp10.dll
可轉散發套件	在 Windows XP 上 Usp10.dll 1.600 版或更新版本