@unif/react-native-design 0.20.0 → 0.21.1

package/src/components/ui/Confirm/store.ts

@@ -0,0 +1,147 @@
+import type { Logger } from '../../../utils/logger';
+import type { ConfirmOptions } from './types';
+
+/**
+ * Confirm 的纯状态机 —— 不含任何 React / 渲染依赖,可直接单测。
+ *
+ * 两条不变量:
+ * 1. **唯一 owner** —— 同一时间只有一个 `<ConfirmHost />` 持有订阅。重复挂载拿到 `null`
+ *    lease、永久惰性,不会出现两个 Host 争抢同一个 entry。
+ * 2. **唯一 active entry** —— 同一时间只有一个未决对话框。所有关闭路径(确认 / 取消 /
+ *    backdrop / 系统返回 / Host 卸载 / subscriber 抛错)都汇聚到 `settle()`。
+ *
+ * `settle()` 用 **identity guard**(`active !== entry` 直接返回 false)而非 id 比较:
+ * 旧 entry 的迟到回调拿着的是旧对象引用,永远匹配不上新 active,因此不可能误关新对话框。
+ */
+
+export type ConfirmEntry = {
+  id: number;
+  options: Readonly<ConfirmOptions>;
+  settled: boolean;
+  resolve: (result: boolean) => void;
+};
+
+export type ConfirmEvent =
+  | { type: 'show'; entry: ConfirmEntry }
+  | { type: 'clear'; id: number };
+
+export type ConfirmSubscriber = (event: ConfirmEvent) => void;
+
+export type ConfirmHostLease = {
+  readonly ownerToken: symbol;
+  /**
+   * Host 卸载。`heldEntry` 是 Host 当时手里那个未决 entry(没有则传 `null`)——
+   * 只有它仍是 active 时才会被 settle 成 `false`,避免误伤后来的对话框。
+   */
+  release(heldEntry: ConfirmEntry | null): void;
+};
+
+export type ConfirmStore = {
+  request(options: ConfirmOptions): Promise<boolean>;
+  registerHost(subscriber: ConfirmSubscriber): ConfirmHostLease | null;
+  settle(entry: ConfirmEntry, result: boolean): boolean;
+  activeEntry(): ConfirmEntry | null;
+};
+
+type Owner = { token: symbol; subscriber: ConfirmSubscriber | null };
+
+export function createConfirmStore(log: Logger): ConfirmStore {
+  let nextId = 0;
+  let active: ConfirmEntry | null = null;
+  let owner: Owner | null = null;
+
+  function settle(entry: ConfirmEntry, result: boolean): boolean {
+    if (entry.settled || active !== entry) return false;
+    // 先翻状态、再断开 active,最后才 resolve —— resolve 的 then 回调可能同步重入
+    // request(),那时必须已经看到「无 active」而不是半更新状态。
+    entry.settled = true;
+    active = null;
+    entry.resolve(result);
+    const current = owner;
+    if (current?.subscriber) {
+      try {
+        current.subscriber({ type: 'clear', id: entry.id });
+      } catch (error) {
+        log.error('ConfirmHost clear subscriber 抛错', error);
+        // 只作废「抛错时捕获到的那个 owner」;期间若已 cleanup / 换人,不能误伤新 owner。
+        // clear 回调可能同步 request() 出新 entry:先摘 owner 再 settle,避免再次回调已坏的
+        // subscriber,同时保证新 Promise 不会以「active 但无 owner」永久悬挂。
+        if (owner?.token === current.token) {
+          owner = null;
+          const reentrant = active;
+          if (reentrant) settle(reentrant, false);
+        }
+      }
+    }
+    return true;
+  }
+
+  function request(options: ConfirmOptions): Promise<boolean> {
+    if (active) {
+      log.warn(
+        'confirm() 已有一个对话框在显示,新请求被拒绝(同一时间只 1 个,避免叠加)。'
+      );
+      return Promise.resolve(false);
+    }
+    // 没有 Host 订阅 → entry 无人接收,Promise 会永久悬挂、调用方 await 卡死。
+    // 立即 resolve(false) 且不占 active(否则后续 confirm 全被重入分支锁死)。
+    const current = owner;
+    if (!current?.subscriber) {
+      log.warn(
+        'confirm() 调用时未挂载 <ConfirmHost />,对话框无法显示,已 resolve(false)。请在 app 根附近挂一次 <ConfirmHost />。'
+      );
+      return Promise.resolve(false);
+    }
+    return new Promise<boolean>((resolve) => {
+      const entry: ConfirmEntry = {
+        id: ++nextId,
+        options,
+        settled: false,
+        resolve,
+      };
+      active = entry;
+      try {
+        current.subscriber?.({ type: 'show', entry });
+      } catch (error) {
+        log.error('ConfirmHost show subscriber 抛错', error);
+        if (owner?.token === current.token) owner = null;
+        // Host 没能接住 entry:直接结算,否则 Promise 永久悬挂并锁死单例。
+        // 此处不能走 settle() —— owner 已被作废,clear 事件无处可发。
+        entry.settled = true;
+        if (active === entry) active = null;
+        resolve(false);
+      }
+    });
+  }
+
+  function registerHost(
+    subscriber: ConfirmSubscriber
+  ): ConfirmHostLease | null {
+    if (owner) {
+      log.warn(
+        '检测到多个 <ConfirmHost />。只有第一个生效,重复挂载的实例保持惰性 —— 请在 app 根只挂一次。'
+      );
+      return null;
+    }
+    const token = Symbol('ConfirmHostOwner');
+    const self: Owner = { token, subscriber };
+    owner = self;
+    return {
+      ownerToken: token,
+      release(heldEntry: ConfirmEntry | null): void {
+        if (owner?.token !== token) return;
+        // 先摘订阅,再结算:settle 内部发的 clear 事件不应再回到正在卸载的 Host。
+        self.subscriber = null;
+        owner = null;
+        if (heldEntry) settle(heldEntry, false);
+      },
+    };
+  }
+
+  return {
+    request,
+    registerHost,
+    settle,
+    activeEntry: () => active,
+  };
+}

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

