RTL 元件模式(Tailwind + shadcn/ui)
邏輯性、方向無關的元件。設定 dir="rtl" 後,flex/grid 會自動鏡像化——但錯誤通常存在於此處列出的遺留問題中。
1. 工具轉換對照表(請牢記)
| LTR 習慣用法 | 邏輯屬性(永遠使用) |
|---|---|
ml- / mr- | ms- / me- |
pl- / pr- | ps- / pe- |
left-0 / right-0 | start-0 / end-0 |
text-left / text-right | text-start / text-end |
border-l- / border-r- | border-s- / border-e- |
rounded-l- / rounded-r- | rounded-s- / rounded-e- |
ml-auto(推到遠端) | ms-auto |
這些類別存在於 Tailwind v3.3+ 和 v4。使用它們意味著元件在兩個方向都能自動運作。
2. 方向性圖示——翻轉清單
僅翻轉真正具有方向性的圖示。切勿翻轉語意穩定的圖示。
需要翻轉(使用 rtl:-scale-x-100、預先翻轉的 SVG,或對箭頭使用 rtl:rotate-180):
- 用於上一步/下一步的 chevron/箭頭、返回按鈕、麵包屑分隔符號
- 縮排/凸排、回覆(分享箭頭)、轉寄、重做
- 時間軸標記、「展開側面板」圖示
不要翻轉:
- 時鐘、鎖定、搜尋、設定、勾選記號、愛心、星號、上傳/下載、WiFi、鈴鐺
<!-- RTL 中,下一頁箭頭指向左方 -->
<svg class="rtl:rotate-180">…</svg>
對於 shadcn/ui + lucide:<ChevronLeft className="rtl:rotate-180" /> 是錯的兩次——相反,只需根據您提供的方向使用正確的圖形。對於僅限 RTL 的產品:下一頁 = ChevronLeft,返回 = ChevronRight。
3. 表單
- 標籤位於輸入框上方的內聯起始處(標準做法)。
- 文字輸入框:名稱/訊息使用
dir="auto";電話、電子郵件、身分證字號、價格輸入框使用dir="ltr"+text-end(內容是 LTR,但位置保持在右側)。 - 輸入框群組附加元件:貨幣「تومان」放在數字之後 → 視覺上在左側;兩邊使用邏輯內邊距,永遠不要硬編碼
pr。 - 驗證圖示:使用
end-0而非right-0定位。 - 錯誤文字:使用波斯語,包含「؛」和正確的 ZWNJ:「ایمیل معتبر نیست」、「رمز عبور باید ۸ نویسه یا بیشتر باشد」。
4. 導覽與版面
- 側邊欄:
start-0(在 RTL 中渲染在右側)。僅顯示圖示的折疊變體需保持工具提示翻轉(在 Radix 工具提示中使用side="start")。 - 麵包屑:分隔符號 =
ChevronLeft(RTL 的「前進向下」方向),最後一項為當前項目。 - 分頁:頁碼向左遞增:۱ ۲ ۳ ۴,下一頁 = ChevronLeft。
Prev在視覺上位於右側。 - 標籤頁:順序從右到左流動;使用
border-b的活躍底線沒問題。 - 表格:欄位順序自動鏡像;將數字儲存格對齊
text-end並讓波斯數字保持其自身的 LTR 順序。
5. 覆蓋層
- 對話框/面板:
Sheet side="start"= RTL 頁面中的右側抽屜。 - 下拉選單/彈出視窗:Radix 使用
side/align——align="start"跟隨內聯起始處(右側)。預設碰撞處理在 RTL 下運作正常。 - 提示通知:定位
bottom-start(視覺上在 RTL 中為右下角),這樣它們就不會與內聯結束處的行動號召按鈕衝突。 - 被截斷的波斯文字上的工具提示:Radix 測量正常;確保設定
max-w——波斯語的省略號運作正常。
6. 卡片與內容區塊
- 內聯起始邊緣的重點條:
border-s-2 border-s-emerald-500(渲染在右側)。 - 元資料列(作者 · 日期 · 閱讀時間):分隔點使用
ms-2 me-2或 flexgap-2。 - 帶操作的卡片:主要操作在內聯結束處?不——在 RTL 閱讀中,主要行動號召按鈕傳統上位於卡片頁尾的內聯結束處(左側),鏡像 LTR 慣例。
7. 動畫與變形
dir 不會鏡像變形。檢查每一個:
translate-x-*(滑桿、螢幕外畫布、跑馬燈)→ 需要明確的 RTL 對應版本rotate-45裝飾性 → 通常沒問題- 輪播滑動:embla/swiper——設定
direction: rtl選項,否則它們會反向滾動 - 進度條:填滿動畫錨定在
start-0,向左增長;百分比顯示為 ۷۰٪ - 骨架屏閃爍動畫:關鍵影格
translate-x必須鏡像,否則閃爍效果會朝錯誤方向滑動
方向感知動畫模式
/* 螢幕外畫布抽屜:從內聯起始處進入,從內聯起始處退出。
一組宣告對即可服務兩個方向。 */
.drawer { transform: translateX(calc(var(--dir-sign, -1) * 100%)); }
[dir="rtl"] .drawer { --dir-sign: 1; }
.drawer.open { transform: translateX(0); }
/* 彈跳 / 強調圖示:翻轉整個動畫,而不是在動畫中途翻轉元素 */
[dir="rtl"] .cta-arrow { animation: nudge-rtl 1.2s infinite; }
@keyframes nudge-rtl { 50% { transform: translateX(-4px); } }
/* 數字計數器和進度填充:對邏輯內聯大小進行動畫,而不是 left */
@keyframes fill { from { inline-size: 0 } }
- CSS 邏輯屬性
inset-inline-start+ 自定義屬性符號切換,勝過為每個方向複製整個關鍵影格。 prefers-reduced-motion: reduce→ 停用輕推/跑馬燈效果,保持透明度淡入淡出。
8. shadcn/ui RTL 注意事項(v4 tokens,New York 風格)
- 當應用程式在
<html>上設定dir="rtl"時,大多數基本元件在 RTL 下是乾淨的。 - 已知需要調整的地方:
DropdownMenuContent align="start"使選單保持在觸發器右邊緣下方;Select的 chevron 應為ChevronDown(無方向性,無需更改);InputOTP、CommandDialog和ResizablePanel需要手動檢查。 - 設定一次字型 tokens:將 Vazirmatn 放入
--font-sans(globals.css)中,以便每個 shadcn 元件都繼承它。
9. 審計鉤子
在發布元件之前,通過 rtl-audit 檢查清單——特別是圖示翻轉、變形以及 left/right 類別。