m8-mcp-server 1.0.0

package/dist/data/m8mpdoc-develop/009-UI/347/273/204/344/273/266/047-area/347/234/201/345/270/202/345/214/272/351/200/211/346/213/251.md

@@ -0,0 +1,295 @@
+# 组件使用
+
+## area 省市区选择
+
+### 介绍
+
+-   省市区三级联动选择。
+
+### 代码演示
+
+#### 基础用法
+
+要初始化一个`Area`组件，你需要传入一个`area-list`属性，数据格式具体可看下面数据格式章节。
+
+```html
+<em-cell @click="show1 = true">基础用法</em-cell>
+<em-area v-model="show1" title="标题" :area-list="areaList"></em-area>
+```
+
+::: ifdef M83
+
+```js
+export default {
+    data() {
+        return {
+            show1: false
+        };
+    }
+};
+```
+
+::: endif
+::: ifdef M84
+
+```js
+import { ref } from 'vue';
+const show1 = ref(false);
+```
+
+::: endif
+
+#### 选中省市区
+
+如果想选中某个省市区，需要传入一个`code-value`属性，绑定对应的省市区`code`
+
+```html
+<em-cell @click="show2 = true">选中省市区</em-cell>
+<em-area v-model="show2" title="标题" :area-list="areaList" code-value="120105"></em-area>
+```
+
+::: ifdef M83
+
+```js
+export default {
+    data() {
+        return {
+            show2: false
+        };
+    }
+};
+```
+
+::: endif
+::: ifdef M84
+
+```js
+import { ref } from 'vue';
+const show2 = ref(false);
+```
+
+::: endif
+
+#### 配置显示列
+
+可以通过`columns-num`属性配置省市区显示的列数，默认情况下会显示省市区，当你设置为`2`，则只会显示省市选择
+
+```html
+<em-cell @click="show3 = true">配置显示列</em-cell>
+<em-area v-model="show3" title="标题" :area-list="areaList" :columns-num="2"></em-area>
+```
+
+::: ifdef M83
+
+```js
+export default {
+    data() {
+        return {
+            show3: false
+        };
+    }
+};
+```
+
+::: endif
+::: ifdef M84
+
+```js
+import { ref } from 'vue';
+const show3 = ref(false);
+```
+
+::: endif
+
+#### 配置列占位提示文字
+
+可以通过`columns-placeholder`属性配置每一列的占位提示文字
+
+```html
+<em-cell @click="show4 = true">配置列占位提示文字</em-cell>
+<em-area
+    v-model="show4"
+    title="标题"
+    :area-list="areaList"
+    :columns-placeholder="['请选择', '请选择', '请选择']"
+></em-area>
+```
+
+::: ifdef M83
+
+```js
+export default {
+    data() {
+        return {
+            show4: false
+        };
+    }
+};
+```
+
+::: endif
+::: ifdef M84
+
+```js
+import { ref } from 'vue';
+const show4 = ref(false);
+```
+
+::: endif
+
+### API
+
+#### Area Props
+
+| 参数                                                                         | 说明                                           | 类型            | 默认值  |
+| :--------------------------------------------------------------------------- | :--------------------------------------------- | :-------------- | :------ |
+| v-model ::: ifdef M83 (value) ::: endif ::: ifdef M84 (modelValue) ::: endif | 切换组件显隐                                   | boolean         | `false` |
+| code-value                                                                   | 当前选中的省市区`code`                         | string          | -       |
+| title                                                                        | 顶部栏标题                                     | string          | -       |
+| confirm-button-text                                                          | 确认按钮文字                                   | string          | `确认`  |
+| cancel-button-text                                                           | 取消按钮文字                                   | string          | `取消`  |
+| area-list                                                                    | 省市区数据，格式见下方                         | object          | -       |
+| columns-placeholder                                                          | 列占位提示文字                                 | string[]        | `[]`    |
+| loading                                                                      | 是否显示加载状态                               | boolean         | `false` |
+| readonly                                                                     | 是否为只读状态，只读状态下无法切换选项         | boolean         | `false` |
+| item-height                                                                  | 选项高度，支持 `px` `vw` `rem` 单位，默认 `px` | number / string | `44`    |
+| columns-num                                                                  | 显示列数，3-省市区，2-省市，1-省               | number / string | `3`     |
+| visible-item-count                                                           | 可见的选项个数                                 | number / string | `6`     |
+| swipe-duration                                                               | 快速滑动时惯性滚动的时长，单位`ms`             | number / string | `1000`  |
+
+#### Popup Props
+
+省市区选择器组件已经包裹了`popup`组件，故也支持传递`popup`组件的部分`props`。相关`props`的具体示例请参考`popup`组件章节。
+
+| 参数                   |                   说明                    | 类型    | 默认值 |
+| :--------------------- | :---------------------------------------: | :------ | :----- |
+| overlay                |              是否显示遮罩层               | boolean | `true` |
+| overlay-class          |             自定义遮罩层类名              | string  | -      |
+| overlay-style          |             自定义遮罩层样式              | object  | -      |
+| transition             | 动画类名，等价于 `transtion` 的`name`属性 | string  | -      |
+| close-on-click-overlay |          是否在点击遮罩层后关闭           | boolean | `true` |
+| lock-scroll            |             是否锁定背景滚动              | boolean | `true` |
+| lazy-render            |        是否在显示弹层时才渲染节点         | boolean | `true` |
+
+注意，其中`transition`属性组件库支持的可选值有：`em-fade` `em-fade-up` `em-fade-down` `em-fade-left` `em-fade-right` `em-slide-up` `em-slide-down` `em-slide-left` `em-slide-right`
+
+#### Area Events
+
+| 事件    | 说明               | 回调参数                                 |
+| :------ | :----------------- | :--------------------------------------- |
+| confirm | 点击右上方完成按钮 | 一个数组参数，具体格式看下方数据格式章节 |
+| cancel  | 点击取消按钮时     | -                                        |
+| change  | 选项改变时触发     | 所有列选中值，当前列对应的索引           |
+
+#### Popup Events
+
+省市区选择组件已经包裹了`popup`组件，故也支持`popup`组件的部分事件。相关事件的具体示例请参考`popup`组件章节。
+
+| 事件名 |       说明       | 回调参数                    |
+| :----- | :--------------: | :-------------------------- |
+| close  | 关闭弹出层时触发 | `value`: 当前弹出层是否展开 |
+
+#### Area Slots
+
+| 名称           | 说明               |
+| :------------- | :----------------- |
+| title          | 自定义标题内容     |
+| columns-top    | 自定义选项上方内容 |
+| columns-bottom | 自定义选项下方内容 |
+
+#### Area 方法
+
+通过 `ref` 可以获取到 `Area` 实例并调用实例方法，详见组件实例方法
+
+| 方法名 | 说明                                                    | 参数          | 返回值 |
+| :----- | :------------------------------------------------------ | :------------ | :----- |
+| reset  | 根据 `code` 重置所有选项，若不传 `code`，则重置到第一项 | code?: string | -      |
+
+#### 省市区列表数据格式
+
+整体是一个 `object`，包含 `province_list`, `city_list`, `county_list` 三个 `key`。
+
+每项以省市区编码作为 `key`，省市区名字作为 `value`。编码为 `6` 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 `0` 补足 `6` 位。如北京编码为 `11`，以零补足 `6` 位，为 `110000`。
+
+`AreaList`具体格式如下：
+
+```js
+{
+  province_list: {
+    110000: '北京市',
+    120000: '天津市'
+  },
+  city_list: {
+    110100: '北京市',
+    110200: '县',
+    120100: '天津市',
+    120200: '县'
+  },
+  county_list: {
+    110101: '东城区',
+    110102: '西城区',
+    110105: '朝阳区',
+    110106: '丰台区'
+    120101: '和平区',
+    120102: '河东区',
+    120103: '河西区',
+    120104: '南开区',
+    120105: '河北区',
+    // ....
+  }
+}
+```
+
+#### 点击完成时返回的数据格式
+
+返回的数据整体为一个数组，数组内包含 `columnsNum`个数据， 每个数据对应一列选项中被选中的数据。
+
+`code` 代表被选中的地区编码， `name` 代表被选中的地区名称
+
+```js
+[
+    {
+        code: '110000',
+        name: '北京市'
+    },
+    {
+        code: '110100',
+        name: '北京市'
+    },
+    {
+        code: '110101',
+        name: '东城区'
+    }
+];
+```
+
+::: ifdef M83
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/index.html#/modules/m8showcase/examples/em-area"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+::: ifdef M84
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/m8.4/index.html#/modules/m8showcase/examples/em-area"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+
+ <style>
+ .ui-showcase-iframe {
+    position: fixed;
+    right: 3.5vw;
+    top: 17%;
+    width: 375px;
+    height: 75vh;
+    box-shadow: 0 0 12px 6px #eee;
+    border-radius: 15px;
+ }
+ .main .markdown-body {
+    padding: 45px;
+    width: calc(97vw - 661px);
+}
+ </style>