ml-country-selector/README.md

一个国家选择器组件

# 一、ml-country-selector是什么？
"ml-country-selector基于typescript实现和rollup打包,是一款开箱即用的选择国家名称前端组件,支持自定义国家名称数据


# 二、使用步骤
## 1.引入库
代码如下（示例）：

```js
npm i ml-country-selector -S
```

**注意如果是npm方式就需要这样引入**
```js
import { mlCountrySelector } from 'ml-country-selector';
```
## 2.初始化使用
在需要的地方初始化使用,demo如下:
**注意必须提供一个容器元素**

代码如下（示例）：
```js
            let instance = mlCountrySelector.initializationFn({
                el: '#container',
                // 初始化请求类型,建议true
                isHttps: true,
                // 是否开启input动画伸缩功能 即“清除”按钮 强烈建议开启
                animaInput: true,
                // 自定义按钮文案,仅animaInput开启时候生效
                inputOutBtnTxt: '取消',
                // input没有搜到任何内容时 失去焦点立即重制所有状态
                immediatelyReset: false,
                // input搜索是否全局匹配
                globalSearchWord: false,
                // 是否支持拼音搜索,默认false(非全局匹配模式才生效)
                supportEnSearch: false,
                // 是否开启列表独立滚动,搜索区域固定
                fixedAndScroll: true,
                // 自定义滚动区域高度px fixedAndScroll=true有效
                scrollviewHeight: null,
                // 搜索数据源是否需要包含“推荐”部分数据
                serachDataIncludeRecommend: false,
                // 是否在选中国家后重置状态
                selectCountryAfterReset: false,
                // 当使用input搜索结果为0时候是否也显示国家列表现,如果不显示就会是空状态视图, 默认false不显示
                searchEmptyShowCountryList: false,
                // 搜索输入最大字符数 默认值20
                searchInputMaxNum: 10,
                // 是否开启连续匹配模式下的匹配独立样式 默认false 且globalSearchWord=false生效
                searchWordAddStyle: true,
                // 是否滚动出现侧边提示大气泡
                scrollBodyBubble: true,
                // 是否左侧列表区域字母吸顶(仅当fixedAndScroll=true时候有效)
                leftTipTop: true,
                // 侧边栏跟随监听偏移值 PX
                leftActionSpan: 163,
                // input类型 默认值text,如果useServerSeach=true时建议值search
                inputType: 'text',
                // 是否启用server搜索和推荐
                useServerSeach: false,
                // 自定义搜索接口(当useServerSeach=true时生效) GET请求方式
                serverSeaAPI: '',
                // 自定义推荐接口(当useServerSeach=true时生效) GET请求方式
                serverTjAPI: '',
                // 为了提供更好的兼容性可以开启载入polyfill支持
                // getPolyFill: true,
                // 自定义一些配置项
                customOptions: {
                    // 搜索框清楚图标 可以url也可以base64
                    searchclearIcon: '',
                    // 搜索放大镜图标 可以url也可以base64
                    searchIcon: '',
                    // 国家选中态图标 可以url也可以base64
                    selectIcon: '',
                    // 侧边栏字母选中态图标 可以url也可以base64
                    slideItemIcon: '',
                },
                selectedCallback: function(res) {
                    console.log('自定义selectedCallback...执行', res);
                    containerBox.style.display = 'none';
                    myCountry.innerText = JSON.stringify(res.eventItemData);
                },
                // 自定义清除按钮点击回调函数
                inputOutBtnCallback: function(e) {
                    // 主动重置状态方法
                    instance.pubResetFn();
                    console.log('inputOutBtnCallback...执行', e, instance);
                },
                // 搜索input失去焦点回调函数
                inputBlurCallback: function(e) {
                    console.log('inputBlurCallback...执行', e);
                },
                // 搜索input获得焦点回调函数
                inputFocusCallback: function(e) {
                    console.log('inputFocusCallback...执行', e);
                },
                // 点击搜索框清楚按钮图标的回调函数
                searchClearIconCallback: function() {
                    console.log('searchClearIconCallback...执行');
                },
                // 请求开始时触发的回调函数
                apiStartCallback: function() {
                    console.log('apiStartCallback...执行');
                },
                // 请求完成时触发的回调函数
                apiEndCallback: function() {
                    console.log('apiEndCallback...执行');
                },
                // 节点挂在完成后的回调函数
                domRenderAfterCallback: function() {
                    console.log('domRenderAfterCallback...执行');
                }
            }).render();
            bth.onclick = function() {
                containerBox.style.display = 'block';
            };
            containerBoxClose.onclick = function() {
                containerBox.style.display = 'none';
            }
            // 当自定义元素高度时需要一步调用改方法使开启列表独立滚动,搜索区域固定效果生效(fixedAndScroll: true才有效)
            // instance.setfixedAndScroll()
            // 给开发人员使用的通过id获取元素的方法 必须传入id尾缀部分
            // instance.getEleByIdPubFn(tail: string);
            // 切换模式（暗黑ml-country-selector-dark和日间模式）， 默认日间
            // instance.changeThemePubFn('ml-country-selector-dark');
```

