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 覆盖默认样式
|
|||
|
|
|