Merge pull request #1631 from sheinsight/feat/modal-mask-blur

saint3347 · web-flow · commit 2327089409f1 · 2026-02-27T19:49:41.000+08:00
feat(modal): add mask prop with blur support
diff --git a/docs/api/shineout/modal.ts b/docs/api/shineout/modal.ts
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "sheinx",
   "private": true,
-  "version": "3.9.9",
+  "version": "3.9.10-beta.1",
   "description": "A react library developed with sheinx",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
diff --git a/packages/base/src/config/index.ts b/packages/base/src/config/index.ts
@@ -17,6 +17,19 @@ type TooltipConfig = {
   persistent?: boolean;
 }
 
+/**
+ * @en Global configuration for Modal component
+ * @cn Modal组件的全局配置
+ * @version 3.9.10
+ */
+export type ModalConfig = {
+  /**
+   * @en Global default mask setting for Modal component. false to hide mask, { blur: true } to show blurred mask
+   * @cn Modal组件的全局默认遮罩设置。false 隐藏遮罩，{ blur: true } 显示模糊遮罩
+   */
+  mask?: boolean | { blur?: boolean };
+}
+
 /**
  * @en Global configuration for Popover component
  * @cn Popover组件的全局配置
@@ -56,6 +69,12 @@ export interface ConfigOption {
   spin?: SpinConfig;
   tooltip?: TooltipConfig;
   popover?: PopoverConfig;
+  /**
+   * @en Global configuration for Modal component
+   * @cn Modal组件的全局配置
+   * @version 3.9.10
+   */
+  modal?: ModalConfig;
   /**
    * @en Global configuration for Empty component
    * @cn Empty组件的全局配置
@@ -76,6 +95,7 @@ export const defaultConfig: ConfigOption = {
   spin: 'ring',
   tooltip: undefined,
   popover: {},
+  modal: {},
   empty: {},
   direction: 'ltr',
   popupContainer: null,
diff --git a/packages/base/src/modal/modal-content.tsx b/packages/base/src/modal/modal-content.tsx
@@ -271,8 +271,12 @@ const Modal = (props: ModalContentProps) => {
     }
   })
 
+  const maskProp = props.mask ?? globalConfig.modal?.mask;
+  const hideMask = props.hideMask || maskProp === false;
+  const maskBlur = typeof maskProp === 'object' && maskProp?.blur;
+
   useEffect(() => {
-    if (!props.hideMask) {
+    if (!hideMask) {
       if (visible) {
         setDocumentOverflow();
       } else {
@@ -308,6 +312,7 @@ const Modal = (props: ModalContentProps) => {
     if (props.setInnerClose) {
       props.setInnerClose(() => {
         setVisible(false);
+        setAnimation(true);
       });
     }
   }, [props.setInnerClose]);
@@ -500,7 +505,8 @@ const Modal = (props: ModalContentProps) => {
           showMask && modalClasses?.wrapperIsMask,
           props.fullScreen && modalClasses?.wrapperFullScreen,
           props.moveable && modalClasses?.wrapperMoveable,
-          props.hideMask && modalClasses?.wrapperHideMask,
+          hideMask && modalClasses?.wrapperHideMask,
+          maskBlur && modalClasses?.wrapperMaskBlur,
           props.zoom && !props.moveable && modalClasses?.wrapperZoom,
           (isPositionX || isPositionY) && modalClasses?.wrapperDrawer,
           props.position === 'left' && modalClasses?.wrapperDrawerLeft,
diff --git a/packages/base/src/modal/modal-func.tsx b/packages/base/src/modal/modal-func.tsx
@@ -91,13 +91,17 @@ const method =
   (type: MethodType, jssStyle: ModalJssStyle) => (options: Omit<ModalOptions, 'jssStyle'>) => {
     const id = util.getUidStr();
     let innerClose: () => void;
+    let destroyed = false;
     const root = getRoot({ container: options.container });
     if (!root) return;
+    const doDestroy = () => {
+      if (destroyed) return;
+      destroyed = true;
+      destroy(root);
+    };
     const destroyModal = () => {
       if (innerClose) innerClose();
-      setTimeout(() => {
-        destroy(root);
-      }, 300);
+      setTimeout(doDestroy, 300);
     };
     modals.add(root);
     const btnOptions = {
@@ -130,7 +134,7 @@ const method =
         type={type as any}
         footer={footer}
         shouldDestroy={(can) => {
-          if (can) destroyModal();
+          if (can) doDestroy();
         }}
         setInnerClose={(close) => {
           innerClose = close;
diff --git a/packages/base/src/modal/modal.type.ts b/packages/base/src/modal/modal.type.ts
@@ -17,6 +17,7 @@ export interface ModalClasses {
   wrapperZoom: string;
   wrapperIsMask: string;
   wrapperHideMask: string;
+  wrapperMaskBlur: string;
   wrapperDrawer: string;
   wrapperDrawerLeft: string;
   wrapperDrawerRight: string;
@@ -51,8 +52,16 @@ export interface ModalProps extends Pick<CommonType, 'className' | 'style'> {
    * @en Whether to hide mask
    * @cn 是否隐藏遮罩
    * @default false
+   * @deprecated 推荐使用 mask={false} 来隐藏遮罩
    */
   hideMask?: boolean;
