@unif/react-native-design 0.19.0 → 0.21.0

package/src/components/ui/Confirm/ConfirmHost.tsx

@@ -11,20 +11,24 @@ import {
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { space, useThemedStyles } from '../../../theme';
 import { Button } from '../Button';
-import { _subs } from './confirm';
+import { registerConfirmHost, settleConfirm } from './confirm';
+import { resolveConfirmLabels } from './labels';
 import { makeStyles } from './styles';
-import type { ConfirmEntry, Subscriber } from './types';
+import type { ConfirmEntry, ConfirmEvent } from './store';
 
 /** 遮罩淡入 / 淡出时长(ms)—— 出场略长于入场,与 Modal slide 退场(~300ms)大致同步收完。 */
 const SCRIM_IN_MS = 220;
 const SCRIM_OUT_MS = 260;
 
 /**
- * Confirm 对话框宿主 —— App 根挂一次,监听 `confirm()` 调用并渲染。
+ * Confirm 对话框宿主 —— App 根挂**一次**,监听 `confirm()` 调用并渲染。
  *
  * 原生 RN `Modal`(transparent + animationType slide)从底部滑入,backdrop 点击
- * 取消、内层 sheet 拦截点击不冒泡。**不依赖 @gorhom**(0.6.0 去 @gorhom 后改为
- * 纯 RN Modal + pub/sub 实现)。
+ * 取消、内层 sheet 拦截点击不冒泡。**不依赖 @gorhom**。
+ *
+ * 唯一 owner:重复挂载的实例拿到 `null` lease,永久惰性、不渲染 —— 不会出现两个
+ * Host 争抢同一个对话框。所有关闭路径统一走 `settleConfirm(entry, result)`,
+ * 组件内不直接调用 entry 的 resolver。
  */
 export function ConfirmHost(): React.JSX.Element | null {
   const styles = useThemedStyles(makeStyles);
@@ -32,36 +36,55 @@ export function ConfirmHost(): React.JSX.Element | null {
   const { height: screenH } = useWindowDimensions();
   const [entry, setEntry] = useState<ConfirmEntry | null>(null);
 
-  // 跟踪当前未决 entry,供 unmount cleanup resolve(false)。
+  // 同步权威副本:effect cleanup 与迟到回调都读它,不受 React state 批处理延迟影响。
   const pendingRef = useRef<ConfirmEntry | null>(null);
-  pendingRef.current = entry;
+
+  // 注册失败(已有 owner)时保持惰性:不订阅、不渲染。
+  const [inert, setInert] = useState(false);
 
   // 保留最后一次显示的 entry:关闭时 entry 立即置 null,但 slide 退场动画期 Modal 仍可见,
   // 渲染 lastEntry 才不会滑出一个只剩 padding 的空 sheet([M-17])。
   const lastEntryRef = useRef<ConfirmEntry | null>(null);
   if (entry) lastEntryRef.current = entry;
   const display = entry ?? lastEntryRef.current;
+  const labels = resolveConfirmLabels({
+    confirmLabel: display?.options.confirmLabel,
+    cancelLabel: display?.options.cancelLabel,
+  });
 
   useEffect(() => {
-    // [L-101] Subscriber 不再接收 null —— 收到新 entry 即显示;关闭路径由 resolve() 驱动
-    const sub: Subscriber = (next) => setEntry(next);
-    _subs.add(sub);
+    const subscriber = (event: ConfirmEvent) => {
+      // 先写同步 ref 再置 React state —— cleanup 与迟到回调依赖 ref 的即时正确性。
+      if (event.type === 'show') {
+        pendingRef.current = event.entry;
+        setEntry(event.entry);
+        return;
+      }
+      if (pendingRef.current?.id === event.id) {
+        pendingRef.current = null;
+        setEntry((current) => (current?.id === event.id ? null : current));
+      }
+    };
+    const lease = registerConfirmHost(subscriber);
+    if (!lease) {
+      setInert(true);
+      return;
+    }
     return () => {
-      _subs.delete(sub);
-      // Host 卸载时若对话框仍未决(error boundary 重置 / 根 re-key 切语言主题等),
-      // resolve(false) —— 否则 confirm() 的 Promise 永久悬挂、_activeEntry 锁死([H-5])。
-      pendingRef.current?.resolve(false);
+      // 卸载时若对话框仍未决(error boundary 重置 / 根 re-key 切语言主题等),
+      // Store 把它 settle(false) —— 否则 confirm() 的 Promise 永久悬挂并锁死单例([H-5])。
+      const held = pendingRef.current;
+      pendingRef.current = null;
+      lease.release(held);
     };
   }, []);
 
   const handleConfirm = useCallback(() => {
-    entry?.resolve(true);
-    setEntry(null);
+    if (entry) settleConfirm(entry, true);
   }, [entry]);
 
   const handleCancel = useCallback(() => {
-    entry?.resolve(false);
-    setEntry(null);
+    if (entry) settleConfirm(entry, false);
   }, [entry]);
 
   // 遮罩自持淡入 / 淡出(不蹭 Modal 的位移动画,理由见下方 scrim 注释)。退场也要淡:
@@ -76,6 +99,8 @@ export function ConfirmHost(): React.JSX.Element | null {
     }).start();
   }, [entry, scrimOpacity]);
 
