@ 国家状态/ 国家浏览器

有jsDelivr CDN和懒惰加载的浏览器本地国家、州和城市数据。 与服务器软件包相同的API——在React,Vue,Svelte,Vite,以及任何浏览器环境中工作.

环境: 🌐 浏览器本地 (反应, Vue, Svelte, Vite, 以及任何浏览器环境)

升级到 3. 0

此版本使用 v5.2.0-出口。审查 上游 v5 迁移说明 在更新所储存的身份证之前:一些记录被退役或被修复。 城市状态链接现在可以无效 。 全国城市装载机包括这些记录。 保留供应 NOTICE-*.txt 带有重新分配数据的文件。 见 软件包迁移指南。 。 。 .

较早的移徙: 2.0.0

现在的数据来自上游 v 4.0出口.50. v3.2 → v 4.0 过渡取消了4,486个城市标识(重复,美国各县迁移到一个单独的县数据集,不设地),将7,527个城市重新分配到不同的州,在退休时又增加了27个州. 存储的ID和每个州的结果都可以改变;美国县不再作为城市返回. 后来的导出更正包含在本快照中.

在升级存储的城市/州编号之前, 使用 removed_ids_v3.2_to_v4.0.csv 页:1 上游 v 4.0 释放它确定了合并的身份证及其幸存者、迁移到新身份证的县以及退休的州及其继任者。 符合 record, (中文(简体) ), outcome,以及 new_table 使用前的列 new_id;一个县ID不是城市ID. 根据这个快照刷新存储的州协会 .

