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

package/es/col/README.md

@@ -0,0 +1,162 @@
+---
+category: 布局
+---
+
+# Layout 布局
+
+### 介绍
+
+Layout 提供了`Row`和`Col`两个组件来进行行列布局。
+
+### 引入
+
+```jsx
+import { Row, Col } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+Layout 组件提供了`24列栅格`，通过在`Col`上添加`span`属性设置列所占的宽度百分比。此外，添加`offset`属性可以设置列的偏移宽度，计算方式与 span 相同。
+
+```jsx
+import { Row, Col } from '@ray-js/smart-ui';
+import { View } from '@ray-js/ray';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <View>
+      <Row>
+        <Col span="8" customClass={styles.dark}>
+          span: 8
+        </Col>
+        <Col span="8" customClass={styles.light}>
+          span: 8
+        </Col>
+        <Col span="8" customClass={styles.dark}>
+          span: 8
+        </Col>
+      </Row>
+      <Row>
+        <Col span="4" customClass={styles.dark}>
+          span: 4
+        </Col>
+        <Col span="10" offset="4" customClass={styles.light}>
+          offset: 4, span: 10
+        </Col>
+      </Row>
+      <Row>
+        <Col offset="12" span="12" customClass={styles.dark}>
+          offset: 12, span: 12
+        </Col>
+      </Row>
+    </View>
+  );
+}
+```
+
+less 样式：
+
+```less
+.dark,
+.light {
+  color: #fff;
+  font-size: 13px;
+  line-height: 30px;
+  text-align: center;
+  margin-bottom: 10px;
+  background-clip: content-box;
+}
+
+.dark {
+  background-color: #39a9ed;
+}
+
+.light {
+  background-color: #66c6f2;
+}
+```
+
+### 在列元素之间增加间距
+
+通过`gutter`属性可以设置列元素之间的间距，默认间距为 0。
+
+```jsx
+import { Row, Col } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Row gutter="20">
+      <Col span="8" customClass={styles.dark}>
+        span: 8
+      </Col>
+      <Col span="8" customClass={styles.light}>
+        span: 8
+      </Col>
+      <Col span="8" customClass={styles.dark}>
+        span: 8
+      </Col>
+    </Row>
+  );
+}
+```
+
+less 样式：
+
+```less
+.dark,
+.light {
+  color: #fff;
+  font-size: 13px;
+  line-height: 30px;
+  text-align: center;
+  margin-bottom: 10px;
+  background-clip: content-box;
+}
+
+.dark {
+  background-color: #39a9ed;
+}
+
+.light {
+  background-color: #66c6f2;
+}
+```
+
+## API
+
+### Row Props
+
+| 参数   | 说明                          | 类型               | 默认值 |
+| ------ | ----------------------------- | ------------------ | ------ |
+| gutter | 列元素之间的间距（单位为 px） | _string \| number_ | - |
+
+### Col Props
+
+| 参数   | 说明           | 类型               | 默认值 |
+| ------ | -------------- | ------------------ | ------ |
+| offset | 列元素偏移距离 | _string \| number_ | - |
+| span | 列元素宽度 | _string \| number_ | - |
+
+### 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| customClass | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                                          | 默认值                                       | 描述                                       |
+| --------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
+| --collapse-item-transition-duration           | _0.3s_                                       | 折叠项过渡持续时间                         |
+| --collapse-item-content-padding               | _15px_                                       | 折叠项内容内边距                           |
+| --collapse-item-content-font-size             | _13px_                                       | 折叠项内容字体大小                         |
+| --collapse-item-content-line-height           | _1.5_                                        | 折叠项内容行高                             |
+| --collapse-item-content-text-color            | _#969799_                                    | 折叠项内容文本颜色                         |
+| --collapse-item-content-background-color      | _var(--app-B6, #fff)_                        | 折叠项内容背景颜色                         |
+| --collapse-item-title-disabled-color          | _#c8c9cc_                                    | 折叠项标题禁用状态颜色                     |

package/es/collapse/README.md

@@ -0,0 +1,127 @@
+---
+category: 展示
+---
+
+# Collapse 折叠面板
+
+### 介绍
+
+将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。
+
+### 引入
+
+```jsx
+import { Collapse } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+```jsx
+import { Collapse, CollapseItem } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const [state, setState] = React.useState({
+    active1: [0],
+    active2: 0,
+    active3: [],
+    active4: [],
+    title1: '标题1',
+    title2: '标题2',
+    title3: '标题3',
+    content1: '代码是写出来给人看的，附带能在机器上运行',
+    content2: '代码是写出来给人看的，附带能在机器上运行',
+    content3: '代码是写出来给人看的，附带能在机器上运行',
+  });
+
+  const onChange = event => {
+    const { key } = event.currentTarget.dataset;
+    setState(v => ({
+      ...v,
+      [key]: event.detail,
+    }));
+  };
+
+  return (
+    <Collapse value={state.active1} data-key="active1" onChange={onChange}>
+      <CollapseItem title={state.title1}>{state.content1}</CollapseItem>
+      <CollapseItem title={state.title2}>{state.content2}</CollapseItem>
+      <CollapseItem title={state.title3} disabled>
+        {state.content3}
+      </CollapseItem>
+    </Collapse>
+  );
+}
+```
+
+## API
+
+### Collapse Props
+
+| 参数      | 说明                | 类型                                                                   | 默认值  |
+| --------- | ------------------- | ---------------------------------------------------------------------- | ------- |
+| accordion | 是否开启手风琴模式 | _boolean_ | `false` |
+| border | 是否显示外边框 | _boolean_ | `true` |
+| value | 当前展开面板的 name | 非手风琴模式：_(string \| number)[]_<br>手风琴模式：_string \| number_ | - |
+
+### Collapse Event
+
+| 事件名 | 说明           | 参数                            |
+| ------ | -------------- | ------------------------------- |
+| change | 切换面板时触发 | activeNames: _string \| Array_ |
+| close | 关闭面板时触发 | currentName: _string \| number_ |
+| open | 展开面板时触发 | currentName: _string \| number_ |
+
+### CollapseItem Props
+
+| 参数      | 说明                                                       | 类型               | 默认值  |
+| --------- | ---------------------------------------------------------- | ------------------ | ------- |
+| border | 是否显示内边框 | _boolean_ | `true` |
+| clickable | 是否开启点击反馈 | _boolean_ | `false` |
+| disabled | 是否禁用面板 | _boolean_ | `false` |
+| icon | 标题栏左侧图标svg值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon) | _string_ | - |
+| isLink | 是否展示标题栏右侧箭头并开启点击反馈 | _boolean_ | `true` |
+| label | 标题栏描述信息 | _string_ | - |
+| name | 唯一标识符，默认为索引值 | _string \| number_ | `index` |
+| size | 标题栏大小，可选值为`large` | _string_ | - |
+| title | 标题栏左侧内容 | _string \| number_ | - |
+| value | 标题栏右侧内容 | _string \| number_ | - |
+
+### CollapseItem Slot
+
+| 名称       | 说明                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| -          | 面板内容                                                                 |
+| icon | 自定义`icon` |
+| rightIcon | 自定义右侧按钮，默认是`arrow`, 需要将 `is-link` 设置为 `false`, 才会生效 |
+| title | 自定义`title` |
+| value | 自定义显示内容 |
+
+### Collapse 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| customClass | 根节点样式类 |
+
+### CollapseItem 外部样式类
+
+| 类名          | 说明         |
+| ------------- | ------------ |
+| contentClass | 内容样式类 |
+| customClass | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                                          | 默认值                                       | 描述                                       |
+| --------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
+| --collapse-item-transition-duration           | _0.3s_                                       | 折叠项过渡持续时间                         |
+| --collapse-item-content-padding               | _15px_                                       | 折叠项内容内边距                           |
+| --collapse-item-content-font-size             | _13px_                                       | 折叠项内容字体大小                         |
+| --collapse-item-content-line-height           | _1.5_                                        | 折叠项内容行高                             |
+| --collapse-item-content-text-color            | _#969799_                                    | 折叠项内容文本颜色                         |
+| --collapse-item-content-background-color      | _var(--app-B6, #fff)_                        | 折叠项内容背景颜色                         |
+| --collapse-item-title-disabled-color          | _#c8c9cc_                                    | 折叠项标题禁用状态颜色                     |

package/es/config-provider/README.md

@@ -0,0 +1,150 @@
+---
+category: 通用
+---
+
+# ConfigProvider 全局配置
+
+## 介绍
+
+用于配置 Smart UI 组件的主题样式。
+* [ConfigProvider 组件最佳实践](https://github.com/Tuya-Community/miniapp-smart-ui/wiki/ConfigProvider-%E7%BB%84%E4%BB%B6%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5)
+
+### 引入
+
+```jsx
+import { ConfigProvider } from '@ray-js/smart-ui';
+```
+
+### 定制主题
+
+```!info
+Smart UI 组件通过丰富的 [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties) 来组织样式，通过覆盖这些 CSS 变量，可以实现**定制主题、动态切换主题**等效果。
+```
+
+
+## 示例
+
+以 Button 组件为例，查看组件的样式，可以看到 `.smart-button--primary` 类名上存在以下变量：
+
+```css
+.smart-button--primary {
+  color: var(--button-primary-color, #fff);
+  background: var(--button-primary-background-color, #07c160);
+  border: var(--button-border-width, 1px) solid var(
+      --button-primary-border-color,
+      #07c160
+    );
+}
+```
+
+
+### 自定义 CSS 变量
+
+#### 通过 CSS 覆盖
+
+你可以直接在app.less中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：
+
+```css
+/* 添加这段样式后，Primary Button 会变成红色 */
+page {
+  --button-primary-background-color: red;
+}
+```
+或者在index.module.less内局部的覆盖
+
+```css
+.custom-box {
+  --button-primary-background-color: red;
+}
+
+```
+
+#### 通过 ConfigProvider 覆盖
+
+只需要将希望修改的组件的CSS变量写成驼峰形式即可，组件有全量的CSS 变量类型提示。
+
+```jsx
+import { ConfigProvider, Button } from '@ray-js/smart-ui';
+import React, { useState } from 'react';
+import { View } from '@ray-js/ray';
+
+export default function Demo() {
+  const [color, setColor] = useState('#07c160');
+
+  return (
+    <>
+      <View style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '24px' }}>
+        <Button type="primary" color="red" onClick={() => setColor('red')}>
+          设置颜色
+        </Button>
+        <Button type="primary" color="green" onClick={() => setColor('green')}>
+          设置颜色
+        </Button>
+        <Button type="primary" color="blue" onClick={() => setColor('blue')}>
+          设置颜色
+        </Button>
+      </View>
+      <ConfigProvider
+        themeVars={{
+          buttonPrimaryBorderColor: color,
+          buttonPrimaryBackgroundColor: color,
+        }}
+      >
+        <Button type="primary">主要按钮</Button>
+      </ConfigProvider>
+    </>
+  );
+}
+```
+
+
+### 主题切换 `v2.8.0`
+
+`ConfigProvider` 组件支持通过 `theme` 属性来切换明暗主题，可选值为 `light` 和 `dark`。
+
+```jsx
+import { ConfigProvider, Cell, CellGroup } from '@ray-js/smart-ui';
+import React, { useState } from 'react';
+import { View, Text } from '@ray-js/ray';
+import { Button } from '@ray-js/smart-ui';
+
+export default function Demo() {
+  const [currentTheme, setCurrentTheme] = useState<'light' | 'dark'>('light');
+
+  return (
+    <>
+      <View
+        style={{
+          display: 'flex',
+          justifyContent: 'space-between',
+          marginBottom: '24px',
+          alignItems: 'center',
+        }}
+      >
+        <Button type="primary" onClick={() => setCurrentTheme('light')}>
+          浅色主题
+        </Button>
+        <Text>当前主题: {currentTheme}</Text>
+        <Button type="primary" onClick={() => setCurrentTheme('dark')}>
+          深色主题
+        </Button>
+      </View>
+      <ConfigProvider theme={currentTheme}>
+        <CellGroup>
+          <Cell title="标题" value="内容" />
+          <Cell title="标题" value="内容" label="详细介绍" isLink />
+        </CellGroup>
+      </ConfigProvider>
+    </>
+  );
+}
+```
+
+## API
+
+### Props
+
+| 参数       | 说明           | 类型     | 默认值 |
+| ---------- | -------------- | -------- | ------ |
+| themeVars | 自定义主题变量 | _object_ | - |
+| theme `v2.8.0` | 主题模式 | _'light'\/'dark'_ | - |

package/es/count-down/README.md

@@ -0,0 +1,201 @@
+---
+category: 反馈
+---
+
+# CountDown 倒计时
+
+### 介绍
+
+用于实时展示倒计时数值，支持毫秒精度。
+
+### 引入
+
+```jsx
+import { CountDown } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+`time`属性表示倒计时总时长，单位为毫秒。
+
+```jsx
+import { CountDown } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <CountDown time={30 * 60 * 60 * 1000} />;
+}
+```
+
+### 自定义格式
+
+通过`format`属性设置倒计时文本的内容。
+
+```jsx
+import { CountDown } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <CountDown time={30 * 60 * 60 * 1000} format="DD 天 HH 时 mm 分 ss 秒" />;
+}
+```
+
+### 毫秒级渲染
+
+通过`millisecond`属性开启毫米级渲染
+
+```jsx
+import { CountDown } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return <CountDown millisecond time={30 * 60 * 60 * 1000} format="HH:mm:ss:SSS" />;
+}
+```
+
+### 自定义样式
+
+设置`useSlot`属性后可以自定义倒计时样式，需要通过`onChange`事件获取`timeData`对象并自行渲染，格式见下方表格。
+
+```jsx
+import { CountDown } from '@ray-js/smart-ui';
+import { View, Text } from '@ray-js/ray';
+import React, { useState, useCallback } from 'react';
+
+const style = {
+  display: 'inline-block',
+  width: '22px',
+  marginRight: '5px',
+  color: '#fff',
+  fontSize: '12px',
+  textAlign: 'center',
+  backgroundColor: '#1989fa',
+  borderRadius: '2px'
+} as React.CSSProperties
+
+export default function Demo() {
+  const [timeData, setTimeData] = useState<any>({});
+
+  const handleChange = useCallback(e => {
+    setTimeData(e.detail);
+  }, []);
+  return (
+    <CountDown useSlot time={30 * 60 * 60 * 1000} onChange={handleChange}>
+      <View>
+        <Text style={style}>{timeData.hours}</Text>
+        <Text style={style}>{timeData.minutes}</Text>
+        <Text style={style}>{timeData.seconds}</Text>
+      </View>
+    </CountDown>
+  );
+}
+```
+
+### 手动控制
+
+通过 `selectComponent` 选择器获取到组件实例后，可以调用`start`、`pause`、`reset`方法。
+
+```jsx
+import { CountDown, Grid, GridItem } from '@ray-js/smart-ui';
+import { showToast, getCurrentPages } from '@ray-js/ray';
+import React, { useCallback } from 'react';
+import PlayIcon from '@tuya-miniapp/icons/dist/svg/Play';
+import PauseIcon from '@tuya-miniapp/icons/dist/svg/Pause';
+import RepeatIcon from '@tuya-miniapp/icons/dist/svg/Repeat';
+
+export default function Demo() {
+  const finished = useCallback(() => {
+    showToast({
+      title: '倒计时结束',
+    });
+  }, []);
+  const start = useCallback(() => {
+    const pages = getCurrentPages();
+    const pageInstall = pages[pages.length - 1];
+    const countdown = pageInstall.selectComponent('.control-count-down');
+    countdown.start();
+  }, []);
+
+  const pause = useCallback(() => {
+    const pages = getCurrentPages();
+    const pageInstall = pages[pages.length - 1];
+    const countdown = pageInstall.selectComponent('.control-count-down');
+    countdown.pause();
+  }, []);
+
+  const reset = useCallback(() => {
+    const pages = getCurrentPages();
+    const pageInstall = pages[pages.length - 1];
+    const countdown = pageInstall.selectComponent('.control-count-down');
+    countdown.reset();
+  }, []);
+  return (
+    <>
+      <CountDown
+        className="control-count-down"
+        millisecond
+        time={3000}
+        autoStart={false}
+        format="ss:SSS"
+        onFinish={finished}
+      />
+      <Grid clickable column-num="3">
+        <GridItem text="开始" icon={PlayIcon} onClick={start} />
+        <GridItem text="暂停" icon={PauseIcon} onClick={pause} />
+        <GridItem text="重置" icon={RepeatIcon} onClick={reset} />
+      </Grid>
+    </>
+  );
+}
+```
+
+## API
+
+### Props
+
+| 参数        | 说明                                           | 类型      | 默认值     |
+| ----------- | ---------------------------------------------- | --------- | ---------- |
+| autoStart | 是否自动开始倒计时 | _boolean_ | `true` |
+| format | 时间格式，DD-日，HH-时，mm-分，ss-秒，SSS-毫秒 | _string_ | `HH:mm:ss` |
+| millisecond | 是否开启毫秒级渲染 | _boolean_ | `false` |
+| time | 倒计时时长，单位毫秒 | _number_ | - |
+| useSlot | 是否使用自定义样式插槽 | _boolean_ | `false` |
+
+### Events
+
+| 事件名      | 说明                                         | 回调参数 |
+| ----------- | -------------------------------------------- | -------- |
+| onChange | 时间变化时触发，仅在开启`use-slot`后才会触发 | timeData |
+| onFinish | 倒计时结束时触发 | - |
+
+### timeData 格式
+
+| 名称         | 说明     | 类型     |
+| ------------ | -------- | -------- |
+| days | 剩余天数 | _number_ |
+| hours | 剩余小时 | _number_ |
+| milliseconds | 剩余毫秒 | _number_ |
+| minutes | 剩余分钟 | _number_ |
+| seconds | 剩余秒数 | _number_ |
+
+### 方法
+
+通过 [selectComponent](/material/smartui?comId=faq) 可以获取到 CountDown 实例并调用实例方法。
+
+| 方法名 | 参数 | 返回值 | 介绍                                                       |
+| ------ | ---- | ------ | ---------------------------------------------------------- |
+| pause | - | - | 暂停倒计时 |
+| reset | - | - | 重设倒计时，若`auto-start`为`true`，重设后会自动开始倒计时 |
+| start | - | - | 开始倒计时 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --count-down-text-color | _var(--app-B6-N2, rgba(0, 0, 0, 0.7))_ | 文本颜色 |
+| --count-down-font-size | _14px_ | 字体大小 |
+| --count-down-line-height | _20px_ | 行高 |