jdf2e · xiaoyatong · Aug 28, 2026 · Aug 26, 2026 · Aug 26, 2026 · Aug 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+# v3.0.22-cpp
+
+`2026-08-28`
+
+- 🐛 fix(swipe): 修复 Taro Android/iOS 环境下 `document.addEventListener` 不是函数导致报错的问题
+- 🐛 fix(taro): 修复 imagepreview/barrage/popover 在 Taro 非 H5 环境下访问 `document` API 报错的问题
+
 # v3.0.21-cpp
 
 `2026-05-20`

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nutui/nutui-react-taro",
-  "version": "3.0.21-cpp",
+  "version": "3.0.22-cpp",
   "style": "dist/style.css",
   "main": "dist/nutui.react.umd.js",
   "module": "dist/es/packages/nutui.react.build.js",

diff --git a/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap b/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap
diff --git a/src/packages/barrage/__tests__/barrage.spec.tsx b/src/packages/barrage/__tests__/barrage.spec.tsx
@@ -88,3 +88,25 @@ test('should danmu rows top', async () => {
     { timeout: 4000 }
   )
 })
+
+describe('barrage.taro document guard logic', () => {
+  test('skips createElement when document.createElement is not a function', () => {
+    const original = document.createElement.bind(document)
+    // @ts-expect-error simulate non-H5 Taro env
+    document.createElement = undefined
+
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.createElement !== 'function'
+    expect(shouldSkip).toBe(true)
+
+    document.createElement = original
+  })
+
+  test('does not skip createElement in normal H5 env', () => {
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.createElement !== 'function'
+    expect(shouldSkip).toBe(false)
+  })
+})
diff --git a/src/packages/barrage/barrage.taro.tsx b/src/packages/barrage/barrage.taro.tsx
@@ -144,6 +144,11 @@ const InternalBarrage: ForwardRefRenderFunction<
     if (!loop && index.current >= list.length) {
       return
     }
+    if (
+      typeof document === 'undefined' ||
+      typeof document.createElement !== 'function'
+    )
+      return
 
     const _index = loop ? index.current % list.length : index.current
     const el = document.createElement(`View`)

diff --git a/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap b/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap
@@ -11,11 +11,13 @@ exports[`Cascader > value 1`] = `<div />`;
 exports[`Cascader > visible true 1`] = `
 <div>
   <div
+    arialabel="蒙层"
     class="nut-overlay"
     style="z-index: 1000;"
   />
   <div
     class="nut-popup nut-popup-round nut-popup-bottom"
+    role="dialog"
     style="z-index: 1000;"
   >
     <div

diff --git a/src/packages/cell/__test__/__snapshots__/cell.spec.tsx.snap b/src/packages/cell/__test__/__snapshots__/cell.spec.tsx.snap
@@ -99,7 +99,11 @@ exports[`slot extra 1`] = `
       class="nut-cell-extra"
     >
       <div
+        aria-checked="true"
+        aria-disabled="false"
         class="nut-switch"
+        role="switch"
+        tabindex="0"
       >
         <div
           class="nut-switch-button nut-switch-button-open"

diff --git a/src/packages/checkbox/__test__/__snapshots__/checkbox.spec.tsx.snap b/src/packages/checkbox/__test__/__snapshots__/checkbox.spec.tsx.snap
@@ -3,7 +3,10 @@
 exports[`should match snapshot 1`] = `
 <DocumentFragment>
   <div
-    class="nut-checkbox nut-checkbox-reverse"
+    aria-checked="true"
+    class="nut-checkbox nut-checkbox-reverse nut-checkbox-active"
+    role="checkbox"
+    tabindex="0"
   >
     <div
       class="nut-checkbox-icon-wrap"

diff --git a/src/packages/grid/__test__/__snapshots__/grid.spec.tsx.snap b/src/packages/grid/__test__/__snapshots__/grid.spec.tsx.snap
@@ -319,6 +319,7 @@ exports[`render with custom content 1`] = `
           >
             <img
               alt=""
+              aria-hidden="false"
               class="nut-image-default"
               src="https://img12.360buyimg.com/imagetools/jfs/t1/143702/31/16654/116794/5fc6f541Edebf8a57/4138097748889987.png"
               style="object-fit: fill; object-position: center;"

