Semi Design v2.102.0：DragMove 定位策略更新与中后台升级指南

Semi Design v2.102.0 已发布。这个由字节跳动抖音前端与 UED 团队维护的设计系统，覆盖 React 组件、设计语言和主题能力，主要服务于中后台应用。本次更新中值得关注的是 DragMove 组件新增 positionStrategy 属性，让拖拽元素的定位方式可以显式配置。

为什么拖拽组件需要定位策略

拖拽看起来只是修改坐标，实际却受到 CSS 定位上下文、滚动容器、祖先元素和页面布局方式的共同影响。

例如，一个可拖动面板可能需要相对业务容器移动，而不是相对整个视口移动。如果组件内部默认采用固定定位或绝对定位，开发者往往需要额外计算容器偏移量；页面滚动、侧边栏收缩或父节点增加 transform 后，坐标还可能出现跳变。

DragMove 新增 positionStrategy，意味着调用方可以更明确地表达定位意图。来源摘要中的属性值被截断为 positionStrategy="relat..."，因此实际可用枚举值应以 v2.102.0 的 TypeScript 类型声明或正式变更记录为准，不应仅凭截断文本推断生产配置。

升级并核对真实 API

现有项目可以先锁定版本安装，避免包管理器自动拉取后续版本，干扰验证结果：

npm install @douyinfe/semi-ui@2.102.0
npm list @douyinfe/semi-ui

使用 pnpm 的项目可以执行：

pnpm add @douyinfe/semi-ui@2.102.0 --save-exact
pnpm list @douyinfe/semi-ui

由于摘要没有给出 positionStrategy 的完整类型，安装后可以直接检查包内声明。这比猜测字符串值更可靠：

rg -n "positionStrategy|interface.*DragMove|type.*DragMove" node_modules/@douyinfe/semi-ui

如果环境没有 rg，可以使用：

grep -RIn "positionStrategy" node_modules/@douyinfe/semi-ui | head -20

重点确认三件事：属性接受哪些值、默认值是否改变、该属性影响的是拖拽节点还是辅助层。TypeScript 项目还会在传入错误枚举时直接给出编译提示。

可以这样实践：在隔离页面验证拖拽行为

下面是一个可改造的 React 验证页面。示例假设类型声明确认 relative 是合法值；运行前请根据本地 v2.102.0 声明调整 positionStrategy，并按项目中 DragMove 的实际导出路径和回调签名修改代码。

import React, { useState } from 'react';
import { DragMove, Typography } from '@douyinfe/semi-ui';

export default function DragMoveCheck() {
  const [position, setPosition] = useState({ x: 24, y: 24 });

  return (
    <div
      style={{
        position: 'relative',
        width: 640,
        height: 360,
        overflow: 'auto',
        border: '1px solid var(--semi-color-border)',
      }}
    >
      <DragMove
        positionStrategy="relative"
        onChange={(next: { x: number; y: number }) => setPosition(next)}
      >
        <div
          style={{
            position: 'absolute',
            left: position.x,
            top: position.y,
            width: 180,
            padding: 16,
            cursor: 'move',
            background: 'var(--semi-color-bg-2)',
            border: '1px solid var(--semi-color-border)',
          }}
        >
          <Typography.Text>拖动并观察容器滚动后的坐标</Typography.Text>
        </div>
      </DragMove>
    </div>
  );
}

验证时不要只测试鼠标移动。应让外层容器产生滚动，分别检查页面顶部和页面底部的拖拽结果；再给父节点添加 transform: translateZ(0)，观察定位上下文变化后是否仍符合预期。若项目支持触摸端，还需要覆盖 Pointer Events 或触摸事件。

中后台项目的升级边界

Semi Design 不只是组件集合，还包含主题和设计语言。升级前应检查锁文件中相关 Semi 包是否保持兼容版本，避免核心组件、图标和主题包出现不一致。对于已经封装过拖拽面板、浮层编辑器或可视化搭建器的项目，建议优先测试这些二次封装，而不是只查看基础组件示例。

可以按下面的清单推进：

• 将版本固定到 2.102.0，保留可重复安装的锁文件。
• 从 TypeScript 声明确认 positionStrategy 的完整取值和默认行为。
• 覆盖普通页面、滚动容器、带 transform 的祖先节点和缩放场景。
• 检查拖拽边界、坐标持久化以及服务端渲染时对浏览器对象的访问。
• 通过视觉回归测试确认主题、间距和浮层层级没有意外变化。

positionStrategy 解决的是一个具体但常见的工程问题：拖拽坐标究竟依附于哪个定位上下文。采用新版本时，最稳妥的方式是先从本地类型声明获得准确契约，再用接近真实页面结构的隔离场景验证，而不是直接在复杂业务页面中替换版本。