前端【免费下载链接】gentelellaFree admin dashboard template — vanilla JS, SCSS, Vite 8. No Bootstrap, no jQuery.项目地址https://gitcode.com/gh_mirrors/ge/gentelella点击查看免费下载output_articleGentelella v4 RTL 支持指南用 CSS 逻辑属性实现阿拉伯语、希伯来语等从右到左布局Gentelella v4 通过 CSS 逻辑属性logical properties为阿拉伯语、希伯来语、波斯语和乌尔都语提供了完整的从右到左right-to-leftRTL布局支持。本文档从「如何开启」到「底层实现原理」再到「如何为 RTL 编写新样式」系统地讲解 Gentelella 的 RTL 架构——你只需在根元素上设置一个dir属性整个模板的布局、间距与对齐规则就会自动镜像读完本文你将掌握运行时切换、逻辑属性对照、无需镜像样式表的实现细节以及如何规避 RTL 开发中常见的陷阱。开启 RTL一行 HTML 属性Gentelella v4 的 RTL 支持建立在一个极简的 API 之上在根元素html上设置dir属性即可。html langar dirrtl设置dirrtl后整个模板——侧边栏、顶部栏、表格、表单、卡片、抽屉、开关控件——的所有布局、间距与对齐规则都会自动翻转。官方文档的表述非常直白Thats 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.jsconst prePaint script(function(){try{var tlocalStorage.getItem(theme);var dwindow.matchMedia((prefers-color-scheme: dark)).matches;var themet||(d?dark:light);document.documentElement.setAttribute(data-theme,theme);var dirlocalStorage.getItem(dir);if(dirrtl||dirltr){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逻辑属性logicalmargin-left/margin-rightmargin-inline-start/margin-inline-endpadding-left/padding-rightpadding-inline-start/padding-inline-endborder-left/border-rightborder-inline-start/border-inline-endleft:/right:inset-inline-start/inset-inline-endtext-align: left/righttext-align: start/endborder-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 cant 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 labelsbackground-position—— 原生的 select 箭头box-shadow偏移量—— 抽屉的边缘阴影沿内联轴指向的 ChevronV 形箭头图标。逐段解读 _rtl.scss 的覆盖规则1. 侧边栏移动端抽屉——从 inline-start 边缘滑入_rtl.scssmedia (max-width: 768px) { [dirrtl] .sidebar { transform: translateX(100%); } [dirrtl] .sidebar.open { transform: translateX(0); } }在移动端≤768px侧边栏变成一个从屏幕边缘滑入的抽屉。LTR 下它从左侧滑入隐藏时translateX(-100%)RTL 下则从右侧滑入因此隐藏状态改为translateX(100%)打开状态归零。2. rail 模式飞出路标——远离 rail 的微调_rtl.scss[dirrtl] 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[dirrtl] .drawer { transform: translateX(-100%); box-shadow: 10px 0 30px rgba(0, 0, 0, 0.12); } [dirrtl] .drawer.open { transform: translateX(0); } [dirrtl] .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[dirrtl] .switch input:checked .track::before, [dirrtl] .toggle.on::after { transform: translateX(-16px); }开关switch和切换toggle的圆形旋钮在轨道内沿内联轴滑动。LTR 下选中状态旋钮右移translateX(16px)RTL 下则左移因此覆盖为translateX(-16px)。5. 原生 select 箭头——background-position 没有逻辑形式_rtl.scss[dirrtl] select.input, [dirrtl] .input select, [dirrtl] select.form-control { background-position: left 10px center; }下拉框的箭头是通过background-position定位的而该属性没有可用的逻辑关键字所以 RTL 下把箭头从右侧挪到左侧left 10px center。6. 侧边栏手风琴 chevron——关闭态沿 inline-end 指向_rtl.scss[dirrtl] .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 isnt mirrored文档明确列出三类不做镜像的内容理解它们可以避免误判为 bug1. 图表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 arent directional。只有沿内联轴指向的 chevron 和箭头会被翻转搜索图标search、垃圾桶图标trash等不具方向性的图标不会被镜像。验证一次改动像素级回归保证RTL 支持迁移有一个硬性验证标准引入逻辑属性后LTR 渲染不得发生任何位移——因为在 LTR 文档中逻辑属性与它们所替代的物理属性计算结果是完全一致的。Gentelella 仓库中的这次转换正是以此为标准进行验证的12 个代表性页面在改动前后分别截图按哈希值hash比较全部像素级一致pixel-identical。这既证明了逻辑属性在 LTR 下与物理属性等价也保证了存量 LTR 用户不会因 RTL 改造而看到任何布局回归。如果你修改了样式可以用同样的思路自检先截 LTR 基线图再验证 RTL 页面在两种方向下都符合预期。仓库自带的冒烟测试脚本 scripts/smoke.mjs 与截图脚本 scripts/screenshots.mjs 可以作为自动化验证的起点。小结主题结论开启方式html langar dirrtl一行属性即完整 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赞分享前端【免费下载链接】gentelellaFree 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 官方 RTLRight to Left从右到左前端UI组件Cycle.js国际化RTL支持实现从右到左语言的响应式布局Cycle.js国际化RTL支持实现从右到左语言的响应式布局 你还在为多语言网站的RTLRight to Left从右到左布局适配烦恼吗当业务扩展到阿前端Web框架Open-Meteo开源天气API架构解析构建企业级气象数据服务平台的技术实现Open Meteo开源天气API架构解析构建企业级气象数据服务平台的技术实现 Open Meteo是一款完全开源的高性能天气数据服务平台为技术团队提供自主后端API网关数据工程上一篇LASP脚本接口完全指南AudioSystem与InputStream类的高级应用下一篇开源项目 routing-controllers 常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考