Vue Area Linkage Picker

Common errors

• TypeError: Cannot read properties of undefined (reading 'pca')

  cause `area-data` not installed or not passed to the component.
  fix Install `area-data` (`npm i area-data`) and ensure it's imported and bound to the `:data` prop, e.g., `<area-select :data="pca"></area-select>`.

• Component is not registered (e.g., `<AreaSelect>` not recognized)

  cause The component was not properly registered globally or locally.
  fix Globally: `import VueAreaLinkage from 'vue-area-linkage'; Vue.use(VueAreaLinkage);`. Locally: `import { AreaSelect } from 'vue-area-linkage'; components: { AreaSelect }`.

• Styles are missing or components appear unstyled.

  cause The required CSS file has not been imported.
  fix Add `import 'vue-area-linkage/dist/index.css';` to your main JavaScript entry file or an appropriate global stylesheet.

• Error: "[Vue warn]: Failed to mount component: template or render function not defined." (or similar related to `vue-area-linkage` in Vue 3)

  cause `vue-area-linkage` is designed for Vue 2 and is not compatible with Vue 3.
  fix This library is for Vue 2 applications only. For Vue 3, you will need to find a different area linkage component or migrate your project to Vue 2 if this component is critical.

Warnings

• breaking Starting with v5.0.0, the package no longer bundles geographical data. Users must explicitly install `area-data` and pass the data (e.g., `pca` or `pcaa`) to the components via the `:data` prop.
  Fix: Install `area-data` (`npm i area-data`) and modify your component usage: `<area-select :data="pca"></area-select>`. Also, update your imports: `import { pca, pcaa } from 'area-data';`
• breaking Version 4.0.0 removed support for street-level selection, limiting components to province, city, and district levels only. The `level` prop no longer accepts a value of 3.
  Fix: Review existing usage that might have relied on street-level selection and adjust the `level` prop to 0, 1, or 2 as appropriate. If street data is still required, consider an older version or an alternative library.
• breaking The `isLinkage` property on `area-select` was renamed to `disableLinkage` in v5.1.0.
  Fix: Replace `isLinkage` with `disableLinkage` in your `area-select` component definitions. Note that the logic of the property might also be inverted (e.g., `isLinkage="false"` becomes `disableLinkage="true"`).
• gotcha The CSS styles are not automatically bundled with the components and must be imported separately to ensure proper rendering.
  Fix: Always include `import 'vue-area-linkage/dist/index.css';` in your main entry file or component that uses `vue-area-linkage`.
• breaking Version 2.0.0 removed the dependency on `element-ui`, which significantly reduced the bundle size but might require adjustments if your project implicitly relied on `element-ui`'s styles or components being present through `vue-area-linkage`.
  Fix: Ensure `element-ui` is explicitly installed and configured if your project still needs it. No direct fix needed for `vue-area-linkage` usage itself, but be aware of style changes.

Install

• npm install vue-area-linkage npm
• yarn add vue-area-linkage yarn
• pnpm add vue-area-linkage pnpm

Imports

• VueAreaLinkage
  wrong:

  import { VueAreaLinkage } from 'vue-area-linkage';

  correct:

  import VueAreaLinkage from 'vue-area-linkage';
  Vue.use(VueAreaLinkage);

  This is the default export for global registration via Vue.use(). Individual components like AreaSelect and AreaCascader are not directly exported this way for global use.
• { AreaSelect, AreaCascader }
  wrong:

  import AreaSelect from 'vue-area-linkage/dist/lib/AreaSelect';

  correct:

  import { AreaSelect, AreaCascader } from 'vue-area-linkage';

  Used for on-demand component import, often with a babel plugin for tree-shaking. Available since v2.1.2. Remember to also import the CSS.
• CSS Styles

  import 'vue-area-linkage/dist/index.css';

  Crucial for styling the components. Must be imported separately since v2 or higher.
• { pca, pcaa }

  import { pca, pcaa } from 'area-data';

  These provide province-city-area data. `pca` is province-city, `pcaa` is province-city-area. Required to be passed as a prop to components since v5.0.0.

Quickstart

This quickstart demonstrates how to register and use both `AreaSelect` and `AreaCascader` components with explicitly imported geographical data (`pca` and `pcaa`) as required by v5+ of the library. It shows basic province-city and province-city-area selection, along with a more advanced `AreaSelect` configuration.

import Vue from 'vue';
import { pca, pcaa } from 'area-data';
import 'vue-area-linkage/dist/index.css';
import VueAreaLinkage from 'vue-area-linkage';

Vue.use(VueAreaLinkage);

export default {
  data() {
    return {
      selectedProvinceCity: [],
      selectedProvinceCityArea: []
    };
  },
  methods: {
    handleSelectChange(value) {
      console.log('AreaSelect value changed:', value);
    },
    handleCascaderChange(value) {
      console.log('AreaCascader value changed:', value);
    }
  },
  template: `
    <div>
      <h2>Province-City Selection</h2>
      <area-select v-model="selectedProvinceCity" :data="pca" @change="handleSelectChange"></area-select>
      <p>Selected: {{ selectedProvinceCity }}</p>

      <h2>Province-City-Area Selection</h2>
      <area-cascader v-model="selectedProvinceCityArea" :data="pcaa" @change="handleCascaderChange"></area-cascader>
      <p>Selected: {{ selectedProvinceCityArea }}</p>

      <h2>Advanced AreaSelect (Level 2, All type)</h2>
      <area-select type='all' :level='2' v-model="selectedProvinceCityArea" :data="pcaa"></area-select>
      <p>Selected (Advanced): {{ selectedProvinceCityArea }}</p>
    </div>
  `
};