useTextDirection

跟蹤文字排列方向

useTextDirection 管理 HTML 元素的文字方向（dir 屬性），支援 "ltr"（從左到右）、"rtl"（從右到左）和 "auto" 值。它回傳一個元組，包含當前方向值和設定函式。預設情況下在 <html> 元素上設定方向，但可以透過選擇器指定其他目標元素。

使用場景

• 為多語言應用程式動態切換文字方向（例如阿拉伯語、希伯來語使用 RTL）
• 根據使用者選擇的語言自動調整 UI 佈局方向
• 在特定區域中為混合方向文字提供正確的顯示

注意事項

• 以元素為準：initialValue 是兜底值而非覆寫值。若目標元素已帶有 dir 屬性，hook 在首次渲染時就會回報該值（而不是等 effect 修正），因此 RTL 文件不會先閃一下 ltr。只有元素沒有 dir 時才會使用 initialValue。
• SSR 安全：伺服器上不會存取 document，伺服器端渲染回傳 initialValue（預設："ltr"）和空操作設定函式。由於用戶端在首次渲染時就讀取元素，請傳入與伺服器渲染標記方向一致的 initialValue，否則兩邊不一致，React 會回報 hydration 不匹配。
• 目標選擇器：預設情況下，此 hook 在 <html> 元素上設定 dir。使用 selector 選項可針對特定元素進行範圍內的方向變更。
• 相關 hooks：另請參閱 usePreferredLanguages 偵測使用者的語言偏好，這可以為文字方向選擇提供參考。

Usage

function Demo() {
  const [dir, setDir] = useTextDirection({
    selector: "#_useTextDirectionDemo",
  });

  const text = useMemo(
    () =>
      dir === "ltr"
        ? "這個段落是英文，正確地從左到右。"
        : "這個段落是英文，但錯誤地從右到左。",
    [dir],
  );

  const handleOnClick = () => {
    const value = dir === "rtl" ? "ltr" : "rtl";
    setDir(value);
  };

  return (
    <div id="_useTextDirectionDemo">
      <p>{text}</p>
      <button onClick={handleOnClick}>
        <span>{dir?.toUpperCase()}</span>
      </button>
      <span>點擊以更改方向</span>
    </div>
  );
};

render(<Demo/>)

API

useTextDirection

Returns

readonly [UseTextDirectionValue, (value: UseTextDirectionValue) => void]: 包含以下元素的元組：

• 文字方向。
• 更新文字方向值的函數。

Arguments

UseTextDirectionOptions

UseTextDirectionValue

Type

export type UseTextDirectionValue = 'ltr' | 'rtl' | 'auto'