字數統計文字區

中文的「字數」和英文的 word count 不是同一回事：漢字每個字算一字，英文則是連續字母整段算一個 word；送進資料庫或舊系統時，又常以位元組計。這個 textarea 把三種計法放在右下角的切換籤裡，即時顯示「目前數字 / 上限」與一個 SVG 進度環——超過 warnAt 比例轉琥珀色、超限轉紅並抖動一下。注音、假名等輸入法組字期間計數會凍結，不會把組字字母算進去；開啟 hardLimit 時超限即阻止輸入，但會等組字結束才裁切，不會把正在組的字剪成半個。文字值與計數模式各自支援受控／非受控雙模式。

Playground

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

import * as React from "react";

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

<CjkWordCountTextarea/>

    </div>
  );
}

安裝

npx webberui@latest add https://webberui.com/r/cjk-word-count-textarea.json

使用

import { CjkWordCountTextarea } from "@/components/ui/cjk-word-count-textarea";

<CjkWordCountTextarea
  label="貼文內容"
  maxCount={140}
  defaultMode="words"
  autoResize
  onChange={(text, counts) => {
    // counts 同時帶有三種計法的數字
    console.log(counts.words, counts.chars, counts.bytes);
  }}
/>

Props

CjkCounts

CountCjkOptions

CjkWordCountLabels

另外具名匯出 countCjk(text, mode, opts) 與 clampCjk(text, max, mode, opts)，方便在表單驗證或伺服器端用同一套規則計數與裁切；兩者都是純函式，不依賴瀏覽器 API。

細節

• words 計法：漢字（含日文假名、韓文字）每個字元算一字；英文字母、數字等連續序列以空白或 CJK 字元斷詞，整段算一個 word；全形標點預設不計，countPunctuation: true 時逐個計入。例如「我買了 3 本 React 書」算 7。
• chars 計法以 Unicode code point 計（Array.from），emoji 等 surrogate pair 不會被拆成兩個字元。
• bytes 計法預設是 UTF-8 長度（漢字多為 3 bytes）；台灣不少舊系統以 Big5 計（漢字 2 bytes），傳 countOptions={{ bytesPerCjk: 2 }} 即可折算。
• 硬性上限用二分搜尋找出最長合法前綴：計數對前綴長度單調遞增，因此不必逐字重算。
• autoResize 先把高度歸零再讀 scrollHeight，內容變少時高度也縮得回來。

可及性

• label 以 htmlFor 關聯至 textarea；未提供 label 時以 placeholder 作為 aria-label
• 計數文字透過 aria-describedby 關聯至 textarea；超限時設定 aria-invalid
• 模式切換是 role="radiogroup"，每個籤為 role="radio" 並帶 aria-checked，採 roving tabindex，方向鍵可循環切換，具 focus-visible 外框
• 警示宣告位於 role="status"、aria-live="polite" 區域，只在跨越 warnAt 或超限的瞬間宣告一次，避免每個按鍵都播報；進度環與警示圖示對輔助科技隱藏
• 使用者系統開啟「減少動態效果」時，停用超限抖動與模式籤滑動動畫，狀態直接切換