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

package/es/notify/README.md

@@ -0,0 +1,121 @@
+<!-- ---
+category: 反馈
+--- -->
+
+
+# Notify 消息提示
+
+### 介绍
+
+在页面顶部展示消息提示，支持函数调用和组件调用两种方式。
+
+### 引入
+
+```jsx
+import { Notify, NotifyInstance } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+```js
+import { Notify, NotifyInstance } from '@ray-js/smart-ui';
+
+NotifyInstance('通知内容');
+```
+
+```jsx
+// 在页面内添加自定义节点
+<Notify id="smart-notify" />
+```
+
+### 通知类型
+
+支持`primary`、`success`、`warning`、`danger`四种通知类型，默认为`danger`。
+
+```js
+// 主要通知
+NotifyInstance({ type: 'primary', message: '通知内容' });
+
+// 成功通知
+NotifyInstance({ type: 'success', message: '通知内容' });
+
+// 危险通知
+NotifyInstance({ type: 'danger', message: '通知内容' });
+
+// 警告通知
+NotifyInstance({ type: 'warning', message: '通知内容' });
+```
+
+### 自定义通知
+
+自定义消息通知的颜色和展示时长。
+
+```js
+NotifyInstance({
+  message: '自定义颜色',
+  color: '#ad0000',
+  background: '#ffe1e1',
+});
+
+NotifyInstance({
+  message: '自定义时长',
+  duration: 1000,
+});
+```
+
+### 自定义选择器
+
+```js
+NotifyInstance({
+  message: '自定义节点选择器',
+  duration: 1000,
+  selector: '#custom-selector',
+});
+```
+
+```jsx
+// 在页面内添加自定义节点
+<Notify id="custom-selector" />
+```
+
+## API
+
+### 方法
+
+| 方法名       | 说明     | 参数                 | 返回值      |
+| ------------ | -------- | -------------------- | ----------- |
+| Notify | 展示提示 | `options \| message` | notify 实例 |
+| Notify.clear | 关闭提示 | `options` | `void` |
+
+### Options
+
+| 参数             | 说明                                                   | 类型       | 默认值         |
+| ---------------- | ------------------------------------------------------ | ---------- | -------------- |
+| background | 背景颜色 | _string_ | - |
+| color | 字体颜色 | _string_ | `#fff` |
+| context | 选择器的选择范围，可以传入自定义组件的 this 作为上下文 | _object_ | 当前页面 |
+| duration | 展示时长(ms)，值为 0 时，notify 不会消失 | _number_ | `3000` |
+| message | 展示文案，支持通过`\n`换行 | _string_ | `''` |
+| onClick | 点击时的回调函数 | _Function_ | - |
+| onClose | 关闭时的回调函数 | _Function_ | - |
+| onOpened | 完全展示后的回调函数 | _Function_ | - |
+| safeAreaInsetTop | 是否留出顶部安全距离（状态栏高度） | _boolean_ | `false` |
+| selector | 自定义节点选择器 | _string_ | `smart-notify` |
+| top | 顶部距离 | _number_ | `0` |
+| type | 类型，可选值为 `primary` `success` `warning` | _string_ | `danger` |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --notify-padding | _6px 15px_ | 通知内边距 |
+| --notify-font-size | _14px_ | 通知字体大小 |
+| --notify-line-height | _20px_ | 通知行高 |
+| --notify-primary-background-color | _#1989fa_ | 主要通知背景颜色 |
+| --notify-success-background-color | _#07c160_ | 成功通知背景颜色 |
+| --notify-danger-background-color | _#ee0a24_ | 危险通知背景颜色 |
+| --notify-warning-background-color | _#ff976a_ | 警告通知背景颜色 |

package/es/overlay/README.md

