function Example() { const [lang, setLang] = React.useState("en"); return ( <UI18nLanguageDropdown value={lang} onChange={setLang} // 默认仅 ["en","zh-CN"]，可传入扩展列表 languages={["en","zh-CN","ja-JP"]} // 自动发现（默认 true）；可关闭或自定义路径 autoDiscover discoverPath="/.ui18n/languages.json" placeholder="搜索语言…" className="w-full max-w-sm" /> ); }

自动发现协议

支持两种返回格式：
- ["en","zh-CN","ja-JP"]
- { "languages": ["en","zh-CN","ja-JP"] }
fetch 失败或未发现时自动降级为默认中英

API

组件 UI18nLanguageDropdown
- value?: string 受控值
- defaultValue?: string 非受控初始值（默认 "en"）
- onChange?: (lang: string) => void 变更回调
- languages?: string[] 预置语言（默认 ["en","zh-CN"]）
- autoDiscover?: boolean 是否自动发现（默认 true）
- discoverPath?: string 自动发现路径（默认 "/.ui18n/languages.json"）
- placeholder?: string | (ctx => string) 占位符（默认：系统语言本地化名称 + " - ui18n"）；可传函数以生成
- className?: string 自定义类名
- renderItem?: (lang: string, label: string) => React.ReactNode 自定义项渲染
- showBrandSuffix?: boolean 是否显示品牌后缀（默认 true）
- brandSuffix?: string 品牌后缀字符串（默认 "- ui18n"）
- showSearchBox?: boolean 是否显示内置搜索框（默认 true）
- renderSearchInput?: (props) => React.ReactNode 自定义搜索输入完整渲染
- filter?: (lang, query, meta) => boolean 自定义过滤逻辑
- selectFirstMatchOnEnter?: boolean 回车时若无聚焦项选中首个匹配（默认 true）
- notFoundText?: string | (query => string) 无匹配提示文案（默认“无法找到该语言，请重新输入”）
- debounceMs?: number 输入去抖毫秒数（默认 0）
- 预览（可选，仅开发/演示用）
  - previewText?: string 要预览的一句话（如 "Hello world"）
  - onPreviewRequest?: (args: { text: string; to: string; from?: string }) => Promise
  - previewRender?: (state: { status: 'idle'|'loading'|'success'|'error'; result?: string; error?: unknown }) => React.ReactNode
Hooks/工具（按需引入）
- useLanguageDropdown(options): 提供 headless 状态与 props 构造器
  - 返回：{ status, list, filtered, current, open, query, activeIndex, refs, setOpen, setQuery, setActiveIndex, commitSelect, onKeyDown, getTriggerProps, getSearchInputProps, getListboxProps, getOptionProps }
- useDiscoveredLanguages({ autoDiscover, discoverPath, initial })
- normalizeLocale(lang: string): string
- labelForLang(lang: string): string

预览能力（可选）

默认不显示。仅当同时提供 previewText 与 onPreviewRequest 时，下拉面板底部会出现一行“预览”区块。
组件不会直接请求任何后端；仅调用你提供的 onPreviewRequest 回调。
示例：通过你的后端代理 /api/translate 进行预览（前端不包含密钥）

return ( <UI18nLanguageDropdown value={"en"} onChange={() => {}} previewText="Hello world" onPreviewRequest={preview} /> ); }

样式

默认极简样式（原生元素 + 少量 Tailwind 类）
如果需要更精致的外观，可参考 demo 中的 shadcn 风格示例组件，自行组合 UI 库

可访问性

触发按钮具备 aria-haspopup/expanded/controls
列表使用 role=listbox / option，支持键盘上下/回车/ESC

建议集成方式

词典/翻译来源由你的应用决定（本组件只提供语言入口）
将所选语言与应用状态管理（如 context/store/URL）打通
对大体量词典建议懒加载 + 预取 + 缓存

开源协议

最小集成片段

Vite（React + Vite）

// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(<App />);

// App.tsx
import * as React from "react";
import { UI18nLanguageDropdown } from "@ui18n/selector-react";

export default function App() {
  const [lang, setLang] = React.useState("en");
  return (
    <div style={{ padding: 16 }}>
      <UI18nLanguageDropdown
        value={lang}
        onChange={setLang}
        languages={["en", "zh-CN"]}
        autoDiscover
        discoverPath="/.ui18n/languages.json"
        placeholder="搜索语言…"
      />
    </div>
  );
}

Next.js（App Router）

// app/page.tsx （服务端）
// 推荐在 Client 组件中使用语言下拉
export default function Page() {
  return <ClientHome />;
}

// app/client-home.tsx
"use client";
import * as React from "react";
import { UI18nLanguageDropdown } from "@ui18n/selector-react";

export default function ClientHome() {
  const [lang, setLang] = React.useState("en");
  return (
    <UI18nLanguageDropdown
      value={lang}
      onChange={setLang}
      autoDiscover
      placeholder="搜索语言…"
    />
  );
}

Create React App

// App.tsx
import * as React from "react";
import { UI18nLanguageDropdown } from "@ui18n/selector-react";

function App() {
  const [lang, setLang] = React.useState("en");
  return (
    <UI18nLanguageDropdown
      value={lang}
      onChange={setLang}
      languages={["en", "zh-CN", "ja-JP"]}
    />
  );
}
export default App;

A11y 键盘导航清单

触发区（按钮）
- Enter / Space：打开下拉
- Escape：关闭下拉并聚焦回按钮
- ArrowDown（在触发上）：打开并聚焦首项
列表（role="listbox"）
- ArrowUp / ArrowDown：在选项间移动
- Home / End：跳转到首/尾项
- Enter / Space：选择当前聚焦项
- Escape：关闭下拉
ARIA 语义
- 触发：aria-haspopup="listbox"、aria-expanded、aria-controls
- 列表：role="listbox"；选项：role="option"、aria-selected
- 活跃项：aria-activedescendant（或 roving tabindex）
屏幕阅读器
- 提供可读标签：aria-label 或与可见文本关联
- 状态变化（选择、错误）可用 aria-live（若在预览区块中提示）
焦点可见性
- 明确的 focus 样式（轮廓或阴影），Tab 路径完整、可回退

Keywords

FAQs

What is @ui18n/selector-react?

Is @ui18n/selector-react well maintained?

Package last updated on 07 Sep 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install