# 国籍选择器
# 一、ml-country-selector是什么？
"ml-country-selector基于typescript实现和rollup打包,是一款开箱即用的选择国家名称前端组件,支持自定义国家名称数据
# 二、使用步骤
# 1.引入库
代码如下（示例）：
npm i ml-country-selector -S
1
注意如果是npm方式就需要这样引入
import { mlCountrySelector } from 'ml-country-selector';
1
# 2.初始化使用
在需要的地方初始化使用,demo如下: 注意必须提供一个容器元素
代码如下（示例）：
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');
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
# 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参数格式例子说明
// 注意:必须这种格式
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'},
]
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
2、selectedCallback(res)中res参数格式例子说明
{
"rescode": 0,
"eventItemData": {
"index": "25",
"name": "文莱",
"enname": "Brunei",
"countrycode": "25"
},
"selectCountry": {
"value": "Brunei",
"label": "文莱",
"index": 25,
"code": 25
},
"originCountryData": [...]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
- rescode值为0表示获取成功,负责为获取异常失败
- eventItemData是选择的国家的具体数据信息
- selectCountry是前选择的国家在countryList的具体那项
- originCountryData是传入的countryList数据
3、serverSeaAPI和serverTjAPI 自定义接口返回数据格式如下:
{
code: 0,
message: '',
data: {
datalist: [
{
"value": "Japan",
"label": "日本",
"index": 81,
"code": 81,
},
{
"value": "Jli",
"label": "日里",
"index": 82,
"code": 82,
},
]
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
值得注意的是：该插件字体等样式的大小是rem单位，所以是以使用场景的html根字体大小为基础的