@winner-fed/convert-rem
v1.0.2
Published
convert rem
Readme
@winner-fed/convert-rem
移动端 rem 适配解决方案，支持响应式设计和多种屏幕适配场景。
📦 安装
# 使用 npm
npm install @winner-fed/convert-rem
# 使用 yarn
yarn add @winner-fed/convert-rem
# 使用 pnpm
pnpm add @winner-fed/convert-rem🚀 快速开始
基础用法（自动执行）
// 默认情况下，直接导入包会自动执行 rem 适配
import '@winner-fed/convert-rem';
// 或者手动调用
import { setRootPixel } from '@winner-fed/convert-rem';
setRootPixel();手动执行模式
// 方式1：使用专门的手动初始化函数
import { initSetRootPixel } from '@winner-fed/convert-rem';
initSetRootPixel({
screenWidth: 375, // UI 设计图宽度
rootFontSize: 37.5, // 根字体大小
maxRootFontSize: 46, // 最大根字体大小
supportLandscape: true // 支持横屏适配
});
// 方式2：使用专门的手动版本
import { manualSetRootPixel } from '@winner-fed/convert-rem';
manualSetRootPixel({
screenWidth: 375,
rootFontSize: 37.5
});禁用自动执行
// 方式1：通过 URL 参数禁用
// https://your-site.com?disableAutoConvertRem=true
// 方式2：通过全局变量禁用
window.__DISABLE_AUTO_CONVERT_REM__ = true;
import '@winner-fed/convert-rem'; // 此时不会自动执行在 HTML 中直接使用
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/@winner-fed/convert-rem"></script>
</head>
<body>
<!-- 页面内容 -->
</body>
</html>🔧 API 参考
setRootPixel(options?)
设置根元素字体大小以实现 rem 适配。
参数
| 参数名 | 类型 | 默认值 | 描述 |
| ------- | ---------------------------- | ----------------- | -------- |
| options | AutoSetRootFontSizeOptions | DEFAULT_OPTIONS | 配置选项 |
initSetRootPixel(options?)
手动初始化 rem 适配，功能与 setRootPixel 相同，语义上更明确表示手动调用。
参数
| 参数名 | 类型 | 默认值 | 描述 |
| ------- | ---------------------------- | ----------------- | -------- |
| options | AutoSetRootFontSizeOptions | DEFAULT_OPTIONS | 配置选项 |
manualSetRootPixel(options?)
手动执行 rem 适配，自动设置 disableAutoExecution: true。
参数
| 参数名 | 类型 | 默认值 | 描述 |
| ------- | ---------------------------- | ----------------- | -------- |
| options | AutoSetRootFontSizeOptions | DEFAULT_OPTIONS | 配置选项 |
getCurrentRootFontSize()
获取当前计算出的根字体大小。
返回值
| 类型 | 描述 |
| -------- | ---------------------- |
| number | 当前根字体大小（像素） |
AutoSetRootFontSizeOptions
| 属性名 | 类型 | 默认值 | 描述 |
| ------------------------ | --------- | ------- | ------------------------------------ |
| screenWidth | number | 375 | UI 设计图宽度，通常为设计稿的宽度 |
| rootFontSize | number | 37.5 | 根字体大小，用于计算 rem 比例 |
| maxRootFontSize | number | 46 | 最大根字体大小，防止大屏幕下字体过大 |
| widthQueryKey | string | '' | 从 URL 查询参数中获取宽度的键名 |
| supportLandscape | boolean | false | 是否支持横屏时使用高度计算 rem |
| useRootFontSizeBeyondMax | boolean | false | 超过最大字体大小时是否使用根字体大小 |
| disableAutoExecution | boolean | false | 是否禁用导入时的自动执行 |
✨ 特性
🌍 多屏幕适配
- 响应式设计：自动根据屏幕宽度调整根字体大小
- 最大字体限制：防止在大屏设备上字体过大
- 横屏支持：可选择在横屏时使用高度计算
📱 折叠屏适配
特别针对华为折叠屏设备进行优化：
// 自动检测鸿蒙系统并适配折叠屏
// 当屏幕宽度 > 460px 时，自动调整为折叠态基准宽度
if (isHarmonyOS() && clientWidth > 460) {
clientWidth = (clientWidth - 20) / 2; // 减去折痕区域宽度
}🔄 动态调整
- 窗口大小变化：监听
resize事件自动调整 - 屏幕旋转：监听
orientationchange事件适配横竖屏切换 - 实时响应：30ms 延迟确保性能和准确性
🎯 灵活配置
- URL 参数控制：支持通过 URL 查询参数动态设置宽度
- 多种计算模式：支持不同的字体大小计算策略
- 兼容性良好：支持各种浏览器环境
📖 使用场景
1. 标准移动端适配
// 375px 设计稿，1rem = 37.5px
setRootPixel({
screenWidth: 375,
rootFontSize: 37.5
});2. 大屏限制适配
// 限制最大字体大小，适配平板等大屏设备
setRootPixel({
screenWidth: 375,
rootFontSize: 37.5,
maxRootFontSize: 50 // 限制最大字体
});3. 横屏游戏适配
// 支持横屏，适合游戏或视频应用
setRootPixel({
screenWidth: 667, // 横屏设计稿宽度
rootFontSize: 66.7,
supportLandscape: true
});4. 动态宽度控制
// 通过 URL 参数控制：https://example.com?width=414
setRootPixel({
widthQueryKey: 'width',
screenWidth: 375,
rootFontSize: 37.5
});5. PC 端适配
// PC 端使用固定字体大小
setRootPixel({
screenWidth: 375,
rootFontSize: 37.5,
maxRootFontSize: 46,
useRootFontSizeBeyondMax: true // 超过最大值时使用固定字体
});6. 自动/手动兼容场景
// 场景1：默认自动执行（推荐）
import '@winner-fed/convert-rem'; // 自动适配
// 场景2：条件性手动执行
import { initSetRootPixel, getCurrentRootFontSize } from '@winner-fed/convert-rem';
// 检查是否已经初始化
if (getCurrentRootFontSize() === 0) {
initSetRootPixel({
screenWidth: 375,
rootFontSize: 37.5
});
}
// 场景3：完全手动控制
window.__DISABLE_AUTO_CONVERT_REM__ = true; // 禁用自动执行
import { manualSetRootPixel } from '@winner-fed/convert-rem';
// 在特定时机手动初始化
document.addEventListener('DOMContentLoaded', () => {
manualSetRootPixel({
screenWidth: 375,
rootFontSize: 37.5
});
});🎨 CSS 使用示例
设置完成后，即可在 CSS 中使用 rem 单位：
/* 基于 375px 设计稿，rootFontSize: 37.5 */
.container {
width: 10rem; /* 375px */
height: 2rem; /* 75px */
font-size: 0.4rem; /* 15px */
margin: 0.5rem; /* 18.75px */
}
.title {
font-size: 0.48rem; /* 18px */
line-height: 1.2rem; /* 45px */
}🔍 内部实现
字体大小计算公式
// 基本计算公式
fontSize = (clientWidth * rootFontSize) / screenWidth;
// 应用最大值限制
fontSize = Math.min(fontSize, maxRootFontSize);
// 折叠屏适配
if (isHarmonyOS() && clientWidth > 460) {
clientWidth = (clientWidth - 20) / 2;
}全局变量
插件会在 window 对象上设置全局变量：
// 当前计算出的根字体大小
window.WINJS_ROOT_FONT_SIZE; // 例如：37.5🎯 最佳实践
1. 设计稿转换
// 750px 设计稿
setRootPixel({
screenWidth: 750,
rootFontSize: 75 // 1rem = 75px，方便计算
});
// CSS 中：设计稿 150px = 2rem2. 多端适配
// 检测设备类型进行不同配置
const isMobile = /Mobi|Android/i.test(navigator.userAgent);
setRootPixel({
screenWidth: 375,
rootFontSize: 37.5,
maxRootFontSize: isMobile ? 50 : 37.5,
supportLandscape: !isMobile
});3. 性能优化
// 避免频繁调用，建议在应用启动时调用一次
document.addEventListener('DOMContentLoaded', () => {
setRootPixel(yourOptions);
});⚠️ 注意事项
- 设计稿尺寸：确保
screenWidth与设计稿宽度一致 - 字体比例：建议
rootFontSize = screenWidth / 10便于计算 - 最大字体：根据实际需求设置
maxRootFontSize防止大屏下字体过大 - 折叠屏：华为折叠屏会自动适配，无需额外配置
- 兼容性：支持 ES5+ 浏览器，包括 IE9+，无需额外 polyfill
🔗 相关资源
📋 更新日志
查看 CHANGELOG.md 了解版本更新详情。
📄 许可证
ISC License
🤝 贡献
欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。
Fork from rsbuild-plugin-rem