diff --git a/src/packages/image/__test__/__snapshots__/image.spec.tsx.snap b/src/packages/image/__test__/__snapshots__/image.spec.tsx.snap
@@ -8,6 +8,7 @@ exports[`image props test 1`] = `
   >
     <img
       alt=""
+      aria-hidden="false"
       class="nut-image-default"
       src="https://img10.360buyimg.com/ling/jfs/t1/181258/24/10385/53029/60d04978Ef21f2d42/92baeb21f907cd24.jpg"
       style="object-fit: fill; object-position: center;"

diff --git a/src/packages/imagepreview/__test__/imagepreview.spec.tsx b/src/packages/imagepreview/__test__/imagepreview.spec.tsx
@@ -196,3 +196,25 @@ describe('ImagePreview Component', () => {
     })
   })
 })
+
+describe('imagepreview.taro document guard logic', () => {
+  test('skips addEventListener when document.addEventListener is not a function', () => {
+    const original = document.addEventListener
+    // @ts-expect-error simulate non-H5 Taro env
+    document.addEventListener = undefined
+
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    expect(shouldSkip).toBe(true)
+
+    document.addEventListener = original
+  })
+
+  test('does not skip addEventListener in normal H5 env', () => {
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    expect(shouldSkip).toBe(false)
+  })
+})
diff --git a/src/packages/imagepreview/imagepreview.taro.tsx b/src/packages/imagepreview/imagepreview.taro.tsx
@@ -149,6 +149,11 @@ export const ImagePreview: FunctionComponent<Partial<TaroImagePreviewProps>> = (
     init()
   }, [])
   const init = () => {
+    if (
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    )
+      return
     document.addEventListener('touchmove', onTouchMove as any)
     document.addEventListener('touchend', onTouchEnd)
     document.addEventListener('touchcancel', onTouchEnd)

diff --git a/src/packages/numberkeyboard/_test_/__snapshots__/index.spec.tsx.snap b/src/packages/numberkeyboard/_test_/__snapshots__/index.spec.tsx.snap
@@ -3,11 +3,13 @@
 exports[`should match custom snapshot 1`] = `
 <div>
   <div
+    arialabel="蒙层"
     class="nut-overlay"
     style="background-color: rgba(0, 0, 0, 0); z-index: 9999;"
   />
   <div
     class="nut-popup nut-popup-round nut-popup-bottom"
+    role="dialog"
     style="z-index: 9999;"
   >
     <div
@@ -196,11 +198,13 @@ exports[`should match custom snapshot 1`] = `
 exports[`should match snapshot 1`] = `
 <div>
   <div
+    arialabel="蒙层"
     class="nut-overlay"
     style="background-color: rgba(0, 0, 0, 0); z-index: 9999;"
   />
   <div
     class="nut-popup nut-popup-round nut-popup-bottom"
+    role="dialog"
     style="z-index: 9999;"
   >
     <div

diff --git a/src/packages/overlay/__tests__/__snapshots__/overlay.spec.tsx.snap b/src/packages/overlay/__tests__/__snapshots__/overlay.spec.tsx.snap
@@ -3,6 +3,7 @@
 exports[`content test 1`] = `
 <div>
   <div
+    arialabel="蒙层"
     class="nut-overlay"
     style="z-index: 1000;"
   >

diff --git a/src/packages/overlay/__tests__/overlay.spec.tsx b/src/packages/overlay/__tests__/overlay.spec.tsx
@@ -11,6 +11,7 @@ test('should change z-index when using z-index prop', () => {
   // @ts-ignore
   expect(getByTestId('overlay-zindex')).toMatchInlineSnapshot(`
     <div
+      arialabel="蒙层"
       class="nut-overlay"
       data-testid="overlay-zindex"
       style="z-index: 99;"