城市 type 使用标准术语(municipality, (中文(简体) ), city, (中文(简体) ), town, (中文(简体) ), village, (中文(简体) ), locality, (中文(简体) ), section对于移徙国家;其他国家可以保留较早的用语,例如: adm1编号 :adm2。本套件有意对上游领域进行子集项目: type_local, (中文(简体) ), county_id, (中文(简体) ), level,以及 parent_id 在城市/州记录中省略,不运出县数据集。 城市翻译为空对象;包含国家翻译. 当您需要正式的本地术语、 县级链接或分级时, 使用上游出口 .

* 特性

• 🌍 完整数据:250+国家,5 000+州,15万+城市
• 🌐 浏览器- Native: 通过获取和jsDelivr CDN在任何浏览器中直接运行
• 🚀 最小套装: < 10KB 初始负载, 懒散地装入其他所有负载
• 🔄 懒惰装入: 点取——只装入所需
• 🌐 翻译: 支持18+语言
• ⏰ 时区数据: 每个地点的全时区信息
• 📝 类型脚本: 包括完整类型定义
• 🔧 可配置: 可选的 CDN 覆盖和缓存调试

* 安装

npm install @countrystatecity/countries-browser
# or
yarn add @countrystatecity/countries-browser
# or
pnpm add @countrystatecity/countries-browser

QQ 快速启动

import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

// Load all countries (~30KB gzipped)
const countries = await getCountries();
console.log(countries[0]);
// { id: 1, name: "United States", iso2: "US", emoji: "🇺🇸", ... }

// Load states for a country (on-demand)
const states = await getStatesOfCountry('US');
console.log(states[0]);
// { id: 1, name: "California", iso2: "CA", ... }

// Load cities for a state (on-demand)
const cities = await getCitiesOfState('US', 'CA');
console.log(cities[0]);
// { id: 1, name: "Los Angeles", latitude: "34.05", ... }

本地包还是活的API?

这个软件包免费地传送了CDN托管的数据快照——当应用程序必须首先下线工作时,这仍然是正确的选择,一个周期快照就足够了,或者你只需要简单的看/倒.

这个 国家 API 当您需要时, 值得同时加入:

• 新鲜度 ——不发布新包版本而更新的数据.
• 搜索 模糊、耐打字、服务器侧搜索(csc.search.fuzzy(...)),而不只是精确匹配的本地外观.
• 缩放支持( S) ——可配置的速率限制和超过捆绑快照的支持.

每月有3 000个请求免费开始. 比较计划 或者说 获取 API 密钥。 。 。 .

npm install @countrystatecity/sdk

// Before
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

const countries = await getCountries();
const states = await getStatesOfCountry('US');
const cities = await getCitiesOfState('US', 'CA');

// After
import { createCSCClient } from '@countrystatecity/sdk';

const csc = createCSCClient({ apiKey: process.env.CSC_API_KEY! });

const { data: countries } = await csc.countries.list();
const { data: states } = await csc.states.list({ country: 'US' });
const { data: cities } = await csc.cities.list({ country: 'US', state: 'CA' });

见 完整移徙指南 用于错误处理、重试等等.

API 参考

核心职能

getCountries()

获得所有国家的轻量级列表(仅基本信息).

• 回返情况: Promise<ICountry[]>

getCountryByCode(code: string)

获得完整的国家元数据,包括时区和翻译.

• 参数: code - ISO2代码(例如“美国”)
• 回返情况: Promise<ICountryMeta | null>

getStatesOfCountry(countryCode: string)

为一国取出一切州/道.

• 参数: countryCode - ISO2 代码
• 回返情况: Promise<IState[]>

getStateByCode(countryCode: string, stateCode: string)

获取具体状态细节.

• 参数: countryCode, (中文(简体) ), stateCode
• 回返情况: Promise<IState | null>

getCitiesOfState(countryCode: string, stateCode: string)

将所有城市都控制在特定状态.

• 参数: countryCode, (中文(简体) ), stateCode
• 回返情况: Promise<ICity[]>

getCityById(countryCode: string, stateCode: string, cityId: number)

以数字标识获取特定城市.

• 参数: countryCode, (中文(简体) ), stateCode, (中文(简体) ), cityId
• 回返情况: Promise<ICity | null>

getAllCitiesOfCountry(countryCode: string)

把全国的城市都找来.

• 警告: 较大数据大小, 少用
• 回返情况: Promise<ICity[]>

getAllCitiesInWorld()

遍及全球.

• 警告: MASSIVE数据(8MB+),极少需要
• 回返情况: Promise<ICity[]>

getRegions()

获取所有地区(大陆)列表.

• 回返情况: Promise<IRegion[]>

getSubregions()

获取所有分区列表 .

• 回返情况: Promise<ISubregion[]>

工具函数

isValidCountryCode(code: string)

检查国家代码是否存在 .

• 回返情况: Promise<boolean>

isValidStateCode(countryCode: string, stateCode: string)

检查一个国家是否存在国家代码 .

• 回返情况: Promise<boolean>

searchCitiesByName(countryCode: string, stateCode: string, term: string)

以部分名称匹配搜索城市.

• 回返情况: Promise<ICity[]>

getCountryNameByCode(code: string)

从代码中获取国名.

• 回返情况: Promise<string | null>

getStateNameByCode(countryCode: string, stateCode: string)

从代码中获取州名.

• 回返情况: Promise<string | null>

getTimezoneForCity(countryCode: string, stateCode: string, cityName: string)

获取特定城市的时区.

• 回返情况: Promise<string | null>

getCountryTimezones(countryCode: string)

得到所有的时间区 一个国家.

• 回返情况: Promise<string[]>

getSubregionsOfRegion(regionId: number)

把属于某个区域的所有次区域都弄来.

• 回返情况: Promise<ISubregion[]>

getCountriesByRegion(region: string | number)

将区域内的所有国家按名称排列(如对案件不敏感). 'Europe')或区域身份证.

• 回返情况: Promise<ICountry[]>

getCountriesBySubregion(subregion: string | number)

