企业官网建设流程全解析

• 前端
• UI组件

在 React 项目中，官方并不推荐直接操作 DOM，而是主张通过状态与虚拟 DOM 驱动界面。但在 RSUITE 组件内部，出于测量尺寸、定位浮层、切换主题类名、监听原生事件等现实需要，仍不得不直接操作真实 DOM。RSUITE 为此封装了一组开箱即用的 DOM 工具方法DOMHelper。读完本篇，你将掌握DOMHelper的导入方式、class/style/events/scroll/query 五大类 API 的完整签名与实战示例，并理解其底层基于dom-lib的实现机制以及在 RSUITE 源码中的真实应用场景。

为什么需要 DOMHelper

原文档开宗明义：在 React 项目中，我们不推荐直接操作 DOM，但是在 RSUITE 组件内部，为了一些考虑不得不直接操作 DOM。如果你在业务开发中也有类似需求（例如需要动态切换元素样式类、测量元素偏移、监听并解绑原生事件、控制页面滚动、实现拖拽交互），可以直接复用这组方法，而不必再依赖 jQuery 或自行封装。

从源码看，DOMHelper本质上是对dom-lib工具的二次包装：src/DOMHelper/index.ts 中export * from 'dom-lib'，并将所有方法合并到DOMHelper对象上，同时补充了 RSUITE 自定义的isElement方法：

import * as helpers from 'dom-lib'; import isElement from './isElement'; export * from 'dom-lib'; export const DOMHelper = { ...helpers, isElement }; export default DOMHelper;

其中isElement用于判断一个值是否为元素节点（实现见 src/DOMHelper/isElement.ts），其逻辑为value?.nodeType === 1 && typeof value?.nodeName === 'string'，对应的单元测试覆盖了 HTML 元素、SVG 元素、文本节点、文档片段等边界情况（见 src/DOMHelper/test/isElement.spec.ts）。dom-lib是 RSUITE 的核心依赖之一，版本为^3.3.1（见 package.json#L68）。

获取方法：如何引入 DOMHelper

DOMHelper与Schema、Whisper、CustomProvider等一样属于无样式组件（见导入指引实现 docs/components/ImportGuide/ImportGuide.tsx#L5-L17），因此引入时无需额外导入任何 CSS。官方文档页提供了两种引入方式（对应 docs/pages/components/dom-helper/index.tsx 中ImportGuide components={['DOMHelper']}渲染的 Main / Individual 两种模式）：

方式一：从主包统一引入（推荐）

import { DOMHelper } from 'rsuite';

方式二：按需单独引入

import DOMHelper from 'rsuite/DOMHelper';

两种方式得到的DOMHelper对象都包含hasClass、addClass、removeClass、toggleClass、addStyle、removeStyle、getStyle、on、off、scrollLeft、scrollTop、getHeight、getWidth、getOffset、getOffsetParent、getPosition、contains、DOMMouseMoveTracker、isElement等全部方法（RSUITE 主入口在 src/index.tsx#L143 处export * from './DOMHelper'）。

class 操作：hasClass / addClass / removeClass / toggleClass

这一组方法用于对元素的 CSS 类名进行判断与增删切换，类型签名如下：

hasClass: (node: HTMLElement, className: string) => boolean; addClass: (node: HTMLElement, className: string) => HTMLElement; removeClass: (node: HTMLElement, className: string) => HTMLElement; toggleClass: (node: HTMLElement, className: string) => HTMLElement;

官方示例（片段见 docs/pages/components/dom-helper/fragments/class-helper.md）演示了四者的配合使用：