## 3.参数和方法说明
#### 1、参数说明:
|  序号| 参数 |值类型 |是否必须|说明|其他|
|--|--|--|--|--|--|
| 1 | el | string|是 |容器元素id ||
| 2 | placeholder | string|否 |搜索input的placeholder ||
| 3 | countryList | object[]|否 |自定义国家列表数据源 |详细格式表后说明|
| 4 | hotCountryList | object[]|否 |自定义常用喧嚣国家列表数据源 |详细格式表后说明|
| 5 | animaInput | boolean|否 |是否开启input动画伸缩功能 即“清除”按钮 强烈建议开启 ||
| 6 | inputOutBtnTxt | string|否 |自定义按钮文案,仅animaInput开启时候生效||
| 7 | immediatelyReset |boolean|否 |input 失去焦点立即重制所有状态 ||
| 8 | fixedAndScroll |boolean|否 |是否开启列表独立滚动,搜索区域固定 ||
| 9 | scrollviewHeight |number|否 |自定义滚动区域高度px fixedAndScroll=true有效 ||
| 10| globalSearchWord |boolean|否 |input搜索是否全局匹配 ||
| 11| serachDataIncludeRecommend |boolean|否 |搜索数据源是否需要包含“推荐”部分数据 ||
| 12| selectCountryAfterReset |boolean|否 |是否在选中国家后重置状态 ||
| 13| searchEmptyShowCountryList |boolean|否 |当使用input搜索结果为0时候是否也显示国家列表现,如果不显示就会是空白视图, 默认false不显示||
| 14| searchInputMaxNum |number|否 |搜索输入最大字符数 默认值20 ||
| 15| supportEnSearch | boolean | 否 |  是否支持拼音搜索,默认false(非全局匹配模式才生效) ||
| 16| searchWordAddStyle |boolean|否 |是否开启连续匹配模式下的匹配独立样式 默认false 且globalSearchWord=false生效 ||
| 17| isHttps |boolean|是 |初始化请求类型,建议true ||
| 18| inputType |string|否 |input类型 默认值text,如果useServerSeach=true时建议值search ||
| 19| useServerSeach |boolean|否 | 是否启用server搜索和推荐 ||
| 20| serverSeaAPI |string|否 | 自定义搜索接口(当useServerSeach=true时生效) GET请求方式 |自定义接口返回数据格式下面说明|
| 21| serverTjAPI |string|否 |  自定义推荐接口(当useServerSeach=true时生效) GET请求方式 |自定义接口返回数据格式下面说明|



#### 2、回调函数说明:
|  序号| 参数 |值类型 |是否必须|说明|其他|
|--|--|--|--|--|--|
| 1 | selectedCallback(res) | Function|是 |完成国家选择后的回调函数,其中res包含选择的国家数据结果 ||
| 2 | errCallback| Function|否 |发生错误的回调函数 ||
| 3 | inputOutBtnCallback| Function|否 |自定义清除按钮点击回调函数 ||
| 4 | inputBlurCallback| Function|否 |搜索input失去焦点回调函数 ||
| 5 | inputFocusCallback| Function|否 | 搜索input获得焦点回调函数 ||
| 6 | domRenderAfterCallback| Function|否 | 节点挂在完成后的回调函数 ||
| 7 | searchClearIconCallback| Function|否 | 点击搜索框清楚按钮图标的回调函数 ||
| 8 | apiStartCallback| Function|否 | 请求开始时触发的回调函数 ||
| 9 | apiEndCallback| Function|否 | 请求完成时触发的回调函数 ||

#### 3、可调用方法说明:
|  序号| 参数 |值类型 |说明|其他|
|--|--|--|--|--|
| 1 | pubResetFn | Function |主动重置状态方法 ||
| 2 | setfixedAndScroll |Function |当自定义元素高度时需要一步调用改方法使开启列表独立滚动,搜索区域固定效果生效(fixedAndScroll: true才有效) ||
| 3 | getEleByIdPubFn| Function |给开发人员使用的通过id获取元素的方法 必须传入id尾缀部分 ||
| 4 | changeThemePubFn| Function | 主动切换模式（暗黑和日间模式）， 默认日间模式。如果需要切换至暗黑模式传入【ml-country-selector-dark】参数值即可，不传则切换至日间模式 ||


 
 1、 **countryList、hotCountryList参数格式例子说明**

```js
// 注意:必须这种格式
countryList:  [
        { value: "Angola", label: "安哥拉" , code: 0, pingyin: 'angela'},
        { value: "Afghanistan", label: "阿富汗", code: 1, pingyin: 'afuhan'},
        { value: "Albania", label: "阿尔巴尼亚", code: 2, pingyin: 'anerniriya'},
        { value: "Algeria", label: "阿尔及利亚", code: 3, pingyin: 'aerjiliya'},
        { value: "Andorra", label: "安道尔共和国", code: 4, pingyin: 'andaogongheguo'},
      ]
```


 2、**selectedCallback(res)中res参数格式例子说明**
```js
{
  "rescode": 0,
  "eventItemData": {
    "index": "25",
    "name": "文莱",
    "enname": "Brunei",
    "countrycode": "25"
  },
  "selectCountry": {
    "value": "Brunei",
    "label": "文莱",
    "index": 25,
    "code": 25
  },
  "originCountryData": [...]
}

```

 - rescode值为0表示获取成功,负责为获取异常失败
 - eventItemData是选择的国家的具体数据信息
 - selectCountry是前选择的国家在countryList的具体那项
 - originCountryData是传入的countryList数据


 3、**serverSeaAPI和serverTjAPI 自定义接口返回数据格式如下:**
```js
{
    code: 0,
    message: '',
    data: {
        datalist: [
            {
                "value": "Japan",
                "label": "日本",
                "index": 81,
                "code": 81,
            },
            {
                "value": "Jli",
                "label": "日里",
                "index": 82,
                "code": 82,
            },
        ]
    }
}

```

**值得注意的是：该插件字体等样式的大小是rem单位，所以是以使用场景的html根字体大小为基础的**


## 效果预览
![图片](https://img-blog.csdnimg.cn/218ebf99348b4e16a5143f4e8d8de4d5.png#pic_center)