v-distpicker

repository·master·Indexed 21 days ago

A flexible Vue component for selecting provinces, cities, and districts of China. It supports both PC and mobile interfaces, custom data sources via provinceSource, citySource, and areaSource props, and is compatible with Vue 2 (v1.3.3) and Vue 3 (v2.1.0).

Tokens: 2.6K
Snippets: 10
Records: 13
Agent score: 66%

What's inside v-distpicker

Install v-distpicker for Vue 2
master
To use v-distpicker with Vue 2, install version 1.x using npm. It is recommended to specify the version to ensure compatibility with Vue 2 environments.
```
npm install v-distpicker@^1.3.3 --save
```
https://github.com/jcc/v-distpicker/blob/master/README.zh_CN.md

Register the v-distpicker component

master

Depending on your Vue usage pattern, register the component as follows:

Global Registration (Vue 3)

import VDistpicker from 'v-distpicker'
const app = createApp(App)
app.component('v-distpicker', VDistpicker)

Local Registration (Options API)

import { defineComponent } from 'vue'
import VDistpicker from 'v-distpicker'

export default defineComponent({
  components: { VDistpicker },
})

Setup API (Script Setup)

<script setup>
import VDistpicker from 'v-distpicker'
</script>

import VDistpicker from 'v-distpicker'
const app = createApp(App)
app.component('v-distpicker', VDistpicker)

Install v-distpicker for Vue 3
master
To use v-distpicker with Vue 3, install version 2.x using npm. Note that npm install defaults to the latest released version, so explicitly specifying the version is advised to ensure you get the Vue 3 compatible release.
```
npm install v-distpicker@^2.1.0 --save
```
https://github.com/jcc/v-distpicker/blob/master/README.zh_CN.md

Install v-distpicker

master

Install v-distpicker via npm depending on your Vue version:

Vue 2

npm install v-distpicker@^1.3.3 --save

Vue 3

npm install v-distpicker@^2.1.0 --save

CDN

<script src="https://cdn.jsdelivr.net/npm/v-distpicker@version/dist/v-distpicker.js"></script>
<!-- or -->
<script src="https://unpkg.com/v-distpicker@version/dist/v-distpicker.js"></script>

npm install v-distpicker@^2.1.0 --save

Use custom data sources with provinceSource, citySource, and areaSource
master
Starting from version 2.0.6, you can provide your own data sources for provinces, cities, and areas using the following props:
- provinceSource: Custom data for provinces.
- citySource: Custom data for cities.
- areaSource: Custom data for areas.
This allows you to override the built-in Chinese administrative division data with your own datasets.
```
// Example usage of custom data sources
<v-distpicker 
  :province-source="myProvinces" 
  :city-source="myCities" 
  :area-source="myAreas" 
/>
```
https://github.com/jcc/v-distpicker/blob/master/CHANGELOG.zh-CN.md
Troubleshoot missing province/city/area data
master
If you find that administrative division data (province, city, or area) is missing:
1. Verify if the data exists in the original sources (National Bureau of Statistics or Ministry of Civil Affairs).
2. Use the provided props to pass in a custom data source.
3. If the data is truly missing, you can contribute by forking the repository and submitting a Pull Request.
https://github.com/jcc/v-distpicker/blob/master/README.zh_CN.md

Use v-distpicker in Vue 3 (Composition API)

master

In Vue 3, import VDistpicker and use the <v-distpicker> component. You can bind the current selection using :province, :city, and :area props. The component emits events like @selected, @change, @province, @city, and @area to handle user interactions.

<template>
<v-distpicker :province="select.province" :city="select.city" :area="select.area" @selected="onSelect" @change="onChange" @province="selectProvince" @city="selectCity" @area="selectArea"></v-distpicker>
</template>

<script setup>
import { reactive } from 'vue'
import VDistpicker from 'v-distpicker'

let select = reactive({ province: '', city: '', area: '' })

function onSelect(data) {
  console.log(data)
}
function onChange(data){
   console.log(data)
}
function selectProvince({code,value}) {
  select.province = value
  console.log({code, value})
}
function selectCity({code,value}) {
  select.city = value
  console.log({code, value})
}
function selectArea({ code, value }) {
  select.area = value
  console.log({code, value})
}
</script>