@@ -0,0 +1,128 @@
+---
+category: 展示
+---
+
+# Overlay 遮罩层
+
+### 介绍
+
+创建一个遮罩层，用于强调特定的页面元素，并阻止用户进行其他操作。
+
+### 引入
+
+```jsx
+import { Overlay } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Overlay, Button } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const onClickShow = () => setShow(true);
+  const onClickHide = () => setShow(false);
+
+  return (
+    <View>
+      <Button type="primary" onClick={onClickShow}>
+        显示遮罩层
+      </Button>
+      <Overlay show={show} onClick={onClickHide} />
+    </View>
+  );
+}
+```
+
+### 嵌入内容
+
+通过默认插槽可以在遮罩层上嵌入任意内容。
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Overlay, Button } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [show, setShow] = React.useState(false);
+  const onClickShow = () => setShow(true);
+  const onClickHide = () => setShow(false);
+
+  const onBlockClick = evt => {
+    evt?.origin?.stopPropagation();
+  };
+  return (
+    <View>
+      <Button type="primary" onClick={onClickShow}>
+        嵌入内容
+      </Button>
+      <Overlay show={show} onClick={onClickHide}>
+        <View style={styles.wrapper}>
+          <View style={styles.block} onClick={onBlockClick} />
+        </View>
+      </Overlay>
+    </View>
+  );
+}
+
+const styles = {
+  wrapper: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: '100%',
+  },
+  block: {
+    width: '120px',
+    height: '120px',
+    backgroundColor: '#fff',
+  },
+};
+```
+
+## API
+
+### Props
+
+| 参数           | 说明                                             | 类型               | 默认值  |
+| -------------- | ------------------------------------------------ | ------------------ | ------- |
+| classmartName | 自定义类名 | _string_ | - |
+| customStyle | 自定义样式 | _React.CSSProperties_ | - |
+| duration | 动画时长，单位秒 | _string \| number_ | `0.3` |
+| lockScroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | _boolean_ | `true` |
+| show | 是否展示遮罩层 | _boolean_ | `false` |
+| zIndex | z-index 层级 | _string \| number_ | `1` |
+
+### Events
+
+| 事件名     | 说明       | 回调参数 |
+| ---------- | ---------- | -------- |
+| onClick | 点击时触发 | - |
+
+### Slots
+
+| 名称 | 说明                               |
+| ---- | ---------------------------------- |
+| -    | 默认插槽，用于在遮罩层上方嵌入内容 |
+
+
+### 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| customClass | 根节点样式类 |
+
+### 样式变量
+
+组件会根据设备是否支持 `backdrop-filter` 自动选择**毛玻璃遮罩**或**半透明遮罩**，以减轻 iOS 输入框聚焦时页面布局上移的跳动感；不支持模糊的机型（如部分 Android）使用半透明降级样式。
+
+| 名称                              | 默认值（浅色 / 深色）                    | 描述 |
+| --------------------------------- | ----------------------------------------- | ---- |
+| --overlay-background-color        | _rgba(0,0,0,0.4)_ / _rgba(0,0,0,0.7)_        | 直接指定遮罩背景色时使用，设置后不再使用毛玻璃/半透明变量 |
+| --overlay-blur-background  `v2.12.0`        | _rgba(40,44,53,0.22)_ / _rgba(0,0,0,0.6)_ | 支持模糊时的毛玻璃遮罩背景色 |
+| --overlay-blur-radius  `v2.12.0`            | _16px_                                    | 毛玻璃模糊半径 |

package/es/picker/README.md

@@ -0,0 +1,412 @@
+---
+category: 反馈
+assets: LoopPicker
+---
+
+
+# Picker 选择器
+
+### 介绍
+
+提供多个选项集合供用户选择，支持单列选择和多列级联，通常与 [弹出层](/material/smartui?comId=popup) 组件配合使用。
+
+### 引入
+
+```jsx
+import { Picker } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+单列时 `active-index` 属性可以控制picker的选中项; `change-animation` 可以开启picker的选中值变化过度动画效果。
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import { showToast } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+
+export default function Demo() {
+  const [activeIndex, setActiveIndex] = useState(3);
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    setActiveIndex(index);
+    showToast({
+      icon: 'none',
+      title: `Value: ${value}, Index：${index}`,
+    });
+  }, []);
+
+  return <Picker activeIndex={activeIndex} changeAnimation columns={['杭州', '宁波', '温州', '嘉兴', '湖州']} onChange={onChange} />;
+}
+```
+
+### 多列用法
+
+`disabled` `v2.3.5` 属性可以禁用此列；`style` 属性可以设置此列的样式；`fontStyle` `v2.3.5` 属性可以设置此列的字体样式; `activeIndex` 可以设置列的选中项;`unitGap` `v2.10.0` 属性可以设置单位和列表的距离。
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import { showToast } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+
+const columns = [
+  {
+    values: new Array(100).fill(1).map((x, i) => i),
+    style: { flex: 'none', width: 'auto', minWidth: '61px' },
+    fontStyle: { color: 'rgb(135, 180, 244)' },
+    activeIndex: 0,
+  },
+  {
+    values: ['.'],
+    disabled: true,
+    style: { flex: 'none', width: '8px', display: 'flex', justifyContent: 'center' },
+  },
+  {
+    values: new Array(20).fill(1).map((x, i) => i),
+    style: { flex: 'none', width: 'auto', minWidth: '61px' },
+    unit: 'Kg',
+    unitGap: '10rpx',
+    activeIndex: 1,
+  },
+],
+
+export default function Demo() {
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    showToast({
+      icon: 'none',
+      title: `Value: ${value}, Index：${index}`,
+    });
+  }, []);
+
+  return (
+    <Picker 
+      columns={columns} 
+      onChange={onChange} 
+      activeStyle={{
+        color: 'rgb(135, 180, 244)',
+      }}
+    />
+  );
+}
+```
+
+
+### 循环列表 `v2.7.0`
+
+`loop` 属性可以开启列表的循环渲染，列表会首尾相连，无限循环
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import React from 'react';
+const columns = [
+  {
+    values: new Array(100).fill(1).map((x, i) => i),
+  },
+];
+export default function Demo() {
+  return <Picker loop columns={columns} />;
+}
+```
+
+### 默认选中项
+
+单列选择器可以直接通过`defaultIndex`属性设置初始选中项的索引值。
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import { showToast } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+
+export default function Demo() {
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    showToast({
+      icon: 'none',
+      title: `Value: ${value}, Index：${index}`,
+    });
+  }, []);
+
+  return (
+    <Picker
+      defaultIndex={2}
+      columns={['杭州', '宁波', '温州', '嘉兴', '湖州']}
+      onChange={onChange}
+    />
+  );
+}
+```
+
+### 展示顶部栏
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import { showToast } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+
+export default function Demo() {
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    showToast({
+      icon: 'none',
+      title: `Value: ${value}, Index：${index}`,
+    });
+  }, []);
+
+  return (
+    <Picker
+      showToolbar
+      title="标题"
+      defaultIndex={2}
+      columns={['杭州', '宁波', '温州', '嘉兴', '湖州']}
+      onChange={onChange}
+    />
+  );
+}
+```
+
+### 多列联动
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import React, { useCallback } from 'react';
+
+const citys = [
+  ['杭州', '宁波', '温州', '嘉兴', '湖州'],
+  ['福州', '厦门', '莆田', '三明', '泉州'],
+];
+
+export default function Demo() {
+  const [column, setColumn] = useState([
+    {
+      values: ['浙江', '福建'],
+      className: 'column1',
+      unit: '省',
+    },
+    {
+      values: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
+      className: 'column2',
+      defaultIndex: 2,
+      unit: '市',
+    },
+  ]);
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    const provinceIndex = column[0].values.findIndex(item => item === value[0]);
+    const cityList = cities[provinceIndex];
+    const cityIndex = index ? cityList.findIndex(item => item === value[1]) : 0;
+    setColumn([
+      {
+        ...column[0],
+        activeIndex: provinceIndex,
+      },
+      {
+        ...column[1],
+        activeIndex: cityIndex,
+        values: cityList,
+      },
+    ]);
+  }, []);
+
+  return <Picker columns={columns} onChange={onChange} />;
+}
+```
+
+### 禁用选项
+
+选项可以为对象结构，通过设置 disabled 来禁用该选项。
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import { showToast } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+
+const columns = [{ text: '杭州', disabled: true }, { text: '宁波' }, { text: '温州' }];
+
+export default function Demo() {
+  const onChange = useCallback(event => {
+    const { value, index } = event.detail;
+    showToast({
+      icon: 'none',
+      title: `Value: ${value}, Index：${index}`,
+    });
+  }, []);
+
+  return <Picker columns={columns} onChange={onChange} />;
+}
+```
+
+### 加载状态
+
+当 Picker 数据是通过异步获取时，可以通过 `loading` 属性显示加载提示。
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import React, { useCallback } from 'react';
+
+export default function Demo() {
+  return <Picker loading columns={['杭州', '宁波', '温州', '嘉兴', '湖州']} />;
+}
+```
+
+### 设置列的样式顺序 `v2.2.0`
+
+通过设置列的 `order` 属性可以设置列的顺序，对应列的order越大，就会越靠后，同css的`flex order` 属性，只是从样式层面改变列的顺序，逻辑还是不变。  
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import React from 'react';
+const columns = [
+  {
+    values: ['浙江', '福建'],
+    order: 2,
+  },
+  {
+    values: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
+    order: 1,
+  },
+];
+export default function Demo() {
+  return <Picker columns={columns} />;
+}
+```
+
+
+### 更多3D `v2.7.0`
+
+`fullHeight` 属性可以展示更多的空间，看到更多3D翻转的项；当然你也可以覆盖组件的高度样式，来自定义需要可视的空间
+
+```javascript
+import { Picker } from '@ray-js/smart-ui';
+import React from 'react';
+const columns = [
+  {
+    values: new Array(100).fill(1).map((x, i) => i),
+  },
+];
+export default function Demo() {
+  return <Picker fullHeight loop columns={columns} />;
+}
+```
+
+## API
+
+### Props
+
+| 参数              | 说明                             | 类型      | 默认值  |
+| ---------------- | -------------------------------- | --------- | ------- |
+| activeIndex | 单列选择器的当前选中项索引，<br>多列选择器请参考下方的 Columns 配置 | _number_ | `-1` |
+| cancelButtonText | 取消按钮文字 | _string_ | `取消` |
+| columns | 对象数组，配置每一列显示的数据 | _Array_ | `[]` |
+| confirmButtonText | 确认按钮文字 | _string_ | `确认` |
+| defaultIndex | 单列选择器的默认选中项索引，<br>多列选择器请参考下方的 Columns 配置 | _number_ | `0` |
+| itemHeight | 选项高度 | _number_ | `44` |
+| loading | 是否显示加载状态 | _boolean_ | `false` |
+| showToolbar | 是否显示顶部栏 | _boolean_ | `false` |
+| title | 顶部栏标题 | _string_ | `''` |
+| toolbarPosition | 顶部栏位置，可选值为`bottom` | _string_ | `top` |
+| unit | 单列选择器的默认的单位，<br>多列选择器请参考下方的 Columns 配置 | _number_ | '' |
+| valueKey | 选项对象中，文字对应的 key | _string_ | `text` |
+| visibleItemCount | 可见的选项个数 | _3 \| 5 \| 7 \| 9_ | `5` |
+| activeStyle `v2.0.0` | 选中状态下的样式 | _React.CSSProperties_ | - |
+| changeAnimation `v2.2.0` | 组件受数据驱动选择值改变时是否需要动画过度效果（不包含手指交互滚动的动画） | _boolean_ | `false` |
+| animationTime `v2.3.7` | 过渡动画以及选择回调延迟的时间(单位ms) | _number_ | `800` `v2.3.7` `300` `v2.6.0` |
+| loop `v2.7.0` | 循环列表 | _boolean_ | `false` |
+| fontStyle `v2.7.0` | 字体样式，优先级低于 columns 内的 | _React.CSSProperties_ | - |
+| fullHeight `v2.7.0` | 是否高度直接等于 `visibleItemCount * itemHeight`, 组件默认会再 `* 0.9` 缩小最外层可视的高度 | _boolean_ | `false` |
+
+
+### Events
+
+Picker 组件的事件会根据 columns 是单列或多列返回不同的参数。
+
+| 事件名       | 说明               | 参数                                                                                             |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------ |
+| onCancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
+| onChange | 选项改变时触发 | 单列：Picker 实例，选中值，选中值对应的索引<br>多列：Picker 实例，所有列选中值，当前列对应的索引 |
+| onConfirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
+| onAnimationStart `v2.3.0` | 组件内部动画开始 | - |
+| onAnimationEnd `v2.3.0` | 组件内部动画结束 | - |
+
+### Columns 数据结构
+
+当传入多列数据时，`columns`为一个对象数组，数组中的每一个对象配置每一列，每一列有以下`key`。
+
+| key           | 说明                        |
+| ------------- | --------------------------- |
+| activeIndex | 当前选中项的索引，默认为 -1 |
+| defaultIndex | 初始选中项的索引，默认为 0 |
+| style `v2.0.0` | 列的样式 |
+| fontStyle `v2.3.5` | 列的文字样式 |
+| unit | 列对应的单位，默认为空 |
+| unitGap `v2.10.0` | 单位和值的间隔，默认为 undefined（使用 CSS 默认样式），支持传入数字（自动添加 px 单位）或字符串（如 "8rpx"） | _string \| number_ | `undefined` |
+| values | 列中对应的备选值 |
+| order `v2.2.0` | 设置列的顺序，同`flex order`属性，只是从样式角度修改列的顺序，逻辑还是不变 | _number_ | - |
+| disabled `v2.3.5` | 禁用此列 | _boolean_ | `false` |
+| loop `v2.7.0` | 循环列表 | _boolean_ | `false` |
+
+### 外部样式类
+
+| 类名          | 说明         |
+| ------------- | ------------ |
+| columnClass | 列样式类 |
+| customClass | 根节点样式类 |
+| toolbarClass | 顶部栏样式类 |
+| hairlineClass `v2.6.0` | 分割线的样式类 |
+
+
+### 方法
+
+通过 [selectComponent](/material/smartui?comId=faq) 可以获取到 picker 实例并调用实例方法。
+
+| 方法名          | 参数                     | 返回值      | 介绍                       |
+| --------------- | ------------------------ | ----------- | -------------------------- |
+| getColumnIndex | columnIndex | optionIndex | 获取对应列选中项的索引 |
+| getColumnValue | columnIndex | value | 获取对应列选中的值 |
+| getColumnValues | columnIndex | values | 获取对应列中所有选项 |
+| getIndexes | - | indexes | 获取所有列选中值对应的索引 |
+| getValues | - | values | 获取所有列选中的值 |
+| setColumnIndex | columnIndex, optionIndex | - | 设置对应列选中项的索引 |
+| setColumnValue | columnIndex, value | - | 设置对应列选中的值 |
+| setColumnValues | columnIndex, values | - | 设置对应列中所有选项 |
+| setIndexes | indexes | - | 设置所有列选中值对应的索引 |
+| setValues | values | - | 设置所有列选中的值 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --picker-background-color | _var(--app-B4, #ffffff)_ | 选择器背景颜色 |
+| --picker-padding | _16px_ | 选择器内边距 |
+| --picker-toolbar-height | _44px_ | 工具栏高度 |
+| --picker-title-font-size | _16px_ | 标题字体大小 |
+| --picker-action-padding | _0 @padding-md_ | 操作按钮内边距 |
+| --picker-action-font-size | _14px_ | 操作按钮字体大小 |
+| --picker-confirm-action-color | _#007AFF_ | 确认按钮颜色 |
+| --picker-cancel-action-color | _#969799_ | 取消按钮颜色 |
+| --picker-option-font-size | _16px_ | 选项字体大小 |
+| --picker-option-unit-font-size | _12px_ | 单位字体大小 |
+| --picker-option-text-color | _var(--app-B6-N1, rgba(0, 0, 0, 1))_ | 选项文本颜色 |
+| --picker-option-unit-text-color | _var(--app-B6-N4, rgba(0, 0, 0, 0.4))_ | 单位文本颜色 |
+| --picker-loading-icon-color | _#1989fa_ | 加载图标颜色 |
+| --picker-loading-mask-color | _var(--app-B4, #ffffff)_ | 加载遮罩颜色 |
+| --picker-option-disabled-opacity | _0.3_ | 禁用选项不透明度 |
+| --picker-option-selected-text-color | _var(--app-B6-N1, rgba(0, 0, 0, 1))_ | 选中选项文本颜色 |
+| --picker-option-unit-mid-size `v2.4.0` | _0_  `v2.4.0` _4px_ `v2.6.0` | 单位和内容文案的间隔 |
+| --picker-option-selected-font-weight-bold `v2.6.0` | _700_ | 选中时文案的字重 |
+
+## 常见问题
+
+### 部分文案无法正常展示
+
+当选项文案中包含双引号 `"` 等特殊字符时，可能导致文案显示不全。需在数据中使用 `\` 转义符自行转义，例如将双引号写为 `\"`，即可正常展示。
+
+```javascript
+// 文案 "--"- 中的双引号需转义
+columns: ['杭州', '宁波', '--"-']   // 可能显示不全
+columns: ['杭州', '宁波', '--\\"-'] // 使用 \ 转义后正常展示
+```