Skip to main content

三级联动地区选择器 RegionSelector

RegionSelector 是一个三级联动的省市区选择组件，基于 china-area-data 构建，支持受控和非受控模式，可用于表单选择或自定义展示。

📦 引入方式​

import { RegionSelector } from '@npmqg/react-ui-regionselector';

🧩 使用示例​

📑 组件 API​

组件名描述主要 Props（类型 - 默认值 - 说明）
RegionSelector省市区选择器，支持受控与非受控模式value (Region) - undefined - 当前值
onChange ((val: Region) => void) - () => {} - 选中值变化回调
width (number) - 120 - select 宽度

Ref 方法​

方法名描述
getValue()获取当前选中值
reset()重置选择为初始空值

💄 默认样式​

  • 每个 select 默认圆角（border-radius: 0.5rem）、边框（1px solid #d1d5db）、背景色白色、字体大小 0.875rem。
  • 下拉箭头固定在右侧（▾）。
  • 水平排列，间距 1rem。
  • 可通过 width 自定义宽度。

📌 注意事项​

  • RegionSelector 支持受控和非受控模式：
    • 非受控：内部维护状态，onChange 返回选中结果。
    • 受控：通过 value 传入选中对象，组件会同步显示。
  • onChange 仅在省市区都选择完整时触发。
  • 使用 ref 可调用 getValue() 获取当前值，reset() 重置选择。
  • 值对象结构：
{
  province?: { code: string; name: string };
  city?: { code: string; name: string };
  district?: { code: string; name: string };
}

🧱 依赖项​

  • react
  • china-area-data

如需更复杂的表单集成，可结合 react-hook-form 或 antd Form 使用.