企业官网建设流程全解析

• 前端
• CMS

导读

本文围绕 wp-calypso 仓库中 packages/viewport-react/CHANGELOG.md 记录的版本演进脉络，系统讲解@automattic/viewport-react这个从 Calypso 中提取的 React 视口（viewport）辅助包：它提供了一系列 React Hooks 与高阶组件（HOC），用于识别并实时跟踪浏览器视口尺寸变化，从而让开发者轻松实现"桌面端 / 移动端显示不同组件"的响应式逻辑。读完本文，你将掌握useBreakpoint、useMobileBreakpoint、useDesktopBreakpoint三个 Hook 及withBreakpoint等 HOC 的完整用法、全部受支持断点的边界语义，并理解其底层如何通过@automattic/viewport与window.matchMedia协作工作，以及 1.0.0 → 1.0.2 → 1.0.3 三次发版背后的工程考量。

一、CHANGELOG 概览：三次发版，三个关键决策

packages/viewport-react/CHANGELOG.md 记录了这个包的全部历史版本，虽然条目不多，但每一次发版都对应一个真实的工程决策：

从 packages/viewport-react/package.json 可以证实 1.0.2 与 1.0.3 的落地细节：

{ "name": "@automattic/viewport-react", "version": "1.0.3", "dependencies": { "@automattic/viewport": "workspace:^", "@wordpress/compose": "^8.2.0" }, "peerDependencies": { "react": "^18.3.1 || ^19.0.0", "react-dom": "^18.3.1 || ^19.0.0" } }

可以看到：

• React 19 兼容（1.0.2）：peerDependencies同时声明了react与react-dom的^18.3.1 || ^19.0.0双版本范围，这就是 CHANGELOG 中"Declare React 19 compatibility for package consumers"的源码体现。注意 CHANGELOG 中 1.0.2 与 1.0.3 的顺序：实际上 packages/viewport/CHANGELOG.md 的同名 React 19 声明条目为1.1.1，而 viewport-react 中对应1.0.2，两个包各自独立版本号但同步处理兼容性声明，属于同一轮工程改动（#111721）在两个包中的分别落地。
• npm 可安装的 compose 依赖（1.0.3）：@wordpress/compose采用^8.2.0的常规 semver 范围而非workspace:^，这正是"Use an npm-installable@wordpress/composedependency range for package consumers"的意图——createHigherOrderComponent来自该包，包在发布后需要能被外部消费者通过 npm registry 正常安装解析。
• 该包以 GPL-2.0-or-later 协议开源，构建脚本为transpile（产出dist/cjs与dist/esm两种格式），并设置了publishConfig.access: "public"，说明其定位是公开 npm 包。

二、包的作用与定位：React 侧的视口跟踪帮手

正如 packages/viewport-react/README.md 开篇所述：本包"包含识别并跟踪视口变化的 React 辅助工具，可用于根据桌面或移动视图显示不同组件"。而纯函数（vanilla）版本则放在@automattic/viewport包中，两个包各司其职、相互引用。

从源码结构看（src/index.jsx），这个包对外只导出一个文件、一套 API：

• 3 个 Hooks：useBreakpoint( breakpoint )、useMobileBreakpoint()、useDesktopBreakpoint()
• 3 个 HOC：withBreakpoint( breakpoint )( WrappedComponent )、withMobileBreakpoint( WrappedComponent )、withDesktopBreakpoint( WrappedComponent )

同时 types.d.ts 为 TypeScript 使用者提供了完整的类型声明：

declare module '@automattic/viewport-react' { export const useMobileBreakpoint: () => boolean; export const useDesktopBreakpoint: () => boolean; export const useBreakpoint: ( breakpoint: string ) => boolean; }

三、Hook 用法：一行代码响应视口变化

3.1 useBreakpoint：任意断点的状态 Hook

import { useBreakpoint } from '@automattic/viewport-react'; export default function MyComponent( props ) { const isWide = useBreakpoint( '>1280px' ); return <div>Screen size: { isWide ? 'wide' : 'not wide' }</div>; }