+  if (inert) return null;
+
   return (
     <Modal
       visible={!!entry}
@@ -113,25 +138,25 @@ export function ConfirmHost(): React.JSX.Element | null {
             <>
               <View style={styles.body}>
                 <Text style={styles.title} accessibilityRole="header">
-                  {display.title}
+                  {display.options.title}
                 </Text>
-                {display.message ? (
-                  <Text style={styles.message}>{display.message}</Text>
+                {display.options.message ? (
+                  <Text style={styles.message}>{display.options.message}</Text>
                 ) : null}
               </View>
               <View style={styles.actions}>
                 <Button
                   testID="confirm-cancel"
-                  label={display.cancelLabel ?? '取消'}
+                  label={labels.cancelLabel}
                   variant="secondary"
-                  block
+                  style={styles.action}
                   onPress={handleCancel}
                 />
                 <Button
                   testID="confirm-ok"
-                  label={display.confirmLabel ?? '确认'}
-                  variant={display.destructive ? 'danger' : 'primary'}
-                  block
+                  label={labels.confirmLabel}
+                  variant={display.options.destructive ? 'danger' : 'primary'}
+                  style={styles.action}
                   onPress={handleConfirm}
                 />
               </View>

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

@@ -4,21 +4,24 @@
  * 业务任意位置 `const ok = await confirm({title, message, ...})`,
  * 不用维护 useState / open / onClose。
  *
- * 同一时间只允许 1 个 confirm 活跃;若已有正在显示,新请求立即 resolve(false) 并 warn。
+ * 状态机全部在 `store.ts`(纯逻辑、可单测);本文件只持有唯一的模块级实例,
+ * 并把内部入口暴露给 `ConfirmHost.tsx`。这两个内部导出**不进公共 barrel**。
  */
 import { createLogger } from '../../../utils/logger';
-import type { ConfirmOptions, ConfirmEntry, Subscriber } from './types';
+import { createConfirmStore } from './store';
+import type { ConfirmOptions } from './types';
 
 const log = createLogger('confirm');
 
-let _id = 0;
-let _activeEntry: ConfirmEntry | null = null;
-export const _subs = new Set<Subscriber>();
+const store = createConfirmStore(log);
 
 /**
  * 弹出确认对话框,返回 Promise<boolean>。
  * - 用户点确认 → resolve(true)
- * - 用户点取消 / 点 backdrop / 拖关闭 → resolve(false)
+ * - 用户点取消 / 点 backdrop / 系统返回 → resolve(false)
+ * - 未挂 `<ConfirmHost />`、已有对话框在显示、Host 渲染抛错、Host 卸载 → resolve(false)
+ *
+ * 任何路径都必然 settle,不会悬挂。
  *
  * 示例:
  * ```ts
@@ -31,31 +34,11 @@ export const _subs = new Set<Subscriber>();
  * if (ok) doLogout();
  * ```
  */
-export function confirm(options: ConfirmOptions): Promise<boolean> {
-  if (_activeEntry) {
-    log.warn(
-      'confirm() 已有一个对话框在显示,新请求被拒绝(同一时间只 1 个,避免叠加)。'
-    );
-    return Promise.resolve(false);
-  }
-  // 没有 ConfirmHost 订阅 → entry 无人接收,Promise 会永久悬挂、调用方 await 卡死。
-  // 立即 resolve(false) 并告警,且不占 _activeEntry(否则后续 confirm 全被重入分支锁死)。
-  if (_subs.size === 0) {
-    log.warn(
-      'confirm() 调用时未挂载 <ConfirmHost />,对话框无法显示,已 resolve(false)。请在 app 根附近挂一次 <ConfirmHost />。'
-    );
-    return Promise.resolve(false);
-  }
-  return new Promise<boolean>((resolve) => {
-    const entry: ConfirmEntry = {
-      id: ++_id,
-      ...options,
-      resolve: (confirmed: boolean) => {
-        _activeEntry = null;
-        resolve(confirmed);
-      },
-    };
-    _activeEntry = entry;
-    _subs.forEach((s) => s(entry));
-  });
-}
+export const confirm = (options: ConfirmOptions): Promise<boolean> =>
+  store.request(options);
+
+/** 内部:ConfirmHost 挂载时注册唯一 owner;重复挂载得到 null。 */
+export const registerConfirmHost = store.registerHost;
+
+/** 内部:所有关闭路径的唯一出口(identity-guarded + 幂等)。 */
+export const settleConfirm = store.settle;

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

@@ -0,0 +1,14 @@
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import type { ConfirmOptions } from './types';
+
+export function resolveConfirmLabels(
+  options: Pick<ConfirmOptions, 'confirmLabel' | 'cancelLabel'>
+): {
+  confirmLabel: string;
+  cancelLabel: string;
+} {
+  return {
+    confirmLabel: normalizeNonBlankText(options.confirmLabel) ?? '确认',
+    cancelLabel: normalizeNonBlankText(options.cancelLabel) ?? '取消',
+  };
+}

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}`） */