npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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