从 src/index.jsx 的源码可以看到它的完整实现逻辑：

1. 用useState初始化{ isActive, breakpoint }，其中isActive直接调用底层isWithinBreakpoint( breakpoint )获取当前状态；
2. 在useEffect中调用subscribeIsWithinBreakpoint( breakpoint, handleBreakpointChange )注册监听，并把返回的unsubscribe函数作为 effect 清理函数——组件卸载时自动取消订阅，无需手动清理；
3. 回调里通过"前后状态对比"避免无意义的重复渲染：只有当isActive或breakpoint真正变化时才setState，否则原样返回 prevState 让 React 跳过本次渲染；
4. 返回值做了兜底处理：breakpoint === state.breakpoint ? state.isActive : isWithinBreakpoint( breakpoint )，处理useEffect尚未随新断点重跑时的短暂窗口期。

3.2 useMobileBreakpoint / useDesktopBreakpoint：语义化快捷方式

import { useMobileBreakpoint } from '@automattic/viewport-react'; export default function MyComponent( props ) { const isMobile = useMobileBreakpoint(); return <div>Screen size: { isMobile ? 'mobile' : 'not mobile' }</div>; }

这两个 Hook 本质上是useBreakpoint的封装：useMobileBreakpoint()等价于useBreakpoint( MOBILE_BREAKPOINT )，useDesktopBreakpoint()等价于useBreakpoint( DESKTOP_BREAKPOINT )。其中常量定义在底层包 packages/viewport/src/index.ts：

export const MOBILE_BREAKPOINT = '<480px'; export const DESKTOP_BREAKPOINT = '>960px'; export const WIDE_BREAKPOINT = '>1280px';

也就是说，移动端 = 视口宽度 ≤ 480px，桌面端 = 视口宽度 ≥ 961px（边界语义见第四节）。

四、HOC 用法：为类组件注入 isBreakpointActive

4.1 withBreakpoint：通用断点注入

import { withBreakpoint } from '@automattic/viewport-react'; class MyComponent extends React.Component { render() { const { isBreakpointActive: isMobile } = this.props; return <div>Screen size: { isMobile ? 'mobile' : 'not mobile' }</div>; } } export default withBreakpoint( '<480px' )( MyComponent );

4.2 withMobileBreakpoint / withDesktopBreakpoint：预设断点注入

import { withMobileBreakpoint } from '@automattic/viewport-react'; class MyComponent extends React.Component { render() { const { isBreakpointActive: isMobile } = this.props; return <div>Screen size: { isMobile ? 'mobile' : 'not mobile' }</div>; } } export default withMobileBreakpoint( MyComponent );

从 src/index.jsx 源码可以看到，所有 HOC 都基于@wordpress/compose的createHigherOrderComponent构建（这正是 CHANGELOG 1.0.3 调整依赖的@wordpress/compose），并统一做了两点增强：

• 内部复用useBreakpointHook，保持函数组件与类组件两条使用路径的行为完全一致；
• 通过forwardRef透传ref，让被包装组件可以正常接收 ref，不会因 HOC 包装而丢失。

三个 HOC 注入的 prop 名统一为isBreakpointActive，语义一致、易于记忆。

五、受支持的断点列表与边界语义（重点）

5.1 完整断点列表

packages/viewport-react/README.md 明确列出了全部 17 个受支持断点：

• 上限类（max）：'<480px'、'<660px'、'<800px'、'<960px'、'<1040px'、'<1280px'、'<1400px'
• 下限类（min）：'>480px'、'>660px'、'>800px'、'>960px'、'>1040px'、'>1280px'、'>1400px'
• 区间类：'480px-660px'、'480px-960px'、'660px-960px'

