# @kne/responsive-utils > Unified responsive breakpoints, hooks, popup boundary and scroll context for KNE projects. Latest version **0.1.16** (published 2026-09-03) · ISC license · 0 weekly downloads ## Install ```sh npm install @kne/responsive-utils pnpm add @kne/responsive-utils yarn add @kne/responsive-utils bun add @kne/responsive-utils ``` ## Health **Score 65/100 (B)** — status: active. Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.1.16 | | Published | 2026-09-03 | | First published | 2026-07-07 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 0 | | Unpacked size | 449.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 0 | | Author | linzp | | Maintainers | lingtong, yangwang123456, juliewang, metacoo | | Keywords | responsive, breakpoint, useIsMobile | ## Links - npm: https://www.npmjs.com/package/@kne/responsive-utils - Repository: https://github.com/kne-union/responsive-utils - Issues: https://github.com/kne-union/responsive-utils/issues - npm.io page: https://npm.io/package/@kne/responsive-utils ## Recent versions - 0.1.16 (latest) — 2026-09-03 - 0.1.15 — 2026-07-20 - 0.1.14 — 2026-07-17 - 0.1.13 — 2026-07-14 - 0.1.12 — 2026-07-14 - 0.1.10 — 2026-07-13 - 0.1.9 — 2026-07-08 - 0.1.8 — 2026-07-08 - 0.1.7 — 2026-07-08 - 0.1.6 — 2026-07-08 - 0.1.5 — 2026-07-08 - 0.1.4 — 2026-07-08 - 0.1.3 — 2026-07-08 - 0.1.2 — 2026-07-07 - 0.1.1 — 2026-07-07 - … 1 more at https://npm.io/package/@kne/responsive-utils/versions ## README # responsive-utils ### 描述 Unified responsive breakpoints, hooks, popup boundary and scroll context for KNE projects. ### 安装 ```shell npm i --save @kne/responsive-utils ``` ### 概述 ### 统一响应式基础设施 `@kne/responsive-utils` 为 KNE 前端提供统一的断点 token、React Hooks、弹层边界与滚动上下文，避免各业务包各自手写 `768px` / `getPopupContainer`。 ### 推荐接入顺序 1. **快速入门**：按类名标记 boundary / scroll，包一层 `ResponsiveProvider`，用 `useIsMobile` + `usePopupContainer` 2. **ResponsiveProvider**：理解 `viewport`（跟窗口）与 `container`（跟指定宽度）两种模式 3. **目标类名**：掌握 `RESPONSIVE_*_CLASS` —— 多数场景不必手传 ref 4. **布局 Hooks**：`useIsMobile` → `useBreakpoint` → `useMediaQuery` 5. **浮层与滚动**：`usePopupContainer`、`useScrollElement` 6. **移动端弹层**：`useMobilePopupMount`（业务只选 `cover`） 7. **DOM 工具**：无 React 树时的底层解析 ### 主要能力 | 能力 | 入口 | |------|------| | 移动端判定（<768） | `useIsMobile` / `MOBILE_BREAKPOINT` | | 多断点 | `useBreakpoint` / `BREAKPOINTS` | | 任意 media query | `useMediaQuery` | | 弹层挂载边界 | `usePopupContainer` + `RESPONSIVE_BOUNDARY_CLASS` | | 滚动容器 | `useScrollElement` + `RESPONSIVE_SCROLL_CLASS` | | 移动端 Modal / 半屏 | `useMobilePopupMount({ cover })` | | SCSS 容器查询 | `@use '~@kne/responsive-utils/scss' as resp` | ### 常见误区 - 不要手写 `@media (max-width: 768px)` 或自造断点常量；JS 用 Hooks，样式用包内 SCSS mixin - 跟浏览器窗口走用默认 `viewport`；按局部宽度模拟用 `mode="container"` + `containerWidth` - 移动端弹层只选 `cover: 'boundary' | 'viewport'`，不要自己拼挂载节点策略 ### 示例(全屏) #### 示例样式 ```scss /* 示例公用样式：仅用于文档演示，业务项目请按自身设计体系实现 */ .resp-doc-tip { margin-bottom: 12px; } .resp-doc-frame { position: relative; border: 1px solid #d9d9d9; border-radius: 8px; background: #fff; } .resp-doc-frame-label { display: block; margin-bottom: 8px; font-size: 12px; color: rgba(0, 0, 0, 0.45); } .resp-doc-layout { display: flex; min-height: 220px; border: 1px solid #f0f0f0; border-radius: 8px; overflow: hidden; } .resp-doc-sidebar { width: 180px; flex-shrink: 0; padding: 12px; background: #001529; color: #fff; } .resp-doc-sidebar.is-collapsed { width: 56px; } .resp-doc-main { flex: 1; padding: 12px; background: #f5f5f5; } .resp-doc-overflow { position: relative; overflow: hidden; border: 2px solid #ffa39e; border-radius: 8px; padding: 16px; background: #fff2f0; } .resp-doc-phone { position: relative; margin: 0 auto; border: 8px solid #1f1f1f; border-radius: 24px; overflow: hidden; background: #f5f5f5; box-sizing: content-box; } .resp-doc-code-block { margin: 0; padding: 12px; background: #fafafa; border-radius: 6px; font-size: 12px; line-height: 1.6; white-space: pre-wrap; word-break: break-all; } ``` #### 示例代码 - 快速入门 - 推荐最小接入：目标类名 + ResponsiveProvider + useIsMobile + usePopupContainer - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * 快速入门：一条业务页最小接入模板 * * 1. 用目标类名标记 boundary / scroll * 2. 最外层包 ResponsiveProvider（多数场景可省略，靠类名兜底） * 3. 布局用 useIsMobile，浮层用 usePopupContainer */ const { ResponsiveProvider, RESPONSIVE_BOUNDARY_CLASS, RESPONSIVE_SCROLL_CLASS, MOBILE_BREAKPOINT, BREAKPOINTS, useIsMobile, usePopupContainer } = _ResponsiveUtils; const {Alert, Card, DatePicker, Flex, Form, Select, Space, Tag, Typography} = antd; const DEPARTMENT_OPTIONS = [ {label: '研发中心 / 前端组', value: 'fe'}, {label: '研发中心 / 后端组', value: 'be'}, {label: '产品中心 / 用户研究', value: 'research'}, {label: '运营中心 / 增长运营', value: 'growth'} ]; /** 业务组件：只关心「移动还是桌面」「浮层挂到哪」 */ const StaffFilterForm = () => { const isMobile = useIsMobile(); const getPopupContainer = usePopupContainer(); return ( 员工筛选 {isMobile ? '移动布局' : '桌面布局'} } >
在下方滚动区滑动，观察 scrollTop；切换模式 / 宽度观察 isMobile 是否变化。 {Array.from({length: 6}, (_, i) => ( 审批记录 #{2024001 + i} · 差旅报销 ))} ); }; const ResponsiveProviderExample = () => { const [containerMode, setContainerMode] = useState(true); const [containerWidth, setContainerWidth] = useState(375); const boundaryRef = useRef(null); const scrollRef = useRef(null); return (
  • viewport：跟{' '} window 宽度走（默认）
  • container：跟指定的{' '} containerWidth 走，适合嵌入式区域或本地模拟宽度
    • } /> 容器模式 {containerMode && ( 模拟宽度 setContainerWidth(v || 375)} addonAfter="px" /> {result && ( {result.boundary} {result.scroll} {result.popup} )} ); }; const TargetClassesExample = () => { return ( 容器查询宿主（配合 SCSS @include resp.responsive-container ） 弹层挂载边界（Select / DatePicker / Modal） 滚动参照（Affix、BackTop、虚拟列表、锚点） } /> 
    {`
    
  
    
    
    
      {children}
    
    
  
    

    `}
    .{RESPONSIVE_CONTAINER_CLASS}
    .{RESPONSIVE_BOUNDARY_CLASS}
    .{RESPONSIVE_SCROLL_CLASS}
    传 boundaryRef /{' '} scrollRef 时以 ref 为准；没传则按类名从触发器向上找，再回退{' '} body / 文档滚动根。 ); }; render(); ``` - useIsMobile - 按 768px 切换布局：侧栏、订单列表卡片化、容器宽度模拟 - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * useIsMobile：宽度 < 768 时为 true * * 典型用途：侧栏折叠、表格⇄卡片、底部操作栏、表单 vertical/inline * container 模式下看 containerWidth，不看浏览器视口 */ const {ResponsiveProvider, MOBILE_BREAKPOINT, useIsMobile} = _ResponsiveUtils; const {Alert, Card, Col, Flex, InputNumber, Radio, Row, Space, Tag, Typography} = antd; const {useState} = React; const ORDERS = [ {id: 'ORD-20240701-001', customer: '华东分公司', amount: '¥12,800', status: '待发货'}, {id: 'ORD-20240701-002', customer: '华南渠道部', amount: '¥6,420', status: '已发货'}, {id: 'ORD-20240701-003', customer: '华北直客', amount: '¥28,100', status: '待审核'} ]; const OrderBoard = () => { const isMobile = useIsMobile(); return ( 订单列表 {isMobile ? '卡片列表' : '三列栅格'} } extra={ isMobile ? ( 筛选 ) : ( 导出 批量发货 ) } > {isMobile ? ( {ORDERS.map(item => ( {item.id} {item.status} {item.customer} · {item.amount} ))} ) : ( {ORDERS.map(item => ( {item.id}
    {item.customer} · {item.amount}
    {item.status}     ))}     )}     ); }; const Shell = ({children}) => { const isMobile = useIsMobile(); return (
    {!isMobile && (
    导航
    订单
    客户
    库存
    )}
    {isMobile && ( )} {children}
    ); }; const UseIsMobileExample = () => { const viewportIsMobile = useIsMobile(); const [source, setSource] = useState('viewport'); const [containerWidth, setContainerWidth] = useState(414); const board = ( ); return ( setSource(e.target.value)} options={[ {label: '视口（当前浏览器）', value: 'viewport'}, {label: '容器模拟宽度', value: 'container'} ]} />
    视口判定：{' '} {String(viewportIsMobile)} （改变浏览器宽度即可验证）
    {source === 'container' && ( 模拟宽度 setContainerWidth(v || 414)} addonAfter="px" /> setContainerWidth(e.target.value)} options={[ {label: '375', value: 375}, {label: '767', value: 767}, {label: '768', value: 768}, {label: '1024', value: 1024} ]} /> )}     {source === 'container' ? (
    ResponsiveProvider mode="container" containerWidth={containerWidth} {board}
    ) : ( board )}     ); }; render(); ``` - useBreakpoint - xs~xxl 命中状态驱动表格列、侧栏宽度与栅格 - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * useBreakpoint：返回 xs~xxl 是否「达到」该宽度，以及 isMobile * * 适合比「是否移动端」更细的栅格 / 侧栏 / 表格列显隐 * 判定语义：width >= BREAKPOINTS[key] */ const {BREAKPOINTS, ResponsiveProvider, useBreakpoint} = _ResponsiveUtils; const {Alert, Card, Col, Flex, Radio, Row, Space, Table, Tag, Typography} = antd; const {useMemo, useState} = React; const BREAKPOINT_META = [ {key: 'xs', label: '超小屏', hint: '手机竖屏起步'}, {key: 'sm', label: '小屏', hint: '手机横屏 / 小平板'}, {key: 'md', label: '中屏', hint: '平板；移动端阈值'}, {key: 'lg', label: '大屏', hint: '桌面'}, {key: 'xl', label: '超大屏', hint: '宽屏桌面'}, {key: 'xxl', label: '巨屏', hint: '超宽 / 4K'} ]; const STAFF = [ {key: '1', name: '陈晓', dept: '研发中心', city: '上海', role: '前端', phone: '138****1201'}, {key: '2', name: '林舟', dept: '产品中心', city: '北京', role: '产品', phone: '139****8830'}, {key: '3', name: '周宁', dept: '运营中心', city: '深圳', role: '运营', phone: '137****4412'} ]; const StaffTable = () => { const bp = useBreakpoint(); const columns = useMemo(() => { const cols = [ {title: '姓名', dataIndex: 'name'}, {title: '部门', dataIndex: 'dept'} ]; if (bp.md) cols.push({title: '城市', dataIndex: 'city'}); if (bp.lg) cols.push({title: '岗位', dataIndex: 'role'}); if (bp.xl) cols.push({title: '手机', dataIndex: 'phone'}); return cols; }, [bp.md, bp.lg, bp.xl]); const gutter = bp.xxl ? 24 : bp.lg ? 16 : 8; const siderWidth = bp.isMobile ? 0 : bp.xl ? 220 : bp.lg ? 180 : 140; return ( isMobile={String(bp.isMobile)} 可见列数 {columns.length} 栅格 gutter {gutter} {!bp.isMobile && 侧栏 {siderWidth}px}
    {!bp.isMobile && (
    组织树
    研发中心
    产品中心
    )}
    {['在职', '试用', '待入职'].map(label => ( {label}统计卡 ))} ); }; const HitList = () => { const bp = useBreakpoint(); return ( {BREAKPOINT_META.map(({key, label, hint}) => ( {key} {label}（≥{BREAKPOINTS[key]}px） {hint} {bp[key] ? '命中' : '未达'} ))} ); }; const UseBreakpointExample = () => { const [mode, setMode] = useState('viewport'); const [width, setWidth] = useState(1024); const content = ( ); return ( setMode(e.target.value)} options={[ {label: '跟视口', value: 'viewport'}, {label: '模拟宽度', value: 'container'} ]} /> {mode === 'container' && ( setWidth(e.target.value)} options={[ {label: '375 xs', value: 375}, {label: '600 sm', value: 600}, {label: '800 md', value: 800}, {label: '1100 lg', value: 1100}, {label: '1300 xl', value: 1300}, {label: '1700 xxl', value: 1700} ]} /> )} {mode === 'container' ? ( {content} ) : ( content )} ); }; render(); ``` - useMediaQuery - 订阅任意 media query；container 下 max-width 映射到 getIsMobile - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * useMediaQuery：订阅任意 CSS media query * * - 视口模式：标准 matchMedia * - container 模式：含 max-width 的 query 会映射到 Provider.getIsMobile() */ const {ResponsiveProvider, IS_MOBILE_QUERY, useIsMobile, useMediaQuery} = _ResponsiveUtils; const {Alert, Card, Flex, InputNumber, Space, Switch, Tag, Typography} = antd; const {useState} = React; const QUERIES = [ {label: '官方移动端 query', query: IS_MOBILE_QUERY, note: '与 useIsMobile 同源'}, {label: '紧凑布局', query: '(max-width: 576px)', note: '可驱动更窄的表单间距'}, {label: '宽屏工作台', query: '(min-width: 1200px)', note: 'container 下 min-width 仍走真实视口'}, {label: '横屏', query: '(orientation: landscape)', note: '设备方向'}, {label: '深色偏好', query: '(prefers-color-scheme: dark)', note: '系统主题'} ]; const QueryRow = ({label, query, note}) => { const matches = useMediaQuery(query); return (
    {label}
    {query} {note && ( <>
    {note} )}
    {matches ? '匹配' : '不匹配'}     ); }; const Panel = () => { const isMobile = useIsMobile(); return ( useIsMobile {String(isMobile)} {QUERIES.map(item => ( ))} ); }; const UseMediaQueryExample = () => { const [containerMode, setContainerMode] = useState(false); const [containerWidth, setContainerWidth] = useState(500); return ( 容器模式 {containerMode && ( <> containerWidth setContainerWidth(v || 500)} addonAfter="px" /> )} 打开容器模式后，调节宽度观察含 max-width{' '} 的条目；其它 query（横屏、深色、min-width）仍跟随真实浏览器。 {containerMode ? ( ) : ( )} ); }; render(); ``` - usePopupContainer - 对比 overflow:hidden 下未挂载 / 已挂载 antd 浮层 - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * usePopupContainer：给 antd 浮层一个不会被 overflow 裁剪的挂载点 * * 对比：左侧未传 getPopupContainer（易被裁剪），右侧使用 Hook */ const { ResponsiveProvider, RESPONSIVE_BOUNDARY_CLASS, usePopupContainer, useIsMobile } = _ResponsiveUtils; const {Alert, Card, Col, DatePicker, Flex, Row, Select, Tooltip, Typography} = antd; const {useRef} = React; const DEPARTMENT_OPTIONS = [ {label: '研发中心 / 前端组', value: 'fe'}, {label: '研发中心 / 后端组', value: 'be'}, {label: '产品中心 / 设计组', value: 'design'}, {label: '运营中心 / 增长组', value: 'growth'} ]; const BrokenForm = () => ( 未传 getPopupContainer —— 打开下拉看裁剪 悬停 Tooltip ); }; const UsePopupContainerExample = () => { const boundaryRef = useRef(null); return ( const getPopupContainer = usePopupContainer(); {' → '} 传给 Select / DatePicker / Tooltip / Dropdown 的同名 prop。 } />
    页面根节点打上 {RESPONSIVE_BOUNDARY_CLASS}{' '} 后，多数情况不必再传 boundaryRef 。移动端全屏 Modal / 半屏请改用 useMobilePopupMount。 ); }; render(); ``` - useScrollElement - 主内容区滚动监控、回顶与锚点跳转 - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * useScrollElement：拿到真正的滚动根 * * 后台常在「主内容区」滚，而不是 window。锚点、Affix、锁滚动、虚拟列表都需要这个 getter。 */ const { ResponsiveProvider, RESPONSIVE_SCROLL_CLASS, useScrollElement } = _ResponsiveUtils; const {Alert, Button, Card, Flex, Space, Typography} = antd; const {useEffect, useRef, useState} = React; const APPROVALS = Array.from({length: 12}, (_, i) => ({ id: 10086 + i, title: `差旅报销单 #${10086 + i}`, owner: ['陈晓', '林舟', '周宁'][i % 3], status: ['待部门经理', '待财务', '已通过'][i % 3] })); const ScrollToolbar = () => { const getScrollElement = useScrollElement(); const [info, setInfo] = useState({scrollTop: 0, clientHeight: 0, scrollHeight: 0, tag: '-'}); useEffect(() => { const el = getScrollElement(); if (!el) return undefined; const update = () => { setInfo({ scrollTop: Math.round(el.scrollTop || 0), clientHeight: el.clientHeight || 0, scrollHeight: el.scrollHeight || 0, tag: el.className || el.tagName }); }; update(); el.addEventListener('scroll', update, {passive: true}); return () => el.removeEventListener('scroll', update); }, [getScrollElement]); return ( 当前滚动根：{info.tag} scrollTop {info.scrollTop} / 可视 {info.clientHeight} / 总高 {info.scrollHeight}
    ); }; const UseScrollElementExample = () => { const scrollRef = useRef(null); return ( const getScrollElement = useScrollElement(); {' → '} getScrollElement() 得到 HTMLElement，再监听 scroll / scrollTo / 量尺寸。 } />
    {APPROVALS.map(item => ( {item.title}
    {item.owner} · {item.status}     ))}
    也可只标 {RESPONSIVE_SCROLL_CLASS} ，不传 scrollRef。打开弹层锁滚动等场景常与 usePopupContainer{' '} 一起用。     ); }; render(); ``` - useMobilePopupMount - cover=boundary / viewport：对照 container 与 viewport 两种 Provider 模式下的挂载结果 - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd),ReactDOM(react-dom) ```jsx /** * useMobilePopupMount：移动端弹层一站式挂载 * * 业务只选 cover： * - cover='boundary'（默认）：罩住 Provider boundary —— Modal 推荐 * - cover='viewport'：罩住当前移动可视区 —— 半屏 Select / Sheet * · mode=container → 挂 boundary + kne-is-boundary * · mode=viewport 且移动端 → body + kne-is-viewport */ const { ResponsiveProvider, RESPONSIVE_BOUNDARY_CLASS, RESPONSIVE_SCROLL_CLASS, MOBILE_POPUP_MODE, MOBILE_POPUP_COVER, useMobilePopupMount, useResponsiveContext } = _ResponsiveUtils; const {Alert, Button, Card, Descriptions, Flex, Radio, Space, Tag, Typography} = antd; const {useEffect, useMemo, useRef, useState} = React; const {createPortal} = ReactDOM; const PHONE_WIDTH = 375; const PHONE_HEIGHT = 620; const formatMount = node => { if (!node) return '-'; if (node === document.body) return 'document.body'; const cls = node.className || ''; if (cls.includes(RESPONSIVE_BOUNDARY_CLASS)) return `.${RESPONSIVE_BOUNDARY_CLASS}`; return cls || node.tagName; }; /** 演示弹层：按 fixedModeClass 切换 absolute / fixed */ const DemoOverlay = ({open, fixedModeClass, title, onClose, mountNode}) => { if (!open || !mountNode) return null; const useAbsolute = fixedModeClass === MOBILE_POPUP_MODE.boundary; const position = useAbsolute ? 'absolute' : 'fixed'; return createPortal( <>
    {title} fixedModeClass = {fixedModeClass || 'null（桌面）'} mount = {formatMount(mountNode)}
    组件侧 CSS：.kne-is-boundary 用 absolute；.kne-is-viewport 用 fixed。
    , mountNode ); }; const MountDemo = ({cover, title, tip}) => { const {mode} = useResponsiveContext(); const {isMobile, fixedModeClass, getMountNode, getPopupContainer, anchorRef} = useMobilePopupMount({ cover }); const [open, setOpen] = useState(false); const [mountNode, setMountNode] = useState(null); useEffect(() => { if (!open) { setMountNode(null); return; } const trigger = document.querySelector(`[data-cover="${cover}"][data-mode="${mode}"]`); setMountNode(getMountNode(trigger) || getPopupContainer(trigger)); }, [open, cover, mode, getMountNode, getPopupContainer]); return ( cover={cover}} > {tip} {mode} {String(isMobile)} {fixedModeClass || 'null'} {open ? formatMount(mountNode) : '（打开后显示）'}
    setOpen(false)} />     ); }; const ContainerModeDemo = () => { const boundaryRef = useRef(null); const scrollRef = useRef(null); const [containerWidth, setContainerWidth] = useState(PHONE_WIDTH); return ( 按 containerWidth 判定移动端。两种 cover 都应挂在当前 boundary 内，class 为 kne-is-boundary。 } /> setContainerWidth(e.target.value)} options={[ {label: '375 窄屏', value: 375}, {label: '768 临界', value: 768}, {label: '1024 宽屏', value: 1024} ]} />
    滚动后弹层仍相对本 boundary 铺满。
    ); }; const ViewportModeDemo = () => { const boundaryRef = useRef(null); return ( 跟浏览器窗口宽度走。把窗口缩到 <768px 后：
    cover=boundary → 本区 boundary + kne-is-boundary
    cover=viewport → document.body + kne-is-viewport } />
    ); }; const UseMobilePopupMountExample = () => { const [tab, setTab] = useState('container'); const snippet = useMemo( () => `// Modal const { isMobile, getPopupContainer, fixedModeClass, anchorRef } = useMobilePopupMount(); // 半屏 Sheet / Select const sheet = useMobilePopupMount({ cover: 'viewport' }); // Antd `, [] ); return ( {MOBILE_POPUP_MODE.boundary} {MOBILE_POPUP_MODE.viewport} } /> 
            {snippet}
    setTab(e.target.value)} optionType="button" buttonStyle="solid" options={[ {label: '① container 模式', value: 'container'}, {label: '② viewport 模式', value: 'viewport'} ]} /> {tab === 'container' ? : }     ); }; render(); ``` - DOM 工具 - findScrollParent / findResponsive* / resolve* 等底层解析（优先用 Hooks） - _ResponsiveUtils(@kne/current-lib_responsive-utils)[import * as _ResponsiveUtils from "@kne/responsive-utils"],antd(antd) ```jsx /** * DOM 工具：无 React 上下文、或写底层封装时使用 * * 业务组件优先用 Hooks；此处演示纯函数如何解析 boundary / scroll。 */ const { RESPONSIVE_BOUNDARY_CLASS, RESPONSIVE_SCROLL_CLASS, findScrollParent, findResponsiveBoundary, findResponsiveScroll, resolveBoundaryElement, resolveScrollElement, getDefaultBoundaryElement, getDefaultScrollElement } = _ResponsiveUtils; const {Alert, Button, Card, Descriptions, Flex, Typography} = antd; const {useRef, useState} = React; const DomUtilsExample = () => { const boundaryRef = useRef(null); const scrollRef = useRef(null); const anchorRef = useRef(null); const [result, setResult] = useState(null); const inspect = () => { const anchor = anchorRef.current; const scrollParent = findScrollParent(anchor); const byClassBoundary = findResponsiveBoundary(anchor); const byClassScroll = findResponsiveScroll(anchor); setResult({ findScrollParent: scrollParent ? scrollParent.className || scrollParent.tagName : 'null（无可滚动祖先）', findResponsiveBoundary: byClassBoundary ? byClassBoundary.className : 'null', findResponsiveScroll: byClassScroll ? byClassScroll.className : 'null', resolveBoundaryElement: (() => { const el = resolveBoundaryElement(boundaryRef); return el === document.body ? 'document.body' : el.className || el.tagName; })(), resolveScrollElement: (() => { const el = resolveScrollElement(scrollRef, anchor); return el.className || el.tagName; })(), getDefaultBoundaryElement: getDefaultBoundaryElement().tagName, getDefaultScrollElement: getDefaultScrollElement().tagName }); }; return (
    外层 overflow:auto（findScrollParent 可能先命中它）
    锚点元素 — 点下方按钮解析
    {result && ( {Object.entries(result).map(([key, value]) => ( {value} ))} )} resolveBoundaryElement(ref) 优先 ref，否则{' '} body； resolveScrollElement(ref, anchor) 优先 ref，否则从 anchor 找可滚父级 / 文档滚动根。 ); }; render(); ``` ### API ### 怎么选 API | 你想做的事 | 用这个 | |-----------|--------| | 判断是不是移动端 | `useIsMobile` | | 按 xs~xxl 改布局 | `useBreakpoint` | | 任意 media query | `useMediaQuery` | | antd Select / DatePicker 不被裁剪 | `usePopupContainer` + `RESPONSIVE_BOUNDARY_CLASS` | | 拿到主内容滚动根 | `useScrollElement` + `RESPONSIVE_SCROLL_CLASS` | | 移动端 Modal / 半屏挂载 | `useMobilePopupMount({ cover })` | | 按局部容器宽度判定 | `ResponsiveProvider mode="container"` | | 样式断点 | SCSS `@use '~@kne/responsive-utils/scss' as resp` | 完整用法见各 Demo；下面是参数与返回值明细。 ### 断点 Token 统一断点常量，与 SCSS mixin 同源。 #### 导出 | 名称 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `BREAKPOINTS` | `Record` | `{ xs:0, sm:576, md:768, lg:992, xl:1200, xxl:1600 }` | 断点像素值 | | `MOBILE_BREAKPOINT` | `number` | `768` | 移动端阈值，等于 `BREAKPOINTS.md` | | `IS_MOBILE_QUERY` | `string` | `(max-width: 768px)` | `matchMedia` 查询字符串 | | `BREAKPOINT_KEYS` | `string[]` | `['xs','sm','md','lg','xl','xxl']` | 断点 key 列表 | ### SCSS 容器查询使用统一名称 `kne-responsive`（`$responsive-container-name`），业务方无需硬编码。 **宿主元素**（需要容器查询的根节点）： ```scss @use '@kne/responsive-utils/scss' as resp; .page-host { @include resp.responsive-container; } ``` **子元素样式**： ```scss @include resp.mobile-container { ... } @include resp.container-down(md) { ... } @include resp.mobile { ... } // 视口 @media ``` ### 响应式目标类名 | 名称 | 类名 | 用途 | |------|------|------| | `RESPONSIVE_CONTAINER_CLASS` | `kne-responsive-container` | 容器查询宿主（配合 `responsive-container` mixin） | | `RESPONSIVE_BOUNDARY_CLASS` | `kne-responsive-boundary` | 弹层挂载边界（`getPopupContainer` / `usePopupContainer`） | | `RESPONSIVE_SCROLL_CLASS` | `kne-responsive-scroll` | 滚动参照容器（`useScrollElement` / Affix / BackTop） | DOM 查找：`findResponsiveBoundary(anchor)`、`findResponsiveScroll(anchor)`。无自定义注入时 Provider 默认按类名解析，再回退 `body` / `documentElement`。 ```jsx
    {children}
    {children}
    ``` ### 容器查询（JS / 内联样式） | 名称 | 说明 | |------|------| | `containerMobileBlock(rules)` | 生成移动端 `@container` 规则块，无需知道容器名 | | `containerDownBlock('sm', rules)` | 按断点 key 生成容器查询块 | | `RESPONSIVE_CONTAINER_NAME` | 高级场景用，一般不必直接使用 | ```js import { containerMobileBlock } from '@kne/responsive-utils'; const css = ` .box { background: blue; } ${containerMobileBlock('.box { background: green; }')} `; ``` ### ResponsiveProvider 为子树注入响应式上下文，控制移动端判定、弹窗边界与滚动容器。 #### 属性 | 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `mode` | `'viewport' \| 'container'` | `'viewport'` | 视口模式或容器宽度模式 | | `containerWidth` | `number` | - | `container` 模式下用于 `useIsMobile` / `useBreakpoint` 的宽度 | | `getBoundaryElement` | `() => HTMLElement` | - | 自定义弹窗挂载边界 | | `getScrollElement` | `() => HTMLElement` | - | 自定义滚动参照元素 | | `boundaryRef` | `RefObject` | - | 边界 DOM ref，优先级低于 `getBoundaryElement` | | `scrollRef` | `RefObject` | - | 滚动容器 ref | | `scrollAnchorRef` | `RefObject` | - | 从锚点向上解析滚动父级 | ### useIsMobile 判断当前是否为移动端（宽度 < 768px）。 | 返回值 | 类型 | 描述 | |--------|------|------| | `isMobile` | `boolean` | 视口或容器宽度是否小于 `md` | 无 Provider 时回退到 `(max-width: 768px)` 的 `matchMedia`。 ### useBreakpoint 返回各断点命中状态与 `isMobile`。 | 返回值 | 类型 | 描述 | |--------|------|------| | `xs` ~ `xxl` | `boolean` | 当前宽度是否达到对应断点 | | `isMobile` | `boolean` | 同 `useIsMobile` | ### useMediaQuery 订阅任意 CSS media query。 #### 参数 | 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `query` | `string` | - | 标准 media query 字符串 | | 返回值 | 类型 | 描述 | |--------|------|------| | `matches` | `boolean` | 查询是否命中 | `container` 模式下对含 `max-width` 的 query 会映射到 `getIsMobile()`。 ### usePopupContainer 返回 antd `getPopupContainer` 回调。 | 返回值 | 类型 | 描述 | |--------|------|------| | `getPopupContainer` | `() => HTMLElement` | 弹窗挂载边界 getter | ### useScrollElement 返回滚动容器 getter。 | 返回值 | 类型 | 描述 | |--------|------|------| | `getScrollElement` | `() => HTMLElement` | 滚动参照元素 getter | ### 移动端弹层挂载（推荐） 业务只关心「罩住哪」：选 `cover` 即可，挂载节点与定位类名由库根据 Provider 模式自动决定。 #### 常量 | 名称 | 值 | 描述 | |------|-----|------| | `MOBILE_POPUP_MODE.boundary` | `kne-is-boundary` | 相对 boundary `absolute`（组件自行写 CSS） | | `MOBILE_POPUP_MODE.viewport` | `kne-is-viewport` | 相对视口 `fixed` | | `MOBILE_POPUP_COVER.boundary` | `boundary` | 罩住 Provider boundary（**默认**，Modal） | | `MOBILE_POPUP_COVER.viewport` | `viewport` | 罩住当前移动可视区域（半屏 Select） | #### `useMobilePopupMount` ```jsx import { useMobilePopupMount } from '@kne/responsive-utils'; // Modal：默认挂 boundary const { isMobile, getPopupContainer, fixedModeClass, anchorRef } = useMobilePopupMount(); // 底部半屏 const sheet = useMobilePopupMount({ cover: 'viewport' }); ``` | 参数 | 类型 | 默认 | 描述 | |------|------|------|------| | `cover` | `'boundary' \| 'viewport'` | `'boundary'` | 弹层罩住范围 | | `getPopupContainer` | `(trigger?) => HTMLElement \| null` | - | 调用方覆盖挂载节点 | | 返回值 | 类型 | 描述 | |--------|------|------| | `isMobile` | `boolean` | 是否移动端 UI | | `fixedModeClass` | `string \| null` | `kne-is-boundary` / `kne-is-viewport` / 桌面 `null` | | `getMountNode` | `(trigger?) => HTMLElement \| null` | portal 挂载节点 | | `getPopupContainer` | `(trigger?) => HTMLElement` | 可直接给 Antd | | `resolveMount` | `(trigger?) => { isMobile, fixedModeClass, mountNode, ... }` | 命令式打开时按触发点同步解析 | | `anchorRef` | `(node) => void` | 挂到触发器上，便于解析挂载上下文 | 行为摘要： | `cover` | `mode=container`（或嵌套 boundary） | `mode=viewport` 且移动端 | |---------|--------------------------------------|---------------------------| | `boundary` | boundary + `kne-is-boundary` | boundary + `kne-is-boundary` | | `viewport` | boundary + `kne-is-boundary` | `body` + `kne-is-viewport` | 另有 `useMobileFixedMode`、`resolveMobilePopupContainer` 等供高级/测试场景。 ### DOM 工具 | 函数 | 参数 | 返回值 | 描述 | |------|------|--------|------| | `findScrollParent` | `(element: HTMLElement)` | `HTMLElement \| null` | 向上查找最近可滚动祖先 | | `findResponsiveBoundary` | `(anchor?)` | `HTMLElement \| null` | 查找 boundary | | `findResponsiveScroll` | `(anchor?)` | `HTMLElement \| null` | 查找 scroll 容器 | | `resolveMobilePopupContainer` | `(options)` | `HTMLElement \| null` | 纯函数挂载策略 | | `resolveBoundaryElement` | `(boundaryRef?)` | `HTMLElement` | 解析边界元素，默认 `document.body` | | `resolveScrollElement` | `(scrollRef?, anchor?)` | `HTMLElement` | 解析滚动元素，默认文档滚动根 | | `getDefaultScrollElement` | - | `HTMLElement` | 默认滚动根 | | `getDefaultBoundaryElement` | - | `HTMLElement` | 默认 `document.body` | --- _Source: https://npm.io/package/@kne/responsive-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._