使用Foldables.js库可以简化H5页面在折叠屏设备上的适配流程，以下是详细的使用步骤，包括安装、核心API调用和实际场景示例：
一、安装Foldables.js
Foldables.js是轻量级库，可通过多种方式引入项目：
1. 直接引入CDN
适合快速原型开发，在HTML中添加：
<script src="https://unpkg.com/foldables.js@latest/dist/foldables.min.js"></script>
2. npm安装（推荐生产环境）
npm install foldables.js --save
引入方式（ES6模块）：
import {
Foldables } from 'foldables.js';
二、核心API使用指南
1. 初始化折叠屏检测器
创建Foldables实例，用于获取状态和监听事件：
// 初始化实例
const fold = new Foldables();
2. 获取当前折叠状态
通过getCurrentState()方法获取设备当前的折叠信息：
const currentState = fold.getCurrentState();
console.log('当前折叠状态:', currentState);
返回的标准化状态对象包含以下关键信息：
{
isFolded: false, // 是否折叠（true=折叠，false=展开）
segments: [ // 视口分割区域数组
{
width: 650, height: 900 }, // 左侧区域尺寸
{
width: 1300, height: 900 } // 右侧区域尺寸
],
foldPosition: 650, // 折痕位置（水平折叠时为X坐标）
orientation: 'horizontal',// 折叠方向（horizontal/vertical）
source: 'standard' // 数据来源（standard/vendor/fallback）
}
3. 监听折叠状态变化
通过addEventListener监听foldchange事件，在折叠/展开切换时触发：
// 监听状态变化
fold.addEventListener('foldchange', (event) => {
const newState = event.detail;
// 根据新状态切换页面样式
if (newState.isFolded) {
// 折叠状态：单屏布局
document.body.classList.add('folded');
document.body.classList.remove('unfolded');
console.log('设备已折叠，切换为紧凑布局');
} else {
// 展开状态：双屏布局
document.body.classList.add('unfolded');
document.body.classList.remove('folded');
console.log(`设备已展开，折痕位置：${
newState.foldPosition}px`);
}
});
4. 安全区域计算（避免折痕遮挡）
使用getSafeArea()方法获取避开折痕的安全区域参数：
// 获取安全区域（单位：px）
const safeArea = fold.getSafeArea();
/*
返回示例：
{
top: 0,
right: 24, // 右侧区域避开折痕的右内边距
bottom: 0,
left: 24 // 左侧区域避开折痕的左内边距
}
*/
// 应用到页面元素
const content = document.querySelector('.main-content');
content.style.paddingLeft = `${
safeArea.left}px`;
content.style.paddingRight = `${
safeArea.right}px`;
5. 获取推荐布局方案
根据当前状态获取建议的布局参数（辅助快速适配）：
const layout = fold.getRecommendedLayout();
/*
折叠状态返回：
{
type: 'single-column',
maxWidth: 480 // 建议的最大宽度
}
展开状态返回：
{
type: 'two-column',
left: { width: 350 }, // 左侧区域建议宽度
right: { width: 650 } // 右侧区域建议宽度
}
*/
三、实际场景示例：响应式布局切换
结合CSS实现折叠/展开状态下的布局自适应：
1. HTML结构
<div class="app-container">
<!-- 侧边栏（展开时显示） -->
<aside class="sidebar">导航菜单</aside>
<!-- 主内容区 -->
<main class="main-content">核心内容</main>
</div>
2. CSS样式
/* 基础样式 */
.app-container {
display: flex;
height: 100vh;
}
.sidebar {
width: 280px;
background: #f5f5f5;
display: none; /* 默认隐藏 */
}
.main-content {
flex: 1;
padding: 16px;
}
/* 展开状态样式（通过JS添加的类名触发） */
.unfolded .sidebar {
display: block; /* 展开时显示侧边栏 */
}
.unfolded .main-content {
padding: 24px;
}
3. JavaScript逻辑
import {
Foldables } from 'foldables.js';
const fold = new Foldables();
// 初始化布局
function initLayout() {
const state = fold.getCurrentState();
document.body.classList.toggle('unfolded', !state.isFolded);
document.body.classList.toggle('folded', state.isFolded);
}
// 监听状态变化并更新布局
fold.addEventListener('foldchange', () => {
initLayout();
// 额外逻辑：如保存滚动位置、刷新数据等
});
// 初始执行
initLayout();
四、注意事项
兼容性处理
- 对于不支持折叠屏API的设备，库会自动降级为基于屏幕宽高比的判断，确保基础兼容性。
- 可通过
fold.isSupported()方法检测设备是否支持高级特性：if (!fold.isSupported()) { console.warn('当前设备不支持折叠屏API，使用降级方案'); }
性能优化
- 状态变化事件可能频繁触发（如折叠过程中），可通过
setTimeout节流：let layoutTimer; fold.addEventListener('foldchange', () => { clearTimeout(layoutTimer); layoutTimer = setTimeout(initLayout, 100); // 100ms防抖 });
- 状态变化事件可能频繁触发（如折叠过程中），可通过
厂商适配
- 针对三星、华为等特定机型，建议在真实设备上测试，库已内置大部分厂商的适配逻辑。
总结
Foldables.js的核心价值在于屏蔽不同折叠屏设备的底层差异，通过统一的API简化状态检测和事件监听。使用时只需：
- 初始化实例并获取当前状态；
- 监听
foldchange事件处理状态切换； - 结合CSS实现布局自适应。
对于需要跨厂商适配折叠屏的H5项目，该库能显著降低开发成本，推荐优先采用。
