@unif/react-native-design 0.19.0 → 0.21.0

package/src/components/ui/Switch/Switch.tsx

@@ -1,4 +1,5 @@
 import React, { useEffect } from 'react';
+import { View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
 
 import Animated, {
@@ -9,10 +10,21 @@ import Animated, {
   useSharedValue,
   withTiming,
 } from 'react-native-reanimated';
-import { fixed, motion, r, useColors, useThemedStyles } from '../../../theme';
-import { makeStyles, THUMB_OFF_X, THUMB_ON_X, TRACK_H } from './styles';
+import {
+  motion,
+  useColors,
+  usePrefersReducedMotion,
+  useThemedStyles,
+} from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import { makeStyles, THUMB_OFF_X, THUMB_ON_X } from './styles';
 import type { SwitchProps } from './types';
 
+const log = createLogger('Switch');
+
 /**
  * 布尔切换。32×20 轨道 + 16×16 白色把手,200ms 缓动。
  *
@@ -28,12 +40,26 @@ export function Switch({
 }: SwitchProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
+  const reducedMotion = usePrefersReducedMotion();
   const progress = useSharedValue(value ? 1 : 0);
+  const accessibleName = normalizeNonBlankText(accessibilityLabel);
+  const hasBlankLabel = accessibleName === undefined;
+  const isDisabled = disabled === true || hasBlankLabel;
 
   useEffect(() => {
-    progress.value = withTiming(value ? 1 : 0, { duration: motion.base });
+    if (reducedMotion) {
+      cancelAnimation(progress);
+      progress.value = value ? 1 : 0;
+    } else {
+      progress.value = withTiming(value ? 1 : 0, { duration: motion.base });
+    }
     return () => cancelAnimation(progress);
-  }, [value, progress]);
+  }, [progress, reducedMotion, value]);
+  useEffect(() => {
+    if (hasBlankLabel) {
+      log.warn('Switch accessibilityLabel 不能为空白，当前 action 已禁用。');
+    }
+  }, [hasBlankLabel]);
 
   const trackStyle = useAnimatedStyle(() => ({
     backgroundColor: interpolateColor(
@@ -57,19 +83,32 @@ export function Switch({
 
   return (
     <Pressable
-      onPress={() => !disabled && onChange(!value)}
-      disabled={disabled}
-      // [M-7] 轨道高 r(20)≈20pt;补 (44-20)/2=12 到 fixed.hitTarget
-      hitSlop={Math.round((fixed.hitTarget - r(TRACK_H)) / 2)}
-      style={disabled ? styles.pressableDisabled : styles.pressableEnabled}
-      accessibilityRole="switch"
-      accessibilityState={{ checked: value, disabled: !!disabled }}
-      accessibilityLabel={accessibilityLabel}
+      accessible={!hasBlankLabel}
+      onPress={isDisabled ? undefined : () => onChange(!value)}
+      disabled={isDisabled}
+      style={[styles.pressable, isDisabled && styles.pressableDisabled]}
+      accessibilityRole={hasBlankLabel ? undefined : 'switch'}
+      accessibilityState={
+        hasBlankLabel ? undefined : { checked: value, disabled: isDisabled }
+      }
+      accessibilityLabel={accessibleName}
       testID={testID}
     >
-      <Animated.View style={[styles.track, trackStyle]}>
-        <Animated.View style={[styles.thumb, thumbStyle]} />
-      </Animated.View>
+      <View
+        {...A11Y_HIDDEN_PROPS}
+        style={styles.visualFrame}
+        testID={childTestID(testID, 'visual')}
+      >
+        <Animated.View
+          style={[styles.track, trackStyle]}
+          testID={childTestID(testID, 'track')}
+        >
+          <Animated.View
+            style={[styles.thumb, thumbStyle]}
+            testID={childTestID(testID, 'thumb')}
+          />
+        </Animated.View>
+      </View>
     </Pressable>
   );
 }

package/src/components/ui/Switch/Switch.web.tsx

@@ -1,10 +1,21 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Pressable } from 'react-native-gesture-handler';
 import { View } from 'react-native';
-import { motion, useColors, useThemedStyles } from '../../../theme';
+import {
+  motion,
+  useColors,
+  usePrefersReducedMotion,
+  useThemedStyles,
+} from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
 import { makeStyles, THUMB_OFF_X, THUMB_ON_X } from './styles';
 import type { SwitchProps } from './types';
 
+const log = createLogger('Switch');
+
 /**
  * Web 端 Switch —— RN-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle
  * 链路会抛 `Object.keys(undefined)` TypeError(切换时打印,thumb 卡住),走 CSS
@@ -24,37 +35,64 @@ export function Switch({
 }: SwitchProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
+  const reducedMotion = usePrefersReducedMotion();
+  const accessibleName = normalizeNonBlankText(accessibilityLabel);
+  const hasBlankLabel = accessibleName === undefined;
+  const isDisabled = disabled === true || hasBlankLabel;
+
+  useEffect(() => {
+    if (hasBlankLabel) {
+      log.warn('Switch accessibilityLabel 不能为空白，当前 action 已禁用。');
+    }
+  }, [hasBlankLabel]);
 
-  // 给 RN style 数组追加 web-only 字段:transition + 切换值
+  // 给 RN style 数组追加 web-only 字段；reduced motion 时连 transition key
+  // 都不输出，避免浏览器仍创建零时长 transition。
   const trackWebStyle = {
     ...styles.track,
     backgroundColor: value ? c.primary : c.surfaceContainerHighest,
-    // RN style 不识 transition 但 RN-Web 会把它当 inline style 透传给 DOM
-    transitionProperty: 'background-color',
-    transitionDuration: `${motion.base}ms`,
-    transitionTimingFunction: 'ease-out',
+    ...(reducedMotion
+      ? {}
+      : {
+          // RN style 不识 transition 但 RN-Web 会把它当 inline style 透传给 DOM
+          transitionProperty: 'background-color',
+          transitionDuration: `${motion.base}ms`,
+          transitionTimingFunction: 'ease-out',
+        }),
   } as unknown as object;
   const thumbWebStyle = {
     ...styles.thumb,
     transform: [{ translateX: value ? THUMB_ON_X : THUMB_OFF_X }],
-    transitionProperty: 'transform',
-    transitionDuration: `${motion.base}ms`,
-    transitionTimingFunction: 'ease-out',
+    ...(reducedMotion
+      ? {}
+      : {
+          transitionProperty: 'transform',
+          transitionDuration: `${motion.base}ms`,
+          transitionTimingFunction: 'ease-out',
+        }),
   } as unknown as object;
 
   return (
     <Pressable
-      onPress={() => !disabled && onChange(!value)}
-      disabled={disabled}
-      hitSlop={6}
-      style={disabled ? styles.pressableDisabled : styles.pressableEnabled}
-      accessibilityRole="switch"
-      accessibilityState={{ checked: value, disabled: !!disabled }}
-      accessibilityLabel={accessibilityLabel}
+      accessible={!hasBlankLabel}
+      onPress={isDisabled ? undefined : () => onChange(!value)}
+      disabled={isDisabled}
+      style={[styles.pressable, isDisabled && styles.pressableDisabled]}
+      accessibilityRole={hasBlankLabel ? undefined : 'switch'}
+      accessibilityState={
+        hasBlankLabel ? undefined : { checked: value, disabled: isDisabled }
+      }
+      accessibilityLabel={accessibleName}
       testID={testID}
     >
-      <View style={trackWebStyle}>
-        <View style={thumbWebStyle} />
+      <View
+        {...A11Y_HIDDEN_PROPS}
+        style={styles.visualFrame}
+        testID={childTestID(testID, 'visual')}
+      >
+        <View style={trackWebStyle} testID={childTestID(testID, 'track')}>
+          <View style={thumbWebStyle} testID={childTestID(testID, 'thumb')} />
+        </View>
       </View>
     </Pressable>
   );

package/src/components/ui/Switch/styles.ts

@@ -1,5 +1,5 @@
 import { StyleSheet } from 'react-native';
-import { r, radius } from '../../../theme';
+import { fixed, r, radius } from '../../../theme';
 import type { ColorTokens } from '../../../theme';
 
 /** 轨道宽 32 / 高 20、把手 16×16、轨道内边距 2 —— Unif 自有 Switch 物理尺寸。
@@ -16,14 +16,21 @@ export const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
 
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
-    pressableEnabled: {
-      opacity: 1,
+    // 固定命中框不走 r()/fontScale:它是手指可达性约束,不是视觉 token。
+    pressable: {
+      width: fixed.hitTarget,
+      height: fixed.hitTarget,
+      alignItems: 'center',
+      justifyContent: 'center',
       // [L-37] alignSelf:'flex-start' 防止父容器拉伸把手区域(与 Chip [M-8] 同口径)
       alignSelf: 'flex-start' as const,
     },
     pressableDisabled: {
       opacity: 0.5,
-      alignSelf: 'flex-start' as const,
+    },
+    visualFrame: {
+      width: r(TRACK_W),
+      height: r(TRACK_H),
     },
     track: {
       width: r(TRACK_W),

package/src/components/ui/Switch/types.ts

@@ -1,8 +1,8 @@
 export type SwitchProps = {
   value: boolean;
   onChange: (value: boolean) => void;
+  /** Switch 没有内置可见文字，必须显式提供读屏名称 */
+  accessibilityLabel: string;
   disabled?: boolean;
-  /** 用于无障碍 / 测试 */
-  accessibilityLabel?: string;
   testID?: string;
 };

package/src/components/ui/Tag/Tag.tsx

@@ -1,5 +1,5 @@
 import { Text, View } from 'react-native';
-import { useColors } from '../../../theme';
+import { scaleFontMetric, useColors, useFontScale } from '../../../theme';
 import { paletteFor, sizingFor, styles } from './styles';
 import type { TagProps } from './types';
 
@@ -12,6 +12,7 @@ export function Tag({
   testID,
 }: TagProps) {
   const c = useColors();
+  const fontScale = useFontScale();
   const palette = paletteFor(variant, c);
   const sizing = sizingFor(size);
 
@@ -22,7 +23,10 @@ export function Tag({
     borderColor: palette.border ?? 'transparent',
     borderWidth: palette.border ? 1 : 0,
   };
-  const dynamicTextStyle = { color: palette.fg, fontSize: sizing.fs };
+  const dynamicTextStyle = {
+    color: palette.fg,
+    fontSize: scaleFontMetric(sizing.fs, fontScale),
+  };
 
   return (
     <View style={[styles.base, dynamicStyle, style]} testID={testID}>

package/src/components/ui/TextField/TextFieldBase.tsx

@@ -1,35 +1,40 @@
-import React, { type ComponentRef, forwardRef, useState } from 'react';
-import { Text, TextInput, View } from 'react-native';
-import { control, r, space, useColors, useThemedStyles } from '../../../theme';
+import React, {
+  type ComponentRef,
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useState,
+} from 'react';
+import { Platform, Text, TextInput, View } from 'react-native';
+import type { TextInputProps } from 'react-native';
+import { fixed, space, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
+import { createLogger } from '../../../utils/logger';
+import {
+  normalizeInputHeight,
+  normalizeTextareaHeights,
+  sanitizeTextFieldContainerStyle,
+} from './normalize';
 import { makeStyles } from './styles';
-import type { TextFieldBaseProps } from './types';
+import { TextFieldSlot } from './TextFieldSlot';
+import type { TextFieldBaseProps, TextFieldHandle } from './types';
+import { useErrorAnnouncement } from './useErrorAnnouncement';
+import { useTextFieldValue } from './useTextFieldValue';
 
-/** `TextInput` 在 react-native-strict-api 下是组件类型(`TextInputType`),
- *  ref 实例类型走 `ComponentRef<typeof TextInput>`(对应内部 `_TextInputInstance`)。 */
-export type TextInputRef = ComponentRef<typeof TextInput>;
+const log = createLogger('TextField');
 
-/**
- * Input / Textarea 共享 primitive —— internal,不在主 barrel 导出。
- *
- * 行为:
- * - 视觉 4 态:idle(浅灰)/ focus(白底 brand 边)/ filled(白底 outline 边)/ error
- * - leading / trailing 左右 slot
- * - disabled 优先于 editable
- * - multiline=false → 单行 fixed height(默认 control.lg)
- * - multiline=true → 多行 minHeight/maxHeight,文字顶对齐,wrap 上下加 padding
- * - forwardRef<TextInput> —— 业务表单 inputRef.current?.focus() 聚焦
- *
- * 公开 API 是 Input / Textarea(本组件不直接给业务用)。
- */
-export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
-  function TextFieldBase(
-    {
-      multiline = false,
-      height = control.lg,
-      // [L-81] multiline minHeight 裸 96 → r(96),随设备缩放
-      minHeight = r(96),
+/** internal native ref type;公开 ref 一律用 TextFieldHandle。 */
+type NativeTextInputRef = ComponentRef<typeof TextInput>;
+
+/** Input / Textarea / Search 共享的严格输入 primitive — internal,不进公共 barrel。 */
+export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
+  function TextFieldBase(props, forwardedRef): React.JSX.Element {
+    const {
+      multiline,
+      height,
+      minHeight,
       maxHeight,
+      searchLayout,
       leading,
       trailing,
       error,
@@ -37,29 +42,96 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
       editable,
       containerStyle,
       value,
+      defaultValue,
+      onChangeText,
+      accessibilityState,
+      accessibilityRole,
+      placeholderTextColor: callerPlaceholder,
       onFocus,
       onBlur,
-      onChangeText,
       testID,
-      ...rest
-    },
-    ref
-  ): React.JSX.Element {
-    const c = useColors();
+      style: _style,
+      numberOfLines: _numberOfLines,
+      ['aria-disabled']: _ariaDisabled,
+      readOnly: _readOnly,
+      role: _role,
+      enterKeyHint: _enterKeyHint,
+      clearTextOnFocus: _clearTextOnFocus,
+      ...allowedNativeProps
+    } = props as TextFieldBaseProps & Record<string, unknown>;
+    const removedNativeAliasKey = Object.entries({
+      'style': _style,
+      'numberOfLines': _numberOfLines,
+      'aria-disabled': _ariaDisabled,
+      'readOnly': _readOnly,
+      'role': _role,
+      'enterKeyHint': _enterKeyHint,
+      'clearTextOnFocus': _clearTextOnFocus,
+    })
+      .filter(([, entry]) => entry !== undefined)
+      .map(([name]) => name)
+      .join(',');
+    const colors = useColors();
     const styles = useThemedStyles(makeStyles);
     const [focused, setFocused] = useState(false);
-    // [M-9] 内部镜像 state:非受控场景 value 不传,用 _mirror 做 hasValue 判断
-    const [_mirror, setMirror] = useState('');
-    // [M-9] filled 在受控 value 和内部镜像 state 之间取 hasValue,
-    // 保证非受控场景 filled 视觉态能正确响应用户输入,且受控用法行为不变
-    const filled =
-      value != null ? String(value).length > 0 : _mirror.length > 0;
-    const isEditable = disabled ? false : editable;
-    // [L-31] editable=false(非 disabled)时也应进入 disabled a11y state
-    const isDisabledA11y = disabled || editable === false;
+    const nativeRef = React.useRef<NativeTextInputRef>(null);
+    const scope = multiline ? 'Textarea' : 'Input';
+    const controller = useTextFieldValue(
+      {
+        value,
+        defaultValue,
+        onChangeText:
+          typeof onChangeText === 'function'
+            ? (onChangeText as (next: string) => void)
+            : undefined,
+      },
+      scope
+    );
+    const normalizedInputHeight = normalizeInputHeight(
+      height === undefined ? fixed.hitTarget : height
+    );
+    const normalizedTextareaHeights = normalizeTextareaHeights(
+      minHeight,
+      maxHeight
+    );
+    const sanitizedContainer = sanitizeTextFieldContainerStyle(containerStyle);
+    const effectiveEditable = disabled !== true && editable !== false;
+    const mergedAccessibilityState = {
+      ...accessibilityState,
+      disabled: !effectiveEditable,
+    };
+    const normalizedHeight = multiline
+      ? normalizedTextareaHeights.minHeight
+      : normalizedInputHeight.value;
+    const filled = controller.value.length > 0;
+    const diagnostics = [
+      ...normalizedInputHeight.diagnostics,
+      ...normalizedTextareaHeights.diagnostics,
+      ...sanitizedContainer.diagnostics,
+    ];
+    const diagnosticKey = diagnostics.join(',');
+
+    useEffect(() => {
+      if (diagnosticKey.length > 0) {
+        log.warn(`${scope}: 非法布局值(${diagnosticKey})已回退。`);
+      }
+    }, [diagnosticKey, scope]);
+    useEffect(() => {
+      if (removedNativeAliasKey.length > 0) {
+        log.warn(`${scope}: 已忽略受管原生 props(${removedNativeAliasKey})。`);
+      }
+    }, [removedNativeAliasKey, scope]);
+    useErrorAnnouncement(error);
+
+    useImperativeHandle(
+      forwardedRef,
+      () => ({
+        focus: () => nativeRef.current?.focus(),
+        blur: () => nativeRef.current?.blur(),
+      }),
+      []
+    );
 
-    // 视觉态优先级:error > focused > filled > idle。
-    // active 三态(focus/filled/error)共享 wrapActive 白底,各自只覆 borderColor 差量。
     const wrapStateStyles = error
       ? [styles.wrapActive, styles.wrapError]
       : focused
@@ -67,62 +139,95 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
         : filled
           ? [styles.wrapActive, styles.wrapFilled]
           : [styles.wrapIdle];
+    const interactiveHeight =
+      searchLayout?.interactiveHeight ?? normalizedHeight;
 
     return (
       <View
-        style={[containerStyle, disabled && styles.containerDisabled]}
+        style={[
+          sanitizedContainer.style,
+          !effectiveEditable && styles.containerDisabled,
+          searchLayout !== undefined && !multiline && styles.rootCentered,
+          { minWidth: fixed.hitTarget, minHeight: normalizedHeight },
+        ]}
         testID={testID}
       >
         <View
           style={[
             styles.wrap,
             multiline && styles.wrapMultiline,
-            ...wrapStateStyles,
+            searchLayout === undefined && wrapStateStyles,
+            searchLayout !== undefined && styles.searchInteractiveRow,
             multiline
-              ? { minHeight, ...(maxHeight != null && { maxHeight }) }
-              : { height },
+              ? {
+                  minHeight: normalizedHeight,
+                  ...(normalizedTextareaHeights.maxHeight !== undefined && {
+                    maxHeight: normalizedTextareaHeights.maxHeight,
+                  }),
+                }
+              : { height: interactiveHeight },
           ]}
         >
-          {leading != null ? <View>{leading}</View> : null}
+          {searchLayout ? (
+            <View
+              pointerEvents="none"
+              style={[
+                styles.searchVisibleSurface,
+                ...wrapStateStyles,
+                {
+                  top: searchLayout.verticalInset,
+                  bottom: searchLayout.verticalInset,
+                },
+              ]}
+            />
+          ) : null}
+          <TextFieldSlot
+            slot={leading}
+            effectiveEditable={effectiveEditable}
+            testID={childTestID(testID, 'leading')}
+          />
           <TextInput
-            ref={ref}
-            {...rest}
-            editable={isEditable}
-            value={value}
-            onChangeText={(text) => {
-              // [M-9] 同步内部镜像,非受控场景 filled 视觉态依赖此 state
-              setMirror(text);
-              onChangeText?.(text);
-            }}
+            ref={nativeRef}
+            {...(allowedNativeProps as TextInputProps)}
+            value={controller.value}
+            onChangeText={controller.onChangeText}
+            editable={effectiveEditable}
             multiline={multiline}
-            onFocus={(e) => {
+            onFocus={(event) => {
               setFocused(true);
-              onFocus?.(e);
+              onFocus?.(event);
             }}
-            onBlur={(e) => {
+            onBlur={(event) => {
               setFocused(false);
-              onBlur?.(e);
+              onBlur?.(event);
             }}
             style={[
               styles.input,
               multiline && styles.inputMultiline,
-              // multiline:wrap 上下 padding 为 space[4]*2=20,input 内部 minHeight 减掉避免溢出
               multiline && {
-                minHeight: Math.max(0, minHeight - space[4] * 2),
+                minHeight: Math.max(0, normalizedHeight - space[4] * 2),
+              },
+              searchLayout !== undefined && {
+                minHeight: searchLayout.interactiveHeight,
               },
             ]}
-            placeholderTextColor={c.foregroundSubtle}
-            // [L-31] editable=false 并入 disabled a11y state,SR 能正确播报不可编辑
-            accessibilityState={isDisabledA11y ? { disabled: true } : undefined}
+            placeholderTextColor={callerPlaceholder ?? colors.foregroundSubtle}
+            accessibilityRole={accessibilityRole}
+            accessibilityState={mergedAccessibilityState}
             testID={childTestID(testID, 'input')}
           />
-          {trailing != null ? <View>{trailing}</View> : null}
+          <TextFieldSlot
+            slot={trailing}
+            effectiveEditable={effectiveEditable}
+            testID={childTestID(testID, 'trailing')}
+          />
         </View>
-        {/* [L-31] error Text 补 accessibilityLiveRegion="polite" —— 错误出现时 SR 自动播报 */}
         {error ? (
           <Text
             style={styles.errorMsg}
-            accessibilityLiveRegion="polite"
+            accessibilityLiveRegion={
+              Platform.OS === 'android' ? 'polite' : undefined
+            }
             testID={childTestID(testID, 'error')}
           >
             {error}

package/src/components/ui/TextField/TextFieldSlot.tsx

@@ -0,0 +1,91 @@
+import { useEffect } from 'react';
+import { Text, View } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { Icon } from '../Icon';
+import { normalizeSlotIconSize, normalizeTextFieldSlot } from './normalize';
+import { makeStyles } from './styles';
+import type { TextFieldSlot as TextFieldSlotConfig } from './types';
+
+const log = createLogger('TextFieldSlot');
+
+type TextFieldSlotProps = {
+  slot: TextFieldSlotConfig | unknown;
+  effectiveEditable: boolean;
+  testID?: string;
+};
+
+/**
+ * 受控 slot renderer。展示内容与真实操作在这里分叉,避免未知 ReactNode 绕过
+ * 44pt action frame 或可访问名称约束。
+ */
+export function TextFieldSlot({
+  slot,
+  effectiveEditable,
+  testID,
+}: TextFieldSlotProps): React.JSX.Element | null {
+  const colors = useColors();
+  const styles = useThemedStyles(makeStyles);
+  const normalizedSlot = normalizeTextFieldSlot(slot);
+  const safeSlot = normalizedSlot.slot;
+  const iconSize =
+    safeSlot?.kind === 'icon'
+      ? normalizeSlotIconSize(safeSlot.size)
+      : undefined;
+  const iconDiagnosticKey = iconSize?.diagnostics.join(',') ?? '';
+  const slotDiagnosticKey = normalizedSlot.diagnostics.join(',');
+
+  useEffect(() => {
+    if (iconDiagnosticKey.length > 0) {
+      log.warn('slot.icon.size 非法，已回退为 18。');
+    }
+  }, [iconDiagnosticKey]);
+  useEffect(() => {
+    if (slotDiagnosticKey.length > 0) {
+      log.warn(`非法 TextField slot(${slotDiagnosticKey})已移除。`);
+    }
+  }, [slotDiagnosticKey]);
+
+  if (!safeSlot) return null;
+
+  switch (safeSlot.kind) {
+    case 'icon':
+      return (
+        <View {...A11Y_HIDDEN_PROPS} style={styles.slotDisplay} testID={testID}>
+          <Icon
+            name={safeSlot.icon}
+            size={iconSize?.value ?? 18}
+            color={safeSlot.color ?? colors.foregroundMuted}
+          />
+        </View>
+      );
+    case 'text':
+      return (
+        <Text
+          {...A11Y_HIDDEN_PROPS}
+          style={[styles.slotDisplay, styles.slotText]}
+          testID={testID}
+        >
+          {safeSlot.value}
+        </Text>
+      );
+    case 'action': {
+      const disabled = !effectiveEditable || safeSlot.disabled === true;
+      return (
+        <Pressable
+          onPress={disabled ? undefined : safeSlot.onPress}
+          disabled={disabled}
+          accessibilityRole="button"
+          accessibilityLabel={safeSlot.accessibilityLabel}
+          accessibilityState={{ disabled }}
+          style={styles.actionFrame}
+          testID={testID}
+        >
+          <Icon name={safeSlot.icon} size={18} color={colors.foregroundMuted} />
+        </Pressable>
+      );
+    }
+  }
+}