多語翻牌文字｜免費 React 元件

同一句話在多種語言之間翻牌或垂直滾動切換，可停在指定語言，示範繁中、英文、日文，適合「現在支援多國語言」的公告。

讓一句話在繁中、English、日本語等語言版本之間輪流切換。預設的 roll 模式是舊句往上滾出、新句從下方彈入，容器寬度隨句子長短平滑伸縮——不同語言的長度差很多，這是它跟一般文字輪播最大的差別；flap 模式則是逐字分格翻牌，字數不同時以空白格補齊。設定 settleOn 後會先播完一輪，再停在指定語言，傳 "auto" 則停在使用者的瀏覽器語言，很適合「現在支援多國語言」的公告大標。

把這個效果裝進你的專案

在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。

npx webberui@latest add language-flip-text

還沒有專案，或安裝遇到問題？看快速開始 →

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

切換方式variant

輪播節奏（ms）interval

2000

顯示語言標籤showLabel

自動輪播autoPlay

播完停在settleOn

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

編輯中的呼叫預設屬性

<LanguageFlipText/>

    </div>
  );
}

完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。

安裝

npx webberui@latest add https://webberui.com/r/language-flip-text.json

或在 components.json 設定 registries 後，改用 @webberui/language-flip-text 安裝。

使用

import { LanguageFlipText } from "@/components/ui/language-flip-text";

const phrases = [
  { lang: "zh-Hant", label: "繁中", text: "現在，用你的語言" },
  { lang: "en", label: "English", text: "Now, in your language" },
  { lang: "ja", label: "日本語", text: "いま、あなたの言葉で" },
];

<LanguageFlipText
  phrases={phrases}
  settleOn="auto"
  className="text-3xl font-semibold"
/>

<LanguageFlipText
  variant="flap"
  as="p"
  phrases={[
    { lang: "zh-Hant", label: "繁中", text: "歡迎" },
    { lang: "en", label: "English", text: "Welcome" },
    { lang: "ja", label: "日本語", text: "ようこそ" },
  ]}
/>

Props

Prop	型別	預設值	說明
`phrases`	`LanguageFlipPhrase[]`	—	要輪流顯示的各語言句子
`variant`	`"roll" \| "flap"`	`"roll"`	切換方式：`roll` 垂直滾動（容器寬度平滑伸縮）、`flap` 逐字翻牌
`index`	`number`	—	受控的目前句子索引；未提供時由元件內部管理（非受控）
`defaultIndex`	`number`	`0`	非受控模式的初始索引
`onIndexChange`	`(index: number) => void`	—	句子切換時回呼，參數為新的索引
`autoPlay`	`boolean`	`true`	是否自動輪播
`interval`	`number`	`2000`	自動輪播的間隔（毫秒）
`settleOn`	`string`	—	播完一輪後停在哪個語言：傳 lang（例 `"zh-Hant"`），或 `"auto"` 讀取瀏覽器語言
`loop`	`boolean`	`true`	播到最後一句後是否回到第一句繼續；有 `settleOn` 時忽略
`showLabel`	`boolean`	`true`	是否顯示語言小標籤（膠囊）
`as`	`"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "p" \| "div" \| "span"`	`"h2"`	根元素的標籤
`className`	`string`	—	透傳到根元素

LanguageFlipPhrase

欄位	型別	預設值	說明
`lang`	`string`	—	BCP 47 語言標籤（例 `zh-Hant`、`en`、`ja`），會寫進句子節點的 `lang` 屬性
`label`	`string`	—	語言小標籤上顯示的名稱（例「繁中」「English」）
`text`	`string`	—	這個語言的句子內容

另外具名匯出 matchPhraseLocale(phrases, locale)，回傳最接近該語言的句子索引（找不到回傳 -1）。

CSS 變數

變數	預設值	說明
`--wb-language-flip-duration`	`420ms`	`roll` 容器寬高伸縮與標籤交叉淡接的時長
`--wb-language-flip-flap`	`280ms`	單格翻牌（上下兩半合計）的時長
`--wb-language-flip-stagger`	`30ms`	翻牌由左到右每格的錯開時間

細節

寬度伸縮：roll 模式量測目前句子的實際寬高，直接對容器的 width／height 做補間，而不是用 scale 型的 layout 動畫——文字不會在伸縮途中被壓扁拉長。句子以單行顯示，長句請縮小字級。
翻牌：每格分成上下兩半，上半片向後倒下、下半片從 90° 落回，字數以所有句子中最長的那句為準，不足的位置補空白格；字串以 Array.from 切字，中日韓文字與表情符號都不會被切壞。
停留：settleOn 會等每句都出現過一次後，才在指定語言停下。"auto" 在 useEffect 中讀取 navigator.languages，伺服器端與首次渲染一致；瀏覽器回報 zh-TW／zh-HK 會對應到 zh-Hant，zh-CN 對應到 zh-Hans，都找不到時停回初始那句。
每個句子節點都設定 lang 屬性，讓瀏覽器為中日韓文字選對字型與斷字規則。

可及性

根元素設定 aria-live="off"，自動輪播不會讓螢幕閱讀器一直朗讀；另有一段 sr-only 文字提供目前語言的完整句子，並帶正確的 lang
視覺上的滾動層、翻牌格與語言標籤都對輔助科技隱藏，避免重複朗讀與逐字唸出
滑鼠移入或鍵盤聚焦時暫停自動輪播；自動輪播時根元素可用 Tab 聚焦（帶 focus-visible 外框），聚焦後以方向鍵切換上一句／下一句
使用者系統開啟「減少動態效果」時，不翻牌、不滾動，文字直接切換並以 150ms 淡入

多語翻牌文字

把這個效果裝進你的專案

本頁目錄