import { ButtonToolbar, Button, DOMHelper } from 'rsuite'; const { addClass, removeClass, toggleClass, hasClass } = DOMHelper; const App = () => { const [html, setHtml] = React.useState('<div class="view"></div>'); const containerRef = React.useRef(); const viewRef = React.useRef(); const viewHtmlCode = () => { setHtml(containerRef.current.innerHTML); }; return ( <div> <div>{html}</div> <div ref={containerRef}> <div className="view" ref={viewRef} /> </div> <hr /> <ButtonToolbar> <Button onClick={() => { addClass(viewRef.current, 'custom'); viewHtmlCode(); }}> addClass </Button> <Button onClick={() => { removeClass(viewRef.current, 'custom'); viewHtmlCode(); }}> removeClass </Button> <Button onClick={() => { toggleClass(viewRef.current, 'custom'); viewHtmlCode(); }}> toggleClass </Button> <Button onClick={() => { alert(hasClass(viewRef.current, 'custom')); }}> hasClass </Button> </ButtonToolbar> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

用法要点：

• addClass(node, 'custom')为目标节点追加类名；removeClass移除类名；toggleClass在「有则移除、无则添加」之间切换；hasClass返回布尔值判断类名是否存在。
• 入参node必须是真实 DOM 节点，因此实践中通常配合ref获取（如上例viewRef.current）。

RSUITE 源码中的应用：主题切换是addClass/removeClass的典型真实场景。src/CustomProvider/CustomProvider.tsx#L47-L58 中，CustomProvider在theme变化时向document.body添加当前主题类名（如rs-theme-dark），并移除其余主题类名以避免样式冲突：

useIsomorphicLayoutEffect(() => { if (canUseDOM && theme) { addClass(document.body, prefix(classPrefix, `theme-${theme}`)); // Remove the className that will cause style conflicts themes.forEach(t => { if (t !== theme) { removeClass(document.body, prefix(classPrefix, `theme-${t}`)); } }); } }, [classPrefix, theme]);

style 操作：addStyle / removeStyle / getStyle

这组方法支持单属性与对象两种传参形态，签名如下：

addStyle: (node: HTMLElement, property: string, value: string) => void; addStyle: (node: HTMLElement, style: Object) => void; removeStyle: (node: HTMLElement, property: string) => void; removeStyle: (node: HTMLElement, propertys: Array<string>) => void; getStyle: (node: HTMLElement, property: string) => string; getStyle: (node: HTMLElement) => Object;

官方示例（片段见 docs/pages/components/dom-helper/fragments/style-helper.md）：

import { ButtonToolbar, Button, DOMHelper } from 'rsuite'; const { addStyle, removeStyle, getStyle } = DOMHelper; const App = () => { const [html, setHtml] = React.useState('<div class="view"></div>'); const containerRef = React.useRef(); const viewRef = React.useRef(); const viewHtmlCode = () => { setHtml(containerRef.current.innerHTML); }; return ( <div> <div> {html}</div> <div ref={containerRef}> <div className="view" ref={viewRef} /> </div> <hr /> <ButtonToolbar> <Button onClick={() => { addStyle(viewRef.current, { 'font-size': '16px', color: '#F00' }); viewHtmlCode(); }} > addStyle </Button> <Button onClick={() => { removeStyle(viewRef.current, ['font-size', 'color']); viewHtmlCode(); }} > removeStyle </Button> <Button onClick={() => { console.log(getStyle(viewRef.current)); alert(getStyle(viewRef.current, 'font-size')); }} > getStyle </Button> </ButtonToolbar> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

用法要点：

• addStyle既可传(node, property, value)设置单个属性，也可传(node, { 'font-size': '16px', color: '#F00' })批量设置；批量场景下的样式属性名需遵循 CSS 写法（如font-size而非fontSize）。
• removeStyle支持移除单个属性（传字符串）或批量移除（传属性名数组）。
• getStyle不传属性名时返回节点的完整样式对象，传入属性名时返回该属性的字符串值（如getStyle(node, 'font-size')返回'16px'）。

events 事件绑定：on / off

on与off提供比原生addEventListener更便于管理的绑定/解绑接口，签名如下：

on: (target: HTMLElement, eventName: string, listener: Function, capture: boolean = false) => {off: Function}; off: (target: HTMLElement, eventName: string, listener: Function, capture: boolean = false) => void;

其中on的返回值是一个包含off方法的对象，可直接调用off()完成解绑，无需再持有原始 listener 引用。官方示例（片段见 docs/pages/components/dom-helper/fragments/event-helper.md）：

import { ButtonToolbar, Button, DOMHelper } from 'rsuite'; const { on, off } = DOMHelper; const App = () => { const btnRef = React.useRef(); const listenerRef = React.useRef(); const handleOnEvent = () => { if (!listenerRef.current) { listenerRef.current = on(btnRef.current, 'click', () => { alert('click'); }); } }; const handleOffEvent = () => { if (listenerRef.current) { listenerRef.current.off(); listenerRef.current = null; } }; return ( <div> <div> <button ref={btnRef}>click me</button> </div> <hr /> <ButtonToolbar> <Button onClick={handleOnEvent}>on</Button> <Button onClick={handleOffEvent}>off</Button> </ButtonToolbar> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

用法要点：

• 第一次点击「on」时通过on(target, 'click', listener)绑定事件，并把返回的{ off }对象存入 ref；之后点击「off」调用listenerRef.current.off()即可解绑。
• 第 4 个可选参数capture默认为false，需要捕获阶段监听时传入true。
• 在 RSUITE 内部，on被广泛用于监听浮层定位、ResizeObserver之外的滚动/事件场景，例如 src/internals/Overlay/Position.tsx#L11 中直接import on from 'dom-lib/on'来监听事件。

scroll 滚动：scrollLeft / scrollTop

这两个方法同时具备getter（读取）与setter（写入）两种形态，且都支持传入window对象，签名如下：

scrollLeft: (node: HTMLElement) => number; scrollLeft: (node: HTMLElement, value: number) => void; scrollTop: (node: HTMLElement) => number; scrollTop: (node: HTMLElement, value: number) => void;

官方示例（片段见 docs/pages/components/dom-helper/fragments/scroll-helper.md）演示了对window的滚动控制：

import { ButtonToolbar, Button, DOMHelper } from 'rsuite'; const { scrollTop } = DOMHelper; const App = () => { return ( <div> <ButtonToolbar> <Button onClick={() => { scrollTop(window, 1500); }} > scrollTop 1500 </Button> <Button onClick={() => { alert(scrollTop(window)); }} > get scrollTop </Button> </ButtonToolbar> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

用法要点：

• 传一个参数为读取：scrollTop(window)返回当前垂直滚动距离（number）；
• 传两个参数为写入：scrollTop(window, 1500)将页面垂直滚动到 1500px 处；
• scrollLeft用法与scrollTop完全一致，对应水平方向；node既可以是任意可滚动元素，也可以是window。

query 查询：尺寸、偏移与包含关系

这一组方法用于获取元素的几何信息与包含关系，签名如下：

getHeight: (node: HTMLElement, client: HTMLElement) => number; getWidth: (node: HTMLElement, client: HTMLElement) => number; getOffset: (node: HTMLElement) => Object; getOffsetParent: (node: HTMLElement) => HTMLElement; getPosition: (node: HTMLElement, offsetParent: HTMLElement) => Object; contains: (context: HTMLElement, node: HTMLElement) => boolean;

官方示例（片段见 docs/pages/components/dom-helper/fragments/query.md）：

import { ButtonToolbar, Button, DOMHelper } from 'rsuite'; const { getOffset, getOffsetParent, getPosition } = DOMHelper; const App = () => { const nodeRef = React.useRef(); return ( <div> <a ref={nodeRef}>Node</a> <ButtonToolbar> <Button onClick={() => { alert(JSON.stringify(getOffset(nodeRef.current))); }} > getOffset </Button> <Button onClick={() => { alert(getOffsetParent(nodeRef.current)); }} > getOffsetParent </Button> <Button onClick={() => { alert(JSON.stringify(getPosition(nodeRef.current))); }} > getPosition </Button> </ButtonToolbar> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

各方法语义说明：

RSUITE 源码中的应用：这类几何查询方法直接支撑着 RSUITE 浮层与选择器组件的定位逻辑。例如 src/internals/Overlay/Position.tsx 中import addStyle from 'dom-lib/addStyle'配合内部calcPosition计算出的坐标，通过addStyle(overlay, getPositionStyle(...))设置浮层位置；src/internals/Picker/hooks/useFocusItemValue.ts#L5 中则通过import { getHeight } from 'dom-lib'获取选项高度用于键盘导航时的滚动定位。

DOMMouseMoveTracker：鼠标拖拽跟踪器

DOMMouseMoveTracker是一个鼠标拖拽跟踪器类，用于在鼠标按下后持续跟踪移动增量并触发回调，签名如下：

new DOMMouseMoveTracker( onMove:(deltaX: number, deltaY: number, moveEvent: Object) => void, onMoveEnd:() => void, container: HTMLElement );

• onMove：鼠标移动时触发，回调参数为本次移动的增量(deltaX, deltaY)以及原生moveEvent；
• onMoveEnd：拖拽结束时触发；
• container：监听鼠标移动事件的容器元素。

官方示例（片段见 docs/pages/components/dom-helper/fragments/dom-mouse-move-tracker.md）用它实现了一个可拖拽按钮：

import { Button, DOMHelper } from 'rsuite'; const { DOMMouseMoveTracker } = DOMHelper; const App = () => { const [left, setLeft] = React.useState(0); const [top, setTop] = React.useState(0); const mouseMoveTracker = React.useRef(); const onMove = React.useCallback((deltaX, deltaY) => { setLeft(x => x + deltaX); setTop(y => y + deltaY); }, []); const onMoveEnd = React.useCallback(() => { if (mouseMoveTracker.current) { mouseMoveTracker.current.releaseMouseMoves(); } }, []); const getMouseMoveTracker = React.useCallback(() => { return mouseMoveTracker.current || new DOMMouseMoveTracker(onMove, onMoveEnd, document.body); }, []); const handleMouseDown = React.useCallback(event => { mouseMoveTracker.current = getMouseMoveTracker(); mouseMoveTracker.current.captureMouseMoves(event); }, []); return ( <div style={{ position: 'relative' }}> {left}, {top} <Button appearance="primary" style={{ position: 'absolute', left, top }} onMouseDown={handleMouseDown} > Drag me </Button> </div> ); }; ReactDOM.render(<App />, document.getElementById('root'));

使用流程可概括为四步：new 创建跟踪器 →captureMouseMoves(event)在 mousedown 时开始跟踪 →onMove回调里累计deltaX/deltaY驱动 UI → 结束时调用releaseMouseMoves()释放事件。这也是典型的「事件捕获 + 增量累计」拖拽模式。

相关实现佐证：RSUITE 的 Slider 组件在拖拽场景使用了dom-lib中机制类似的PointerMoveTracker（见 src/Slider/useDrag.ts#L2-L64），同样包含captureMoves(event)开始跟踪、onMove/onMoveEnd回调、releaseMoves()释放事件的完整生命周期，并支持useTouchEvent: true兼容触摸事件，可作为理解 DOMMouseMoveTracker 拖拽管线的参考实现。

参考及使用的项目

DOMHelper这一组工具的封装思路，参考并借鉴了以下两个开源项目：

• react-bootstrap：其内部 DOM 辅助方法（类名、样式、事件等操作）是本组 API 的重要参考来源；
• facebook/fbjs：Facebook 前端基础设施库，其中的 DOM 操作工具集为本组 API 提供了设计范式。

在 RSUITE 中，这些能力经过dom-lib的整理与 TypeScript 类型化封装后，以DOMHelper的统一形态对外暴露，同时仍在组件内部持续复用（主题切换、浮层定位、选择器滚动、Slider 拖拽等），是理解 RSUITE 底层机制时值得通读的一组实用工具。

• 前端
• UI组件