ml-country-selector
v2.2.75
Published
一个国家选择器组件
Downloads
52
Readme
一、ml-country-selector是什么？
"ml-country-selector基于typescript实现和rollup打包,是一款开箱即用的选择国家名称前端组件,支持自定义国家名称数据
二、使用步骤
1.引入库
代码如下（示例）：
npm i ml-country-selector -S注意如果是npm方式就需要这样引入
import { mlCountrySelector } from 'ml-country-selector';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');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'},
]2、selectedCallback(res)中res参数格式例子说明
{
"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 自定义接口返回数据格式如下:
{
code: 0,
message: '',
data: {
datalist: [
{
"value": "Japan",
"label": "日本",
"index": 81,
"code": 81,
},
{
"value": "Jli",
"label": "日里",
"index": 82,
"code": 82,
},
]
}
}
值得注意的是：该插件字体等样式的大小是rem单位，所以是以使用场景的html根字体大小为基础的
效果预览