将分区域的所有国家按名称排列(对案件不敏感,例如:. 'South America'或次区域身份证.

• 回返情况: Promise<ICountry[]>

配置

import { configure, resetConfiguration, clearCache } from '@countrystatecity/countries-browser';

// Self-host data instead of jsDelivr
configure({
  baseURL: 'https://my-cdn.com/data',
  timeout: 10000,
  cacheSize: 100,
});

// Reset to defaults
resetConfiguration();

// Clear in-memory cache
clearCache();

反应示例

import { useState, useEffect } from 'react';
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';
import type { ICountry, IState, ICity } from '@countrystatecity/countries-browser';

export function LocationSelector() {
  const [countries, setCountries] = useState<ICountry[]>([]);
  const [states, setStates] = useState<IState[]>([]);
  const [cities, setCities] = useState<ICity[]>([]);
  const [selectedCountry, setSelectedCountry] = useState('');
  const [selectedState, setSelectedState] = useState('');

  useEffect(() => {
    getCountries().then(setCountries);
  }, []);

  useEffect(() => {
    if (!selectedCountry) { setStates([]); return; }
    getStatesOfCountry(selectedCountry).then(setStates);
  }, [selectedCountry]);

  useEffect(() => {
    if (!selectedCountry || !selectedState) { setCities([]); return; }
    getCitiesOfState(selectedCountry, selectedState).then(setCities);
  }, [selectedCountry, selectedState]);

  return (
    <div>
      <select value={selectedCountry} onChange={(e) => { setSelectedCountry(e.target.value); setSelectedState(''); }}>
        <option value="">Select Country</option>
        {countries.map(c => <option key={c.iso2} value={c.iso2}>{c.name}</option>)}
      </select>
      <select value={selectedState} onChange={(e) => setSelectedState(e.target.value)} disabled={!selectedCountry}>
        <option value="">Select State</option>
        {states.map(s => <option key={s.iso2} value={s.iso2}>{s.name}</option>)}
      </select>
      <select disabled={!selectedState}>
        <option value="">Select City</option>
        {cities.map(c => <option key={c.id} value={c.id}>{c.name}</option>)}
      </select>
    </div>
  );
}

处理错误

import { getCountries, NetworkError } from '@countrystatecity/countries-browser';

try {
  const countries = await getCountries();
} catch (error) {
  if (error instanceof NetworkError) {
    console.error(`CDN request failed: ${error.statusCode} at ${error.url}`);
  }
}

无效的代码返回 null 或者说 [] 优雅地——无一例外.

QQ 类型脚本

import type { ICountry, ICountryMeta, IState, ICity, IRegion, ISubregion, ITimezone } from '@countrystatecity/countries-browser';

QQ 套装大小

服务器与浏览器比较

测试

# Run all tests
npm test

# Watch mode
npm run test:watch

所有软件包包括全面测试:

• 单位测试
• 综合测试
• iOS/Safari兼容性测试

++CI/CD和自动化

持续整合

每一次推和公关自动:

• QQ 运行类型检查
• * 执行全面测试
• QQ 构建软件包
• 校验捆绑大小
• iOS/Safari 兼容性测试

自动出版

自动向国家预防机制发布版本变化:

• QQ 检测软件包中的版本出错. json
• 发布前的构建和测试
• 国家防范机制登记册出版物
• QQ 创建带有更改日志的 GitHub 发布

许可证

ODbL-1.0. 导弹 © 驱动器5hn

此软件包及其数据由开放数据库许可证(ODbL)v1.0许可. 数据来源于 国家城市数据库 也根据ODbL-1.0获得许可证.

您可以自由分享,创建,并修改这个数据库,只要您将原始源属性化,在同一许可证下发布修改,并且不要使用技术限制来锁定数据.

捐款

欢迎捐款! 请打开一个问题或公关.

数据相关问题 (不正确的国名、缺失的城市、错误的坐标等) 国家城市数据库 寄存器,是此软件包的数据源.

成套生态系统

此软件包是 @ 国家状态包生态系统数字 :

• @ 国家/ 国家 ——服务器侧国家,州和城市数据库. 环境:Node.js, Next.js API路线,快通. Bundle: <10KB初始负载.

• @ 国家状态/ 国家浏览器 (本套件)-浏览器-内置版本有jsDelivr CDN并懒惰地加载. 环境:React,Vue,Svelte,Vite,任意浏览器. 与服务器包相同的API——零配置,只是导入和使用.

• @ 国家状态/ 时区 - 具有转换功能的综合时区数据。 环境:只有服务器侧. Bundle: <20KB初始负载.

链接

• GitHub 仓库
• 问题
• 国家防范机制一揽子计划
• 国家预防机制组织