地理位置搜索 SDK

该 SDK 提供了一套统一的地理位置（国家、地区、城市、港口、机场、码头等）搜索与查询能力，支持 axios/fetch 双请求适配器、多语言适配、动态配置管理，可快速集成到各类前端项目中。

特性

• 🗺️ 覆盖多类型地理实体：国家/地区、省份、城市、港口、机场、码头等
• 🔌 双请求适配器：支持 Axios / Fetch 两种请求方式
• 🌐 多语言适配：自动识别中英文环境，生成对应展示文本
• ⚙️ 动态配置：支持运行时修改请求地址，适配多环境（开发/测试/生产）
• 📦 类型完备：基于 TypeScript 开发，提供完整的类型定义
• 🚀 事件总线：内置全局模态框事件通信能力

安装

npm

npm install @jctrans-materials/shared --save

yarn

yarn add @jctrans-materials/shared

pnpm

pnpm add @jctrans-materials/shared

快速开始

1. 初始化配置（可选）

默认使用测试环境地址，可在项目入口处初始化自定义配置：

import { initSharedConfig } from "@jctrans-materials/shared";

// 初始化自定义配置
initSharedConfig({
  prefixPath: "https://api-production.jctrans.com", // 生产环境域名
  searchPath: "/system/dms/fr/aggr/getLocationOptions", // 接口路径
});

2. 切换请求适配器（可选）

默认使用 Axios 适配器，可切换为 Fetch：

import { createRequest } from "@jctrans-materials/shared";

// 切换为 Fetch 适配器
createRequest("fetch", {
  fetch: window.fetch, // 可传入自定义 fetch 实现（如 node-fetch）
});

3. 基础使用示例

搜索国家

import { searchCountryByName } from "@jctrans-materials/shared";

// 搜索名称包含"中国"的国家
const result = await searchCountryByName("中国", {
  page: 1,
  size: 10,
});
console.log(result.records); // 归一化后的国家列表

按ID查询城市

import { getById } from "@jctrans-materials/shared";

// 查询 ID 为 1001 的城市
const city = await getById("City", 1001);
console.log(city); // 城市详情

获取指定国家下的所有城市

import { getCitiesByCountry } from "@jctrans-materials/shared";

// 获取国家 ID 为 1 的所有城市
const cities = await getCitiesByCountry(1, {
  page: 1,
  size: 100,
});
console.log(cities.records);

使用 V2 版本接口（推荐）

import { locationSearchV2 } from "@jctrans-materials/shared";

// 搜索港口
const seaports = await locationSearchV2.seaport.searchByName({
  keyword: "上海",
  countryId: 1,
  current: 1,
  size: 10,
});
console.log(seaports.records);

核心 API 文档

配置管理

| 方法 | 说明 | 类型 | | ------------------ | ---------------------- | -------------------------------------------- | | initSharedConfig | 初始化全局配置 | (newConfig: Partial<SharedConfig>) => void | | getSharedConfig | 获取当前配置 | () => { basePath: string } | | getIsEn | 判断当前是否为英文环境 | () => boolean |

基础搜索（baseSearch）

| 方法 | 说明 | | --------------------- | ---------------------------------- | | search | 通用搜索接口（支持多条件、多类型） | | searchByName | 按名称搜索指定类型地理实体 | | getByIds | 按类型+ID批量查询 | | getById | 按类型+单个ID查询 | | getCitiesByCountry | 获取指定国家下的所有城市 | | getChildrenByCity | 获取指定城市下的港口/机场 | | searchCountryByName | 按名称搜索国家 | | searchCityByName | 按名称搜索城市（支持国家筛选） | | searchSeaportByName | 按名称搜索港口（支持城市筛选） | | searchAirportByName | 按名称搜索机场（支持城市筛选） |

V2 版本搜索（searchV2）

locationSearchV2 提供更语义化的接口封装：

| 子模块 | 方法 | 说明 | | --------- | ---------------------------------------------- | -------------------------- | | country | searchByName/getByIds | 国家搜索/批量查询 | | region | searchByName/getByIds | 地区搜索/批量查询 | | city | searchByName/getByIds/getCitiesByCountry | 城市搜索/查询/按国家筛选 | | seaport | searchByName/getByIds | 港口搜索/批量查询 | | airport | searchByName/getByIds | 机场搜索/批量查询 | | wharf | getByIds | 码头批量查询 | | - | searchByIdWithType | 按类型+ID查询任意地理实体 | | - | getChildrenByCity | 获取城市下的港口/机场/码头 |

请求适配器

| 方法 | 说明 | | --------------- | ---------------------------------- | | createRequest | 创建/切换请求适配器（axios/fetch） | | request | 全局请求实例（get/post方法） |

事件总线

用于全局模态框交互：

import { emitter, MODAL_ACTION } from "@jctrans-materials/shared";

// 监听模态框打开事件
emitter.on(MODAL_ACTION.Open, () => {
  console.log("模态框已打开");
});

// 触发模态框关闭事件
emitter.emit(MODAL_ACTION.Close);

关键类型定义

地理实体类型

// baseSearch 支持的类型
type DisplayInfo =
  | "Continent"
  | "Country"
  | "Province"
  | "City"
  | "Seaport"
  | "Airport";

// searchV2 支持的类型（扩展）
type LocationType = DisplayInfo | "Region" | "Street" | "Town" | "Wharf";

归一化实体结构

interface UnifiedItem {
  id: number | string; // 实体ID
  type: DisplayInfo; // 实体类型
  nameCn?: string; // 中文名称
  nameEn?: string; // 英文名称
  display?: string; // 适配当前语言的展示文本
  continent?: Record<string, any>; // 所属大洲
  country?: Record<string, any>; // 所属国家
  city?: Record<string, any>; // 所属城市
  province?: Record<string, any>; // 所属省份
  raw?: any; // 原始后端数据
}

请求配置

interface RequestConfig {
  params?: Record<string, any>; // URL参数
  headers?: Record<string, string>; // 请求头
}

注意事项

1. 接口默认分页：current=1（页码）、size=10（每页条数）
2. 多语言判断优先级：Nuxt Cookie > 浏览器 Cookie > Nuxt SSR 上下文
3. 实体展示文本规则：
   • 港口/机场：名称 (城市, 国家)
   • 城市/省份：名称 (国家)
   • 国家：名称 (大洲)
4. 请求超时时间（Axios）：默认 15000ms
5. 重复数据：SDK 内部会自动根据 type + id 去重

许可证

[MIT]（根据实际情况修改）