IsaacLab 里让 Franka 抓起方块：奖励函数避坑与训练全路径
2026/9/20 17:00:30
- 前端
【免费下载链接】gentelella
Free admin dashboard template — vanilla JS, SCSS, Vite 8. No Bootstrap, no jQuery.
项目地址：https://gitcode.com/gh_mirrors/ge/gentelella
<output_article>
Gentelella v4 RTL 支持指南：用 CSS 逻辑属性实现阿拉伯语、希伯来语等从右到左布局
Gentelella v4 通过 CSS 逻辑属性（logical properties）为阿拉伯语、希伯来语、波斯语和乌尔都语提供了完整的从右到左（right-to-left，RTL）布局支持。本文档从「如何开启」到「底层实现原理」再到「如何为 RTL 编写新样式」系统地讲解 Gentelella 的 RTL 架构——你只需在根元素上设置一个dir属性，整个模板的布局、间距与对齐规则就会自动镜像；读完本文你将掌握运行时切换、逻辑属性对照、无需镜像样式表的实现细节，以及如何规避 RTL 开发中常见的陷阱。
开启 RTL：一行 HTML 属性
Gentelella v4 的 RTL 支持建立在一个极简的 API 之上：在根元素<html>上设置dir属性即可。
<html lang="ar" dir="rtl">设置dir="rtl"后，整个模板——侧边栏、顶部栏、表格、表单、卡片、抽屉、开关控件——的所有布局、间距与对齐规则都会自动翻转。官方文档的表述非常直白："That's the whole API."（这就是全部 API）。没有独立的分支样式表，没有额外的 CSS 类，也不需要重新构建。
运行时切换：localStorage + pre-paint 脚本
如果你希望让用户能够在运行时切换方向，并且让选择在刷新后依然生效、且不会出现"方向闪错"（flash of wrong direction），需要将选择写入localStorage的dir键，并同步设置根元素属性：
localStorage.setItem('dir', 'rtl'); document.documentElement.setAttribute('dir', 'rtl');其中的关键机制在于vite.config.js中注入的pre-paint 脚本。构建（或 dev）时，Vite 插件会在每个页面的<head>中注入一段内联脚本，它会在<body>渲染之前读取localStorage中的方向并应用到<html>元素上，其处理方式与主题（theme）的暗色/亮色模式完全一致。源码见 vite.config.js：
const prePaint = `<script>(function(){try{var t=localStorage.getItem('theme');var d=window.matchMedia('(prefers-color-scheme: dark)').matches;var theme=t||(d?'dark':'light');document.documentElement.setAttribute('data-theme',theme);var dir=localStorage.getItem('dir');if(dir==='rtl'||dir==='ltr'){document.documentElement.setAttribute('dir',dir);}}catch(e){}})();</script>`;注意这段脚本对dir值的校验逻辑：
- 合法值只有
'rtl'和'ltr'两个字符串； - 其他任何值都会被忽略，此时文档将使用 HTML 标记自身声明的
dir（即<html dir="...">中写的值，若未写则按浏览器默认的 LTR 处理）。
工作原理：CSS 逻辑属性，而非镜像样式表
Gentelella v4 的 RTL 样式不是靠"镜像样式表"（mirrored stylesheet）实现的，而是构建在CSS 逻辑属性（CSS logical properties）之上：方向由浏览器根据书写模式（writing mode）与方向自动处理，而不是由一套额外维护的样式规则来"反转"每个属性。
物理属性与逻辑属性对照表
| 物理属性（physical） | 逻辑属性（logical） |
|---|---|
margin-left/margin-right | margin-inline-start/margin-inline-end |
padding-left/padding-right | padding-inline-start/padding-inline-end |
border-left/border-right | border-inline-start/border-inline-end |
left:/right: | inset-inline-start/inset-inline-end |
text-align: left/right | text-align: start/end |
border-top-left-radius（及同类） | border-start-start-radius（及同类） |
这套逻辑属性在仓库中的 SCSS 部分里被广泛使用。例如 _apps.scss 中的text-align: start、inset-inline-start、margin-inline-start: auto、padding-inline-start: 24px等；_components.scss 中的border-inline-start: 3px solid var(--green)、inset-inline-end: 16px等。这些写法在 LTR 下与对应的物理属性计算结果完全一致，在 RTL 下则自动沿内联轴（inline axis）镜像。
不需要rtl.css的原因
因为方向由浏览器处理，所以：
- 没有单独的
rtl.css文件需要维护同步——不存在"LTR 改了、RTL 忘了改"这类双份样式漂移问题； - 没有构建步骤去镜像样式表——不存在把
margin-left批量替换成margin-right之类的后处理； - 一套样式规则同时服务两种方向。
从源码结构看，_rtl.scss 在 main.scss 中被@use "rtl"引入，并且特意放在最后一个位置——注释明确说明了原因："RTL overrides only fix what logical properties can't express (transforms, background-position, box-shadow), so they must win the cascade."（RTL 覆盖只修复逻辑属性无法表达的东西——transform、background-position、box-shadow——因此它们必须在层叠中胜出）。也就是说，_rtl.scss不是 RTL 的主体，而只是对逻辑属性盲区的"打补丁"。
_rtl.scss 的真实内容：只为逻辑属性的盲区打补丁
_rtl.scss 只覆盖四类没有逻辑等价物（no logical equivalent）的属性：
translateX()—— transform 按定义就是物理的。涉及：侧边栏移动端抽屉（sidebar drawer）、滑出式抽屉（slide-out drawer）、开关与切换旋钮（switch and toggle knobs）、rail 模式的飞出路标标签（rail flyout labels）；background-position—— 原生的 select 箭头；box-shadow偏移量—— 抽屉的边缘阴影；- 沿内联轴指向的 Chevron（V 形箭头）图标。
逐段解读 _rtl.scss 的覆盖规则
1. 侧边栏移动端抽屉——从 inline-start 边缘滑入（_rtl.scss）
@media (max-width: 768px) { [dir='rtl'] .sidebar { transform: translateX(100%); } [dir='rtl'] .sidebar.open { transform: translateX(0); } }在移动端（≤768px），侧边栏变成一个从屏幕边缘滑入的抽屉。LTR 下它从左侧滑入（隐藏时translateX(-100%)）；RTL 下则从右侧滑入，因此隐藏状态改为translateX(100%)，打开状态归零。
2. rail 模式飞出路标——远离 rail 的微调（_rtl.scss）
[dir='rtl'] body.sidebar-rail .nav-link[data-rail-label]::after { transform: translateY(-50%) translateX(4px); }桌面端侧边栏折叠为 64px rail 后，悬停时导航项右侧会弹出文字标签（label）。RTL 下标签要"推离" rail（而不是贴住它），因此需要镜像translateX的方向。
3. 滑出式抽屉——默认边为 inline-end，.left为 inline-start（_rtl.scss）
[dir='rtl'] .drawer { transform: translateX(-100%); box-shadow: 10px 0 30px rgba(0, 0, 0, 0.12); } [dir='rtl'] .drawer.open { transform: translateX(0); } [dir='rtl'] .drawer.left { transform: translateX(100%); box-shadow: -10px 0 30px rgba(0, 0, 0, 0.12); }抽屉组件默认从 inline-end 边缘滑出（LTR 下是右侧），.left变体从 inline-start 边缘滑出。RTL 下这两者的物理位置互换，因此translateX的符号也要互换；同时box-shadow的 x 偏移方向跟着翻转，保证阴影仍然投射在抽屉与内容交界处。
4. 开关与切换旋钮——沿内联轴滑动（_rtl.scss）
[dir='rtl'] .switch input:checked + .track::before, [dir='rtl'] .toggle.on::after { transform: translateX(-16px); }开关（switch）和切换（toggle）的圆形旋钮在轨道内沿内联轴滑动。LTR 下选中状态旋钮右移（translateX(16px)）；RTL 下则左移，因此覆盖为translateX(-16px)。
5. 原生 select 箭头——background-position 没有逻辑形式（_rtl.scss）
[dir='rtl'] select.input, [dir='rtl'] .input select, [dir='rtl'] select.form-control { background-position: left 10px center; }下拉框的箭头是通过background-position定位的，而该属性没有可用的逻辑关键字，所以 RTL 下把箭头从右侧挪到左侧（left 10px center）。
6. 侧边栏手风琴 chevron——关闭态沿 inline-end 指向（_rtl.scss）
[dir='rtl'] .nav-chev { transform: scaleX(-1); }侧边栏手风琴（accordion）的箭头：关闭时沿内联轴指向（LTR 朝右，RTL 朝左），打开时朝下。因此只镜像关闭状态，打开状态是方向中性的，无需覆盖。注释里还记录了一个宝贵的坑：第一次实现时曾试图加scaleX(-1) rotate(-90deg)，由于rotate先应用，结果箭头指向了"上"——这正是"打开态不要动它"这一结论的由来，详见 _rtl.scss 的注释。
什么是"方向中性"（direction-neutral）——两个关键模式
文档强调，有两类写法不要转换为逻辑属性：
居中模式（Centring）是方向中性的，不要转换它。
.centred { left: 50%; // 保持物理属性——这是正确的 transform: translateX(-50%); }left: 50%配合translateX(-50%)在两种方向下都是正确的：left: 50%把元素左边缘放在容器中间，translateX(-50%)把它左移自身宽度的一半，两者叠加恰好水平居中。如果改成inset-inline-start: 50%反而会破坏 RTL——因为inset-inline-start的偏移会随方向翻转，而 transform 不会翻转，二者不再抵消。因此_rtl.scss顶部注释特意声明："Anything centred withleft: 50%+translateX(-50%)is deliberately NOT here: that pattern is direction-neutral and already correct in both modes."（用left: 50%+translateX(-50%)居中的任何东西都刻意不放在这里：该模式是方向中性的，在两种模式下都已经正确）。
垂直旋转也是方向中性的。一个打开时朝下（pointdown）的 chevron 不应该为了 RTL 去覆盖它；只有关闭态那种沿内联轴指向的状态才需要镜像。这正是上面第 6 条_rtl.scss只处理.nav-chev关闭态的原因。
为 RTL 编写新样式：两条实战规则
规则一：新组件用逻辑属性，双向免费支持
编写新组件样式时，使用逻辑属性，新组件就能免费获得双向支持：
.my-card { padding-inline-start: 16px; // 不要写 padding-left border-inline-end: 1px solid var(--border); text-align: start; // 不要写 text-align: left }规则二：记住两个方向中性模式
- 居中：保持
left: 50%+translateX(-50%)的物理写法，不要改写成逻辑属性； - 垂直旋转：只在关闭态需要沿内联轴镜像时才写 RTL 覆盖，打开态的"朝下"箭头不要动。
遵循这两条规则，新组件在 LTR 与 RTL 下同时可用，且不需要往_rtl.scss里加任何东西。
什么不会被镜像（What isn't mirrored）
文档明确列出三类"不做镜像"的内容，理解它们可以避免误判为 bug：
1. 图表（Charts）。ECharts 自己绘制 canvas，坐标轴和图例（legend）的位置不受dir影响。如果需要镜像的坐标轴，需要给 ECharts 传它自己的配置项（options）。相关图表逻辑集中在 src/v4/charts.js。
2. RTL 页面中的拉丁文本（Latin text inside an RTL page）。英文等拉丁字符串在 RTL 容器中会按照 Unicode 双向算法（Unicode bidi algorithm）重新排序——例如4 of 6 remaining会渲染成of 6 remaining 4。这是正确的 bidi 行为，不是布局 bug；一旦内容真正是 RTL 语言，排序自然恢复正常。如果你需要固定混合方向的文本段，把它包在<bdi>元素里，或给它一个显式dir属性的元素。
3. 非方向性图标（Icons that aren't directional）。只有沿内联轴指向的 chevron 和箭头会被翻转；搜索图标（search）、垃圾桶图标（trash）等不具方向性的图标不会被镜像。
验证一次改动：像素级回归保证
RTL 支持迁移有一个硬性验证标准：引入逻辑属性后，LTR 渲染不得发生任何位移——因为在 LTR 文档中，逻辑属性与它们所替代的物理属性计算结果是完全一致的。
Gentelella 仓库中的这次转换正是以此为标准进行验证的：12 个代表性页面在改动前后分别截图，按哈希值（hash）比较，全部像素级一致（pixel-identical）。这既证明了逻辑属性在 LTR 下与物理属性等价，也保证了存量 LTR 用户不会因 RTL 改造而看到任何布局回归。
如果你修改了样式，可以用同样的思路自检：先截 LTR 基线图，再验证 RTL 页面在两种方向下都符合预期。仓库自带的冒烟测试脚本 scripts/smoke.mjs 与截图脚本 scripts/screenshots.mjs 可以作为自动化验证的起点。
小结
| 主题 | 结论 |
|---|---|
| 开启方式 | <html lang="ar" dir="rtl">，一行属性即完整 API |
| 运行时切换 | localStorage的dir键 + pre-paint 脚本在首帧前应用，合法值仅'rtl'/'ltr' |
| 实现原理 | CSS 逻辑属性（margin-inline-*、inset-inline-*、text-align: start等），由浏览器处理方向 |
| 无镜像样式表 | 没有独立rtl.css、没有构建期镜像步骤，一套规则服务双向 |
| _rtl.scss 的职责 | 仅覆盖 transform / background-position / box-shadow / 内联轴 chevron 等逻辑属性盲区 |
| 编写新样式 | 用逻辑属性；left:50% + translateX(-50%)居中与"朝下"旋转保持物理写法 |
| 不镜像的内容 | ECharts canvas、RTL 容器中的拉丁文本（Unicode bidi 行为）、非方向性图标 |
| 验证标准 | LTR 下逻辑属性与物理属性计算一致；仓库用 12 个页面截图哈希比对确认像素级一致 |
Gentelella v4 的 RTL 方案的核心价值在于"零维护成本"：方向由浏览器原生处理，样式作者只需要养成写逻辑属性的习惯，_rtl.scss永远只承载那四类物理属性的修补。对于需要面向阿拉伯语、希伯来语、波斯语、乌尔都语市场的后台系统，这套方案可以直接套用——无需为 RTL 单独维护一套模板。 </output_article> </output_article>
赞
- 前端
【免费下载链接】gentelella
Free admin dashboard template — vanilla JS, SCSS, Vite 8. No Bootstrap, no jQuery.
项目地址：https://gitcode.com/gh_mirrors/ge/gentelella
相关推荐
PrimeNG RTL 支持指南：基于 CSS 逻辑属性的右到左布局实现与组件适配
PrimeNG RTL 支持指南：基于 CSS 逻辑属性的右到左布局实现与组件适配 本指南以 PrimeNG 官方 RTL（Right to Left，从右到左
前端UI组件Cycle.js国际化RTL支持：实现从右到左语言的响应式布局
Cycle.js国际化RTL支持：实现从右到左语言的响应式布局 你还在为多语言网站的RTL（Right to Left，从右到左）布局适配烦恼吗？当业务扩展到阿
前端Web框架Open-Meteo开源天气API架构解析：构建企业级气象数据服务平台的技术实现
Open Meteo开源天气API架构解析：构建企业级气象数据服务平台的技术实现 Open Meteo是一款完全开源的高性能天气数据服务平台，为技术团队提供自主
后端API网关数据工程
上一篇：LASP脚本接口完全指南：AudioSystem与InputStream类的高级应用
下一篇：开源项目 `routing-controllers` 常见问题解决方案
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考