Use v-distpicker in your templates

master

The component can be used for basic selection, setting default values, or mobile-optimized views.

Basic Usage

<v-distpicker></v-distpicker>

With Default Values Pass province, city, or area as props (accepts String or Number codes/names).

<v-distpicker province="广东省" city="广州市" area="海珠区"></v-distpicker>

Mobile Mode Use the type="mobile" prop to switch to a mobile-friendly interface.

<v-distpicker type="mobile"></v-distpicker>

<v-distpicker
  :province="select.province"
  :city="select.city"
  :area="select.area"
  @selected="onSelect"
  @change="onChange"
  @province="selectProvince"
  @city="selectCity"
  @area="selectArea"
></v-distpicker>

Use v-distpicker in Vue 2 (Options API)

master

In Vue 2, import VDistpicker and register it in your component's components option. Use props :province, :city, and :area for data binding and listen to events like @selected, @province, @city, and @area to update your local state.

<template>
<v-distpicker :province="select.province" :city="select.city" :area="select.area" @selected="onSelect" @province="selectProvince" @city="selectCity" @area="selectArea"></v-distpicker>
</template>

<script>
import VDistpicker from 'v-distpicker'
export default {
  components: { VDistpicker },
  data() {
    return {
       select: { province: '', city: '', area: '' }
    }
  },
  methods: {
    onSelect(data) {
         console.log(data)
    },
    selectProvince({code,value}) {
        this.select.province = value
        console.log({code, value})
    },
    selectCity({code,value}) {
        this.select.city = value
        console.log({code, value})
    },
    selectArea({ code, value }) {
        this.select.area = value
        console.log({code, value})
    }
  }
}
</script>

Listen to the change event
master
As of version 2.0.7, the component emits a change event. You can use this event to react whenever the selected province, city, or area is updated.
```
<v-distpicker @change="handleAddressChange" />

<script setup>
const handleAddressChange = (data) => {
  console.log('Address changed:', data);
};
</script>
```
https://github.com/jcc/v-distpicker/blob/master/CHANGELOG.zh-CN.md

Handle v-distpicker events

master

The component emits several events to allow you to react to user selections:

Name	Type	Description	Return Format
`province`	Function	Triggered when a province is selected	`{code, value}`
`city`	Function	Triggered when a city is selected	`{code, value}`
`area`	Function	Triggered when a district is selected	`{code, value}`
`selected`	Function	Triggered when the final item is selected	`{province:{code,value},city:{code,value},area:{code,value}}`
`change-province`	Function	Triggered when province changes	`{code, value}`
`change-city`	Function	Triggered when city changes	`{code, value}`
`change-area`	Function	Triggered when area changes	`{code, value}`
`change`	Function	Triggered when the full address changes	`{province:{code,value},city:{code,value},area:{code,value}}`

Configure v-distpicker props

master

Use the following props to customize the behavior and appearance of the district selector:

Name	Type	Description	Default
`province`	String/Number	Province code or name
`city`	String/Number	City code or name
`area`	String/Number	District code or name
`placeholder`	Object	Default display values (e.g., `{province:'省',city:'市',area:'区'}`)
`type`	String	Interface type: `pc` or `mobile`	`pc`
`only-province`	Boolean	Only show the province selector	`false`
`hide-area`	Boolean	Hide the district (area) selector	`false`
`disabled`	Boolean	Disable the entire component	`false`
`province-disabled`	Boolean	Disable province selection	`false`
`city-disabled`	Boolean	Disable city selection	`false`
`area-disabled`	Boolean	Disable district selection	`false`
`province-source`	Object	Custom province data source
`city-source`	Object	Custom city data source
`address-source`	Object	Custom district data source
`wrapper`	String	CSS class for the wrapper	`'distpicker-address-wrapper'`
`address-header`	String	CSS class for mobile header	`'address-header'`
`address-container`	String	CSS class for mobile container	`'address-container'`