159 lines
4.0 KiB
Markdown
159 lines
4.0 KiB
Markdown
# yjyl-input-unit 单位转换组件使用说明
|
||
功能特性
|
||
支持双向数值绑定
|
||
内置单位换算逻辑（含温度特殊处理）
|
||
支持单位循环切换/弹窗选择两种模式
|
||
兼容 Vue2/Vue3 和 UniApp 多平台
|
||
支持自定义单位显示
|
||
可配置小数位数精度
|
||
|
||
符合uni-modules标准，直接使用
|
||
|
||
|
||
Props 配置
|
||
|属性名 |类型 |必填 |默认值 |说明 |
|
||
|:-: |:-: |:-: |:-: |:-: |
|
||
|unitType |String |是 |- |单位类型（例：'length', 'weight', 'temperature'） |
|
||
|unitOrder |Number |否 |0 |当前单位序号（需配合 .sync 修饰符使用） |
|
||
|value |Number |是 |- |输入数值（使用 v-model 双向绑定） |
|
||
|showEnglishOnly |Boolean|否 |false |是否只显示英文单位（例：'kg' 代替 ' 千克 (kg)'） |
|
||
|decimalPlaces |Number |否 |5 |小数位数（0 - 10） |
|
||
|width |Number |否 |180 |组件总宽度（px） |
|
||
|height |Number |否 |32 |组件高度（px） |
|
||
|enableConvert |Boolean|否 |true |是否允许单位转换 |
|
||
|userDefined |Boolean|否 |false |是否使用自定义单位 |
|
||
|userDefinedunitName|String |否 |'' |自定义单位显示名称（需 userDefined = true 生效） |
|
||
|
||
|
||
事件说明
|
||
| 事件名称 | 说明 | 回调参数 |
|
||
| input | 数值变化时触发 | (newValue: number) |
|
||
| update:unitOrder | 单位序号变化时触发 | (newOrder: number) |
|
||
| conversion | 完成单位转换时触发 | { initialValue, newValue, oldUnit, newUnit, oldOrder, newOrder } 的 Object |
|
||
使用示例
|
||
基本用法
|
||
vue
|
||
|
||
<template>
|
||
<UniUnitConverter
|
||
v-model="value"
|
||
:unit-type="length"
|
||
:unit-order.sync="currentOrder"
|
||
/>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
data() {
|
||
return {
|
||
value: 100,
|
||
currentOrder: 0
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
禁用转换模式
|
||
|
||
<UniUnitConverter
|
||
v-model="fixedValue"
|
||
:unit-type="weight"
|
||
:enable-convert="false"
|
||
user-defined
|
||
:user-definedunit-name="'特殊单位'"
|
||
/>
|
||
事件处理
|
||
vue
|
||
复制
|
||
<template>
|
||
<UniUnitConverter
|
||
v-model="tempValue"
|
||
:unit-type="temperature"
|
||
@conversion="handleConversion"
|
||
/>
|
||
</template>
|
||
|
||
<script>
|
||
export default {
|
||
methods: {
|
||
handleConversion({ oldUnit, newUnit, newValue }) {
|
||
console.log(`单位从 ${oldUnit} 转换为 ${newUnit}，新值：${newValue}`)
|
||
}
|
||
}
|
||
}
|
||
</script>
|
||
|
||
API 需自己开发，按照下面的数据格式进行组织，参考unitData.js
|
||
组件依赖 listSysUnitConvert API 获取单位数据，需实现以下格式的接口：
|
||
|
||
javascript
|
||
{
|
||
rows: [
|
||
{
|
||
id: 1,
|
||
unitType: 'length',
|
||
unitName: '米(m)',
|
||
conversionFactor: 1,
|
||
baseUnit: 'Y',
|
||
unitOrder: 0
|
||
},
|
||
// ...其他单位数据
|
||
]
|
||
}
|
||
样式调整
|
||
可通过以下 CSS 类名自定义样式：
|
||
|
||
.unit-converter - 组件容器
|
||
|
||
.input-field - 输入框
|
||
|
||
.unit-label - 单位标签
|
||
|
||
.unit-selector - 单位选择器
|
||
|
||
.unit-option - 单位选项
|
||
|
||
平台差异
|
||
|
||
小程序端使用 longpress 事件触发选择器（长按代替双击）
|
||
|
||
H5 端自动适配点击事件
|
||
|
||
单位转换规则
|
||
|
||
温度单位需按约定顺序定义：
|
||
|
||
javascript
|
||
复制
|
||
[
|
||
{ unitOrder: 0, unitName: '℃' }, // 摄氏度
|
||
{ unitOrder: 1, unitName: '℉' }, // 华氏度
|
||
{ unitOrder: 2, unitName: 'K' } // 开尔文
|
||
]
|
||
自定义单位时需确保与现有换算逻辑兼容
|
||
|
||
常见问题
|
||
Q1: 单位选择器不显示
|
||
|
||
检查 enableConvert 是否为 true
|
||
|
||
确认单位数据加载成功
|
||
|
||
查看控制台是否有 API 错误
|
||
|
||
Q2: 数值更新不及时
|
||
|
||
确保使用 v-model 进行双向绑定
|
||
|
||
检查小数位数配置是否符合预期
|
||
|
||
确认没有在父组件中覆盖转换后的值
|
||
|
||
Q3: 样式显示异常
|
||
|
||
检查是否父容器有冲突的布局样式
|
||
|
||
确认单位标签宽度计算正确（通过 updateInputWidth 方法）
|
||
|
||
在小程序端添加 !important 覆盖默认样式
|
||
|