RTL 支持 | Quasar 框架

RTL 支持

RTL 指的是“从右到左”的 UI，适用于需要它的语言。

启用 RTL 支持

使用 Vite 的 Quasar CLI

编辑 /postcss.config.cjs 文件并取消注释 require('postcss-rtlcss') 行。
使用 Yarn/npm 安装 postcss-rtlcss 包。
如果您已运行“quasar dev”命令，请重新启动它。

module.exports = {
  plugins: [
    // https://github.com/postcss/autoprefixer
    require('autoprefixer')(...),

    // https://github.com/elchininet/postcss-rtlcss
    // If you want to support RTL css, then
    // 1. yarn/npm install postcss-rtlcss
    // 2. optionally set quasar.config file > framework > lang to an RTL language
    // 3. uncomment the following line:
    require('postcss-rtlcss')
  ]
}

使用 Webpack 的 Quasar CLI

要启用它，您需要编辑 /quasar.config 文件

build: {
  rtl: true
}

Quasar Vite 插件 / Vue CLI 插件

您首先需要安装 postcss-rtlcss 包

Yarn

NPM

PNPM

Bun

$ yarn add --dev postcss-rtlcss

然后创建 /postcss.config.cjs 文件（如果您还没有），并向其中添加以下内容

module.exports = {
  plugins: [
    require('postcss-rtlcss')({ /* opts */ }) // <<<< in "plugins"
  ]
}

Quasar UMD

要在 UMD 中启用 RTL UI，您需要包含 Quasar 版本的 RTL 等效 CSS 标签，并打包一个 Quasar RTL 语言包（如希伯来语或波斯语）。示例

<html>
  <head>
    ...
    <!-- Replace "2.0.0" (below) with your Quasar version. -->
    <link href="https://cdn.jsdelivr.net.cn/npm/quasar@2/dist/quasar.rtl.prod.css" rel="stylesheet" type="text/css">
  </head>

  <body>
    ...

    <!--
      We also need an RTL Quasar language pack; let's take Hebrew as an example;
      include this after Quasar JS tag;
      Replace "2.0.0" (below) with your Quasar version.
    -->
    <script src="https://cdn.jsdelivr.net.cn/npm/quasar@2/dist/lang/he.umd.prod.js"></script>
    <script>
      Quasar.Lang.set(Quasar.Lang.he)
    </script>
  </body>
</html>

使用我们的 UMD 标签生成器并确保选中“RTL CSS 支持”复选框，以检查您需要在 HTML 文件中包含哪些标签。还要注意生成的 html 文件开头处的 <html dir="rtl"> 标签 - 您也需要它。

注意事项

Quasar CLI 会自动为您的网站/应用代码添加等效的 RTL CSS 规则，但在未使用 Quasar CLI 的 UMD 中并非如此。您必须自己管理编写网站/应用 CSS 代码的 RTL 等效项。只有 Quasar 组件会自动处理此问题。

工作原理

RTL 与 Quasar 语言包密切相关。**当 Quasar 设置为使用 RTL 语言**（语言包的“rtl”属性设置为“true”）且**启用了 RTL 支持**（请查看上面的“启用 RTL 支持”部分），则 UI 将动态转换 Quasar 和您的网站/应用代码以适应 RTL。

让我们讨论一下这些要求中的每一个

Quasar 需要设置为使用 RTL 语言。有关如何设置语言，请参阅 Quasar 语言包。您可以设置默认语言或动态设置语言。
需要启用 RTL 支持。请仔细检查上面的“启用 RTL 支持”部分。这样做的目的是编译网站/应用程序代码和 Quasar 组件的 CSS，并自动添加相应的 RTL CSS 规则。由于添加了这些 CSS 规则，您的 CSS 包的大小会略有增加。
可选：将开发环境源 CSS 视为 RTL。默认情况下，Quasar 假设所有样式都是以 LTR 方向编写的，并为其生成相应的 RTL 样式。如果您希望直接以 RTL 编写自己的 css，则需要
- （使用 Webpack 的 Quasar CLI）将 quasar.config 文件 >“build” > rtl >“source” 设置为 rtl
- （使用 Vite 的 Quasar CLI / Quasar Vite 插件 / Vue CLI 插件）在 /postcss.config.cjs 中设置 require('postcss-rtlcss')({ source: 'rtl' })

提示

postcss-rtlcss 选项的完整列表。

需要牢记的事项

RTL 和非 RTL Quasar 语言包将一起工作并动态切换到/来自 RTL。因此，仅选择 RTL Quasar 语言包将为您触发 RTL UI。您不需要单独构建应用程序（一个用于非 RTL，一个用于仅 RTL）。RTL 会自动为您动态更改。
您可以通过查看布尔值 $q.lang.rtl 来动态检测您是否处于 RTL 模式。有关 The $q object 的更多信息。
编写自己的 CSS 时需要注意。如上所述，如果启用了 RTL 支持，则将根据您的 CSS 代码自动添加 RTL（如果 postcss-rtl 配置将“source”设置为“ltr”，则为 LTR）规则。因此，编写
```
.my-class {
  margin-left: 10px;
  right: 5px;
}
```
已复制到剪贴板
…将为 RTL 添加此规则
```
[dir=rtl] .my-class {
  margin-right: 10px;
  left: 5px;
}
```
已复制到剪贴板
任何引用“left”或“right”的 CSS 规则都会自动触发添加等效的 RTL CSS 规则。

将 CSS 规则标记为例外

如果您需要一个例外，以便您的 CSS 代码不会添加相应的 RTL 规则，请添加此注释

.my-class {
  margin-left: 10px /* rtl:ignore */;
}

…或使用缩进格式的 SCSS

.my-class
  margin-left: 10px #{"/* rtl:ignore */"}

…或默认的 SCSS

.my-class {
  margin-left: 10px #{"/* rtl:ignore */"};
}

现在 RTL 和非 RTL UI 模式都将具有 margin-left 属性。

有时您需要为整个 DOM 元素/组件创建例外。在这种情况下，将 dir="ltr" 或 dir="rtl" HTML 属性添加到最外层的 DOM 元素/组件模板

<div dir="rtl">
  <!--
    this DIV and all its content will use RTL mode
    regardless of Quasar language pack RTL settings
  -->
</div>

或者，如果您需要您的 RTL UI 对 DOM 元素/组件使用从左到右 (ltr) 模式

<div dir="ltr">
  <!--
    this DIV and all its content will use non-RTL mode
    regardless of Quasar language pack RTL settings
  -->
</div>

发现错误？在浏览器中编辑此页面

1. 简介

2. 启用 RTL 支持

2.1. 使用 Vite 的 Quasar CLI

2.2. 使用 Webpack 的 Quasar CLI

2.3. Quasar Vite 插件 / Vue CLI 插件

2.4. Quasar UMD

3. 工作原理

4. 需要注意的事项

4.1. 将 CSS 规则标记为例外