Communitygithub.com

RTL 组件模式

使用 Tailwind 逻辑工具构建适用于波斯语/阿拉伯语 RTL 页面的 UI 组件,涵盖表单、卡片、导航、表格、模态框等常见组件,并修复镜像布局错误。

RTL 组件模式 是什么?

该技能为 AI 代理提供了一个完整的 RTL(从右到左)UI 组件模式指南,专门针对使用 Tailwind CSS 和 shadcn/ui 构建的波斯语/阿拉伯语页面。它解决了 `dir="rtl"` 设置后 Flexbox/Grid 自动镜像,但 `ml-/mr-`、`left/right`、`translate-x` 等遗留属性仍需手动处理的常见问题。技能提供了从 LTR 习惯到逻辑属性的实用转换表,指导如何正确翻转图标(如箭头、面包屑分隔符),并详细处理表单、侧边栏、分页、表格、对话框、卡片等 9 种组件类型的 RTL 适配。同时,它涵盖了 `shadcn/ui` v4 的已知注意事项、CSS 动画的 RTL 镜像模式(如抽屉、进度条、骨架屏闪烁),以及一个用于质量保证的 `rtl-audit` 审计清单。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理工具,帮助开发者快速生成或修复方向无关的组件,确保 BOTH LTR 和 RTL 方向上的视觉一致性,节省手动排查和调试的时间。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mhmdsdqi87-cloud/TEKA_raast/tree/HEAD/skills/rtl-components

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

RTL 组件模式(Tailwind + shadcn/ui)

逻辑化的、不依赖方向的组件。设置 dir="rtl" 后,Flexbox 和 Grid 会自动镜像——问题都留在这里列出的残余部分。

1. 工具类转换表(熟记)

LTR 习惯逻辑属性(始终使用)
ml- / mr-ms- / me-
pl- / pr-ps- / pe-
left-0 / right-0start-0 / end-0
text-left / text-righttext-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 或 flex gap-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 类。

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

相关技能