值得注意的是：底层 viewport 包实际支持更多断点（见 packages/viewport/src/index.ts 的mediaQueryOptions），额外包含'<782px'、'<1180px'、'>=782px'、'>782px'、'>=960px'等。从源码结构看，viewport-react 的 README 列表是其中面向 React 使用者的"推荐公开集合"，若需要更细粒度断点，可直接使用@automattic/viewport包（如isWithinBreakpoint( '<782px' )），详见 packages/viewport/README.md。

5.2 边界语义：最小值排他、最大值包含

这是使用断点最容易踩坑的地方，README 与底层源码都专门强调，与 Calypso 的 Sass media query mixin 实现保持一致：

即：最小值是排他的（exclusive），最大值是包含的（inclusive）。这直接决定了DESKTOP_BREAKPOINT = '>960px'对应(min-width: 961px)而非(min-width: 960px)，也解释了为什么useDesktopBreakpoint在移动端返回false的边界恰好卡在 961px。

底层实现 packages/viewport/src/index.ts 的createMediaQueryList印证了这一点：解析{ min, max }配置时，浏览器端会拼出(min-width: ${ min + 1 }px)（min 加 1 实现排他）与(max-width: ${ max }px)（max 原样包含）的媒体查询字符串。

六、底层原理：与 window.matchMedia 的协作

6.1 调用链

@automattic/viewport-react本身不直接操作 DOM，而是完全委托给@automattic/viewport：

useBreakpoint / withBreakpoint │ ▼ isWithinBreakpoint( breakpoint ) / subscribeIsWithinBreakpoint( breakpoint, listener ) │ ▼ getMediaQueryList( breakpoint ) ──► mediaQueryOptions[ breakpoint ] │ ▼ createMediaQueryList( { min, max } ) ──► window.matchMedia( '(min-width: …px) and (max-width: …px)' )

关键点（见 packages/viewport/src/index.ts）：

• getMediaQueryList对未定义/未知的断点会通过console.warn输出'Undefined breakpoint used in mobile-first-breakpoint'警告并返回undefined，此时isWithinBreakpoint返回undefined（而非布尔值）；
• subscribeIsWithinBreakpoint在非服务端环境下，通过mediaQueryList.addListener注册监听，并返回一个移除该监听的取消订阅函数；在服务端（无window.matchMedia）则返回 noop；
• 由于包装层把MediaQueryList的事件对象解构为evt.matches再回调，React Hook 拿到的一直是布尔值，类型干净。

6.2 服务端渲染（SSR）的兜底

packages/viewport/src/index.ts 中有一个值得注意的工程细节：

// FIXME: We can't detect window size on the server, so until we have more intelligent detection, // use 769, which is just above the general maximum mobile screen width. const SERVER_WIDTH = 769; const isServer = typeof window === 'undefined' || ! window.matchMedia;

服务端无法获取真实窗口尺寸，因此使用固定值769（略高于一般手机最大屏幕宽度）作为模拟宽度来参与断点计算。这意味着在 SSR 场景下，useBreakpoint首次渲染的结果是"预估值"而非真实值，真实值会在浏览器端useEffect注册监听后校正——这是使用本包做服务端渲染时必须知晓的限制。

6.3 类型体系

底层包同时导出了完整的类型定义（packages/viewport/src/index.ts）：QueryOption（{ min?, max? }）、QueryItem、ListenerCallback、MinimalMediaQueryList等，为viewport-react的类型声明提供了坚实基础。MinimalMediaQueryList抽象了addListener/removeListener与matches，让服务端 mock（无实际监听能力）与浏览器真实MediaQueryList可以统一处理。

七、测试验证：三个 Hook 与三个 HOC 的行为保证

packages/viewport-react/test/index.js 是理解这个包行为的权威依据。测试文件在 jsdom 环境下 mock 了window.matchMedia，通过维护listeners映射、用callQueryListeners手动触发监听回调来模拟窗口 resize。核心覆盖场景包括：

