@ldesign/responsive
v3.2.43
Published
LDesign 响应式契约与纯映射工具
Readme
@ldesign/responsive
LDesign 响应式契约与纯映射工具 — 设备检测、Shell 模式、内容宽度推断、运行时设备策略
概述
@ldesign/responsive 是 LDesign 生态的响应式基础包,提供设备类型推断、Shell 模式解析、内容宽度模式计算与运行时设备适配策略等纯函数工具。它是 框架无关 的(不依赖 Vue 运行时),仅通过宽度断点和运行时特征(UA、触摸支持、指针类型、触控点数)来推断设备状态,可安全地在浏览器与 SSR 环境中共用。
- 设备类型推断:
mobile / tablet / laptop / desktop / ultrawide(+unknown检测兜底) - Shell 模式解析:
desktop / compact / mobile— 控制整体布局形态 - 内容宽度模式:
narrow / normal / wide / ultrawide— 控制内容区域宽度 - 运行时策略:
resolveResponsiveRuntimePolicy/constrainResponsiveDevice约束 App 允许适配的设备集合 - 运行时感知:结合 UA、触摸支持、指针类型、
matchMedia做更准确的设备判断 - 纯函数设计:无副作用,易于测试和复用
安装
pnpm add @ldesign/responsive环境要求
- Node.js
>= 20.19.0 - 运行时仅依赖
@babel/runtime,无其他第三方依赖
特性
- 📱 6 种设备值:mobile → tablet → laptop → desktop → ultrawide(+ unknown 作为检测兜底)
- 🖥 3 种 Shell 模式:desktop / compact / mobile
- 📐 4 级内容宽度:narrow / normal / wide / ultrawide
- 🧠 智能推断:结合 UA + 宽度 + 触摸 + 指针 + 触控点数综合判断
- 🎯 可定制断点:所有断点均可自定义覆盖
- 🔧 运行时策略解析:决定 App 是否适配设备、允许哪些设备、是否实时监听 resize
- ✅ TypeScript:完整类型定义与归一化函数(
normalize*) - ⚡ 零运行时依赖:纯函数实现,极致轻量(SSR 安全)
快速上手
import {
inferDeviceTypeByWidth,
inferRuntimeDeviceType,
resolveShellMode,
resolveContentWidthMode,
} from '@ldesign/responsive'
// 仅按宽度推断设备类型
const device = inferDeviceTypeByWidth(window.innerWidth) // 如 'desktop'
// 综合 UA + 触控 + 指针的更准确推断
const precise = inferRuntimeDeviceType(window.innerWidth)
// 解析布局形态与内容宽度
const shellMode = resolveShellMode(device) // 'desktop' | 'compact' | 'mobile'
const contentMode = resolveContentWidthMode(window.innerWidth) // 'narrow' | 'normal' | 'wide' | 'ultrawide'API 参考
类型定义
| 类型名 | 说明 |
|--------|------|
| LDesignResponsiveDevice | 'mobile' \| 'tablet' \| 'laptop' \| 'desktop' \| 'ultrawide' \| 'unknown' |
| LDesignResponsiveRuntimeDevice | Exclude<LDesignResponsiveDevice, 'unknown'> — 运行时策略可启用的设备 |
| LDesignShellMode | 'desktop' \| 'compact' \| 'mobile' — Shell 布局模式 |
| LDesignContentWidthMode | 'narrow' \| 'normal' \| 'wide' \| 'ultrawide' — 内容宽度模式 |
| LDesignResponsiveDeviceBreakpoints | 设备断点配置接口(5 个最小宽度阈值) |
| LDesignContentWidthBreakpoints | 内容宽度断点配置接口(normal/wide/ultrawide) |
| LDesignResponsiveSnapshot | 响应式快照(deviceType/shellMode/contentWidthMode/logicalWidth/supportsTouch) |
| LDesignRuntimeDeviceInferenceOptions | 运行时设备推断的可选覆盖项(UA/触控/指针等显式传值) |
| LDesignResponsiveRuntimeConfig | App 响应式运行时策略的公开配置形态 |
| LDesignResolvedResponsiveRuntimePolicy | 策略解析结果的标准化形态 |
默认断点常量
DEFAULT_RESPONSIVE_DEVICE_BREAKPOINTS
判断规则为左闭右开区间:
| 断点 | 默认值 | 描述 |
|------|--------|------|
| mobile | 768 | 宽度 < 此值为 mobile |
| tablet | 1024 | mobile ≤ 宽度 < 此值为 tablet |
| laptop | 1440 | tablet ≤ 宽度 < 此值为 laptop |
| desktop | 1920 | laptop ≤ 宽度 < 此值为 desktop |
| ultrawide | 2560 | 宽度 ≥ 此值为 ultrawide |
DEFAULT_CONTENT_WIDTH_BREAKPOINTS
| 断点 | 默认值 | 描述 |
|------|--------|------|
| normal | 1440 | 大于等于此值为 normal,未达为 narrow |
| wide | 1920 | 大于等于此值为 wide |
| ultrawide | 2560 | 大于等于此值为 ultrawide |
DEFAULT_RESPONSIVE_RUNTIME_DEVICES
['mobile', 'tablet', 'laptop', 'desktop', 'ultrawide'] —— 排除了 unknown(它只作为检测兜底)。
核心函数
inferDeviceTypeByWidth(logicalWidth?, breakpoints?)
仅基于宽度推断设备类型。
inferDeviceTypeByWidth(800) // 'tablet'
inferDeviceTypeByWidth(1440) // 'desktop'
inferDeviceTypeByWidth(2560) // 'ultrawide'
inferDeviceTypeByWidth(0) // 'unknown'(宽度无法解析或 ≤ 0 时)inferRuntimeDeviceType(logicalWidth?, options?)
综合 UA、宽度、触摸支持、指针类型、触控点数推断设备类型(更准确)。可传 LDesignRuntimeDeviceInferenceOptions 显式指定并跳过自动检测(SSR 场景常需手动传入);useUA: false 时仅返回宽度推断结果。
inferRuntimeDeviceType(1024, {
userAgent: navigator.userAgent,
supportsTouch: true,
hasFinePointer: false,
})
// 平板 + 触控 + 无精细指针 → 可能返回 'tablet' 而非 'laptop'getRuntimeTouchSupport(explicit?) / getRuntimeFinePointerSupport(explicit?)
运行时环境检测:是否支持触控 / 是否拥有精细指针。支持传入显式值跳过自动检测;自动检测结合 matchMedia('(pointer: coarse)') / navigator.maxTouchPoints / ontouchstart 等多策略;无法判断时返回 undefined。
normalizeResponsiveDevice(value) / normalizeShellMode(value) / normalizeContentWidthMode(value)
将任意输入归一化为合法类型值。注意回退值不同:
normalizeResponsiveDevice非法输入返回'unknown'normalizeShellMode/normalizeContentWidthMode非法输入返回undefined(由调用方决定回退策略)
resolveShellMode(device?, shellMode?)
解析 Shell 模式。显式传入优先,否则根据设备类型自动推断(mobile → mobile、tablet → compact、其他 → desktop)。
resolveShellMode('mobile') // 'mobile'
resolveShellMode('tablet') // 'compact'
resolveShellMode('desktop') // 'desktop'
resolveShellMode('desktop', 'mobile') // 'mobile'(显式优先)resolveContentWidthMode(logicalWidth?, contentWidthMode?, breakpoints?)
解析内容宽度模式。显式值优先,否则按宽度推断,宽度无效默认 'normal'。
resolveContentWidthMode(1200) // 'narrow'
resolveContentWidthMode(1600) // 'normal'
resolveContentWidthMode(2000) // 'wide'
resolveContentWidthMode(2600) // 'ultrawide'createResponsiveSnapshot(options) / resolveResponsiveSnapshot(options)
创建完整的响应式快照对象(LDesignResponsiveSnapshot)。
createResponsiveSnapshot是核心实现:对入参做标准化与兜底推断(contentWidthMode 三级回退:显式值 → 宽度计算 → 设备类型粗略推断),适合参数来源不可靠的场景。resolveResponsiveSnapshot用于合并「已有部分快照」(如 SSR 注入的状态)与独立参数:options.responsive中的值优先,缺失字段回退到deviceType/shellMode等独立参数,最终仍经createResponsiveSnapshot标准化。
const snapshot = createResponsiveSnapshot({
deviceType: 'desktop',
logicalWidth: 1920,
supportsTouch: false,
})
// {
// deviceType: 'desktop',
// shellMode: 'desktop',
// contentWidthMode: 'normal',
// logicalWidth: 1920,
// supportsTouch: false,
// }
// SSR 状态合并:responsive 中已有值优先,缺失字段回退到独立参数
resolveResponsiveSnapshot({
responsive: { deviceType: 'tablet' },
logicalWidth: 1920,
})resolveResponsiveRuntimePolicy(input?)
解析 App 的「响应式/设备适配策略」,返回标准化后的 LDesignResolvedResponsiveRuntimePolicy。直接消费 App 的 responsive 配置,兼容 deviceAdapt、runtime.responsive、runtime.deviceAdapt 等旧别名。
const policy = resolveResponsiveRuntimePolicy({
enabled: true,
devices: ['desktop', 'tablet'],
defaultDevice: 'desktop',
listenResize: true,
resizeDebounce: 180,
})
// {
// enabled: true,
// devices: ['desktop', 'tablet'],
// defaultDevice: 'desktop',
// fallbackDevice: 'desktop',
// listenResize: true,
// resizeDebounce: 180,
// detectOrientation: true,
// useUA: true,
// breakpoints: { ...DEFAULT_RESPONSIVE_DEVICE_BREAKPOINTS },
// }LDesignResponsiveRuntimeConfig 可配置项:
| 字段 | 类型 | 说明 |
|------|------|------|
| enabled | boolean | 是否启用设备适配;置 false 强制桌面模式 |
| devices / enabledDevices | readonly LDesignResponsiveRuntimeDevice[] \| value | App 允许适配到的设备集合(省略使用内置全量集合) |
| defaultDevice | LDesignResponsiveRuntimeDevice | 运行时检测无法得出受支持值时的默认设备 |
| fallbackDevice | LDesignResponsiveRuntimeDevice | 检测结果超出受支持集合时的降级设备 |
| listenResize | boolean | 是否监听窗口 resize 实时切换设备模式,默认 false |
| resizeDebounce | number | 实时 resize 检测防抖延迟,默认 180ms |
| detectOrientation | boolean | 移动/平板横屏是否影响逻辑宽度,默认 true |
| useUA | boolean | 运行时检测是否使用 UA 提示,默认 true |
| breakpoints | Partial<LDesignResponsiveDeviceBreakpoints> | 设备断点覆盖 |
constrainResponsiveDevice(device, policyInput?)
根据解析后的运行时策略(尤其 devices / fallbackDevice / defaultDevice)约束原始设备值,返回受支持列表内的最终设备。桌面级设备(laptop/ultrawide ↔ desktop)与移动级设备(mobile ↔ tablet)之间有就近降级规则。
用法示例
根据宽度生成布局配置
import { inferDeviceTypeByWidth, resolveShellMode, resolveContentWidthMode } from '@ldesign/responsive'
function getLayoutConfig(width: number) {
const device = inferDeviceTypeByWidth(width)
const shellMode = resolveShellMode(device)
const contentMode = resolveContentWidthMode(width)
return {
showSidebar: shellMode === 'desktop',
showCollapsedMenu: shellMode === 'compact',
contentMaxWidth: contentMode === 'narrow' ? 960 : contentMode === 'wide' ? 1440 : '100%',
columns: contentMode === 'ultrawide' ? 4 : contentMode === 'wide' ? 3 : 2,
}
}结合运行时策略约束设备
import { resolveResponsiveRuntimePolicy, constrainResponsiveDevice, inferRuntimeDeviceType } from '@ldesign/responsive'
const policy = resolveResponsiveRuntimePolicy(appConfig.responsive)
const device = inferRuntimeDeviceType(window.innerWidth)
const finalDevice = constrainResponsiveDevice(device, policy)
// finalDevice 一定落在 policy.devices 允许的集合内配置
本包无构建期配置文件;所有行为均通过函数参数注入(断点、UA、触控、指针、运行时策略对象)。App 侧的 responsive 配置结构见上文 LDesignResponsiveRuntimeConfig 表格。
目录结构
responsive/src/
└── index.ts # 单文件实现(类型 + 断点常量 + 推断 + 运行时策略解析)单文件架构,包含:
- 类型定义:
LDesignResponsiveDevice、LDesignShellMode、LDesignContentWidthMode、LDesignResponsiveSnapshot等 - 断点常量:
DEFAULT_RESPONSIVE_DEVICE_BREAKPOINTS、DEFAULT_CONTENT_WIDTH_BREAKPOINTS、DEFAULT_RESPONSIVE_RUNTIME_DEVICES - 核心函数:设备推断、Shell 模式解析、内容宽度模式解析、快照创建、运行时策略解析
- 辅助函数:
normalize*归一化、getRuntime*运行时环境检测
相关包
以下均为 package.json 中声明的直接依赖:
| 包 | 关系 | 说明 |
|----|------|------|
| @babel/runtime | 运行时依赖 | 编译产物辅助函数 |
作为零业务依赖的基础层包,它被生态内多个包消费(如 @ldesign/base 与 @ldesign/desktop-next 均在各自 package.json 中声明依赖本包)。
本地开发
pnpm dev # 启动文档开发环境(ldesign doc:dev)
pnpm build # 构建产物(ldesign build)
pnpm site # 构建文档站点(ldesign doc:build)
pnpm test # 运行测试
pnpm lint # 代码检查
pnpm release # 发布
pnpm repair # 工作区修复(ldesign repair)许可证
ISC © ldesign
