Package Exports
- @pikaz/location
- @pikaz/location/lib/pikazLocation.js
- @pikaz/location/lib/pikazLocationModule.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@pikaz/location) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
介绍
供中国地区使用的 js 定位插件
特性：
- 支持浏览器 h5 定位、ip 定位、经纬度查询地址、ip 查询、地区编码查询地址、地址文本解析、省市区三级联动列表搜索
- 定位信息文件已做压缩处理，如果有启用 gzip 时部分定位大约只会花费几十 k
- web 端定位库，无需在服务端额外运行定位服务，没有并发限制、次数限制且无收费
ps：
由于浏览器限制，http 域名的网页使用 h5 定位可能会出现问题，如定位不准、禁止定位等，如果想要定位结果更加精准，最好使用 https 域名；
该插件的定位文件存放在第三方 cdn 中，若想存放至自己的 cdn 上，则可参考setConfig函数使用方法介绍
更新日志：
- 0.1.x 文档请点击这里，1.x.x 版本相比 0.1.x 版本有破坏性更新，如需升级注意重新对接文档。
- 相比 0.1.x 版本新增了 ip 查询地址、地址文本解析、地区编码查询地址。
- 重构了 ip 定位方法，使用 ip 文件处理 ip 定位，对第三方的 ip 定位无依赖，ip 获取默认会缓存一天，也可自行结合自己服务获取用户 ip 进行 ip 定位。
- 对定位文件进行优化，使每次定位所加载的文件更小，且对所有加载过的定位文件进行持久化缓存，第二次对于同市的定位速度在 100ms 以内。
- 1.0.9 版本优化了 cdn 文件加载逻辑
- 1.0.10 版本新增 esmodule 包，兼容 vite
demo 示例点击这里一键体验
demo 代码点击这里一键 copy
安装
with npm or yarn
yarn add @pikaz/location
npm i -S @pikaz/locationimport { getLocation } from '@pikaz/location'with cdn
<script
type="text/javascript"
src="https://cdn.jsdelivr.net/npm/@pikaz/location"
></script>
或者
<script type="text/javascript" src="https://unpkg.com/@pikaz/location"></script>const { getLocation } = window.pikazLocation方法函数
| 方法名 | 方法说明 | 参数/object | 参数说明 | 默认参数值 |
| setConfig | 设置全局配置（不调用则使用默认配置） | timeout: Number/选填 | 所有定位函数默认超时时间，单位毫秒 | 10000 |
| url: String/选填 | 静态文件cdn地址 | https://cdn.jsdelivr.net/npm/@pikaz/location/lib | ||
| getLocation | 默认定位函数，优先使用html5定位，html5定位失败，则会自动切换为ip定位 | 对应定位类型的参数同下方的getH5Location方法和getIpLocation方法 | - | - |
| getH5Location | html5定位 | timeout: Number/选填 | 超时时间 | 10000 |
| enableHighAccuracy: Boolean/选填 | 是否开启设备gps启用高精度定位（更耗时） | false | ||
| detail: Boolean/选填 | 是否需要地址详细信息（更耗时） | false | ||
| latitude: Number/选填 | 手动传入经纬度查询地址信息，latitude与longitude需同时传入，不传则使用设备定位 | - | ||
| longitude: Number/选填 | 可手动传入经纬度查询地址信息，latitude与longitude需同时传入，不传则使用设备定位 | - | ||
| getIpLocation | ip定位 | timeout: Number/选填 | 超时时间 | 10000 |
| detail: Boolean/选填 | 是否需要地址详细信息（更耗时） | false | ||
| ip: String/选填 | 可手动传入ipv4格式的ip地址（如114.114.114.114）查询地址信息，不传则使用设备ip定位 | - | ||
| searchAddress | 解析地址文本 | timeout: Number/选填 | 超时时间 | 10000 |
| detail: Boolean/选填 | 是否需要地址详细信息（更耗时） | false | ||
| address: String/必填 | 地址文本字符串，必须带有省级或市级的全写或简写，不能只包含区县名称，如广东深圳/深圳南山 | - | ||
| searchCodeAddress | 地区编码查询 | timeout: Number/选填 | 超时时间 | 10000 |
| detail: Boolean/选填 | 是否需要地址详细信息（更耗时） | false | ||
| code: String/必填 | 地区编码 | - | ||
| searchList | 省市区三级联动，传入地区编码获取该地区下级地区列表 | code: String/选填 | 地区编码，若不传则获取所有省级地区列表 | - |
| searchCodeDetail | 获取单个地区编码的详细信息，等同于其他方法中的detail数据 | timeout: Number/选填 | 超时时间 | 10000 |
| code: String/必填 | 地区编码 | - |
注：detail开启则会在原本基础定位信息的基础上返回省市区的详细信息
方法示例
setConfig
说明：设置全局配置（不调用则使用默认配置）
可把该项目的根目录下的 static 文件夹整个上传至您的 oss 上，将 static 文件夹的链接地址作为 url 传入，如 oss 上的 static 文件夹可通过https://xxx.com/file/static访问，则url可传入https://xxx.com/file，若不设置，则url默认使用https://cdn.jsdelivr.net/npm/@pikaz/location/lib等公共cdn地址（第三方cdn可能不稳定，最好自行上传定位文件）
import { setConfig } from '@pikaz/location'
setConfig({
// 超时时间
timeout: 10000,
// 您的oss地址
url: 'https://unpkg.com/@pikaz/location/lib',
})getLocation
说明：默认定位函数，优先使用 html5 定位，html5 定位失败，则会自动切换为 ip 定位
import { getLocation } from '@pikaz/location'
getLocation()
.then((res) => {
// 返回数据结构: {
// ...,//返回对应定位类型数据，同下方的getH5Location和getIpLocation返回数据格式
// type:"h5"//定位类型：h5/ip
// }
})
.catch((err) => {
console.log(err)
})getH5Location
说明：html5 定位函数，html5 定位推荐使用 https 协议，若为 http，则 html5 定位可能出现定位不准确或无法定位（取决于浏览器策略），开启高精度定位会更加耗时；
import { getH5Location } from '@pikaz/location'
getH5Location({
// 开启gps高精度定位
enableHighAccuracy: true,
})
.then((res) => {
// 返回数据结构:{
// address: "广东省深圳市福田区"//完整地址
// city: "深圳市"//市级名称
// code: "440304"//地区编码
// district: "福田区"//区县级名称
// latitude: 22.547//区县级纬度
// longitude: 114.085947//区县级经度
// province: "广东省"//省级名称
// }
})
.catch((err) => {
console.log(err)
})getIpLocation
说明：ip 定位函数，ip 定位相比 html5 定位精度更差且可能不准，但是若用户拒绝定位授权时，则可以使用 ip 定位作为兜底方案；
import { getIpLocation } from '@pikaz/location'
getIpLocation()
.then((res) => {
// 返回数据结构:{
// address: "江苏省南京市"//完整地址
// city: "南京市"//市级名称
// code: "320100"//地区编码
// district: ""//区县级名称
// province: "江苏省"//省级名称
// ip: "114.114.114.114"//ip地址
// }
})
.catch((err) => {
console.log(err)
})searchAddress
说明：解析地址文本，必须带有省级或市级的全写或简写，不能只包含区县名称，如广东深圳/广东省深圳市/广东南山/深圳/深圳南山
import { searchAddress } from '@pikaz/location'
searchAddress({
address: '广东福田',
})
.then((res) => {
// 返回数据结构:{
// address: "广东省深圳市福田区"//完整地址
// city: "深圳市"//市级名称
// code: "440304"//地区编码
// district: "福田区"//区县级名称
// province: "广东省"//省级名称
// }
})
.catch((err) => {
console.log(err)
})searchCodeAddress
说明：地区编码查询地址信息
import { searchCodeAddress } from '@pikaz/location'
searchCodeAddress({
code: '440304',
})
.then((res) => {
// 返回数据结构:{
// address: "广东省深圳市福田区"//完整地址
// city: "深圳市"//市级名称
// code: "440304"//地区编码
// district: "福田区"//区县级名称
// province: "广东省"//省级名称
// }
})
.catch((err) => {
console.log(err)
})searchList
说明：省市区三级联动，传入对应行政单位编码，获取下级行政单位列表；不传行政单位编码默认获取省级单位列表
import { searchList } from '@pikaz/location'
searchList({
code: '110000',
})
.then((res) => {
// 返回数据结构: [
// {
// "code":"110101",//该地区编码
// "name":"东城区",//该地区名称
// },
// {
// "code":"110102",//该地区编码
// "name":"西城区",//该地区名称
// }
// ]
})
.catch((err) => {
console.log(err)
})searchCodeDetail
说明：获取单个地区的详细信息：地区编码、经纬度、名称、名称拼音
import { searchCodeDetail } from '@pikaz/location'
searchCodeDetail({
code: '440304',
})
.then((res) => {
// {
// "code": "440304", //该地区编码
// "location": { //该地区经纬度
// "latitude": 22.521541,
// "longitude": 114.05498
// },
// "name": "福田区", //该地区名称
// "pinyin": "futianqu" //该地区拼音
// }
})
.catch((err) => {
console.log(err)
})detail
说明：若开启则会在原本的返回数据中额外返回详细的地址信息
import { getH5Location } from '@pikaz/location'
getH5Location({
// 获取详细地址信息
detail: true,
})
.then((res) => {
// {
// address: "广东省深圳市福田区" //完整地址
// city: "深圳市" //市级名称
// code: "440304" //地区编码
// district: "福田区" //区县级名称
// latitude: 22.547 //区县级纬度
// longitude: 114.085947 //区县级经度
// province: "广东省" //省级名称
// "detail": { //详细地址信息
// "province": {
// "code": "440000", //省级地区编码
// "location": { //省级地区经纬度
// "latitude": 23.13171,
// "longitude": 113.26627
// },
// "name": "广东省", //省级名称
// "pinyin": "guangdong" //省级名称拼音
// },
// "city": {
// "code": "440300", //市级地区编码
// "location": { //市级地区经纬度
// "latitude": 22.54286,
// "longitude": 114.05956
// },
// "name": "深圳市", //市级名称
// "pinyin": "shenzhen" //市级名称拼音
// },
// "district": {
// "code": "440304", //区县级地区编码
// "location": { //区县级地区经纬度
// "latitude": 22.521541,
// "longitude": 114.05498
// },
// "name": "福田区", //区县级名称
// "pinyin": "futianqu" //区县级名称拼音
// }
// }
})
.catch((err) => {
console.log(err)
})