RTL 支援 | Quasar 框架

RTL 支援

RTL 指的是為需要從右到左語言的使用者介面。

啟用 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/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"> 標籤 – 您也需要它。

注意事項

Quasar CLI 會自動為您的網站/應用程式碼新增對等的 RTL CSS 規則，但 UMD 並非如此，因為 UMD 沒有使用 Quasar CLI。您必須自行管理編寫網站/應用程式 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 模式。更多資訊請參閱$q 物件。
在編寫自己的 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 規則標記為例外