@unif/react-native-design 0.8.2 → 0.10.0

package/src/components/ui/StatusDot/StatusDot.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View } from 'react-native';
-import { useColors } from '../../../theme';
+import { r, useColors } from '../../../theme';
 import { Icon } from '../Icon';
 import { PulseDot } from '../Pulse';
 import { paletteFor, styles } from './styles';
@@ -10,14 +10,28 @@ import type { StatusDotProps } from './types';
  * 任务列表 / 推理链通用的状态圆点。
  * done = 绿底 + 白勾；active = 边框 + 内部 PulseDot；pending = 仅边框。
  */
+// status 派生默认 a11y label —— 不传时 SR 仍能播报状态语义。
+const DEFAULT_A11Y: Record<string, string> = {
+  pending: 'pending',
+  active: 'active',
+  done: 'done',
+};
+
 export function StatusDot({
   status,
-  size = 16,
+  size = r(16),
   tone = 'flat',
+  accessibilityLabel,
+  style,
   testID,
 }: StatusDotProps): React.JSX.Element {
   const c = useColors();
   const { bg, border } = paletteFor(status, tone, c);
+  // [L-14] 优先用 caller 传入值;空字符串表示由容器负责播报,不派生默认。
+  const a11yLabel =
+    accessibilityLabel !== undefined
+      ? accessibilityLabel || undefined
+      : DEFAULT_A11Y[status];
 
   return (
     <View
@@ -30,7 +44,10 @@ export function StatusDot({
           backgroundColor: bg,
           borderColor: border,
         },
+        style,
       ]}
+      accessible={!!a11yLabel}
+      accessibilityLabel={a11yLabel}
       testID={testID}
     >
       {status === 'done' ? (
@@ -41,7 +58,8 @@ export function StatusDot({
           strokeWidth={2.5}
         />
       ) : status === 'active' ? (
-        <PulseDot />
+        // [L-13] size 随外圈等比派生(系数 0.375 ≈ 6/16),视觉居中且不溢出。
+        <PulseDot size={Math.round(size * 0.375)} />
       ) : null}
     </View>
   );

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

@@ -16,7 +16,7 @@ export const styles = StyleSheet.create({
 });
 
 /** StatusDot 颜色推导:status × tone → { bg, border } 二色,全走 ColorTokens。
- *  签名 `(target, context, tokens)` 与 Tag/Tool 的 paletteFor 一致。
+ *  与 Tag/Button 的 paletteFor 同约定(状态入参 + ColorTokens → 配色对象),多一维 tone。
  *  `flat` = pending/active 底色透明；`soft` = pending 走 surface、active 走 primaryContainer。 */
 export function paletteFor(
   status: StatusDotStatus,

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

@@ -1,8 +1,10 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 export type StatusDotStatus = 'pending' | 'active' | 'done';
 
 /**
  * `flat`：pending/active 底色透明（任务列表风格）。
- * `soft`：pending = bgCard、active = primary0，常用于推理链。
+ * `soft`：pending = surface、active = primaryContainer，常用于推理链。
  */
 export type StatusDotTone = 'flat' | 'soft';
 
@@ -10,6 +12,17 @@ export type StatusDotProps = {
   status: StatusDotStatus;
   size?: number;
   tone?: StatusDotTone;
+  /**
+   * [L-14] Screen Reader 朗读文本。
+   * 不传时按 status 派生默认值("pending" / "active" / "done")。
+   * 若状态语义已由父容器的 accessibilityLabel 覆盖,可传空字符串 "" 屏蔽默认值。
+   *
+   * 注:StatusDot 本身属于装饰性图标,状态语义通常由容器(列表行 / 任务项)负责播报;
+   * 对于需要独立播报的场景(独立状态指示器),请通过此 prop 传入有意义的描述。
+   */
+  accessibilityLabel?: string;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
 };

package/src/components/ui/Stepper/Stepper.tsx

@@ -1,13 +1,17 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useThemedStyles } from '../../../theme';
+import { fixed, pressedOpacity, useThemedStyles } from '../../../theme';
 import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
 import { makeStyles, sizingFor } from './styles';
 import type { StepperProps } from './types';
 
 const log = createLogger('Stepper');
 
+// [L-30] 模块级 Set 去重 —— step/min/max 告警只打一次,避免渲染阶段刷屏
+const _warned = new Set<string>();
+
 /**
  * 数字步进器 [−][ N ][+]。
  * 按钮自动夹到 min/max；越界的按钮透明度变 0.4。
@@ -28,11 +32,21 @@ export function Stepper({
   const styles = useThemedStyles(makeStyles);
   const dims = sizingFor(size);
 
-  if (Number.isFinite(step) && step <= 0) {
-    log.warn(`step 必须是正数，传入 ${step}，已 fallback 为 1`);
+  // [L-30] step 口径对齐:非有限数(NaN/Infinity)也告警,与 min>max 告警保持一致
+  // 模块级 Set 去重:每个异常组合只打一次告警,避免渲染阶段重复刷屏
+  if (!Number.isFinite(step) || step <= 0) {
+    const k = `step:${step}`;
+    if (!_warned.has(k)) {
+      _warned.add(k);
+      log.warn(`step 必须是有限正数，传入 ${step}，已 fallback 为 1`);
+    }
   }
   if (Number.isFinite(min) && Number.isFinite(max) && min > max) {
-    log.warn(`min(${min}) 不能大于 max(${max})，已按 min 渲染`);
+    const k = `minmax:${min}:${max}`;
+    if (!_warned.has(k)) {
+      _warned.add(k);
+      log.warn(`min(${min}) 不能大于 max(${max})，已按 min 渲染`);
+    }
   }
   const safeStep = Number.isFinite(step) && step > 0 ? step : 1;
   const safeMin = Number.isFinite(min) ? min : 0;
@@ -44,8 +58,15 @@ export function Stepper({
   const decDisabled = disabled || safeValue <= safeMin;
   const incDisabled = disabled || safeValue >= safeMax;
 
+  // [M-7] 按钮高 sm=28 / md=32 均低于 fixed.hitTarget=44;hitSlop 不越父边界,
+  // 须让容器一并扩展:wrap 加垂直 padding 把命中区撑到 44pt。
+  const wrapPaddingV = Math.max(0, Math.round((fixed.hitTarget - dims.h) / 2));
+
   return (
-    <View style={styles.wrap} testID={testID}>
+    <View
+      style={[styles.wrap, { paddingVertical: wrapPaddingV }]}
+      testID={testID}
+    >
       <Pressable
         onPress={() => onChange(Math.max(safeMin, safeValue - safeStep))}
         disabled={decDisabled}
@@ -53,21 +74,35 @@ export function Stepper({
         accessibilityLabel="减少"
         accessibilityState={{ disabled: decDisabled }}
         accessibilityHint={`当前值 ${safeValue}，减 ${safeStep}`}
-        testID={testID ? `${testID}-decrement` : undefined}
+        testID={childTestID(testID, 'decrement')}
         style={({ pressed }) => [
           styles.cell,
           styles.btnLeft,
           { width: dims.btn, height: dims.h },
-          { opacity: decDisabled ? 0.4 : pressed ? 0.7 : 1 },
+          { opacity: decDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
         ]}
       >
         <Text style={styles.btnText}>−</Text>
       </Pressable>
+      {/* [L-29] adjustable 需配 accessible + accessibilityActions + onAccessibilityAction,
+          否则 iOS VoiceOver 宣读"可调节"但滑动手势无响应。*/}
       <View
+        accessible
         accessibilityRole="adjustable"
         accessibilityValue={{ min: safeMin, max: safeMax, now: safeValue }}
+        accessibilityActions={[
+          { name: 'increment', label: '增加' },
+          { name: 'decrement', label: '减少' },
+        ]}
+        onAccessibilityAction={(e) => {
+          if (e.nativeEvent.actionName === 'increment' && !incDisabled) {
+            onChange(Math.min(safeMax, safeValue + safeStep));
+          } else if (e.nativeEvent.actionName === 'decrement' && !decDisabled) {
+            onChange(Math.max(safeMin, safeValue - safeStep));
+          }
+        }}
         style={[styles.cell, { minWidth: dims.w, height: dims.h }]}
-        testID={testID ? `${testID}-value` : undefined}
+        testID={childTestID(testID, 'value')}
       >
         <Text style={[styles.valueText, { fontSize: dims.fs }]}>
           {safeValue}
@@ -80,12 +115,12 @@ export function Stepper({
         accessibilityLabel="增加"
         accessibilityState={{ disabled: incDisabled }}
         accessibilityHint={`当前值 ${safeValue}，加 ${safeStep}`}
-        testID={testID ? `${testID}-increment` : undefined}
+        testID={childTestID(testID, 'increment')}
         style={({ pressed }) => [
           styles.cell,
           styles.btnRight,
           { width: dims.btn, height: dims.h },
-          { opacity: incDisabled ? 0.4 : pressed ? 0.7 : 1 },
+          { opacity: incDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
         ]}
       >
         <Text style={styles.btnText}>+</Text>

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

@@ -9,17 +9,10 @@ import Animated, {
   useSharedValue,
   withTiming,
 } from 'react-native-reanimated';
-import { motion, r, useColors, useThemedStyles } from '../../../theme';
-import { INSET, makeStyles, THUMB, TRACK_W } from './styles';
+import { fixed, motion, r, useColors, useThemedStyles } from '../../../theme';
+import { makeStyles, THUMB_OFF_X, THUMB_ON_X, TRACK_H } from './styles';
 import type { SwitchProps } from './types';
 
-// ─── 动画派生常量(组件私有,非 style)─────────────────────────────────────
-// 把手 translateX 的 off / on 端点:左右各留 INSET 间距,
-// off = INSET(2),on = trackW - INSET - thumbW(32-2-16=14)。
-// 走 r() 保证多设备缩放跟 track / thumb 物理尺寸一致(否则非设计基准设备会错位)。
-const THUMB_OFF_X = r(INSET);
-const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
-
 /**
  * 布尔切换。32×20 轨道 + 16×16 白色把手,200ms 缓动。
  *
@@ -66,7 +59,8 @@ export function Switch({
     <Pressable
       onPress={() => !disabled && onChange(!value)}
       disabled={disabled}
-      hitSlop={6}
+      // [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 }}

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

@@ -1,16 +1,10 @@
 import React from 'react';
 import { Pressable } from 'react-native-gesture-handler';
 import { View } from 'react-native';
-import { motion, r, useColors, useThemedStyles } from '../../../theme';
-import { INSET, makeStyles, THUMB, TRACK_W } from './styles';
+import { motion, useColors, useThemedStyles } from '../../../theme';
+import { makeStyles, THUMB_OFF_X, THUMB_ON_X } from './styles';
 import type { SwitchProps } from './types';
 
-// ─── 动画派生常量(组件私有,非 style)─────────────────────────────────────
-// 把手 translateX 的 off / on 端点:左右各留 INSET 间距,
-// off = INSET(2),on = trackW - INSET - thumbW(32-2-16=14)。
-const THUMB_OFF_X = r(INSET);
-const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
-
 /**
  * Web 端 Switch —— RN-Web 上 reanimated 4 + worklets 0.9.x 的 useAnimatedStyle
  * 链路会抛 `Object.keys(undefined)` TypeError(切换时打印,thumb 卡住),走 CSS

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

@@ -9,13 +9,21 @@ export const TRACK_H = 20;
 export const THUMB = 16;
 export const INSET = 2;
 
+/** [M-25] 把手 translateX 端点 —— 与 styles 同源导出,Switch.tsx / Switch.web.tsx 两端 import。
+ *  off = INSET(2),on = TRACK_W - INSET - THUMB(32-2-16=14)。走 r() 保证多设备缩放一致。 */
+export const THUMB_OFF_X = r(INSET);
+export const THUMB_ON_X = r(TRACK_W - INSET - THUMB);
+
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
     pressableEnabled: {
       opacity: 1,
+      // [L-37] alignSelf:'flex-start' 防止父容器拉伸把手区域(与 Chip [M-8] 同口径)
+      alignSelf: 'flex-start' as const,
     },
     pressableDisabled: {
       opacity: 0.5,
+      alignSelf: 'flex-start' as const,
     },
     track: {
       width: r(TRACK_W),
@@ -26,7 +34,8 @@ export const makeStyles = (c: ColorTokens) =>
     thumb: {
       width: r(THUMB),
       height: r(THUMB),
-      borderRadius: radius.md,
+      // [L-79] radius.pill —— sentinel 999 确保把手始终是真圆
+      borderRadius: radius.pill,
       backgroundColor: c.onPrimary,
     },
   });

package/src/components/ui/TabBar/TabBar.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { icon, useColors, useThemedStyles } from '../../../theme';
+import { pressedOpacity, r, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { Icon } from '../Icon';
 import { makeStyles } from './styles';
@@ -9,38 +9,46 @@ import type { TabBarProps } from './types';
 
 /**
  * 固定底部 tab bar —— App 主导航。
- * 高 50px，顶部一条细线边框。激活色：primary-300。
+ * 高 50px，顶部一条细线边框。激活色：primary。
  * 想留 home indicator 的安全区，请外面包一层 `<SafeAreaView edges={['bottom']}>`。
  */
 export function TabBar({
   active,
   onChange,
   items,
+  style,
   testID,
 }: TabBarProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
   return (
-    <View style={styles.bar} testID={testID}>
+    <View
+      style={[styles.bar, style]}
+      testID={testID}
+      accessibilityRole="tablist"
+    >
       {items.map((item) => {
         const on = item.id === active;
         const tint = on ? c.primary : c.foregroundSubtle;
         const itemTestID = childTestID(testID, item.id, item.testID);
+        // a11y label 包含角标数量,SR 用户知晓待处理条目数(如"消息,3条未读")
+        const a11yLabel =
+          item.badge != null ? `${item.label},${item.badge}条未读` : item.label;
         return (
           <Pressable
             key={item.id}
             onPress={() => onChange(item.id)}
             accessibilityRole="tab"
             accessibilityState={{ selected: on }}
-            accessibilityLabel={item.label}
+            accessibilityLabel={a11yLabel}
             testID={itemTestID}
             style={({ pressed }) => [
               styles.tab,
-              { opacity: pressed ? 0.7 : 1 },
+              { opacity: pressed ? pressedOpacity : 1 },
             ]}
           >
             <View>
-              <Icon name={item.icon} size={icon.sm} color={tint} />
+              <Icon name={item.icon} size={r(22)} color={tint} />
               {item.badge != null ? (
                 <View style={styles.badge}>
                   <Text style={styles.badgeText}>{item.badge}</Text>

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

@@ -1,9 +1,12 @@
 import { StyleSheet } from 'react-native';
 import type { ColorTokens } from '../../../theme';
-import { fixed, fw, r, radius, space, type as t } from '../../../theme';
+import { fixed, fw, r, type as t } from '../../../theme';
+import { badgeStyles } from '../shared/badgeStyles';
 
-export const makeStyles = (c: ColorTokens) =>
-  StyleSheet.create({
+export const makeStyles = (c: ColorTokens) => {
+  // TabBar 图标 22pt,角标上边缘偏移 r(-3):使圆心落在图标右上角
+  const badge = badgeStyles(c, r(-3));
+  return StyleSheet.create({
     bar: {
       height: fixed.tabbarH,
       flexDirection: 'row',
@@ -22,22 +25,7 @@ export const makeStyles = (c: ColorTokens) =>
       fontWeight: fw.medium,
       lineHeight: 12,
     },
-    badge: {
-      position: 'absolute',
-      top: r(-3),
-      right: r(-10),
-      minWidth: r(16),
-      height: r(16),
-      borderRadius: radius.md,
-      backgroundColor: c.error,
-      paddingHorizontal: space[1],
-      alignItems: 'center',
-      justifyContent: 'center',
-    },
-    badgeText: {
-      color: c.onError,
-      fontSize: t.nano,
-      fontWeight: fw.bold,
-      lineHeight: 12,
-    },
+    badge: badge.badge,
+    badgeText: badge.badgeText,
   });
+};

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

@@ -1,3 +1,4 @@
+import type { StyleProp, ViewStyle } from 'react-native';
 import type { IconName } from '../Icon';
 
 export type TabBarItem = {
@@ -14,6 +15,8 @@ export type TabBarProps = {
   active: string;
   onChange: (id: string) => void;
   items: TabBarItem[];
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** 容器 testID；item testID 自动派生为 `${testID}-${id}` */
   testID?: string;
 };

package/src/components/ui/Tabs/Tabs.tsx

@@ -1,11 +1,14 @@
 import React from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
-import { useColors, useThemedStyles, fw } from '../../../theme';
+import { fw, pressedOpacity, useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
 import { childTestID } from '../../../utils/testID';
 import { makeStyles } from './styles';
 import type { TabsProps } from './types';
 
+const log = createLogger('Tabs');
+
 /**
  * 页面级下划线 tabs。
  * 占满宽度，高 44px，激活项下方有 2px 主色下划线。
@@ -14,26 +17,42 @@ export function Tabs({
   value,
   onChange,
   items,
+  disabled: allDisabled = false,
+  style,
   testID,
 }: TabsProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
+  // items 长度守卫 —— types 注释承诺「≥2 项才有意义」,此处对违规使用方 dev warn。
+  // 不 return null:渲染空 tablist 比渲染单 tab 更符合 a11y 预期,且不破坏 hook 调用顺序。
+  if (items.length < 2) {
+    log.warn(`Tabs 至少需要 2 项，当前传入 ${items.length} 项`);
+  }
   return (
-    <View style={styles.under} testID={testID}>
+    <View
+      style={[styles.under, style]}
+      testID={testID}
+      accessibilityRole="tablist"
+    >
       {items.map((it) => {
         const on = it.id === value;
+        const itemDisabled = allDisabled || (it.disabled ?? false);
         const itemTestID = childTestID(testID, it.id, it.testID);
         return (
           <Pressable
             key={it.id}
-            onPress={() => onChange(it.id)}
+            onPress={() => !itemDisabled && onChange(it.id)}
+            disabled={itemDisabled}
             accessibilityRole="tab"
-            accessibilityState={{ selected: on }}
+            accessibilityState={{
+              selected: on,
+              disabled: itemDisabled || undefined,
+            }}
             accessibilityLabel={it.label}
             testID={itemTestID}
             style={({ pressed }) => [
               styles.underTab,
-              { opacity: pressed ? 0.7 : 1 },
+              { opacity: itemDisabled ? 0.4 : pressed ? pressedOpacity : 1 },
             ]}
           >
             <Text

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

@@ -1,6 +1,10 @@
 import { StyleSheet } from 'react-native';
 import type { ColorTokens } from '../../../theme';
-import { fixed, icon, r, type as t } from '../../../theme';
+import { fixed, r, type as t } from '../../../theme';
+
+// 下划线宽度固定 36pt —— 视觉上比 tab 文字稍宽、比整个 tab 格窄,
+// 刻意不用 icon.xl(语义是图标盒),此处是装饰性下划线,用具名常量自文档化。
+const UNDER_BAR_WIDTH = r(36);
 
 export const makeStyles = (c: ColorTokens) =>
   StyleSheet.create({
@@ -23,7 +27,7 @@ export const makeStyles = (c: ColorTokens) =>
       position: 'absolute',
       bottom: 0,
       height: r(2),
-      width: icon.xl,
+      width: UNDER_BAR_WIDTH,
       backgroundColor: c.primary,
       borderRadius: r(1),
     },

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

@@ -1,8 +1,12 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
 export type TabItem = {
   /** 唯一 id，用作 key 跟选中标识 */
   id: string;
   /** 显示文本 */
   label: string;
+  /** 禁用该 tab —— disabled=true 时不可点击 + SR 报 disabled 状态 */
+  disabled?: boolean;
   /** 单 item testID（不传则自动用 `${tabsTestID}-${id}`） */
   testID?: string;
 };
@@ -12,8 +16,13 @@ export type TabsProps = {
   value: string;
   /** 切换 tab 回调 */
   onChange: (id: string) => void;
-  /** tab 列表（≥2 项才显示） */
+  /** tab 列表（≥2 项才显示）
+   *  @note 传入 < 2 项时组件仍渲染,但通常无意义;调用方应保证传入 ≥2 项。 */
   items: TabItem[];
+  /** 整体禁用 —— 所有 tab 不可点击(如异步加载数据期间) */
+  disabled?: boolean;
+  /** 容器附加样式(margin / position 等布局微调)。 */
+  style?: StyleProp<ViewStyle>;
   /** 容器 testID；item testID 自动派生为 `${testID}-${id}` */
   testID?: string;
 };

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

@@ -1,5 +1,12 @@
 import { StyleSheet } from 'react-native';
-import { fw, radius, type ColorTokens } from '../../../theme';
+import {
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
 import type { TagSize, TagVariant } from './types';
 
 /** Tag 静态 base —— alignSelf 防 flex 父容器拉伸,radius 走 token。 */
@@ -24,16 +31,23 @@ export function sizingFor(size: TagSize): {
 } {
   switch (size) {
     case 'md':
-      return { h: 22, px: 8, fs: 12 };
+      return { h: r(22), px: space['3'], fs: t.xxs };
     case 'lg':
-      return { h: 26, px: 10, fs: 13 };
+      return { h: r(26), px: space['4'], fs: t.xs };
   }
 }
 
 /** Tag 颜色推导:variant → { bg, fg, border } 三色,全走 ColorTokens。
- *  签名 `(target, context)` 与 chat/Tool 的 tintFor / variantFor / labelFor 一致。 */
+ *  签名 `(variant, c)` 与 Button/Avatar 的 paletteFor 一致。
+ *  新增 variant 在 types.ts 加 union + 这里加 case。 */
 export function paletteFor(variant: TagVariant, c: ColorTokens) {
   switch (variant) {
+    case 'neutral':
+      return {
+        bg: c.surfaceContainerHigh,
+        fg: c.foregroundMuted,
+        border: undefined,
+      };
     case 'brand':
       return { bg: c.primaryContainer, fg: c.primary, border: undefined };
     case 'success':
@@ -48,11 +62,5 @@ export function paletteFor(variant: TagVariant, c: ColorTokens) {
         fg: c.foregroundMuted,
         border: c.outline,
       };
-    default:
-      return {
-        bg: c.surfaceContainerHigh,
-        fg: c.foregroundMuted,
-        border: undefined,
-      };
   }
 }

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

@@ -14,7 +14,7 @@ export type TagVariant =
   | 'info'
   | 'outline';
 
-/** Tag 尺寸：md=22 (h) / lg=26 (h) */
+/** Tag 尺寸：md=22 (h) / lg=26 (h)，均随设备宽度缩放 */
 export type TagSize = 'md' | 'lg';
 
 export type TagProps = {
@@ -26,7 +26,11 @@ export type TagProps = {
   size?: TagSize;
   /** 额外样式覆盖 */
   style?: StyleProp<ViewStyle>;
-  /** 文本 numberOfLines，默认 1（超长 ellipsis） */
+  /**
+   * 文本截断行数，默认 1（超长 ellipsis）。
+   * **警告：Tag 高度钉死（md=22 / lg=26），传 >1 时多余行溢出或被裁，
+   * 仅在同时自定义高度的场景才有意义。**
+   */
   numberOfLines?: number;
   /** E2E / 测试定位 */
   testID?: string;