+
+  /**
+   * @en Control mask display. false to hide mask, { blur: true } to show blurred mask
+   * @cn 控制遮罩显示。false 隐藏遮罩，{ blur: true } 显示模糊遮罩
+   * @version 3.9.10
+   */
+  mask?: boolean | { blur?: boolean };
   /**
    * @en Whether to force the mask transparency (in multi-layer Modal, the transparency of other Modal masks except the first layer will be adjusted to 0.01)
    * @cn 是否强制设置遮罩透明度（多层Modal中，除第一层外的其他弹出层遮罩透明度会被调整为0.01）
diff --git a/packages/shineout-style/src/modal/modal.ts b/packages/shineout-style/src/modal/modal.ts
@@ -183,6 +183,10 @@ const modalStyle: JsStyles<ModalClassType> = {
       pointerEvents: 'none',
     },
   },
+  wrapperMaskBlur: {
+    backdropFilter: 'blur(4px)',
+    WebkitBackdropFilter: 'blur(4px)',
+  },
   wrapperMoveable: {
     '& $header': {
       cursor: 'move',
diff --git a/packages/shineout/src/modal/__doc__/changelog.cn.md b/packages/shineout/src/modal/__doc__/changelog.cn.md
@@ -1,3 +1,8 @@
+## 3.9.10-beta.1
+2026-02-25
+### 🆕 Feature
+- `Modal` 新增 `mask` 属性支持设置为 `{ blur: true }` 来启用模糊遮罩效果 ([#1631](https://github.com/sheinsight/shineout-next/pull/1631))
+
 ## 3.9.8-beta.11
 2026-01-21
 ### 🐞 BugFix
diff --git a/packages/shineout/src/modal/__example__/15-mask.tsx b/packages/shineout/src/modal/__example__/15-mask.tsx
@@ -0,0 +1,67 @@
+/**
+ * cn - 遮罩
+ *    -- 通过 `mask` 属性控制遮罩的显示。设置 `mask={false}` 隐藏遮罩，设置 `mask={{ blur: true }}` 显示模糊遮罩
+ * en - Mask
+ *    -- Use the `mask` prop to control the mask display. Set `mask={false}` to hide the mask, set `mask={{ blur: true }}` to show a blurred mask
+ */
+import React, { useState } from 'react';
+import { Modal, Button } from 'shineout';
+
+const App: React.FC = () => {
+  const [visible1, setVisible1] = useState(false);
+  const [visible2, setVisible2] = useState(false);
+
+  const info1 = () => {
+    Modal.info({
+      title: 'This is a info message',
+      content: 'this is some information that user must know',
+      mask: { blur: true },
+    });
+  };
+
+  const info2 = () => {
+    Modal.info({
+      title: 'This is a success message',
+      content: 'this is some information that user successful operation',
+      mask: false,
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', gap: '16px' }}>
+      <Button mode='outline' onClick={() => setVisible1(true)}>
+        mask blur
+      </Button>
+      <Button mode='outline' onClick={() => setVisible2(true)}>
+        mask=false
+      </Button>
+      <Modal
+        title='Modal with blur mask'
+        visible={visible1}
+        onClose={() => setVisible1(false)}
+        mask={{ blur: true }}
+        footer={<Button type="primary" onClick={() => setVisible1(false)}>Close</Button>}
+      >
+        This modal has a blurred mask
+      </Modal>
+      <Modal
+        title='Modal without mask'
+        visible={visible2}
+        onClose={() => setVisible2(false)}
+        mask={false}
+        footer={<Button type="primary" onClick={() => setVisible2(false)}>Close</Button>}
+      >
+        This modal has no mask
+      </Modal>
+
+      <Button type='primary' onClick={info1}>
+        info (blur)
+      </Button>
+      <Button type='primary' onClick={info2}>
+        info (no mask)
+      </Button>
+    </div>
+  );
+};
+
+export default App;

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "sheinx",`
`3`	`3`	`"private": true,`
`4`		`- "version": "3.9.9",`
	`4`	`+ "version": "3.9.10-beta.1",`
`5`	`5`	`"description": "A react library developed with sheinx",`
`6`	`6`	`"module": "dist/index.js",`
`7`	`7`	`"types": "dist/index.d.ts",`