ScriptItemize 函式 (usp10.h)

發行項
03/03/2024

將 Unicode 字串分成可個別成形的專案。

語法

HRESULT ScriptItemize(
  [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]          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] pcItems

已處理之SCRIPT_ITEM 結構的指標。

傳回值

若成功，即傳回 0。如果函式不成功，函式會傳回非零 HRESULT 值。

如果 pwcInChars 設定為 NULL，cInChars 為 0、pItems 設定為 NULL 或 cMaxItems< 2，則函式會傳回E_INVALIDARG。

如果 cMaxItems 的值不足，此函式會傳回E_OUTOFMEMORY。如同所有錯誤案例，不會完全處理任何專案，而且輸出陣列中沒有任何部分包含已定義的值。如果函式傳回E_OUTOFMEMORY，應用程式可以使用較大的 pItems 緩衝區再次呼叫它。

備註

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

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

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

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

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

SCRIPT_ITEM enabled=“1” 參考SCRIPT_ANALYSIS的 fRTL 成員。 scriptGetProperties 會擷取SCRIPT_PROPERTIES的 fNumeric 成員。這些成員會一起提供與 GetCharacterPlacement 中 lpResults 所參考GCP_RESULTSlpClass 成員相同的分類。

歐洲數位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 。函式會在處理強文本時更新腳本狀態。

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	usp10.h
程式庫	Usp10.lib
Dll	Usp10.dll
可轉散發套件	Windows Me/98/95 上的 Internet Explorer 5 或更新版本