RTL 组件模式(Tailwind + shadcn/ui)
逻辑化的、不依赖方向的组件。设置 dir="rtl" 后,Flexbox 和 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):
- 用于“下一个/上一个”、返回按钮、面包屑分隔符的 V 形符号/箭头
- 缩进/取消缩进、回复(分享箭头)、转发、重做
- 时间线标记、“展开侧面板”图标
不要翻转:
- 时钟、锁定、搜索、设置、勾选、心形、星星、上传/下载、Wi-Fi、铃铛
<!-- RTL 中指向左的下一个箭头 -->
<svg class="rtl:rotate-180">…</svg>
对于 shadcn/ui + lucide:<ChevronLeft className="rtl:rotate-180" /> 实际上犯了两次错——只需根据你提供的方向使用正确的字形。对于纯 RTL 产品:next = ChevronLeft,back = ChevronRight。
3. 表单
- 标签位于输入框上方行内开始位置(标准方式)。
- 文本输入框:对于姓名/消息使用
dir="auto";对于电话号码、电子邮件、身份证号、价格输入框使用dir="ltr"+text-end(内容为 LTR,但位置保持在右侧)。 - 输入组附加元素:货币「تومان」位于数字之后 → 视觉上在左侧;两边都使用逻辑内边距,切勿硬编码
pr。 - 验证图标:使用
end-0而非right-0定位。 - 错误文本:使用波斯语,包含「؛」和正确的 ZWNJ:«ایمیل معتبر نیست»، «رمز عبور باید ۸ نویسه یا بیشتر باشد».
4. 导航与界面框架
- 侧边栏:
start-0(在 RTL 中渲染在右侧)。仅图标折叠变体保持提示翻转(Radix 工具提示中使用side="start")。 - 面包屑:分隔符 =
ChevronLeft(RTL“向前向下”方向),最后一项为当前项。 - 分页:页码向左升序排列:۱ ۲ ۳ ۴,next = ChevronLeft。“Prev”在视觉上位于右侧。
- 标签页:顺序从右到左流动;通过
border-b实现的活动下划线没有问题。 - 表格:列顺序自动镜像;将数字单元格对齐为
text-end,让波斯数字保持其自身的 LTR 运行。
5. 覆盖层
- 对话框/抽屉:
Sheet side="start"= 在 RTL 页面中为右侧抽屉。 - 下拉菜单/弹出框:Radix 使用
side/align——align="start"跟随行内开始位置(右侧)。默认碰撞处理在 RTL 下工作正常。 - Toast 通知:定位为
bottom-start(视觉上为 RTL 的右下角),这样它们就不会与行内结束位置的行动号召元素冲突。 - 截断的波斯文本上的工具提示:Radix 测量正常;确保设置了
max-w——波斯省略号工作正常。
6. 卡片与内容块
- 在行内开始边缘的强调条:
border-s-2 border-s-emerald-500(渲染在右侧)。 - 元数据行(作者 · 日期 · 阅读时间):使用
ms-2 me-2或 flexgap-2作为分隔点。 - 带操作的卡片:主要操作位于行内结束位置?不——在 RTL 阅读中,主要 CTA 传统上位于卡片页脚的行内结束位置(左侧),镜像 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 令牌,New York 风格)
- 当应用在
<html>上设置dir="rtl"时,大多数基元组件都是 RTL 干净的。 - 已知需要调整的地方:
DropdownMenuContent align="start"使菜单锚定在触发器右侧边缘下方;Select的 V 形符号应为ChevronDown(无方向性,无需更改);InputOTP、CommandDialog和ResizablePanel需要手动检查。 - 一次设置字体令牌:将 Vazirmatn 放入
--font-sans(globals.css),这样每个 shadcn 组件都会继承它。
9. 审计钩子
通过 rtl-audit 检查清单交付组件——特别注意图标翻转、变换和 left/right 类。