RTL 支持 | Quasar 中文网

RTL 支持

RTL 指的是针对需要它的语言的 “从右到左” UI。

¥RTL is referring to “right to left” UI for languages that need it.

启用 RTL 支持(Enabling RTL support)

¥Enabling RTL support

Quasar CLI 与 Vite 结合使用(Quasar CLI with Vite)

¥Quasar CLI with Vite

编辑 /postcss.config.js 文件并取消注释 import rtlcss from 'postcss-rtlcss' 行。
¥Edit /postcss.config.js file and uncomment the import rtlcss from 'postcss-rtlcss' line.
Yarn/npm/pnpm/bun 安装 postcss-rtlcss 包。
¥Yarn/npm/pnpm/bun install the postcss-rtlcss package.
如果你已在运行 “quasar dev” 命令，请重新启动它。
¥If you are already running “quasar dev” command, restart it.

import autoprefixer from 'autoprefixer'
import rtlcss from 'postcss-rtlcss'

export default {
  plugins: [
    // https://github.com/postcss/autoprefixer
    autoprefixer({
      overrideBrowserslist: [
        'last 4 Chrome versions',
        'last 4 Firefox versions',
        'last 4 Edge versions',
        'last 4 Safari versions',
        'last 4 Android versions',
        'last 4 ChromeAndroid versions',
        'last 4 FirefoxAndroid versions',
        'last 4 iOS versions'
      ]
    }),

    // https://github.com/elchininet/postcss-rtlcss
    // If you want to support RTL css, then
    // 1. yarn/pnpm/bun/npm install postcss-rtlcss
    // 2. optionally set quasar.config.js > framework > lang to an RTL language
    // 3. uncomment the following line (and its import statement above):
    rtlcss()
  ]
}

Quasar CLI 与 Webpack 结合使用(Quasar CLI with Webpack)

¥Quasar CLI with Webpack

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

¥To enable it, you need to edit the /quasar.config file:

build: {
  rtl: true
}

Vite 插件(Vite Plugin)

¥Vite Plugin

你首先需要安装 postcss-rtlcss 软件包：

¥You first need to install postcss-rtlcss package:

Yarn

NPM

PNPM

Bun

$ yarn add --dev postcss-rtlcss

如果你还没有 /postcss.config.js 文件，请创建一个，并在其中添加以下内容：

¥Then create /postcss.config.js file if you don’t have it already, and add this to it:

import rtlcss from 'postcss-rtlcss'

export default {
  plugins: [
    rtlcss({ /* opts */ }) // <<<< in "plugins"
  ]
}

Quasar UMD(Quasar UMD)

要在 UMD 中启用 RTL UI，你需要为你的 Quasar 版本添加与 RTL 等效的 CSS 标签，并安装 Quasar RTL 语言包（例如希伯来语或波斯语）。示例：

¥To enable RTL UIs in UMD you need to include the RTL equivalent CSS tag for your Quasar version and also pack in a Quasar RTL language pack (like Hebrew or Farsi). Example:

<html>
  <head>
    ...
    <!-- Replace "2.0.0" (below) with your Quasar version. -->
    <link href="https://cdn.jsdelivr.net/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/npm/quasar@2/dist/lang/he.umd.prod.js"></script>
    <script>
      Quasar.Lang.set(Quasar.Lang.he)
    </script>
  </body>
</html>

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

¥Check what tags you need to include in your HTML files by using our UMD tag generator and making sure that you tick the “RTL CSS support” checkbox. Also notice the <html dir="rtl"> tag at the beginning of the generated html file – you’ll need that too.

CAVEAT

Quasar CLI 会自动为你的网站/应用代码添加等效的 RTL CSS 规则，但对于未使用 Quasar CLI 的 UMD 版本，情况并非如此。你必须自己编写与你的网站/应用 CSS 代码等效的 RTL 代码。只有 Quasar 组件才会自动处理此问题。

¥Quasar CLI automatically adds equivalent RTL CSS rules for your website/app code, but this is not the case for UMD where Quasar CLI is not being used. You’ll have to manage writing the RTL equivalent of your website/app CSS code by yourself. It’s only Quasar components that will have this handled automatically.

工作原理(How it works)

¥How it works

RTL 与 Quasar 语言包紧密耦合。当 Quasar 设置为使用 RTL 语言（语言包将 “rtl” 属性设置为 “true”）并且启用了 RTL 支持（查看上面的 “启用 RTL 支持” 部分）时，UI 将动态转换 Quasar 和你的网站/应用代码以适应 RTL。

¥RTL is tightly coupled to Quasar Language Packs. When Quasar is set to use an RTL language (language pack has “rtl” prop set to “true”) and RTL support is enabled (check the “Enabling RTL support” section above), then the UI will dynamically transform Quasar & your website/app code for RTL.

让我们讨论一下每个要求：

¥Let’s discuss about each of these requirements:

