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

package/lib/grid/README.md

@@ -0,0 +1,273 @@
+---
+category: 布局
+---
+
+# Grid 宫格
+
+### 介绍
+
+宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。
+
+### 引入
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`icon`属性设置格子内的图标，`text`属性设置文字内容。
+
+```jsx
+import React from 'react';
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+
+export default function Demo() {
+  const array = [0, 1, 2, 3];
+  return (
+    <Grid>
+      {array.map((item, index) => (
+        <GridItem icon={IconBubble} text="文字" key={`${index + 1}`} />
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 自定义列数
+
+默认一行展示四个格子，可以通过`columnNum`自定义列数。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import React from 'react';
+
+export default function Demo() {
+  const array = [0, 1, 2, 3, 4, 5];
+  return (
+    <Grid columnNum={2}>
+      {array.map((item, index) => (
+        <GridItem icon={IconBubble} text="文字" key={`${index + 1}`} />
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 自定义内容
+
+通过插槽可以自定义格子展示的内容。
+
+```jsx
+import { Grid, GridItem, Image } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import React from 'react';
+
+export default function Demo() {
+  const array = [0, 1, 2];
+  return (
+    <Grid columnNum={3} border={false}>
+      {array.map((item, index) => (
+        <GridItem useSlot icon={IconBubble} text="文字" key={`${index + 1}`}>
+          <Image
+            width="90px"
+            height="90px"
+            fit="contain"
+            src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+          />
+        </GridItem>
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 正方形格子
+
+设置`square`属性后，格子的高度会和宽度保持一致。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import React from 'react';
+
+export default function Demo() {
+  const array = [0, 1, 2, 3, 4, 5, 6, 7];
+  return (
+    <Grid square>
+      {array.map((item, index) => (
+        <GridItem icon={IconBubble} text="文字" key={`${index + 1}`} />
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 格子间距
+
+通过`gutter`属性设置格子之间的距离。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import React from 'react';
+
+export default function Demo() {
+  const array = [0, 1, 2, 3, 4, 5, 6, 7];
+  return (
+    <Grid gutter="10px">
+      {array.map((item, index) => (
+        <GridItem icon={IconBubble} text="文字" key={`${index + 1}`} />
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 内容横排
+
+将`direction`属性设置为`horizontal`，可以让宫格的内容呈横向排列。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import React from 'react';
+
+export default function Demo() {
+  const array = [0, 1, 2];
+  return (
+    <Grid direction="horizontal" columnNum={3}>
+      {array.map((item, index) => (
+        <GridItem icon={IconBubble} text="文字" key={`${index + 1}`} />
+      ))}
+    </Grid>
+  );
+}
+```
+
+### 页面跳转
+
+可以通过`url`属性进行页面跳转，通过`linkType`属性控制跳转类型。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import IconHandPoint from '@tuya-miniapp/icons/dist/svg/HandPoint';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Grid direction="horizontal" columnNum="2">
+      <GridItem
+        icon={IconBubble}
+        text="Navigate 跳转"
+        linkType="navigateTo"
+        url="/pages/home/index"
+      />
+      <GridItem
+        icon={IconHandPoint}
+        linkType="reLaunch"
+        url="/pages/home/index"
+        text="ReLaunch 跳转"
+      />
+    </Grid>
+  );
+}
+```
+
+### 徽标提示
+
+设置`dot`属性后，会在图标右上角展示一个小红点。设置`badge`属性后，会在图标右上角展示相应的徽标。
+
+```jsx
+import { Grid, GridItem } from '@ray-js/smart-ui';
+import IconBubble from '@tuya-miniapp/icons/dist/svg/Bubble';
+import IconHandPoint from '@tuya-miniapp/icons/dist/svg/HandPoint';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Grid columnNum="2">
+      <GridItem icon={IconBubble} text="文字" dot />
+      <GridItem icon={IconHandPoint} text="文字" badge="99+" />
+    </Grid>
+  );
+}
+```
+
+## API
+
+### Grid Props
+
+| 参数               | 说明                                      | 类型               | 默认值     |
+| ------------------ | ----------------------------------------- | ------------------ | ---------- |
+| border | 是否显示边框 | _boolean_ | `true` |
+| center | 是否将格子内容居中显示 | _boolean_ | `true` |
+| clickable | 是否开启格子点击反馈 | _boolean_ | `false` |
+| columnNum | 列数 | _number_ | `4` |
+| direction | 格子内容排列的方向，可选值为 `horizontal` | _string_ | `vertical` |
+| gutter | 格子之间的间距，默认单位为`px` | _string \| number_ | `0` |
+| iconSize `v1.3.2` | 图标大小，默认单位为`px` | _string_ | `28px` |
+| reverse `v1.7.0` | 是否调换图标和文本的位置 | _boolean_ | `false` |
+| square | 是否将格子固定为正方形 | _boolean_ | `false` |
+| useSlot | 是否使用自定义内容的插槽 | _boolean_ | `false` |
+
+### Grid 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| customClass | 根节点样式类 |
+
+### GridItem Props
+
+| 参数                 | 说明                                                                                                                                       | 类型               | 默认值       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------ |
+| ariaLabel `v2.13.0` | 无障碍读屏文案，设置在根节点的 `aria-label` 上 | _string_ | - |
+| badge | 图标右上角徽标的内容 | _string \| number_ | - |
+| dot | 是否显示图标右上角小红点 | _boolean_ | `false` |
+| icon | 图标 svg 值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon) | _string_ | - |
+| iconColor | 图标颜色 | _string_ | - |
+| iconPrefix `v1.7.0` | 第三方图标前缀 | _string_ | `smart-icon` |
+| linkType | 链接跳转类型，可选值为 `redirectTo` [`switchTab`](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.switchTab.html) `reLaunch` | _string_ | `navigateTo` |
+| text | 文字 | _string_ | - |
+| url | 点击后跳转的链接地址 | _string_ | - |
+
+### GridItem Events
+
+| 事件名     | 说明           | 回调参数 |
+| ---------- | -------------- | -------- |
+| onClick | 点击格子时触发 | - |
+
+### GridItem Slots
+
+| 名称 | 说明                                                   |
+| ---- | ------------------------------------------------------ |
+| -    | 自定义宫格的所有内容，需要设置`use-slot`属性           |
+| icon | 自定义图标，如果设置了`use-slot`或者`icon`属性则不生效 |
+| text | 自定义文字，如果设置了`use-slot`或者`text`属性则不生效 |
+
+### GridItem 外部样式类
+
+| 类名          | 说明         |
+| ------------- | ------------ |
+| contentClass | 内容样式类 |
+| customClass | 根节点样式类 |
+| iconClass | 图标样式类 |
+| textClass | 文本样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                                 | 默认值                                 | 描述         |
+| ------------------------------------ | -------------------------------------- | ------------ |
+| --grid-item-content-padding          | _@padding-md @padding-xs_              | 内容内边距   |
+| --grid-item-content-background-color | _var(--app-B3, #ffffff)_               | 背景颜色     |
+| --grid-item-content-active-color     | _#f2f3f5_                              | 激活时颜色   |
+| --grid-item-icon-size                | _26px_                                 | 图标大小     |
+| --grid-item-text-color               | _var(--app-B6-N2, rgba(0, 0, 0, 0.7))_ | 文本颜色     |
+| --grid-item-text-font-size           | _12px_                                 | 文本字体大小 |

package/lib/icon/README.md

@@ -0,0 +1,178 @@
+---
+category: 展示
+assets: Svg
+---
+
+# Icon 图标
+
+### 介绍
+
+基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过 icon 属性引用。
+
+### 引入
+
+```jsx
+import { Icon } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+
+`Icon`的`name`属性支持传入图标名称或图片链接。
+
+```jsx
+import WarningIcon from '@tuya-miniapp/icons/dist/svg/Warning';
+import { View } from '@ray-js/ray';
+import { Icon } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <View>
+      <Icon name={WarningIcon} />
+      <Icon name="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png" />
+    </View>
+  );
+}
+```
+
+### 提示信息
+
+设置`dot`属性后，会在图标右上角展示一个小红点。设置`info`属性后，会在图标右上角展示相应的徽标。
+
+```jsx
+import WarningIcon from '@tuya-miniapp/icons/dist/svg/Warning';
+import { View } from '@ray-js/ray';
+import { Icon } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <View style={{padding: 48}}>
+      <Icon name={WarningIcon} dot />
+      <Icon name={WarningIcon} info="9" />
+      <Icon name={WarningIcon} info="99+" />
+    </View>
+  );
+}
+```
+
+### 图标颜色
+
+设置`color`属性来控制图标颜色。
+
+```jsx
+import AlarmIcon from '@tuya-miniapp/icons/dist/svg/Alarm';
+import WarningIcon from '@tuya-miniapp/icons/dist/svg/Warning';
+import { Icon } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <>
+      <Icon name={AlarmIcon} size="36px" color="#1989fa" />
+      <Icon name={WarningIcon} size="36px" color="#07c160" />
+    </>
+  );
+}
+```
+
+### 图标大小
+
+设置`size`属性来控制图标大小。
+
+```jsx
+import WarningIcon from '@tuya-miniapp/icons/dist/svg/Warning';
+import { Icon } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <>
+      <Icon name={WarningIcon} size="36"/>
+      <Icon name={WarningIcon} size="48"/>
+    </>
+  );
+}
+```
+
+
+### Svg Path `v2.3.3`
+
+组件现在也支持传入path的方式渲染
+
+```jsx
+import { Icon } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  const svgPath = 'M192 448C192 624.736 335.264 768 512 768s320-143.264 320-320a319.872 319.872 0 0 0-160-277.184V160a64 64 0 0 0-64-64h-192a64 64 0 0 0-64 64v10.816A319.872 319.872 0 0 0 192 448z m224-384h192a32 32 0 0 0 0-64h-192a32 32 0 0 0 0 64z';
+  return (
+    <Icon name={svgPath} size="42" color="#1989fa" />
+  );
+}
+```
+
+### 自定义图标
+
+如果需要在现有 Icon 的基础上使用更多图标，可以引入第三方 iconfont 对应的字体文件和 CSS 文件，之后就可以在 Icon 组件中直接使用。例如，可以在 `app.wxss` 文件中引入。
+
+```css
+/* 引入第三方或自定义的字体图标样式 */
+@font-face {
+  font-family: 'my-icon';
+  src: url('./my-icon.ttf') format('truetype');
+}
+
+.my-icon {
+  font-family: 'my-icon';
+}
+
+.my-icon-extra::before {
+  content: '\e626';
+}
+```
+
+```jsx
+// 通过 class-prefix 指定类名为 my-icon
+<Icon class-prefix="my-icon" name="extra" />
+```
+
+## API
+
+### Props
+
+| 参数         | 说明                                       | 类型               | 默认值       |
+| ------------ | ------------------------------------------ | ------------------ | ------------ |
+| ariaLabel `v2.13.0` | 无障碍读屏文案；非空时根节点 `aria-role` 为 `button` | _string_ | - |
+| ariaRole `v2.13.0` | 无障碍 `aria-role` | _string_ | - |
+| classPrefix | 类名前缀 | _string_ | `smart-icon` |
+| color | 图标颜色 | _string_ | `inherit` |
+| customStyle | 自定义样式 | _React.CSSProperties_ | - |
+| dot | 是否显示图标右上角小红点 | _boolean_ | `false` |
+| info | 图标右上角文字提示 | _string \| number_ | - |
+| name | 图标名称或 Svg URL 或图片链接 | _string_ | - |
+| size | 图标大小，如 `20px`，`2em`，默认单位为`px` | _string \| number_ | `inherit` |
+
+### Events
+
+| 事件名     | 说明           | 参数 |
+| ---------- | -------------- | ---- |
+| onClick | 点击图标时触发 | - |
+
+### 外部样式类
+
+| 类名         | 说明                 |
+| ------------ | -------------------- |
+| customClass | 根节点样式类 |
+| infoClass | 图标右上角文字样式类 |
+
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --icon-color | _var(--app-B4-N2, rgba(0, 0, 0, 0.7))_ | 图标颜色 |

package/lib/image/README.md

@@ -0,0 +1,225 @@
+---
+category: 展示
+---
+
+# Image 图片
+
+### 介绍
+
+图片
+
+### 引入
+
+```jsx
+import { Image } from '@ray-js/smart-ui';
+```
+
+## 代码演示
+
+### 基础用法
+基础用法与原生 [image](<(https://developers.weixin.qq.com/miniprogram/dev/component/image.html)>) 标签一致，可以设置`src`、`width`、`height`等原生属性。
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image width="100px" height="100px" src="https://images.tuyacn.com/rms-static/f350c8a0-0eb2-11ef-8f06-49ae7b2fadcf-1715334722090.jpeg?tyName=cat.jpeg" />
+  );
+}
+```
+
+### 填充模式
+
+通过`fit`属性可以设置图片填充模式，可选值见下方表格。
+
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      width="100px" 
+      height="100px"
+      fit="contain"
+      src="https://images.tuyacn.com/rms-static/f350c8a0-0eb2-11ef-8f06-49ae7b2fadcf-1715334722090.jpeg?tyName=cat.jpeg" />
+  );
+}
+```
+
+### 圆形图片
+
+通过`round`属性可以设置图片变圆，注意当图片宽高不相等且`fit`为`contain`或`scale-down`时，将无法填充一个完整的圆形。
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      width="100px" 
+      height="100px"
+      round
+      src="https://images.tuyacn.com/rms-static/f350c8a0-0eb2-11ef-8f06-49ae7b2fadcf-1715334722090.jpeg?tyName=cat.jpeg" />
+  );
+}
+```
+
+### 图片懒加载
+
+图片懒加载，在即将进入一定范围（上下三屏）时才开始加载。
+
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      width="100px" 
+      height="100px"
+      lazyLoad
+      src="https://images.tuyacn.com/rms-static/f350c8a0-0eb2-11ef-8f06-49ae7b2fadcf-1715334722090.jpeg?tyName=cat.jpeg" />
+  );
+}
+```
+
+
+### 加载中提示
+
+`Image`组件提供了默认的加载中提示，支持通过`loading`插槽自定义内容。
+
+```jsx
+import { Image, Loading } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      width="100px"
+      height="100px"
+      showLoading
+      useLoadingSlot 
+      slot={{
+        loading: <Loading type="spinner" size="20" vertical />
+      }} 
+    />
+  );
+}
+```
+
+### 加载失败提示
+
+`Image`组件提供了默认的加载失败提示，支持通过`error`插槽自定义内容。
+
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import { Text } from '@ray-js/ray'
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      width="100px"
+      height="100px"
+      useErrorSlot
+      src="error-test"
+      slot={{
+        error: <Text>加载失败</Text>
+      }} 
+    />
+  );
+}
+```
+
+
+### 修改图片颜色 `v2.3.3`
+
+`tintColor`属性可以直接修改图片的颜色，类似RN的tintColor属性，原理是通过css mask实现的，所以使用之前要做好用户兼容性调查哦。
+
+```jsx
+import { Image } from '@ray-js/smart-ui';
+import React from 'react';
+
+export default function Demo() {
+  return (
+    <Image 
+      src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png" 
+      width="100px" 
+      height="100px"
+      tintColor="rgba(255, 255, 25, 0.8)"
+    />
+  );
+}
+```
+
+## API
+
+### Props
+
+| 参数                   | 说明                                 | 类型               | 默认值  |
+| ---------------------- | ------------------------------------ | ------------------ | ------- |
+| alt | 替代文本 | _string_ | - |
+| fit | 图片填充模式 | _string_ | _fill_ |
+| height | 高度，默认单位为`px` | _string \| number_ | - |
+| lazyLoad | 是否懒加载 | _boolean_ | `false` |
+| radius | 圆角大小，默认单位为`px` | _string \| number_ | `0` |
+| round | 是否显示为圆形 | _boolean_ | `false` |
+| showError | 是否展示图片加载失败提示 | _boolean_ | `true` |
+| showLoading | 是否展示图片加载中提示 | _boolean_ | `true` `v2.0.0` `false` `v2.7.0` |
+| showMenuByLongpress | 是否开启长按图片显示识别小程序码菜单 | _boolean_ | `false` |
+| src | 图片链接 | _string_ | - |
+| useErrorSlot | 是否使用 error 插槽 | _boolean_ | `false` |
+| useLoadingSlot | 是否使用 loading 插槽 | _boolean_ | `false` |
+| webp `v1.10.11` | 是否解析 webp 格式 | _boolean_ | `false` |
+| width | 宽度，默认单位为`px` | _string \| number_ | - |
+| tintColor `v2.3.3` | 修改图片颜色，类似RN的tintColor，采用css mask实现 | _string_ | - |
+
+### 图片填充模式
+
+| 名称      | 含义                                                   |
+| --------- | ------------------------------------------------------ |
+| contain | 保持宽高缩放图片，使图片的长边能完全显示出来 |
+| cover | 保持宽高缩放图片，使图片的短边能完全显示出来，裁剪长边 |
+| fill | 拉伸图片，使图片填满元素 |
+| heightFix | 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变 |
+| none | 保持图片原有尺寸 |
+| widthFix | 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变 |
+
+### Events
+
+| 事件名     | 说明               | 回调参数     |
+| ---------- | ------------------ | ------------ |
+| onClick | 点击图片时触发 | event: Event |
+| onError | 图片加载失败时触发 | event: Event |
+| onLoad | 图片加载完毕时触发 | event: Event |
+
+### Slots
+
+| 名称    | 说明                       |
+| ------- | -------------------------- |
+| error | 自定义加载失败时的提示内容 |
+| loading | 自定义加载中的提示内容 |
+
+### 外部样式类
+
+| 类名          | 说明           |
+| ------------- | -------------- |
+| customClass | 根节点样式类 |
+| errorClass | error 样式类 |
+| imageClass | 图片样式类 |
+| loadingClass | loading 样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --image-placeholder-text-color    | _#969799_       | 加载描述文字    |
+| --image-placeholder-font-size    | _14px_       | 加载文字字体    |
+| --image-placeholder-background-color    | _#f7f8fa_       | 加载遮照背景色    |
+| --image-loading-icon-size    | _32px_       | 加载图标体积    |
+| --image-loading-icon-color    | _#dcdee0_       | 加载图标颜色    |
+| --image-error-size `v2.0.0`   | _32px_       | 图片加载错误时默认图片    |