@@ -48,4 +48,8 @@ export const makeStyles = (c: ColorTokens) =>
       paddingHorizontal: space['9'],
       paddingTop: space['7'],
     },
+    // action row 的两个直接 Button 平分横向主轴；不借用 Button.block 的交叉轴语义。
+    action: {
+      flex: 1,
+    },
   });

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

@@ -12,13 +12,5 @@ export type ConfirmOptions = {
   destructive?: boolean;
 };
 
-/** Host 内部 entry —— options + resolve 回调,用户点 确认/取消/backdrop 时 resolve。 */
-export type ConfirmEntry = ConfirmOptions & {
-  id: number;
-  resolve: (confirmed: boolean) => void;
-};
-
-/** ConfirmHost 监听器签名 —— 收到 entry 渲染对话框。
- *  [L-101] 删去 null 分支:全仓唯一发射点 confirm.ts:_subs.forEach 只发非 null entry,
- *  关闭路径由 ConfirmEntry.resolve() 驱动;null 分支是死协议,对齐 Toast Subscriber 签名。 */
-export type Subscriber = (entry: ConfirmEntry) => void;
+// entry / event / lease 类型都在 `store.ts` —— 它们是 Host 与 Store 之间的内部协议,
+// 不进公共 barrel。本文件只保留对外的 `ConfirmOptions`。

package/src/components/ui/DrawerHeader/DrawerHeader.tsx

@@ -1,6 +1,9 @@
-import React, { useEffect, useState } from 'react';
-import { Image, Text, View } from 'react-native';
+import React from 'react';
+import { Text, View } from 'react-native';
 import { useThemedStyles } from '../../../theme';
+import { resolveImageSource } from '../../../utils/imageSource';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { ImageAttempt } from '../shared/ImageAttempt';
 import { makeStyles } from './styles';
 import type { DrawerHeaderProps } from './types';
 
