refactor(tag-input): extracts the common logic of the scroll (#4210)

RSS1102 · tdesign-bot · web-flow · commit af4690267a53 · 2026-06-26T16:26:01.000+08:00
* refactor(tag-input): 提取滚动逻辑到公共工具函数

* fix(tag-input): 修正 common 子模块为远程可拉取提交

* refactor(tag-input): 滚动逻辑内置至组件 utils

* fix: 修复布局错误

* chore: stash changelog [ci skip]

---------

Co-authored-by: tdesign-bot &lt;tdesign@tencent.com&gt;
diff --git a/packages/components/tag-input/TagInput.tsx b/packages/components/tag-input/TagInput.tsx
@@ -8,6 +8,7 @@ import useControlled from '../hooks/useControlled';
 import useDefaultProps from '../hooks/useDefaultProps';
 import useDragSorter from '../hooks/useDragSorter';
 import useGlobalIcon from '../hooks/useGlobalIcon';
+import useUpdateLayoutEffect from '../hooks/useUpdateLayoutEffect';
 import TInput from '../input';
 import { tagInputDefaultProps } from './defaultProps';
 import useHover from './useHover';
@@ -80,16 +81,24 @@ const TagInput = forwardRef<InputRef, TagInputProps>((originalProps, ref) => {
       getDragProps,
     });
 
+  useUpdateLayoutEffect(() => {
+    if (excessTagsDisplayType === 'scroll') {
+      scrollToRight();
+    }
+  }, [tagValue]);
+
   const NAME_CLASS = `${prefix}-tag-input`;
   const WITH_SUFFIX_ICON_CLASS = `${prefix}-tag-input__with-suffix-icon`;
   const CLEAR_CLASS = `${prefix}-tag-input__suffix-clear`;
   const BREAK_LINE_CLASS = `${prefix}-tag-input--break-line`;
 
   const tagInputPlaceholder = !tagValue?.length ? placeholder : '';
 
-  const showClearIcon = Boolean(!readOnly && !disabled && clearable && isHover && tagValue?.length);
+  const showClearIcon = Boolean(!readOnly && !disabled && clearable && isHover && (tagValue?.length || tInputValue));
 
-  useImperativeHandle(ref as InputRef, () => ({ ...(tagInputRef.current || {}) }));
+  useImperativeHandle(ref as InputRef, () => ({
+    ...(tagInputRef.current || {}),
+  }));
 
   const updateSuffixWidth = (selector: string, cssVar: string, widthRef: React.MutableRefObject<number>) => {
     const wrapperEl = tagInputRef.current?.currentElement as HTMLElement;
@@ -140,9 +149,11 @@ const TagInput = forwardRef<InputRef, TagInputProps>((originalProps, ref) => {
   };
 
   const onInputEnter = (value: InputValue, context: { e: KeyboardEvent<HTMLInputElement> }) => {
+    context.e?.preventDefault?.();
     setTInputValue('', { e: context.e, trigger: 'enter' });
-    !isCompositionRef.current && onInnerEnter(value, context);
-    scrollToRight();
+    if (!isCompositionRef.current) {
+      onInnerEnter(value, context);
+    }
   };
 
   const onInnerClick = (context: { e: MouseEvent<HTMLDivElement> }) => {
diff --git a/packages/components/tag-input/_example/custom-tag.tsx b/packages/components/tag-input/_example/custom-tag.tsx
@@ -18,7 +18,12 @@ export default function CustomTagExample() {
           <span>
             <img
               src="https://tdesign.gtimg.com/site/avatar.jpg"
-              style={{ maxWidth: '18px', maxHeight: '18px', borderRadius: '50%', verticalAlign: 'text-top' }}
+              style={{
+                maxWidth: '18px',
+                maxHeight: '18px',
+                borderRadius: '50%',
+                verticalAlign: 'text-top',
+              }}
             />
             {value}
           </span>
@@ -38,7 +43,12 @@ export default function CustomTagExample() {
               <div>
                 <img
                   src="https://tdesign.gtimg.com/site/avatar.jpg"
-                  style={{ maxWidth: '18px', maxHeight: '18px', borderRadius: '50%', verticalAlign: 'text-top' }}
+                  style={{
+                    maxWidth: '18px',
+                    maxHeight: '18px',
+                    borderRadius: '50%',
+                    verticalAlign: 'text-top',
+                  }}
                 />
                 {item}
               </div>
diff --git a/packages/components/tag-input/_example/excess.tsx b/packages/components/tag-input/_example/excess.tsx
@@ -4,7 +4,7 @@ import { Space, TagInput } from 'tdesign-react';
 import type { TagInputValue } from 'tdesign-react';
 
 export default function TagInputExcessExample() {
-  const [tags, setTags] = useState<TagInputValue>(['Vue', 'React']);
+  const [tags, setTags] = useState<TagInputValue>(['Vue', 'React', 'Angular', 'Miniprogram', 'Uniapp', 'Flutter']);
   return (
     <Space direction="vertical" style={{ width: '80%' }}>
       {/* <!-- 标签数量超出时，滚动显示 --> */}
diff --git a/packages/components/tag-input/useTagScroll.ts b/packages/components/tag-input/useTagScroll.ts
@@ -1,106 +1,90 @@
 /**
  * 当标签数量过多时，输入框显示不下，则需要滚动查看，以下为滚动逻辑
- * 如果标签过多时的处理方式，是标签省略，则不需要此功能
  */
-import { useEffect, useRef, useState } from 'react';
-import { isFunction } from 'lodash-es';
+import { useEffect, useRef } from 'react';
+
+import useConfig from '../hooks/useConfig';
+import {
+  getScrollContainer,
+  handleWheelScroll,
+  scrollToLeft as scrollToLeftBase,
+  scrollToRight as scrollToRightBase,
+} from './utils/tagInputScroll';
 
 import type { WheelEvent } from 'react';
 import type { InputRef } from '../input';
 import type { TdTagInputProps } from './type';
 
-let mouseEnterTimer = null;
-
 export default function useTagScroll(props: TdTagInputProps) {
-  const { excessTagsDisplayType = 'scroll', disabled } = props;
+  const { excessTagsDisplayType, disabled } = props;
   const readOnly = props.readOnly || props.readonly;
+  const { classPrefix: prefix } = useConfig();
 
+  /** 标签输入框组件 ref */
   const tagInputRef = useRef<InputRef>(null);
-
-  // 允许向右滚动的最大距离
-  const [scrollDistance, setScrollDistance] = useState(0);
-  const [scrollElement, setScrollElement] = useState<HTMLDivElement>();
-
-  const updateScrollElement = (element: HTMLDivElement) => {
-    const scrollElement = element.children[0] as HTMLDivElement;
-    setScrollElement(scrollElement);
-  };
-
-  const updateScrollDistance = () => {
-    if (!scrollElement) return;
-    setScrollDistance(scrollElement.scrollWidth - scrollElement.clientWidth);
-  };
-
-  const scrollTo = (distance: number) => {
-    if (isFunction(scrollElement?.scroll)) {
-      scrollElement.scroll({ left: distance, behavior: 'smooth' });
+  /** 滚动容器元素缓存（.input__prefix） */
+  const scrollElementRef = useRef<HTMLElement>();
+  /** 进入防抖定时器 */
+  const mouseEnterTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /** 是否为可交互的 scroll 模式 */
+  const isScrollMode = excessTagsDisplayType === 'scroll' && !readOnly && !disabled;
+
+  /** 获取滚动容器（带缓存） */
+  const getScrollElement = () => {
+    const root = tagInputRef.current?.currentElement as HTMLElement;
+    if (!root) return scrollElementRef.current;
+    if (scrollElementRef.current?.parentElement !== root) {
+      const found = getScrollContainer(root, prefix);
+      if (found) scrollElementRef.current = found;
     }
+    return scrollElementRef.current;
   };
 
+  /** 滚动到最右侧并开启 scrollable，用于：悬浮进入、tag 变化后定位末尾 */
   const scrollToRight = () => {
-    updateScrollDistance();
-    scrollTo(scrollDistance);
+    const el = getScrollElement();
+    if (el) scrollToRightBase(el, prefix);
   };
 
-  const scrollToLeft = () => {
-    scrollTo(0);
+  /** 处理滚轮事件，绑定到 TInput 的 onWheel */
+  const onWheel = ({ e }: { e: WheelEvent<HTMLDivElement> }) => {
+    if (!isScrollMode) return;
+    const el = getScrollElement();
+    if (el) handleWheelScroll(el, e);
   };
 
-  // TODO：MAC 电脑横向滚动，Windows 纵向滚动。当前只处理了横向滚动
-  const onWheel = ({ e }: { e: WheelEvent<HTMLDivElement> }) => {
-    if (readOnly || disabled) return;
-    if (!scrollElement) return;
-    if (e.deltaX > 0) {
-      const distance = Math.min(scrollElement.scrollLeft + 120, scrollDistance);
-      scrollTo(distance);
-    } else {
-      const distance = Math.max(scrollElement.scrollLeft - 120, 0);
-      scrollTo(distance);
+  /** 清除防抖定时器 */
+  const clearEnterTimer = () => {
+    if (mouseEnterTimerRef.current) {
+      clearTimeout(mouseEnterTimerRef.current);
+      mouseEnterTimerRef.current = null;
     }
   };
 
-  // 鼠标 hover，自动滑动到最右侧，以便输入新标签
+  /** 鼠标悬浮进入：延迟 100ms 后滚动到最右侧 */
   const scrollToRightOnEnter = () => {
-    if (excessTagsDisplayType !== 'scroll') return;
-    // 一闪而过的 mousenter 不需要执行
-    mouseEnterTimer = setTimeout(() => {
+    if (!isScrollMode) return;
+    clearEnterTimer();
+    mouseEnterTimerRef.current = setTimeout(() => {
       scrollToRight();
-      clearTimeout(mouseEnterTimer);
+      mouseEnterTimerRef.current = null;
     }, 100);
   };
 
+  /** 鼠标离开：滚回最左并关闭 scrollable */
   const scrollToLeftOnLeave = () => {
-    if (excessTagsDisplayType !== 'scroll') return;
-    scrollTo(0);
-    clearTimeout(mouseEnterTimer);
-  };
-
-  const clearScroll = () => {
-    clearTimeout(mouseEnterTimer);
-  };
-
-  const initScroll = (element: HTMLDivElement) => {
-    if (!element) return;
-    updateScrollElement(element);
+    if (!isScrollMode) return;
+    clearEnterTimer();
+    const el = getScrollElement();
+    if (el) scrollToLeftBase(el, prefix);
   };
 
-  useEffect(() => {
-    initScroll(tagInputRef?.current?.currentElement);
-    return clearScroll;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+  useEffect(() => clearEnterTimer, []);
 
   return {
-    initScroll,
-    clearScroll,
     tagInputRef,
-    scrollElement,
-    scrollDistance,
-    scrollTo,
     scrollToRight,
-    scrollToLeft,
-    updateScrollElement,
-    updateScrollDistance,
     onWheel,
     scrollToRightOnEnter,
     scrollToLeftOnLeave,
diff --git a/packages/components/tag-input/utils/tagInputScroll.ts b/packages/components/tag-input/utils/tagInputScroll.ts
@@ -0,0 +1,50 @@
+/**
+ * TagInput 滚动相关逻辑
+ * 当标签数量过多时，输入框显示不下则需要滚动查看
+ */
+
+const SCROLL_CONTAINER_CLASS = 'input__prefix';
+const SCROLLABLE_CLASS = 'input__prefix--scrollable';
+
+/** 根据根元素查找滚动容器 .{classPrefix}-input__prefix */
+export function getScrollContainer(root: HTMLElement, classPrefix: string): HTMLElement | null {
+  return root.querySelector(`.${classPrefix}-${SCROLL_CONTAINER_CLASS}`);
+}
+
+/** 计算元素的最大可滚动距离 scrollWidth - clientWidth */
+export function getScrollDistance(el: HTMLElement): number {
+  return el.scrollWidth - el.clientWidth;
+}
+
+/** 设置/移除 scrollable 状态类，控制 overflow 是否开放 */
+export function setScrollableClass(el: HTMLElement, classPrefix: string, scrollable: boolean): void {
+  const className = `${classPrefix}-${SCROLLABLE_CLASS}`;
+  if (scrollable) {
+    el.classList.add(className);
+  } else {
+    el.classList.remove(className);
+  }
+}
+
+/** 处理滚轮事件：MAC deltaX / Windows deltaY 兼容 */
+export function handleWheelScroll(el: HTMLElement, e: { deltaX: number; deltaY: number }): void {
+  const delta = Math.abs(e.deltaX) >= Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
+  if (delta === 0) return;
+  const max = getScrollDistance(el);
+  // eslint-disable-next-line no-param-reassign
+  el.scrollLeft = Math.max(0, Math.min(el.scrollLeft + delta, max));
+}
+
+/** 滚动到最左侧并移除 scrollable class（鼠标离开时） */
+export function scrollToLeft(el: HTMLElement, classPrefix: string): void {
+  // eslint-disable-next-line no-param-reassign
+  el.scrollLeft = 0;
+  setScrollableClass(el, classPrefix, false);
+}
+
+/** 滚动到最右侧并开启 scrollable class */
+export function scrollToRight(el: HTMLElement, classPrefix: string): void {
+  setScrollableClass(el, classPrefix, true);
+  // eslint-disable-next-line no-param-reassign
+  el.scrollLeft = getScrollDistance(el);
+}
diff --git a/packages/tdesign-react/.changelog/pr-4210.md b/packages/tdesign-react/.changelog/pr-4210.md
@@ -0,0 +1,7 @@
+---
+pr_number: 4210
+contributor: RSS1102
+---
+
+- fix(TagInput): 修复 `excessTagsDisplayType="scroll` 时，没有显示横向滚动条等交互问题 @RSS1102 ([#4210](https://github.com/Tencent/tdesign-react/pull/4210))
+- fix(TagInput): 在启用 `clearable` 的前提下，当仅输入文字时也可以显示清除按钮 @RSS1102 ([#4210](https://github.com/Tencent/tdesign-react/pull/4210))
diff --git a/test/snap/__snapshots__/csr.test.jsx.snap b/test/snap/__snapshots__/csr.test.jsx.snap
diff --git a/test/snap/__snapshots__/ssr.test.jsx.snap b/test/snap/__snapshots__/ssr.test.jsx.snap