• 初始状态正确：渲染三个相同组件，container.textContent为'truetruetrue'，且注册了 3 个监听；
• resize 实时更新：向监听回调传入false后，三个组件全部变为'falsefalsefalse'；
• 卸载自动清理：组件卸载后，listeners[ query ].length归零，验证useEffectcleanup 生效；
• 未知断点安全：useBreakpoint()不传参或传'unknown'均返回undefined（对应底层getMediaQueryList的警告与undefined返回）；
• 断点切换：Hook 从'<960px'切换到'<480px'后，旧查询(max-width: 960px)的监听被移除（length 0），新查询(max-width: 480px)的监听建立（length 1）；
• 预设断点映射正确：useMobileBreakpoint对应(max-width: 480px)，useDesktopBreakpoint对应(min-width: 961px)——再次印证"最大值包含、最小值排他"的语义。

此外，测试文件头部的/* @jest-environment jsdom */与globalThis.IS_REACT_ACT_ENVIRONMENT = true表明其使用 jsdom 环境 + Reactact()统一包裹渲染与事件触发，是 React 18/19 下规范的组件测试写法；包配置的 jest 预设见 packages/viewport-react/jest.config.js。

八、版本演进带来的工程启示

把 packages/viewport-react/CHANGELOG.md 放在整个 wp-calypso 单体仓库（monorepo）语境下看，三次发版恰好呈现了"从内部模块到成熟 npm 包"的完整路径：

1. 1.0.0（提取发布）：与底层@automattic/viewport的 1.0.0 同步从 Calypso 中抽出，属于"先独立、再打磨"的策略——React 侧与 vanilla 侧分别封装，各自维护版本；
2. 1.0.2（生态适配）：React 19 发布后，通过peerDependencies声明双版本兼容，这一改动的价值在于让包消费者（而非包作者）在安装解析时得到正确的版本约束提示，避免 peer dependency 冲突；
3. 1.0.3（消费侧可用性）：将@wordpress/compose从 workspace 内部依赖改为 npm 可安装的^8.2.0范围，解决外部项目安装时"找不到 workspace 包"的解析问题。

对比 packages/viewport/CHANGELOG.md 可以看出，vanilla 包在提取后还经历了 TypeScript 迁移（#59031）、类型注解修复（#59875）、新增isTabletResolution/resolveDeviceTypeByViewPort方法（#48728）、补充'<782px'/'>782px'断点（#48803）等持续演进，而 React 包装层保持 API 稳定——这本身就是"薄封装层 + 厚底层实现"架构设计的体现：React 层只做状态订阅与渲染绑定，断点解析、SSR 兜底、媒体查询构造等复杂逻辑全部下沉到 viewport 包，这也是该包从 1.0.0 到 1.0.3 API 几乎无破坏性变更的原因。

九、小结：如何选用 Hook 还是 HOC

综合 README、源码与测试，选型建议如下：

• 函数组件优先使用 Hook：useMobileBreakpoint()/useDesktopBreakpoint()语义清晰，自定义断点用useBreakpoint( '>1400px' )；
• 类组件（或需要向任意组件注入能力时）使用 HOC：withBreakpoint( breakpoint )( Comp )以isBreakpointActiveprop 注入，且通过forwardRef保持 ref 可用；
• 非 React 场景（如纯 JS 逻辑、事件监听、需要getWindowInnerWidth的场景）直接使用@automattic/viewport的isDesktop/isMobile/subscribeIsDesktop/subscribeIsMobile等 vanilla 方法（packages/viewport/README.md）；
• 牢记边界语义：min 排他、max 包含，'>960px'≠(min-width: 960px)而是(min-width: 961px)；
• 留意 SSR 限制：服务端首屏基于固定宽度 769 的估算值，真实值以浏览器端订阅后的回调为准。

wp-calypso 正是依托这套 viewport 工具链，在整个产品的组件层实现了"桌面 / 移动 / 平板视图下差异化渲染"的响应式能力；理解本包的版本演进与实现细节，有助于你在自己的 React 项目中正确复用这套成熟方案，或在阅读 wp-calypso 源码时快速定位其响应式分支逻辑。

• 前端
• CMS