Quasar 需要设置为使用 RTL 语言。有关如何设置语言，请参阅 Quasar 语言包。你可以将语言设置为默认语言，也可以动态设置语言。
¥Quasar needs to be set to use an RTL language. See Quasar Language Packs on how you can set a language. You can set a language as default or dynamically set one.
需要启用 RTL 支持。请仔细检查上面的 “启用 RTL 支持” 部分。它的作用是，它会为你的网站/应用代码和 Quasar 组件编译 CSS，并自动添加相应的 RTL CSS 规则。由于添加了这些 CSS 规则，你的 CSS 包大小会略有增加。
¥RTL support needs to be enabled. Please double-check the “Enabling RTL support” section above. What this does is it compiles CSS for both your website/app code and for Quasar components and add corresponding RTL CSS rules automatically. Your CSS bundle will slightly increase in size due to the addition of these CSS rules.
可选：将 devland 源 CSS 视为 RTL。默认情况下，Quasar 假定所有样式均按从左到右方向编写，并为其生成相应的从右到左样式。如果你希望直接在 RTL 中编写自己的 CSS，那么你需要：
¥Optional: Treat devland source CSS as RTL. By default, Quasar assumes that all styles are written in LTR direction and generates corresponding RTL styles for them. Should you wish to write your own css directly in RTL then you need to:
- （Quasar CLI 与 Webpack）设置 quasar.config 文件 > “build” > rtl > “source” 至 rtl
  ¥(Quasar CLI with Webpack) set quasar.config file > “build” > rtl > “source” to rtl
- （Quasar CLI 与 Vite / Quasar Vite 插件）在 /postcss.config.js 中设置 postcssRtlCss({ source: 'rtl' })
  ¥(Quasar CLI with Vite / Quasar Vite plugin) set postcssRtlCss({ source: 'rtl' }) in /postcss.config.js

提示

postcss-rtlcss 选项的完整列表。

¥Full list of postcss-rtlcss options.

注意事项(Things to keep in mind)

¥Things to keep in mind

Quasar RTL 和非 RTL 语言包将协同工作，并动态地在 RTL 和 RTL 之间切换。因此，只有选择 RTL Quasar 语言包才能为你触发 RTL UI。你不需要单独构建应用（一个用于非 RTL 版本，一个用于仅 RTL 版本）。RTL 会自动为你动态更改。
¥Both RTL and non-RTL Quasar language packs will work together and dynamically switch to/from RTL. So only choosing an RTL Quasar language pack will trigger the RTL UI for you. You don’t need separate builds of your app (one for non-RTL and one for RTL-only). The RTL is dynamically changed for you automatically.
你可以通过查看布尔值 $q.lang.rtl 来动态检测你是否处于 RTL 模式。更多关于 $q 对象的信息。
¥You can dynamically detect if you are on RTL mode by taking a look at Boolean $q.lang.rtl. More info on The $q object.
编写自己的 CSS 时需要小心谨慎。如上所述，如果启用了 RTL 支持，则将根据你的 CSS 代码自动添加 RTL（如果 postcss-rtl 配置将 “source” 设置为 “ltr”，则为 LTR）规则。因此写法：
¥You need to be careful when writing your own CSS. Like mentioned above, if RTL support is enabled then RTL (LTR if postcss-rtl config has “source” set to “ltr”) rules will be automatically added based on your CSS code. So writing:
```
.my-class {
  margin-left: 10px;
  right: 5px;
}
```
Copied to clipboard
…将为 RTL 添加此规则：
¥…will add this rule for RTL:
```
[dir=rtl] .my-class {
  margin-right: 10px;
  left: 5px;
}
```
Copied to clipboard
任何引用 “left” 或 “right” 的 CSS 规则都会自动触发添加等效的 RTL CSS 规则。
¥Any CSS rule that refers to “left” or “right” is automatically triggering an equivalent RTL CSS rule to be added.

将 CSS 规则标记为例外(Marking CSS rules as exceptions)

¥Marking CSS rules as exceptions

如果你需要一个例外，以便你的 CSS 代码不会添加相应的 RTL 规则，那么请添加以下注释：

¥If you need an exception so your CSS code will not add a corresponding RTL rule, then add this comment:

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

…或缩进形式的 SCSS：

¥…or SCSS with indented form:

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

…或默认 SCSS：

¥…or default SCSS:

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

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

¥Now both RTL and non-RTL UI mode will have margin-left prop.

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

¥Sometimes you’ll need to make exceptions for whole DOM elements / components. In this case, add dir="ltr" or dir="rtl" HTML attribute to the outermost DOM element / component template:

<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) 模式：

¥Or, if you need your RTL UI to use left-to-right (ltr) mode for a DOM element / component:

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

1. Introduction

2. 启用 RTL 支持(Enabling RTL support)

2.1. Quasar CLI 与 Vite 结合使用(Quasar CLI with Vite)

2.2. Quasar CLI 与 Webpack 结合使用(Quasar CLI with Webpack)

2.3. Vite 插件(Vite Plugin)

2.4. Quasar UMD(Quasar UMD)

3. 工作原理(How it works)

4. 注意事项(Things to keep in mind)

4.1. 将 CSS 规则标记为例外(Marking CSS rules as exceptions)