@mijadesign/nut-mcp 1.0.0-alpha.0

package/docs/docs/components/feedback/popup/index.md

@@ -0,0 +1,563 @@
+---
+order: 11
+demoUrl: 'https://frontend.mishudata.com/mobile/demo/#/feedback/pages/popup/index'
+group:
+    title: 操作反馈
+    order: 6
+---
+
+# Popup 弹出层 <Badge>2.0.0</Badge>
+
+弹出层容器，用于展示弹窗、信息提示等内容
+
+## 引入
+
+```tsx
+import { Popup } from '@mijadesign/mjui-react-taro'
+```
+
+## 示例代码
+
+### 基础用法
+
+`visible` 控制显示/隐藏
+
+
+```tsx
+import { Button, Cell, Popup } from '@mijadesign/mjui-react-taro'
+import { View } from '@tarojs/components'
+import React, { useState } from 'react'
+
+const Demo1 = () => {
+  const [showBasic, setShowBasic] = useState(false)
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowBasic(true)
+        }}
+        fill="outline"
+        block
+      >
+        展示弹出层
+      </Button>
+      <Popup
+        visible={showBasic}
+        style={{ padding: '30px 50px' }}
+        onClose={() => {
+          setShowBasic(false)
+        }}
+      >
+        <View style={{ height: '200px', overflowY: 'scroll' }}>
+          {Array.from({ length: 20 })
+            .fill('')
+            .map((_, i) => (
+              <Cell key={i}>
+                <View>正文</View>
+              </Cell>
+            ))}
+        </View>
+      </Popup>
+    </>
+  )
+}
+export default Demo1
+
+```
+    
+### 弹出位置
+
+
+```tsx
+import { Button, Popup } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo2 = () => {
+  const [showCenter, setShowCenter] = useState(false)
+  const [showTop, setShowTop] = useState(false)
+  const [showBottom, setShowBottom] = useState(false)
+  const [showLeft, setShowLeft] = useState(false)
+  const [showRight, setShowRight] = useState(false)
+
+  const marginStyle = {
+    marginBottom: '12px',
+  }
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowCenter(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        中间弹出
+      </Button>
+      <Button
+        onClick={() => {
+          setShowTop(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        顶部弹出
+      </Button>
+      <Button
+        onClick={() => {
+          setShowBottom(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        底部弹出
+      </Button>
+      <Button
+        onClick={() => {
+          setShowLeft(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        左侧弹出
+      </Button>
+      <Button
+        onClick={() => {
+          setShowRight(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+      >
+        右侧弹出
+      </Button>
+      <Popup
+        visible={showCenter}
+        style={{ height: '260px', width: '260px' }}
+        onClose={() => {
+          setShowCenter(false)
+        }}
+      />
+      <Popup
+        visible={showTop}
+        destroyOnClose
+        position="top"
+        style={{ height: '36%' }}
+        onClose={() => {
+          setShowTop(false)
+        }}
+      />
+      <Popup
+        visible={showBottom}
+        position="bottom"
+        onClose={() => {
+          setShowBottom(false)
+        }}
+        lockScroll
+        style={{ height: '80%' }}
+      />
+      <Popup
+        visible={showLeft}
+        style={{ width: '20%', height: '100%' }}
+        position="left"
+        onClose={() => {
+          setShowLeft(false)
+        }}
+      />
+      <Popup
+        visible={showRight}
+        style={{ width: '20%', height: '100%' }}
+        position="right"
+        onClose={() => {
+          setShowRight(false)
+        }}
+      />
+    </>
+  )
+}
+export default Demo2
+
+```
+    
+### 关闭图标
+
+
+```tsx
+import { Button, Popup } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo3 = () => {
+  const [showIcon, setShowIcon] = useState(false)
+  const [showIconPosition, setShowIconPosition] = useState(false)
+  const [showIconDefine, setShowIconDefine] = useState(false)
+
+  const marginStyle = {
+    marginBottom: '12px',
+  }
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowIcon(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        底部弹出-仅标题
+      </Button>
+
+      <Button
+        onClick={() => {
+          setShowIconPosition(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+        style={marginStyle}
+      >
+        底部弹出-带标题及图标
+      </Button>
+
+      <Button
+        onClick={() => {
+          setShowIconDefine(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+      >
+        底部弹出-带标题及操作（最大高度）
+      </Button>
+      <Popup
+        closeable={false}
+        visible={showIcon}
+        title="我是标题"
+        position="bottom"
+        onClose={() => {
+          setShowIcon(false)
+        }}
+      />
+      <Popup
+        closeable
+        title="我是标题"
+        visible={showIconPosition}
+        position="bottom"
+        onClose={() => {
+          setShowIconPosition(false)
+        }}
+      />
+      <Popup
+        closeable
+        title="我是标题"
+        left={
+          <div
+            onClick={() => {
+              setShowIconDefine(false)
+            }}
+          >
+            取消
+          </div>
+        }
+        closeIcon={<div style={{ color: '#006DFC' }}>确认</div>}
+        visible={showIconDefine}
+        style={{ height: '100%' }}
+        position="bottom"
+        onClose={() => {
+          setShowIconDefine(false)
+        }}
+      />
+    </>
+  )
+}
+export default Demo3
+
+```
+    
+### 阻塞关闭
+
+
+```tsx
+import { Button, Popup } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo4 = () => {
+  const [showOverlayStop, setShowOverlayStop] = useState(false)
+  const [showCloseIconStop, setShowCloseIconStop] = useState(false)
+
+  const marginStyle = {
+    marginBottom: '12px',
+  }
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowOverlayStop(true)
+        }}
+        fill="outline"
+        type="primary"
+        block
+        style={marginStyle}
+      >
+        阻塞点击 Overlay 关闭
+      </Button>
+
+      <Popup
+        visible={showOverlayStop}
+        style={{ padding: '30px 50px' }}
+        onClose={() => {
+          setShowOverlayStop(false)
+        }}
+        onOverlayClick={() => {
+          console.log('onOverlayClick')
+          return false
+        }}
+      >
+        正文
+      </Popup>
+      <Button
+        onClick={() => {
+          setShowCloseIconStop(true)
+        }}
+        type="primary"
+        fill="outline"
+        block
+      >
+        阻塞点击 close icon 关闭
+      </Button>
+      <Popup
+        closeable
+        title=" "
+        position="bottom"
+        visible={showCloseIconStop}
+        closeOnOverlayClick={false}
+        style={{ height: '40%' }}
+        onCloseIconClick={() => {
+          console.log('onCloseIconClick')
+          setShowCloseIconStop(false)
+        }}
+      />
+    </>
+  )
+}
+export default Demo4
+
+```
+    
+### 圆角弹框
+
+
+```tsx
+import { Button, Popup } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo4 = () => {
+  const [showBottomRound, setShowBottomRound] = useState(false)
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowBottomRound(true)
+        }}
+        fill="outline"
+        block
+        type="primary"
+      >
+        直角弹框
+      </Button>
+      <Popup
+        visible={showBottomRound}
+        style={{ height: '20%' }}
+        position="top"
+        round={false}
+        onClose={() => {
+          setShowBottomRound(false)
+        }}
+      />
+    </>
+  )
+}
+export default Demo4
+
+```
+    
+### 多层堆叠
+
+
+```tsx
+import { Button, Popup } from '@mijadesign/mjui-react-taro'
+import React, { useState } from 'react'
+
+const Demo6 = () => {
+  const [showMutiple, setShowMutiple] = useState(false)
+  const [showMutipleInner, setShowMutipleInner] = useState(false)
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setShowMutiple(true)
+        }}
+        fill="outline"
+        block
+        type="primary"
+      >
+        多层堆叠
+      </Button>
+      <Popup
+        visible={showMutiple}
+        position="bottom"
+        style={{ padding: '30px 50px', height: 500, boxSizing: 'border-box' }}
+        onClose={() => {
+          setShowMutiple(false)
+        }}
+      >
+        <span
+          onClick={() => {
+            setShowMutipleInner(true)
+          }}
+        >
+          Click It
+        </span>
+      </Popup>
+      <Popup
+        visible={showMutipleInner}
+        position="bottom"
+        style={{ padding: '40px 50px', height: 200, boxSizing: 'border-box' }}
+        onClose={() => {
+          setShowMutipleInner(false)
+        }}
+      >
+        <span
+          onClick={() => {
+            setShowMutipleInner(false)
+          }}
+        >
+          close
+        </span>
+      </Popup>
+    </>
+  )
+}
+export default Demo6
+
+```
+    
+### 禁止滚动穿透
+
+> 2.3.0 版本更新，仅适用于 H5 与微信小程序
+
+使用这类全局遮罩类型的组件时，滑动组件可能会出现底层页面一起滑动的问题。
+
+开启 lockScroll 可以阻止 Popup 的背景遮罩层的滚动穿透问题，已默认开启。
+
+使用 Taro 提供的 catchMove 可以阻止 Popup 的内容区域的滚动穿透问题，但会导致其本身无法滑动。
+
+如果需要内容支持溢出滚动，则需要包裹一层 ScrollView 组件。
+
+
+```tsx
+import { Button, Cell, Popup } from '@mijadesign/mjui-react-taro'
+import { ScrollView } from '@tarojs/components'
+import React, { useState } from 'react'
+
+const Demo6 = () => {
+  const [scrollPenetration, setScrollPenetration] = useState(false)
+
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setScrollPenetration(true)
+        }}
+        fill="outline"
+        block
+        type="primary"
+      >
+        禁止滚动穿透
+      </Button>
+      <Popup title="我是标题" visible={scrollPenetration} position="bottom" lockScroll>
+        <ScrollView scrollY style={{ height: '300px' }}>
+          {Array.from({ length: 200 })
+            .fill('')
+            .map((_, i) => (
+              <Cell key={i}>禁止滚动穿透-{i}</Cell>
+            ))}
+        </ScrollView>
+      </Popup>
+    </>
+  )
+}
+export default Demo6
+
+```
+    
+## Popup
+
+### Props
+
+| 属性                | 说明                                           | 类型                                                         | 默认值      |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------------ | ----------- |
+| visible             | 当前组件是否显示                               | `boolean`                                                    | `false`     |
+| zIndex              | 遮罩层级                                       | `string` \| `number`                                         | `2000`      |
+| duration            | 遮罩动画时长，单位毫秒                         | `number`                                                     | `300`       |
+| overlayClassName    | 自定义遮罩类名                                 | `string`                                                     | `-`         |
+| overlayStyle        | 自定义遮罩样式                                 | `CSSProperties`                                              | `-`         |
+| lockScroll          | 背景是否锁定                                   | `boolean`                                                    | `true`      |
+| overlay             | 是否显示遮罩                                   | `boolean`                                                    | `true`      |
+| closeOnOverlayClick | 是否点击遮罩关闭                               | `boolean`                                                    | `true`      |
+| position            | 弹出位置                                       | `top` \| `bottom` \| `left` \| `right` \| `center`           | `center`    |
+| transition          | 动画名                                         | `string`                                                     | `-`         |
+| closeable           | 是否显示关闭按钮                               | `boolean`                                                    | `false`     |
+| closeIconPosition   | 关闭按钮位置                                   | `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` | `top-right` |
+| closeIcon           | 自定义 Icon                                    | `ReactNode`                                                  | `<Close />` |
+| left                | 标题左侧部分                                   | `ReactNode`                                                  | `-`         |
+| title               | 标题中间部分                                   | `ReactNode`                                                  | `-`         |
+| description         | 子标题/描述部分                                | `ReactNode`                                                  | `-`         |
+| destroyOnClose      | 组件不可见时，卸载内容                         | `boolean`                                                    | `false`     |
+| round               | 是否显示圆角                                   | `boolean`                                                    | `true`      |
+| portal              | 指定节点挂载                                   | `HTMLElement` \| `(() => HTMLElement)`                       | `null`      |
+| customHeader        | 页面是否自定义导航栏，如果自定义，则需要传true | `boolean`                                                    | `false`     |
+| portal              | 指定节点挂载                                   | `HTMLElement` \| `(() => HTMLElement)`                       |
+| onClick             | 点击弹框时触发                                 | `event: MouseEvent`                                          | `-`         |
+| onCloseIconClick    | 点击关闭图标时触发                             | `event: MouseEvent`                                          | `-`         |
+| onOpen              | 打开弹框时触发                                 | `-`                                                          | `-`         |
+| onClose             | 关闭弹框时触发                                 | `-`                                                          | `-`         |
+| afterShow           | 继承于`Overlay`, 遮罩打开动画结束时触发        | `event: HTMLElement`                                         | `-`         |
+| afterClose          | 继承于`Overlay`, 遮罩关闭动画结束时触发        | `event: HTMLElement`                                         | `-`         |
+| onOverlayClick      | 点击遮罩触发                                   | `event: MouseEvent`                                          | `-`         |
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](#/zh-CN/component/configprovider)。
+
+| 名称                                    | 说明                  | 默认值              |
+| --------------------------------------- | --------------------- | ------------------- |
+| \--nutui-popup-animation-duration       | 弹框最大高度          | `0.3s`              |
+| \--nutui-popup-border-radius            | 弹框的圆角值          | `$radius-3`         |
+| \--nutui-popup-description-font-size    | 子标题/描述栏的字号   | `$font-size-2`      |
+| \--nutui-popup-description-spacing      | 子标题/描述栏的间距   | `$spacing-base`     |
+| \--nutui-popup-icon-size                | 弹框关闭按钮的大小    | `$icon-font-size`   |
+| \--nutui-popup-max-height               | 弹框最大高度          | `80%`               |
+| \--nutui-popup-min-height               | 弹框最小高度          | `36%`               |
+| \--nutui-popup-title-border-bottom      | 标题栏底部边框        | `0`                 |
+| \--nutui-popup-title-font-size          | 标题栏的字号          | `$font-size-3`      |
+| \--nutui-popup-title-font-weight        | 标题栏的字体权重      | `$font-weight-bold` |
+| \--nutui-popup-title-height             | 标题栏的高度          | `inherit`           |
+| \--nutui-popup-title-horizontal-padding | 标题栏的水平padding值 | `$spacing-3`        |
+| \--nutui-popup-title-padding            | 标题栏的padding值     | `20px 16px`         |
+| \--nutui-popup-title-vertical-padding   | 标题栏的垂直padding值 | `$spacing-4`        |