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

package/es/slider/README.md

@@ -0,0 +1,444 @@
+---
+category: 数据录入
+assets: LampTouchSlider,LampColorSlider,LampSaturationSlider,LampTempSlider,LampBrightSlider,LampStyleSlider,LampVerticalTouchSlider,LampVerticalPercentSlider,HighPerfText,CircleProgress
+---
+
+# Slider 滑动条
+
+### 介绍
+
+滑动条是代表模拟无线电调谐或音量控制表盘的 UI 组件。它允许用户从左到右滑动旋钮、手柄或栏，反之亦然。UI 滑动条非常适合用户快速同时探索许多不同的选项或值。最重要的是，当数量或值不需要精确时，它们对于用户来说是实用的组件。
+
+### 引入
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 普通滑动条
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      maxTrackHeight="4px"
+      minTrackHeight="4px"
+      thumbHeight="28px"
+      thumbWidth="28px"
+      value={value}
+      onAfterChange={value => setValue(value)}
+    />
+  );
+}
+```
+
+### 间隔滑动条
+
+设置 `isShowTicks` 为 `true` ，可以展示出滑动间隔
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      value={value}
+      onAfterChange={value => setValue(value)}
+      maxTrackHeight={8}
+      minTrackHeight={8}
+      tickHeight="4px"
+      tickWidth="4px"
+      thumbHeight="18px"
+      thumbWidth="18px"
+      minTrackTickColor="#fff"
+      maxTrackTickColor="#fff"
+      isShowTicks
+      step={10}
+      min={0}
+      max={100}
+    />
+  );
+}
+```
+
+### 间隔滑动条 - 样式2
+
+设置 `hideThumbButton` 为 `true` ，可以隐藏滑块按钮
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      isShowTicks
+      step={30}
+      min={0}
+      max={90}
+      maxTrackHeight="40px"
+      maxTrackRadius="16px"
+      minTrackWidth="40px"
+      minTrackHeight="40px"
+      minTrackRadius="16px"
+      tickWidth="4px"
+      tickHeight="12px"
+      tickRadius="4px"
+      hideThumbButton
+      value={value}
+      onAfterChange={value => setValue(value)}
+    />
+  );
+}
+```
+
+### 拖动滑动条
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      minTrackRadius="13px"
+      minTrackHeight="22px"
+      maxTrackRadius="13px"
+      maxTrackHeight="26px"
+      value={value}
+      thumbWidth={18}
+      thumbHeight={18}
+      parcel
+      parcelMargin={2}
+      onAfterChange={value => setValue(value)}
+    />
+  );
+}
+```
+
+### 拖动滑动条 - 样式2
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      minTrackRadius="8px"
+      minTrackHeight="45px"
+      maxTrackRadius="8px"
+      maxTrackHeight="45px"
+      value={value}
+      onAfterChange={value => setValue(value)}
+      thumbWidth={15}
+      thumbHeight={50}
+      thumbRadius={2}
+      thumbStyle={{
+        background: '#BBC5D4',
+        border: '2px solid #FFFFFF',
+        boxShadow: '0px 0px 2px 0px rgba(0, 0, 0, 0.5)',
+      }}
+    />
+  );
+}
+```
+
+### 拖动滑动条 - 样式3
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+
+  return (
+    <Slider
+      parcel
+      parcelMargin={2}
+      minTrackRadius="5px"
+      minTrackHeight="22px"
+      maxTrackRadius="5px"
+      maxTrackHeight="26px"
+      value={value}
+      thumbWidth={3}
+      thumbHeight={16}
+      onAfterChange={value => setValue(value)}
+    />
+  );
+}
+```
+
+### 双滑块滑动条
+
+```jsx
+import { View } from '@ray-js/ray';
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState([10, 30]);
+
+  return (
+    <View style={{ padding: 48 }}>
+      <Slider.RangeSlider
+        min={0}
+        max={100}
+        barHeight="4px"
+        value={value}
+        inActiveColor="#D8D9DC"
+        activeColor="#007AFF"
+        onChange={event => setValue(event.detail)}
+      />
+    </View>
+  );
+}
+```
+
+
+### 竖向
+
+```jsx
+import { Slider } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [value, setValue] = React.useState(30);
+  return (
+    <Slider
+      isVertical
+      value={value}
+      step={1}
+      min={0}
+      max={100}
+      parcel
+      parcelMargin={2}
+      useParcelPadding={false}
+      thumbWidth={12}
+      thumbHeight={2}
+      thumbRadius={2}
+      maxTrackWidth="48px"
+      maxTrackHeight="203px"
+      maxTrackRadius="8px"
+      minTrackWidth="48px"
+      minTrackHeight="114px"
+      maxTrackColor="rgba(0, 0, 0, 0.08)"
+      minTrackColor="#1989FA"
+      onAfterChange={setValue}
+      thumbStyle={{
+        borderRadius: '2px',
+        width: '12px',
+        height: '2px',
+      }}
+    />
+  );
+}
+```
+
+## API
+
+### Slider Props
+
+|属性名|描述|类型|默认值|
+|---|---|---|---|
+|instanceId|--|string|undefined|
+|className|类名|string|undefined|
+|style|样式|CSSProperties|undefined|
+|isVertical|是否垂直展示，垂直展示时，需要设置滑槽宽高|boolean|false|
+|value|样式|number|undefined|
+|defaultValue|默认值|number|0|
+|min|最小值|number|0|
+|max|最大值|number|100|
+|step|步距，取值必须大于 `0`，并且可被 `(max - min)` 整除。|number|1|
+|forceStep|和 step 一致，用于滑块不跟随刻度时设置|number|1|
+|disabled|是否禁用|boolean|false|
+|onChange|拖拽滑块时触发，并把当前拖拽的值作为参数传入|(value: number) => void|undefined|
+|onBeforeChange|滑块拖拽开始时触发，并把当前拖拽的值作为参数传入|(value: number) => void|undefined|
+|onAfterChange|与 `touchend` 触发时机一致，把当前值作为参数传入|(value: number) => void|undefined|
+|maxTrackWidth|滑槽宽度|Width<string \| number>|'100%'|
+|maxTrackHeight|滑槽高度|Width<string \| number>|'4px'|
+|maxTrackRadius|滑槽圆角|BorderRadius<string \| number>|'4px'|
+|maxTrackColor|滑槽颜色|Background<0 \| (string & {})>|'#d8d8d8'|
+|minTrackWidth|滑条最小宽度|Width<string \| number>|'28px'|
+|minTrackHeight|滑条高度|Width<string \| number>|'4px'|
+|minTrackRadius|滑条圆角|BorderRadius<string \| number>|'inherit'|
+|minTrackColor|滑条颜色|Background<0 \| (string & {})>|'#158CFB'|
+|thumbWidth|滑块宽度|Width<string \| number>|'28px'|
+|thumbStyle|滑块样式|CSSProperties|null|
+|thumbWrapStyle|滑块wrap样式|CSSProperties|null|
+|thumbHeight|滑块高度|string | number|'28px'|
+|thumbRadius|滑块圆角|string | number|'28px'|
+|thumbColor|滑块颜色|Background<0 \| (string & {})>|'#ffffff'|
+|thumbBorderStyle|滑块边框类型|BorderStyle|'none'|
+|thumbBoxShadowStyle|滑块阴影|BoxShadow|'0px 0.5px 4px rgba(0, 0, 0, 0.12), 0px 6px 13px rgba(0, 0, 0, 0.12)'|
+|isShowTicks|是否显示刻度|boolean|false|
+|tickWidth|刻度宽度|string|'4px'|
+|tickHeight|刻度高度|string|'12px'|
+|tickRadius|刻度圆角|string|'4px'|
+|maxTrackTickColor|滑槽刻度颜色|string|'#158CFB'|
+|minTrackTickColor|滑条刻度颜色|string|'#ffffff'|
+|trackStyle|轨道样式|CSSProperties|undefined|
+|barStyle|滑条样式|CSSProperties|undefined|
+|renderType|渲染方式|"ray" | "sjs"|'sjs'|
+|hideThumbButton|隐藏滑块|boolean|null|
+|thumbStyleRenderFormatter|渲染按钮背景色，例如 "rgb(value,100,100)"，将value替换为滑动值(仅sjs支持)|Partial<Record<keyof CSSProperties, string>>|null|
+|thumbStyleRenderValueScale|渲染value时的缩放倍数|number|1|
+|thumbStyleRenderValueStart|渲染value时的起始值|number|0|
+|thumbStyleRenderValueReverse|渲染value时反转值|boolean|false|
+|enableTouch|使用触摸跳跃|boolean|true|
+|hidden|是否隐藏|boolean|false|
+|parcel|包裹滑动条|boolean|false|
+|parcelMargin|包裹滑动条间隔|number|0|
+
+### Slot
+
+| 名称  | 说明     |
+| ----- | -------- |
+| bar `v2.4.0` | 滑动条插槽 |
+| thumb  `v2.4.0` | 滑块插槽 |
+
+### RangeSlider Props
+
+|参数|说明|类型|默认值|
+|---|---|---|---|
+|value|当前进度百分比，在双滑块模式下为数组格式|number | number[]|0|
+|disabled|是否禁用滑块|boolean|false|
+|max|最大值|number|100|
+|min|最小值|number|0|
+|step|步长|number|1|
+|barHeight|进度条高度，默认单位为 px|string | number|2px|
+|activeColor|进度条激活态颜色|string|#1989fa|
+|inactiveColor|进度条默认颜色|string|#e5e5e5|
+|vertical|是否垂直展示|boolean|false|
+|onDrag|拖动进度条时触发|event.detail.value: 当前进度|
+|onChange|进度值改变后触发|event.detail: 当前进度|
+|onDragStart|开始拖动时触发|-|
+|onDragEnd|结束拖动时触发|-|
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --slider-active-background-color | _#1989fa_ | 设置滑块激活状态下的背景颜色。 |
+| --slider-inactive-background-color | _#ebedf0_ | 设置滑块未激活状态下的背景颜色。 |
+| --slider-disabled-opacity | _0.3_ | 设置滑块禁用状态的透明度，数值越小透明度越高。 |
+| --slider-bar-height | _2px_ | 设置滑块轨道的高度。 |
+| --slider-button-width | _24px_ | 设置滑块按钮的宽度。 |
+| --slider-button-height | _24px_ | 设置滑块按钮的高度。 |
+| --slider-button-border-radius | _50%_ | 设置滑块按钮的圆角半径，通常用来实现圆形按钮。 |
+| --slider-button-background-color | _#fff_ | 设置滑块按钮的背景颜色。 |
+| --slider-button-box-shadow | _0 1px 2px rgba(0, 0, 0, 0.5)_ | 设置滑块按钮的阴影效果，可以增强立体感。 |
+| --slider-thumb-color | _var(--app-B3, #ffffff)_ | 设置滑块按钮的指示色，通常用于显示当前进度的指示器。 |
+
+## 常见问题
+
+### Slider 拖动时会抖动卡顿
+
+Slider 拖动时会抖动卡顿，需要检查一下是否为非受控组件写法，尽量使用 `onAfterChange` 来更新 `value`，推荐写法如下：
+
+```tsx
+export default () => {
+  const [value, setValue] = useState(10) // onAfterChange 拖动结束后更新
+  const [showValue, setShowValue] = useState(10) // 只用作实时展示使用
+
+  return (
+    <>
+      <View>当前值：{showValue}</View>
+      <Slider
+        value={value}
+        onChange={(newValue) => {
+          setShowValue(newValue)
+        }}
+        onAfterChange={setValue} // 松开滑块时触发
+      />
+    </>
+  )
+}
+```
+
+
+### Slider 受控模式滑动位置定位异常，该如何处理？
+
+这种情况往往是在在`Popup`弹框内嵌套使用`Slider`，由于 `Slider` 组件使用到 `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>
+  );
+}
+```
+
+注意，`isReady` 可能存在首次渲染布局抖动，请升级到最新版，使用 `Slider` 的 `deps` 属性进行渲染优化，示例：
+
+```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' }}>
+          <Slider deps={[show]} value={value} max={100} min={0} onChange={handleChange} />
+        </View>
+      </Popup>
+    </DemoBlock>
+  );
+}
+```

package/es/stepper/README.md

@@ -0,0 +1,231 @@
+---
+category: 数据录入
+---
+
+# Stepper 步进器
+
+### 介绍
+
+步进器由增加按钮、减少按钮和输入框组成，用于在一定范围内输入、调整数字。
+
+### 引入
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`value`设置输入值，可以通过`onChange`事件监听到输入值的变化。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const onChange = event => {
+    console.log(event.detail);
+  };
+
+  return <Stepper value={1} onChange={onChange} />;
+}
+```
+
+### 步长设置
+
+通过`step`属性设置每次点击增加或减少按钮时变化的值，默认为`1`。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} step="2" />;
+}
+```
+
+### 限制输入范围
+
+通过`min`和`max`属性限制输入值的范围。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={5} min="5" max="8" />
+}
+```
+
+### 限制输入整数
+
+设置`integer`属性后，输入框将限制只能输入整数。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} integer />
+}
+```
+
+### 禁用状态
+
+通过设置`disabled`属性来禁用步进器，禁用状态下无法点击按钮或修改输入框。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} disabled />
+}
+```
+
+### 禁用长按
+
+通过设置`longpress`属性决定步进器是否开启长按手势。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} longPress={false} />
+}
+```
+
+### 固定小数位数
+
+通过设置`decimalLength`属性可以保留固定的小数位数。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} step="0.2" decimalLength={1} />
+}
+```
+
+### 异步变更
+
+如果需要异步地修改输入框的值，可以设置`asyncChange`属性，并在`onChange`事件中手动修改`value`。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React, { useState } from 'react';
+import { showLoading, hideLoading } from '@ray-js/ray';
+
+export default function Demo() {
+  const [value, setValue] = useState(1);
+  const onChange = event => {
+    showLoading({ title: '', mask: true });
+
+    setTimeout(() => {
+      hideLoading();
+      setValue(event.detail);
+    }, 500);
+  };
+
+  return <Stepper value={value} asyncChange onChange={onChange} />
+}
+```
+
+### 自定义大小
+
+通过`inputWidth`属性设置输入框宽度，通过`buttonSize`属性设置按钮大小和输入框高度。
+
+```jsx
+import { Stepper } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <Stepper value={1} inputWidth="40px" buttonSize="32px" />
+}
+```
+
+## API
+
+### Props
+
+| 参数                  | 说明                                                                            | 类型               | 默认值  |
+| --------------------- | ------------------------------------------------------------------------------- | ------------------ | ------- |
+| alwaysEmbed `v1.9.3` | 强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效) | _boolean_ | `false` |
+| asyncChange | 是否开启异步变更，开启后需要手动控制输入值 | _boolean_ | `false` |
+| buttonSize | 按钮大小，默认单位为 `px`，输入框高度会和按钮大小保持一致 | _string \| number_ | `28px` |
+| decimalLength | 固定显示的小数位数 | _number_ | - |
+| disableInput | 是否禁用输入框 | _boolean_ | `false` |
+| disableMinus | 是否禁用减少按钮 | _boolean_ | - |
+| disablePlus | 是否禁用增加按钮 | _boolean_ | - |
+| disabled | 是否禁用 | _boolean_ | `false` |
+| inputWidth | 输入框宽度，默认单位为 `px` | _string \| number_ | `32px` |
+| integer | 是否只允许输入整数 | _boolean_ | `false` |
+| longPress | 是否开启长按手势 | _boolean_ | `true` |
+| max | 最大值 | _string \| number_ | - |
+| min | 最小值 | _string \| number_ | `1` |
+| minusAriaLabel `v2.13.0` | 减少按钮的无障碍读屏文案 | _string_ | - |
+| name | 在表单内提交时的标识符 | _string_ | - |
+| plusAriaLabel `v2.13.0` | 增加按钮的无障碍读屏文案 | _string_ | - |
+| showMinus | 是否显示减少按钮 | _boolean_ | `true` |
+| showPlus | 是否显示增加按钮 | _boolean_ | `true` |
+| step | 步长 | _string \| number_ | `1` |
+| theme | 样式风格，可选值为 `round` | _string_ | - |
+| value | 输入值 | _string \| number_ | 最小值 |
+
+### Events
+
+| 事件名         | 说明                     | 回调参数                   |
+| -------------- | ------------------------ | -------------------------- |
+| onBlur | 输入框失焦时触发 | - |
+| onChange | 当绑定值变化时触发的事件 | event.detail: 当前输入的值 |
+| onFocus | 输入框聚焦时触发 | - |
+| onMinus | 点击减少按钮时触发 | - |
+| onOverlimit | 点击不可用的按钮时触发 | - |
+| onPlus | 点击增加按钮时触发 | - |
+
+### Slot
+
+| 名称  | 说明     |
+| ----- | -------- |
+| minus | 减号按钮 |
+| plus | 加号按钮 |
+
+### 外部样式类
+
+| 类名            | 说明           |
+| --------------- | -------------- |
+| customClass | 根节点样式类 |
+| inputClass | 输入框样式类 |
+| minusmartClass | 减号按钮样式类 |
+| plusmartClass | 加号按钮样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --stepper-container-background-color | _var(--app-B6-N9, rgba(0, 0, 0, 0.05))_ | 背景色 |
+| --stepper-background-border-radius | _10px_ | 背景圆角 |
+| --stepper-padding | _2px_ | 外部合作内边距 |
+| --stepper-active-color | _#e8e8e8_ | 按钮点击后颜色 |
+| --stepper-background-color | _var(--app-B6, #fff)_ | 按钮背景色 |
+| --stepper-button-icon-color | _var(--app-B6-N3, rgba(0, 0, 0, 0.5))_ | 按钮内部图标颜色 |
+| --stepper-button-disabled-color | _none_ `v2.1.7`  _var(--app-B6, #ffffff)_ `v2.6.1` | 按钮禁用颜色 |
+| --stepper-button-disabled-icon-color | _var(--app-B6-N7, rgba(0, 0, 0, 0.1))_ | 按钮禁用图标颜色 |
+| --stepper-button-round-theme-color | _#ee0a24_ | 圆角样式按钮颜色 |
+| --stepper-btn-width | _44px_ | 按钮宽度 |
+| --stepper-btn-height | _28px_ | 按钮高度 |
+| --stepper-input-width | _50px_ | 中间数组输入框宽度 |
+| --stepper-input-height | _28px_ | 中间数组输入框高度 |
+| --stepper-input-font-size | _16px_ | 中间数组输入框字体大小 |
+| --stepper-input-line-height | _normal_ | 中间数组输入框字体高度 |
+| --stepper-input-text-color | _var(--app-B6-N1, rgba(0, 0, 0, 1))_ | 中间数组输入框字体颜色 |
+| --stepper-input-disabled-text-color | _var(--app-B6-N7, rgba(0, 0, 0, 0.1))_ | 中间数组输入框禁用模式字体颜色 |
+| --stepper-border-radius | _8px_ | 按钮圆角 |
+| --stepper-button-border `v2.2.0` | _0_ | 按钮边框 |
+| --stepper-button-icon-font-size `v2.2.0` | _22px_ | 按钮内部图标的字体大小 |