diff --git a/src/packages/popover/popover.taro.tsx b/src/packages/popover/popover.taro.tsx
@@ -86,7 +86,9 @@ export const Popover: FunctionComponent<
     nextTick(async () => {
       const rect = targetId
         ? await getRectInMultiPlatform(
-            document.querySelector(`#${targetId}`),
+            typeof document !== 'undefined'
+              ? document.querySelector(`#${targetId}`)
+              : null,
             targetId
           )
         : await getRectInMultiPlatform(popoverRef.current, popoverId)

diff --git a/src/packages/progress/__tests__/progress.spec.tsx b/src/packages/progress/__tests__/progress.spec.tsx
@@ -69,7 +69,7 @@ test('should handle animation mode and duration', () => {
 
 test('should render with aria-label', () => {
   const { container } = render(
-    <Progress percent={50} ariaLabel="当前进度50%" />
+    <Progress percent={50} aria-label="当前进度50%" />
   )
   const progressDiv = container.querySelector('.nut-progress')
   expect(progressDiv?.getAttribute('aria-label')).toBe('当前进度50%')

diff --git a/src/packages/resultpage/__test__/__snapshots__/resultpage.spec.tsx.snap b/src/packages/resultpage/__test__/__snapshots__/resultpage.spec.tsx.snap
@@ -6,6 +6,7 @@ exports[`should render description correctly 1`] = `
     class="nut-resultpage"
   >
     <div
+      aria-hidden="true"
       class="nut-resultpage-icon"
     >
       <svg

diff --git a/src/packages/skeleton/__test__/__snapshots__/skeleton.spec.tsx.snap b/src/packages/skeleton/__test__/__snapshots__/skeleton.spec.tsx.snap
diff --git a/src/packages/swipe/__tests__/swipe.spec.tsx b/src/packages/swipe/__tests__/swipe.spec.tsx
@@ -96,3 +96,28 @@ test('base swipe content', async () => {
     container.querySelector('.nut-swipe .nut-swipe-right .nut-button-wrap')
   ).toHaveTextContent('购物车')
 })
+
+describe('swipe.taro document guard logic', () => {
+  test('skips addEventListener when document.addEventListener is not a function', () => {
+    const addSpy = vi.spyOn(document, 'addEventListener')
+    const original = document.addEventListener
+
+    // @ts-expect-error simulate non-H5 Taro env
+    document.addEventListener = undefined
+
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    expect(shouldSkip).toBe(true)
+
+    document.addEventListener = original
+    addSpy.mockRestore()
+  })
+
+  test('does not skip addEventListener in normal H5 env', () => {
+    const shouldSkip =
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    expect(shouldSkip).toBe(false)
+  })
+})
diff --git a/src/packages/swipe/swipe.taro.tsx b/src/packages/swipe/swipe.taro.tsx
@@ -231,6 +231,11 @@ export const Swipe = forwardRef<
   }))
 
   useEffect(() => {
+    if (
+      typeof document === 'undefined' ||
+      typeof document.addEventListener !== 'function'
+    )
+      return
     // 并没有生效
     const handler: any = (event: { target: Node | null }) => {
       const targets = [root]

diff --git a/src/packages/timeselect/__test__/__snapshots__/timeselect.spec.tsx.snap b/src/packages/timeselect/__test__/__snapshots__/timeselect.spec.tsx.snap
@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`timeselect props test 1`] = `"<div><div class="nut-overlay" style="z-index: 1000;"></div><div style="z-index: 1000;" class="nut-popup nut-popup-round nut-popup-bottom"><div class="nut-popup-title"><div class="nut-popup-title-wrapper"><div class="nut-popup-title-title">取件时间</div></div><div class="nut-popup-title-right nut-popup-title-right-top-right"><svg class="nut-icon nut-icon-Close " xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" aria-labelledby="Close" role="presentation"><path d="M512 557.23 783.57 828.8c8.32 8.32 21.76 8.32 30.3 0l14.93-14.93c8.32-8.32 8.32-21.76 0-30.3L557.23 512 828.8 240.43c8.32-8.32 8.32-21.76 0-30.3l-14.93-14.93c-8.32-8.32-21.76-8.32-30.3 0L512 466.77 240.43 195.2c-8.32-8.32-21.76-8.32-30.3 0l-14.93 14.93c-8.32 8.32-8.32 21.76 0 30.3L466.77 512 195.2 783.57c-8.32 8.32-8.32 21.76 0 30.3l14.93 14.93c8.32 8.32 21.76 8.32 30.3 0z" fill="currentColor"></path></svg></div></div><div class="nut-timeselect"><div class="nut-timeselect-content"><div class="nut-timeselect-content-left"><div class="nut-timepannel active">520</div><div class="nut-timepannel">521</div></div><div class="nut-timedetail"><span class="nut-timedetail-item">09:00-10:00</span><span class="nut-timedetail-item">10:00-11:00</span><span class="nut-timedetail-item">11:00-12:00</span></div></div></div></div></div>"`;
+exports[`timeselect props test 1`] = `"<div><div class="nut-overlay" style="z-index: 1000;" arialabel="蒙层"></div><div style="z-index: 1000;" class="nut-popup nut-popup-round nut-popup-bottom" role="dialog"><div class="nut-popup-title"><div class="nut-popup-title-wrapper"><div class="nut-popup-title-title">取件时间</div></div><div class="nut-popup-title-right nut-popup-title-right-top-right" role="button" aria-label="关闭" tabindex="0"><svg class="nut-icon nut-icon-Close " xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" aria-labelledby="Close" role="presentation"><path d="M512 557.23 783.57 828.8c8.32 8.32 21.76 8.32 30.3 0l14.93-14.93c8.32-8.32 8.32-21.76 0-30.3L557.23 512 828.8 240.43c8.32-8.32 8.32-21.76 0-30.3l-14.93-14.93c-8.32-8.32-21.76-8.32-30.3 0L512 466.77 240.43 195.2c-8.32-8.32-21.76-8.32-30.3 0l-14.93 14.93c-8.32 8.32-8.32 21.76 0 30.3L466.77 512 195.2 783.57c-8.32 8.32-8.32 21.76 0 30.3l14.93 14.93c8.32 8.32 21.76 8.32 30.3 0z" fill="currentColor"></path></svg></div></div><div class="nut-timeselect"><div class="nut-timeselect-content"><div class="nut-timeselect-content-left"><div class="nut-timepannel active">520</div><div class="nut-timepannel">521</div></div><div class="nut-timedetail"><span class="nut-timedetail-item">09:00-10:00</span><span class="nut-timedetail-item">10:00-11:00</span><span class="nut-timedetail-item">11:00-12:00</span></div></div></div></div></div>"`;
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,7 @@ exports[`should render description correctly 1`] = ` @@
         class="nut-resultpage"
       >
         <div
+          aria-hidden="true"
           class="nut-resultpage-icon"
         >
           <svg
@@ Expand Down @@