@@ -16,38 +19,30 @@ export function DrawerHeader({
   testID,
 }: DrawerHeaderProps): React.JSX.Element {
   const styles = useThemedStyles(makeStyles);
-  const [imageFailed, setImageFailed] = useState(false);
-
-  // [M-20] React 18+ 已移除 unmount 后 setState 的 warning,mountedRef 守卫为死码,删除。
-  // [L-44] source 变化时重置 imageFailed,否则换图 URL 后仍展示 fallback 文字。
-  const uri =
-    source != null && typeof source === 'object' && 'uri' in source
-      ? (source as { uri?: string }).uri
-      : null;
-  useEffect(() => {
-    setImageFailed(false);
-  }, [uri, source]);
-
-  const handleImageError = () => {
-    setImageFailed(true);
-  };
   // [L-51] 码点级取首字,防 emoji / 代理对被截断为乱码。
   const initial = [...name.trim()][0] ?? '?';
-  const showImage = source != null && !imageFailed;
+  const resolvedSource = resolveImageSource(source);
+  const fallback = <Text style={styles.avatarText}>{initial}</Text>;
+
   return (
     <View style={[styles.header, style]} testID={testID}>
-      <View style={[styles.avatar, showImage && styles.avatarImageMode]}>
-        {showImage ? (
-          <Image
-            source={source}
-            onError={handleImageError}
+      <View
+        {...A11Y_HIDDEN_PROPS}
+        style={[
+          styles.avatar,
+          resolvedSource !== undefined && styles.avatarImageMode,
+        ]}
+      >
+        {resolvedSource === undefined ? (
+          fallback
+        ) : (
+          <ImageAttempt
+            key={resolvedSource.key}
+            source={resolvedSource.source}
+            fallback={fallback}
             style={styles.avatarImage}
             resizeMode="cover"
-            accessible={!!name}
-            accessibilityLabel={name}
           />
-        ) : (
-          <Text style={styles.avatarText}>{initial}</Text>
         )}
       </View>
       <Text style={styles.name} numberOfLines={1}>

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

@@ -5,7 +5,13 @@ export type DrawerHeaderProps = {
   name: string;
   /** 副标题（comGroup · role 之类的辅助信息） */
   subtitle?: string;
-  /** 真实头像图片（URL 或 require）；提供时优先渲染 image，加载失败 fallback 到 letter */
+  /**
+   * 真实头像图片（URI object / 数组或 require）。
+   * 运行时校验后用 immutable semantic snapshot 隔离 keyed attempt；非法 source
+   * 或当前 attempt 加载失败时 fallback 到首字符，失败 state 不跨 source 共享。
+   * Web 对数组使用首个 candidate，native 保留完整数组；对象只读取 own
+   * enumerable data，继承属性、non-enumerable 与 accessor 不参与。
+   */
   source?: ImageSourcePropType;
   /** 容器附加样式(margin / position 等布局微调)。 */
   style?: StyleProp<ViewStyle>;

package/src/components/ui/Grid/Grid.tsx

@@ -1,17 +1,19 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Text, View } from 'react-native';
 import { Pressable } from 'react-native-gesture-handler';
 import { pressedOpacity, r, useColors, useThemedStyles } from '../../../theme';
 import { createLogger } from '../../../utils/logger';
 import { childTestID } from '../../../utils/testID';
 import { Icon } from '../Icon';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { gridItemAccessibilityLabel } from './accessibility';
 import { colWidth, makeStyles } from './styles';
 import type { GridProps } from './types';
 
 const log = createLogger('Grid');
 
 // 渲染路径去重集合 —— 同一 columns 值只在首次渲染时告警一次,避免长列表重复刷 log。
-const _warnedColumns = new Set<number>();
+const _warnedColumns = new Set<unknown>();
 
 /**
  * 图标入口宫格 —— 首页 / 分类落地页。1..6 列。
@@ -29,23 +31,47 @@ export function Grid({
 }: GridProps): React.JSX.Element {
   const c = useColors();
   const styles = useThemedStyles(makeStyles);
-  if (![1, 2, 3, 4, 5, 6].includes(columns) && !_warnedColumns.has(columns)) {
-    _warnedColumns.add(columns);
-    log.warn(`columns 仅支持 1..6，传入 ${columns}，已 fallback 为 4 列`);
-  }
+  const hasInvalidColumns = ![1, 2, 3, 4, 5, 6].includes(columns);
+  const actionHandler = typeof onPress === 'function' ? onPress : undefined;
+  const itemAccessibility = items.map(gridItemAccessibilityLabel);
+  const missingActionNameKey =
+    actionHandler === undefined
+      ? ''
+      : itemAccessibility
+          .map((label, index) => (label === undefined ? String(index) : ''))
+          .filter(Boolean)
+          .join(',');
+
+  useEffect(() => {
+    if (hasInvalidColumns && !_warnedColumns.has(columns)) {
+      _warnedColumns.add(columns);
+      log.warn(
+        `columns 仅支持 1..6，传入 ${String(columns)}，已 fallback 为 4 列`
+      );
+    }
+  }, [columns, hasInvalidColumns]);
+  useEffect(() => {
+    if (missingActionNameKey.length > 0) {
+      log.warn(
+        `Grid item 缺少非空业务名称(${missingActionNameKey})，已按 display-only 渲染。`
+      );
+    }
+  }, [missingActionNameKey]);
+
   const cellWidth = colWidth(columns);
   return (
     <View style={[styles.wrap, card && styles.card, style]} testID={testID}>
       <View style={styles.inner}>
-        {items.map((item) => {
+        {items.map((item, index) => {
           const itemTestID = childTestID(testID, item.id, item.testID);
+          const accessibilityLabel = itemAccessibility[index];
           const cellContent = (
             <>
               <View>
                 {/* 28pt 介于 icon.md(26) / icon.lg(30) 之间的设计稿专定字形尺寸 */}
                 <Icon name={item.icon} size={r(28)} color={c.foregroundMuted} />
                 {item.badge != null ? (
-                  <View style={styles.badge}>
+                  <View {...A11Y_HIDDEN_PROPS} style={styles.badge}>
                     <Text style={styles.badgeText}>{item.badge}</Text>
                   </View>
                 ) : null}
@@ -57,12 +83,13 @@ export function Grid({
           );
           return (
             <View key={item.id} style={cellWidth}>
-              {onPress ? (
+              {actionHandler !== undefined &&
+              accessibilityLabel !== undefined ? (
                 // 有 onPress 才挂 Pressable + button 语义,纯展示宫格不播报 button
                 <Pressable
-                  onPress={() => onPress(item)}
+                  onPress={() => actionHandler(item)}
                   accessibilityRole="button"
-                  accessibilityLabel={item.label}
+                  accessibilityLabel={accessibilityLabel}
                   testID={itemTestID}
                   style={({ pressed }) => [
                     styles.cell,
@@ -72,7 +99,12 @@ export function Grid({
                   {cellContent}
                 </Pressable>
               ) : (
-                <View style={styles.cell} testID={itemTestID}>
+                <View
+                  accessible={accessibilityLabel !== undefined}
+                  accessibilityLabel={accessibilityLabel}
+                  style={styles.cell}
+                  testID={itemTestID}
+                >
                   {cellContent}
                 </View>
               )}

package/src/components/ui/Grid/accessibility.ts

@@ -0,0 +1,21 @@
+import type { GridItem } from './types';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+
+type GridItemAccessibilityContent = Pick<
+  GridItem,
+  'accessibilityLabel' | 'badge' | 'label'
+>;
+
+export function gridItemAccessibilityLabel(
+  item: GridItemAccessibilityContent
+): string | undefined {
+  const explicitLabel = normalizeNonBlankText(item.accessibilityLabel);
+  if (explicitLabel !== undefined) {
+    return explicitLabel;
+  }
+  const visibleLabel = normalizeNonBlankText(item.label);
+  if (visibleLabel === undefined) return undefined;
+  return item.badge != null
+    ? `${visibleLabel}，${String(item.badge).trim()}`
+    : visibleLabel;
+}

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

@@ -5,6 +5,8 @@ export type GridItem = {
   id: string;
   icon: IconName;
   label: string;
+  /** 覆盖单格的可访问名称；空白值回退到 label + 可选 badge。 */
+  accessibilityLabel?: string;
   /** 图标右上角的数字角标（用 string 才能写 '99+'） */
   badge?: number | string;
   /** 单 cell 测试定位（不传则自动用 `${gridTestID}-${id}`） */

package/src/components/ui/IconButton/IconButton.tsx

@@ -1,8 +1,12 @@
-import React from 'react';
+import React, { useEffect } from 'react';
+import { createLogger } from '../../../utils/logger';
 import { ButtonBase } from '../Button/ButtonBase';
 import { Icon } from '../Icon';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
 import type { IconButtonProps } from './types';
 
+const log = createLogger('IconButton');
+
 /**
  * Icon-only 按钮 —— 与 Button 共享 ButtonBase chrome。
  *
@@ -22,9 +26,21 @@ export function IconButton({
   loading,
   accessibilityLabel,
   accessibilityHint,
+  accessibilityState,
   style,
   testID,
 }: IconButtonProps): React.JSX.Element {
+  const accessibleName = normalizeNonBlankText(accessibilityLabel);
+  const hasBlankLabel = accessibleName === undefined;
+
+  useEffect(() => {
+    if (hasBlankLabel) {
+      log.warn(
+        'IconButton accessibilityLabel 不能为空白，当前 action 已禁用。'
+      );
+    }
+  }, [hasBlankLabel]);
+
   return (
     <ButtonBase
       square
@@ -32,9 +48,10 @@ export function IconButton({
       size={size}
       variant={variant}
       loading={loading}
-      disabled={disabled}
-      accessibilityLabel={accessibilityLabel}
+      disabled={disabled === true || hasBlankLabel}
+      accessibilityLabel={accessibleName}
       accessibilityHint={accessibilityHint}
+      accessibilityState={accessibilityState}
       style={style}
       testID={testID}
     >

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

@@ -1,4 +1,4 @@
-import type { StyleProp, ViewStyle } from 'react-native';
+import type { AccessibilityState, StyleProp, ViewStyle } from 'react-native';
 import type { IconName } from '../Icon';
 import type { ButtonSize, ButtonVariant } from '../Button/types';
 
@@ -9,7 +9,7 @@ export type IconButtonProps = {
   /** 图标名 */
   icon: IconName;
   /** 点击;disabled 时不触发 */
-  onPress?: () => void;
+  onPress: () => void;
   /** 尺寸,默认 'md'(28 / 36 / 44 方形) */
   size?: ButtonSize;
   /** 视觉变体,默认 'ghost'(透明底,适合 header right-tray 场景)。
@@ -27,6 +27,8 @@ export type IconButtonProps = {
   accessibilityLabel: string;
   /** SR 朗读 label 后的行为说明 hint。仅在"行为不显然"时加。 */
   accessibilityHint?: string;
+  /** 额外 a11y 状态；disabled / busy 由组件根据 disabled / loading 统一上报。 */
+  accessibilityState?: Omit<AccessibilityState, 'disabled' | 'busy'>;
   /** 额外样式 */
   style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */

package/src/components/ui/Input/Input.tsx

@@ -1,5 +1,7 @@
 import { forwardRef } from 'react';
-import { TextFieldBase, type TextInputRef } from '../TextField/TextFieldBase';
+import { TextFieldBase } from '../TextField/TextFieldBase';
+import { sanitizeTextFieldWrapperProps } from '../TextField/normalize';
+import type { TextFieldHandle } from '../TextField/types';
 import type { InputProps } from './types';
 
 /**
@@ -7,14 +9,22 @@ import type { InputProps } from './types';
  *
  * 视觉状态由 props 隐式驱动:idle / focus / filled / error / disabled。
  *
- * 实现层走 `<TextFieldBase multiline={false}>`,本组件是薄 wrap,
- * 公开 API 跟历史完全一致。
+ * 实现层走 `<TextFieldBase multiline={false}>`,本组件是薄 wrap。
  *
- * Ref:forwardRef<TextInput> —— 业务表单调 `inputRef.current?.focus()` 聚焦错误字段。
+ * Ref:forwardRef<TextFieldHandle> —— 业务表单只能调 focus()/blur(),不会绕过值状态机。
  */
-export const Input = forwardRef<TextInputRef, InputProps>(
+export const Input = forwardRef<TextFieldHandle, InputProps>(
   function Input(props, ref) {
-    return <TextFieldBase ref={ref} multiline={false} {...props} />;
+    const { props: safeProps } = sanitizeTextFieldWrapperProps(
+      props as InputProps & Record<string, unknown>
+    );
+    return (
+      <TextFieldBase
+        ref={ref}
+        {...(safeProps as InputProps)}
+        multiline={false}
+      />
+    );
   }
 );
 

package/src/components/ui/Input/index.ts

@@ -1,2 +1,7 @@
 export { Input } from './Input';
 export type { InputProps } from './types';
+export type {
+  TextFieldContainerStyle,
+  TextFieldHandle,
+  TextFieldSlot,
+} from '../TextField/types';

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

@@ -1,5 +1,9 @@
-import type { ReactNode } from 'react';
-import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
+import type { TextInputProps } from 'react-native';
+import type {
+  RemovedTextInputProps,
+  TextFieldCommonProps,
+  TextFieldValueProps,
+} from '../TextField/types';
 
 /**
  * 单行文本输入框。多行内容请用 `<Textarea />`。
@@ -9,24 +13,9 @@ import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
  *
  * `multiline` / `numberOfLines` 故意 omit —— 单行场景这俩属性无意义，多行请用 Textarea。
  */
-export type InputProps = Omit<
-  TextInputProps,
-  'style' | 'multiline' | 'numberOfLines'
-> & {
-  /** 可选的前置插槽（图标、label 等） */
-  leading?: ReactNode;
-  /** 可选的后置插槽（清除按钮、眼睛切换等） */
-  trailing?: ReactNode;
-  /** 错误信息 —— 容器进入错误态并在下方显示。
-   *  空串 `""` / undefined 都不进 error 态(truthy 判定),与 TextFieldBase 保持一致。[L-96] */
-  error?: string;
-  /** 覆盖单行高度，默认 control.lg(r(44),随设备缩放) */
-  height?: number;
-  /** 容器外层样式（含 leading/trailing 整个 wrap） */
-  containerStyle?: StyleProp<ViewStyle>;
-  /**
-   * 整体禁用：等价于 `editable={false}` + 视觉变灰；优先级高于 RN 原生 `editable`。
-   * 业务表单常用此 prop 而非 editable，命名更直觉。
-   */
-  disabled?: boolean;
-};
+export type InputProps = Omit<TextInputProps, RemovedTextInputProps> &
+  TextFieldCommonProps &
+  TextFieldValueProps & {
+    /** 覆盖单行高度，默认 control.lg(r(44),随设备缩放) */
+    height?: number;
+  };

package/src/components/ui/Logo/Logo.tsx

@@ -1,8 +1,12 @@
-import React from 'react';
+import React, { useEffect, useRef } from 'react';
 import { Image } from 'react-native';
 import { r } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
 import type { LogoProps } from './types';
 
+const log = createLogger('Logo');
+
 /**
  * 品牌 logo 容器组件 —— 提供尺寸 / 圆角 / a11y 标准化包装。
  *
@@ -10,20 +14,39 @@ import type { LogoProps } from './types';
  * (推荐 1024×1024 RGBA PNG / SVG 转 png)。
  *
  * @example
- * <Logo source={require('@/assets/logo.png')} size={64} label="Unif" />
+ * <Logo source={require('@/assets/logo.png')} size={64} accessibilityLabel="Unif" />
  */
 export function Logo({
   source,
   size = r(64),
   borderRadius,
-  label = 'Logo',
+  accessibilityLabel,
   style,
   testID,
 }: LogoProps): React.JSX.Element {
+  const warnedBlankLabelRef = useRef(false);
+  const normalizedLabel = accessibilityLabel?.trim();
+  const hasBlankLabel = accessibilityLabel != null && normalizedLabel === '';
+
+  useEffect(() => {
+    if (__DEV__ && hasBlankLabel && !warnedBlankLabelRef.current) {
+      warnedBlankLabelRef.current = true;
+      log.warn('accessibilityLabel 不能为空白，当前 Logo 已按装饰图片处理');
+    }
+  }, [hasBlankLabel]);
+
+  const accessibilityProps = normalizedLabel
+    ? {
+        accessible: true,
+        accessibilityLabel: normalizedLabel,
+        accessibilityRole: 'image' as const,
+      }
+    : A11Y_HIDDEN_PROPS;
+
   return (
     <Image
+      {...accessibilityProps}
       source={source}
-      accessibilityLabel={label}
       style={[
         {
           width: size,

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

@@ -7,8 +7,8 @@ export type LogoProps = {
   size?: number;
   /** 覆盖圆角。默认 `size / 4`,呈柔和的 squircle。 */
   borderRadius?: number;
-  /** SR / 测试用文案,默认 'Logo'。 */
-  label?: string;
+  /** 非空时作为有意义图片的可访问名称；缺省时按装饰图片处理。 */
+  accessibilityLabel?: string;
   style?: StyleProp<ImageStyle>;
   /** E2E / 测试定位 */
   testID?: string;