@ray-js/smart-ui 2.13.2-beta-0 → 2.13.2-beta-1

package/es/popover/README.md

@@ -0,0 +1,338 @@
+---
+category: 反馈
+new: true
+version: v2.3.0
+---
+
+# Popover 弹出提示
+
+### 介绍
+
+v2.3.0开始加入，弹出层容器，用于展示弹窗、信息提示等轻量内容。
+
+### 引入
+
+```jsx
+import { Popover } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popover, Icon, Button } from '@ray-js/smart-ui';
+import React from 'react';
+import Sun from '@tuya-miniapp/icons/dist/svg/Sun';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const showPopup = () => setShow(true);
+  const onClose = () => setShow(false);
+
+  return (
+    <View style={{paddingBottom: '64px'}}>
+      <View
+        style={{
+          padding: '10vh',
+          paddingTop: 0,
+          paddingLeft: 8,
+        }}
+      >
+        <Popover
+          show={show}
+          onClose={() => setShow(false)}
+          placement="bottomLeft"
+          customStyle={{
+            padding: '0px',
+            width: '200px',
+          }}
+          slot={{
+            overlay: (
+              <View>
+                {[1, 2, 3].map(n => (
+                  <View className={styles.listItem} key={n}>
+                    <Icon name={Sun} size="24px" color="#3678E3" />
+                    <Text className={styles.listText}>Title</Text>
+                  </View>
+                ))}
+              </View>
+            ),
+          }}
+        >
+          <Button>下左弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          padding: '10vh',
+          paddingTop: 0,
+          paddingLeft: '20vw',
+        }}
+      >
+        <Popover
+          placement="bottom"
+          customStyle={{
+            padding: '0px',
+            width: '200px',
+          }}
+          slot={{
+            overlay: (
+              <View>
+                {[1, 2, 3].map(n => (
+                  <View className={styles.listItem} key={n}>
+                    <Icon name={Sun} size="24px" color="#3678E3" />
+                    <Text className={styles.listText}>Title</Text>
+                  </View>
+                ))}
+              </View>
+            ),
+          }}
+        >
+          <Button>下中弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          padding: '10vh',
+          paddingTop: 0,
+          paddingLeft: '40vw',
+        }}
+      >
+        <Popover
+          placement="bottomRight"
+          customStyle={{
+            padding: '0px',
+            width: '200px',
+          }}
+          slot={{
+            overlay: (
+              <View>
+                {[1, 2, 3].map(n => (
+                  <View className={styles.listItem} key={n}>
+                    <Icon name={Sun} size="24px" color="#3678E3" />
+                    <Text className={styles.listText}>Title</Text>
+                  </View>
+                ))}
+              </View>
+            ),
+          }}
+        >
+          <Button>下右弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          paddingLeft: 8,
+          paddingTop: '10vh',
+        }}
+      >
+        <Popover
+          placement="top"
+          slot={{
+            overlay: <View>tip</View>,
+          }}
+        >
+          <Button>上侧弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          paddingLeft: '20vw',
+          paddingTop: '10vh',
+        }}
+      >
+        <Popover
+          placement="left"
+          slot={{
+            overlay: <View>tip</View>,
+          }}
+        >
+          <Button>左侧弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          paddingLeft: '8px',
+          paddingTop: '10vh',
+        }}
+      >
+        <Popover
+          placement="right"
+          slot={{
+            overlay: <View>tip</View>,
+          }}
+        >
+          <Button>右侧弹出</Button>
+        </Popover>
+      </View>
+      <View
+        style={{
+          paddingLeft: '8px',
+          paddingTop: '10vh',
+        }}
+      >
+        <Popover
+          placement="bottom"
+          slot={{
+            overlay: <View>tip</View>,
+          }}
+        >
+          <Button>下中弹出</Button>
+        </Popover>
+      </View>
+    </View>
+  );
+}
+```
+
+less 样式如下
+
+```less
+.listItem {
+  height: 96rpx;
+  padding: 0 32rpx;
+  line-height: 96rpx;
+  display: flex;
+  align-items: center;
+  position: relative;
+  &:nth-child(n + 2)::after {
+    display: block;
+    content: '';
+    height: 1px;
+    background-color: #ebebeb;
+    width: 90%;
+    position: absolute;
+    right: 0;
+    top: 0;
+  }
+}
+
+.listText {
+  margin-left: 20rpx;
+  font-size: 16px;
+  color: rgba(0, 0, 0, 0.9);
+}
+```
+
+### 受控用法
+
+通过`show`属性控制弹出层是否展示。
+
+```tsx
+import { View } from '@ray-js/ray';
+import { Popover, Button } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+
+  return (
+    <Popover placement="bottom" show={show} onClose={() => setShow(false)} onShowChange={e => setShow(e.detail)} slot={{
+      overlay: <View>tip</View>
+    }}>
+      <Button>下方弹出</Button>
+    </Popover>
+  )
+}
+```
+
+### 弹出位置
+
+通过`position`属性设置弹出位置，默认居右弹出，可以设置为`top`、`topLeft`、`topRight`、`bottom`、`bottomLeft`、`bottomRight`、`left`、`leftTop`、`leftBottom`、`right`、`rightTop`、`rightBottom`。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popover, Button } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Popover placement="right" slot={{
+      overlay: <View>弹框内容</View>
+    }}>
+      <Button>右侧弹出</Button>
+    </Popover>
+  );
+}
+```
+
+### 自定义遮罩样式 `v2.13.1`
+
+通过 `overlayStyle` 可自定义遮罩层样式，透传至内部 `smart-overlay` 的 `custom-style`。
+
+```jsx
+import { View, Text } from '@ray-js/ray';
+import { Popover, Button } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <View style={{ paddingLeft: 8, paddingTop: '10vh' }}>
+      <Popover
+        placement="bottom"
+        overlayStyle={{
+          backgroundColor: 'rgba(64, 128, 255, 0.25)',
+        }}
+        customStyle={{
+          padding: '0px',
+          width: '200px',
+        }}
+        slot={{
+          overlay: (
+            <View>
+              <Text>tip</Text>
+            </View>
+          ),
+        }}
+      >
+        <Button>自定义遮罩样式</Button>
+      </Popover>
+    </View>
+  );
+}
+```
+
+## API
+
+### Props
+| 参数             | 说明                                                                                                                                                           | 类型      | 默认值  |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
+| customStyle | 自定义弹出层样式 | _React.CSSProperties_ | - |
+| overlayStyle `v2.13.1` | 自定义遮罩层样式，透传至内部 `smart-overlay` 的 `custom-style` | _React.CSSProperties_ | - |
+| duration | 延迟关闭的时间(ms) | number | `3000` |
+| placement | 弹出层的位置，支持值：`top`、`topLeft`、`topRight`、`bottom`、`bottomLeft`、`bottomRight`、`left`、`leftTop`、`leftBottom`、`right`、`rightTop`、`rightBottom` | _string_ | `right` |
+| show | 控制弹出层是否显示，并监听状态变化，值变更时更新 `currentShow` | _boolean_ | `false` |
+| trigger `v2.5.0` | 控制弹出层触发方式，支持 `tap`、`longpress` | _string_ | `tap` |
+
+### Events
+
+| 事件名           | 说明            | 参数 |
+| ---------------- | --------------- | ---- |
+| onClose | 关闭时触发 | - |
+| onShowChange | 显示/隐藏时触发 | - |
+
+### Popover Slot
+
+| 名称    | 说明     |
+| ------- | -------- |
+| overlay | 弹窗内容 |
+
+### 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| customClass | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                             | 默认值                              | 描述             |
+| -------------------------------- | ----------------------------------- | ---------------- |
+| --popover-background-color       | #fff                                | 弹出层背景色     |
+| --popover-border-radius          | 12px                                | 弹出层圆角       |
+| --popover-box-shadow             | 0px 6px 12px 0px rgba(0, 0, 0, 0.1) | 弹出层阴影       |
+| --popover-overlay-color `v2.8.0` | var(--app-B1-N1, rgba(0, 0, 0, 1))  | 遮照插槽文字颜色 |
+| --popover-padding                | 12px                                | 弹出层内边距     |

package/es/popup/README.md

@@ -0,0 +1,272 @@
+---
+category: 反馈
+---
+
+# Popup 弹出层
+
+### 介绍
+
+弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。
+
+### 引入
+
+```jsx
+import { Popup } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`show`属性控制弹出层是否展示。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popup, Cell } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const showPopup = () => setShow(true);
+  const onClose = () => setShow(false);
+
+  return (
+    <View>
+      <Cell title="展示弹出层" isLink onClick={showPopup} />
+      <Popup show={show} onClose={onClose}>
+        内容
+      </Popup>
+    </View>
+  );
+}
+```
+
+### 弹出位置
+
+通过`position`属性设置弹出位置，默认居中弹出，可以设置为`top`、`bottom`、`left`、`right`。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popup, Cell } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const showPopup = () => setShow(true);
+  const onClose = () => setShow(false);
+
+  return (
+    <View>
+      <Cell title="展示弹出层" isLink onClick={showPopup} />
+      <Popup show={show} position="top" customStyle={{ height: '20%' }} onClose={onClose} />
+    </View>
+  );
+}
+```
+
+### 关闭图标
+
+设置`closeable`属性后，会在弹出层的右上角显示关闭图标，并且可以通过`closeIcon`属性自定义图标，使用`closeIconPosition`属性可以自定义图标位置。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popup, Cell } from '@ray-js/smart-ui';
+import Close from '@tuya-miniapp/icons/dist/svg/Close';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const showPopup = () => setShow(true);
+  const onClose = () => setShow(false);
+
+    const [show1, setShow1] = React.useState(false);
+  const showPopup1 = () => setShow1(true);
+  const onClose1 = () => setShow1(false);
+
+    const [show2, setShow2] = React.useState(false);
+  const showPopup2 = () => setShow2(true);
+  const onClose2 = () => setShow2(false);
+  
+
+  return (
+    <View>
+      <Cell title="显示关闭图标" isLink onClick={showPopup} />
+      <Cell title="自定义图标" isLink onClick={showPopup1} />
+      <Cell title="图标位置" isLink onClick={showPopup2} />
+      <Popup
+        show={show}
+        closeable
+        position="bottom"
+        customStyle={{ height: '20%' }}
+        onClose={onClose}
+      />
+      <Popup
+        show={show1}
+        closeable
+        closeIcon={Close}
+        position="bottom"
+        customStyle={{ height: '20%' }}
+        onClose={onClose1}
+      />
+      <Popup
+        show={show2}
+        closeable
+        closeIconPosition="top-left"
+        position="bottom"
+        customStyle={{ height: '20%' }}
+        onClose={onClose2}
+      />
+    </View>
+  );
+}
+```
+
+### 圆角弹窗
+
+设置`round`属性后，弹窗会根据弹出位置添加不同的圆角样式。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Popup, Cell } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const showPopup = () => setShow(true);
+  const onClose = () => setShow(false);
+
+  return (
+    <View>
+      <Cell title="显示圆角弹窗" isLink onClick={showPopup} />
+      <Popup show={show} round position="bottom" customStyle={{ height: '20%' }} onClose={onClose} />
+    </View>
+  );
+}
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| closeIcon | 关闭图标名称或图片链接 | _string_ | `cross` |
+| closeIconAriaLabel `v2.13.0` | 关闭按钮的无障碍读屏文案，透传至内部 `smart-icon` 的 `aria-label` | _string_ | - |
+| closeIconPosition | 关闭图标位置，可选值为 `top-left`<br>`bottom-left` `bottom-right` | _string_ | `top-right` |
+| closeOnClickOverlay | 是否在点击遮罩层后关闭 | _boolean_ | `true` |
+| closeable | 是否显示关闭图标 | _boolean_ | `false` |
+| customStyle | 自定义弹出层样式 | _React.CSSProperties_ | - |
+| duration | 动画时长，单位为毫秒 | _number \| object_ | `300` |
+| lockScroll | 是否锁定背景滚动 | _boolean_ | `true` |
+| overlay | 是否显示遮罩层 | _boolean_ | `true` |
+| overlayStyle | 自定义遮罩层样式 | _React.CSSProperties_ | - |
+| position | 弹出位置，可选值为 `top` `bottom` `right` `left` | _string_ | `center` |
+| round | 是否显示圆角 | _boolean_ | `false` |
+| safeAreaInsetBottom | 是否留出底部安全距离，v2.7.1 开始默认关闭 | _boolean_ | `false` |
+| safeAreaInsetBottomMin `v1.1.0` | 是否需要预留出一个最小的底部安全距离，用于在 safeArea 底部为 0 时进行追加，需要在 safeAreaInsetBottom 为 true 时生效 | _number_ | `0` |
+| safeAreaInsetTop | 是否留出顶部安全距离（状态栏高度） | _boolean_ | `false` |
+| safeAreaTabBar | 是否留出底部 tabbar 安全距离（在使用 tabbar 组件 & 小程序自定义 tabbar 时，popup 组件层级无法盖住 tabbar） | _boolean_ | `false` |
+| show | 是否显示弹出层 | _boolean_ | `false` |
+| zIndex | z-index 层级 | _number_ | `100` |
+| nativeDisabled `v2.3.8` | 开启弹框期间是否禁用本地手势; 会在弹框开始进入动画时调用 `ty.nativeDisabled(true)`, 在弹框关闭动画结束时调用 `ty.nativeDisabled(false)` 恢复异层组件的点击能力；由于`ty.nativeDisabled` 是全局生效的，所以多个弹框组件同时打开时注意是否传 `native-disabled`属性和关闭的时机，防止 `native-disabled` 属性失效 | _boolean_ | `false` |
+| fullCoverView `v2.11.1` | 是否使用 cover-view 包裹弹层，用于覆盖原生组件（如 map、video）时使用 | _boolean_ | `false` |
+
+### Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| onAfterEnter | 进入后触发 | - |
+| onAfterLeave | 离开后触发 | - |
+| onBeforeEnter | 进入前触发 | - |
+| onBeforeLeave | 离开前触发 | - |
+| onClickOverlay | 点击遮罩层时触发 | - |
+| onClose | 关闭弹出层时触发 | - |
+| onEnter | 进入中触发 | - |
+| onLeave | 离开中触发 | - |
+
+### 外部样式类
+
+| 类名 | 说明 |
+| --- | --- |
+| customClass | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称 | 默认值 | 描述 |
+| --- | --- | --- |
+| --popup-background-color | _var(--app-B4, #ffffff)_ | 弹窗背景颜色 |
+| --popup-round-border-radius | _16px_ | 圆形边框半径 |
+| --popup-close-icon-size | _24px_ | 关闭图标大小 |
+| --popup-close-icon-color | _#969799_ | 关闭图标颜色 |
+| --popup-close-icon-margin | _12px_ | 关闭图标边距 |
+| --popup-close-icon-z-index | _1_ | 关闭图标层级 |
+
+## 常见问题
+
+### Popup 嵌套涉及布局定位的组件时渲染异常，该如何处理？
+
+由于一些组件，如 `Slider` 组件、`Textarea` 组件使用到 `auto-height` 属性时，在 `Popup` 打开时可能尚未完全渲染，因此我们无法获取其 DOM，从而导致定位出现问题。解决方案是在 `Popup` 的 `onAfterEnter` 事件回调之后再开始渲染此类组件。这样，我们可以确保此类组件能够在获取 DOM 时被正常渲染。请参考以下示例：
+
+```jsx
+import React from 'react';
+import { Cell, Popup } from '@ray-js/smart-ui';
+import { DemoBlock } from '@/components';
+import { View, Slider } from '@ray-js/ray';
+
+function Demo() {
+  const [show, setShow] = React.useState(false);
+  const [isReady, setIsReady] = React.useState(false);
+  const showBasic = () => setShow(true);
+  const handleChange = e => setValue(e.detail.value);
+
+  return (
+    <DemoBlock title="基础用法">
+      <Cell title="展示弹出层" isLink onClick={showBasic} />
+      <Popup
+        show={show}
+        position="bottom"
+        onClose={hideBasic}
+        onAfterEnter={() => setIsReady(true)}
+      >
+        <View style={{ padding: '32px', position: 'relative' }}>
+          {isReady && <Slider value={value} max={100} min={0} onChange={handleChange} />}
+        </View>
+      </Popup>
+    </DemoBlock>
+  );
+}
+```
+
+### Popup 在IDE上内部元素过高时可以滚动为什么到手机上就不行了？
+
+`Popup`内部本身没有`ScrollView`能力，所以本身不具备滚动的功能，可以滚动是因为IDE和真实手机的不一致性导致的，所以希望可以滚动需要使用`ScrollView` 包裹内部元素。
+
+```jsx
+import React from 'react';
+import { Popup } from '@ray-js/smart-ui';
+import { DemoBlock } from '@/components';
+import { View, ScrollView } from '@ray-js/ray';
+
+function Demo() {
+  return (
+    <DemoBlock title="基础用法">
+      <Popup
+        show
+        position="bottom"
+      >
+        <ScrollView scrollY style={{ height: '400px' }}>
+          <View style={{ height: '1000px' }}>
+            test
+          </View>
+        </ScrollView>
+      </Popup>
+    </DemoBlock>
+  );
+}
+```
+
+### Popup 弹出框在真机上底部有空隙怎么回事？
+
+`Popup`内置的底部安全距离是会距离底部有一个外边距，会有一种弹框不通底的效果，如果希望弹框和底部是链接在一起的，安全距离是通过内边距的形式请使用 `BottomSheet` 组件。

package/es/progress/README.md

@@ -0,0 +1,88 @@
+<!-- ---
+category: 展示
+--- -->
+
+# Progress 进度条
+
+### 介绍
+
+进度条
+
+### 引入
+
+```jsx
+import { Progress } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+```jsx
+import React from 'react';
+import { Progress } from '@ray-js/smart-ui';
+
+export default function Demo() {
+  return (
+    <Progress
+      percentage={70}
+      color="linear-gradient(to right, #FA709A 0%, #FEDD44 100%)"
+    />
+  );
+}
+```
+
+### 圆形进度条
+
+```jsx
+<Progress.Circle percent={20} />
+```
+
+## API
+
+### Progress
+
+<!-- prettier-ignore -->
+| 参数         | 说明                       | 类型               | 默认值           |
+| ------------ | -------------------------- | ------------------ | ---------------- |
+| color        | 进度条颜色                 | _string_           | `#1989fa`        |
+| inactive     | 是否置灰                   | _boolean_          | `false`          |
+| percentage   | 进度百分比                 | _number_           | `0`              |
+| pivotColor  | 文字背景色                 | _string_           | 与进度条颜色一致 |
+| pivotText   | 文字显示                   | _string_           | 百分比文字       |
+| showPivot   | 是否显示进度文字           | _boolean_          | `true`           |
+| strokeWidth | 进度条粗细，默认单位为`px` | _string \| number_ | `4px`            |
+| textColor   | 进度文字颜色               | _string_           | `#fff`           |
+| trackColor  | 轨道颜色                   | _string_           | `#e5e5e5`        |
+
+
+### Progress.Circle
+
+<!-- prettier-ignore -->
+| 属性名 | 描述 | 类型 | 默认值 |
+| ------ | ---- | ---- | ------ |
+className|类名|string|undefined|
+children|子元素|ReactNode|undefined|
+style|样式|CSSProperties|undefined|
+size|尺寸|string|'100px'|
+trackWidth|滑槽宽度|string|'10px'|
+trackColor|滑槽颜色|string|'#d3d3d3'|
+fillColor|填充颜色|string|'#007AFF'|
+percent|百分比|number|0|
+maskColor|遮罩颜色|string|'#ffffff'|
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                              | 默认值    | 描述 |
+| --------------------------------- | --------- | ---- |
+| --progress-height | _4px_ | - |
+| --progress-background-color | _#ebedf0_ | - |
+| --progress-pivot-padding | _0 5px_ | - |
+| --progress-color | _#1989fa_ | - |
+| --progress-pivot-font-size | _10px_ | - |
+| --progress-pivot-line-height | _1.6_ | - |
+| --progress-pivot-background-color | _#1989fa_ | - |
+| --progress-pivot-text-color | _#fff_ | - |
+| --circle-text-color | _#323233_ | 圆环内的文字颜色 |