@tuya-miniapp/smart-ui 2.13.2-beta-0 → 2.13.2-beta-2

package/dist/popup/README.md

@@ -0,0 +1,162 @@
+---
+category: 反馈
+---
+
+# Popup 弹出层
+
+### 介绍
+
+弹出层容器，用于展示弹窗、信息提示等内容，支持多个弹出层叠加展示。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-popup": "@tuya-miniapp/smart-ui/lib/popup/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`show`属性控制弹出层是否展示。
+
+```html
+<smart-cell title="展示弹出层" is-link bind:click="showPopup" />
+
+<smart-popup show="{{ show }}" bind:close="onClose">内容</smart-popup>
+```
+
+```javascript
+Page({
+  data: {
+    show: false,
+  },
+
+  showPopup() {
+    this.setData({ show: true });
+  },
+
+  onClose() {
+    this.setData({ show: false });
+  },
+});
+```
+
+### 弹出位置
+
+通过`position`属性设置弹出位置，默认居中弹出，可以设置为`top`、`bottom`、`left`、`right`。
+
+```html
+<smart-popup show="{{ show }}" position="top" custom-style="height: 20%;" bind:close="onClose" />
+```
+
+### 关闭图标
+
+设置`closeable`属性后，会在弹出层的右上角显示关闭图标，并且可以通过`close-icon`属性自定义图标，使用`close-icon-position`属性可以自定义图标位置。
+
+```html
+<smart-popup
+  show="{{ show }}"
+  closeable
+  position="bottom"
+  custom-style="height: 20%"
+  bind:close="onClose"
+/>
+
+<!-- 自定义图标 -->
+<smart-popup
+  show="{{ show }}"
+  closeable
+  close-icon="close"
+  position="bottom"
+  custom-style="height: 20%"
+  bind:close="onClose"
+/>
+
+<!-- 图标位置 -->
+<smart-popup
+  show="{{ show }}"
+  closeable
+  close-icon-position="top-left"
+  position="bottom"
+  custom-style="height: 20%"
+  bind:close="onClose"
+/>
+```
+
+### 圆角弹窗
+
+设置`round`属性后，弹窗会根据弹出位置添加不同的圆角样式。
+
+```html
+<smart-popup
+  show="{{ show }}"
+  round
+  position="bottom"
+  custom-style="height: 20%"
+  bind:close="onClose"
+/>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| close-icon | 关闭图标名称或图片链接 | _string_ | `cross` |
+| close-icon-aria-label `v2.13.0` | 关闭按钮的无障碍读屏文案，透传至内部 `smart-icon` 的 `aria-label` | _string_ | - |
+| close-icon-position | 关闭图标位置，可选值为 `top-left`<br>`bottom-left` `bottom-right` | _string_ | `top-right` |
+| close-on-click-overlay | 是否在点击遮罩层后关闭 | _boolean_ | `true` |
+| closeable | 是否显示关闭图标 | _boolean_ | `false` |
+| custom-style | 自定义弹出层样式 | _string_ | `''` |
+| duration | 动画时长，单位为毫秒 | _number \| object_ | `300` |
+| lock-scroll | 是否锁定背景滚动 | _boolean_ | `true` |
+| overlay | 是否显示遮罩层 | _boolean_ | `true` |
+| overlay-style | 自定义遮罩层样式 | _string_ | `''` |
+| position | 弹出位置，可选值为 `top` `bottom` `right` `left` | _string_ | `center` |
+| round | 是否显示圆角 | _boolean_ | `false` |
+| safe-area-inset-bottom | 是否留出底部安全距离，v2.7.1 开始默认关闭 | _boolean_ | `false` |
+| safe-area-inset-bottom-min `v1.1.0` | 是否需要预留出一个最小的底部安全距离，用于在 safeArea 底部为 0 时进行追加，需要在 safeAreaInsetBottom 为 true 时生效 | _number_ | `0` |
+| safe-area-inset-top | 是否留出顶部安全距离（状态栏高度） | _boolean_ | `false` |
+| safe-area-tab-bar | 是否留出底部 tabbar 安全距离（在使用 tabbar 组件 & 小程序自定义 tabbar 时，popup 组件层级无法盖住 tabbar） | _boolean_ | `false` |
+| show | 是否显示弹出层 | _boolean_ | `false` |
+| z-index | z-index 层级 | _number_ | `100` |
+| native-disabled `v2.3.8` | 开启弹框期间是否禁用本地手势; 会在弹框开始进入动画时调用 `ty.nativeDisabled(true)`, 在弹框关闭动画结束时调用 `ty.nativeDisabled(false)` 恢复异层组件的点击能力；由于`ty.nativeDisabled` 是全局生效的，所以多个弹框组件同时打开时注意是否传 `native-disabled`属性和关闭的时机，防止 `native-disabled` 属性失效 | _boolean_ | `false` |
+| full-cover-view `v2.11.1` | 是否使用 cover-view 包裹弹层，用于覆盖原生组件（如 map、video）时使用 | _boolean_ | `false` |
+
+### Events
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| bind:after-enter | 进入后触发 | - |
+| bind:after-leave | 离开后触发 | - |
+| bind:before-enter | 进入前触发 | - |
+| bind:before-leave | 离开前触发 | - |
+| bind:click-overlay | 点击遮罩层时触发 | - |
+| bind:close | 关闭弹出层时触发 | - |
+| bind:enter | 进入中触发 | - |
+| bind:leave | 离开中触发 | - |
+
+### 外部样式类
+
+| 类名 | 说明 |
+| --- | --- |
+| custom-class | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称 | 默认值 | 描述 |
+| --- | --- | --- |
+| --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_ | 关闭图标层级 |

package/dist/progress/README.md

@@ -0,0 +1,99 @@
+<!-- ---
+category: 展示
+--- -->
+
+# Progress 进度条
+
+### 介绍
+
+用于展示操作的当前进度。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-progress": "@tuya-miniapp/smart-ui/lib/progress/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+进度条默认为蓝色，使用`percentage`属性来设置当前进度。
+
+```html
+<smart-progress percentage="50" />
+```
+
+### 线条粗细
+
+通过`stroke-width`可以设置进度条的粗细。
+
+```html
+<smart-progress :percentage="50" stroke-width="8" />
+```
+
+### 置灰
+
+设置`inactive`属性后进度条将置灰。
+
+```html
+<smart-progress inactive percentage="50" />
+```
+
+### 样式定制
+
+可以使用`pivot-text`属性自定义文字，`color`属性自定义进度条颜色。
+
+```html
+<smart-progress pivot-text="橙色" color="#f2826a" percentage="25" />
+
+<smart-progress pivot-text="红色" color="#ee0a24" percentage="50" />
+
+<smart-progress
+  percentage="75"
+  pivot-text="紫色"
+  pivot-color="#7232dd"
+  color="linear-gradient(to right, #be99ff, #7232dd)"
+/>
+```
+
+## API
+
+### Props
+
+| 参数         | 说明                       | 类型               | 默认值           |
+| ------------ | -------------------------- | ------------------ | ---------------- |
+| color        | 进度条颜色                 | _string_           | `#1989fa`        |
+| inactive     | 是否置灰                   | _boolean_          | `false`          |
+| percentage   | 进度百分比                 | _number_           | `0`              |
+| pivot-color  | 文字背景色                 | _string_           | 与进度条颜色一致 |
+| pivot-text   | 文字显示                   | _string_           | 百分比文字       |
+| show-pivot   | 是否显示进度文字           | _boolean_          | `true`           |
+| stroke-width | 进度条粗细，默认单位为`px` | _string \| number_ | `4px`            |
+| text-color   | 进度文字颜色               | _string_           | `#fff`           |
+| track-color  | 轨道颜色                   | _string_           | `#e5e5e5`        |
+
+### 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| custom-class | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --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_ | - |

package/dist/radio/README.md

@@ -0,0 +1,303 @@
+---
+category: 数据录入
+---
+
+# Radio 单选框
+
+### 介绍
+
+在一组备选项中进行单选。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-radio": "@tuya-miniapp/smart-ui/lib/radio/index",
+  "smart-radio-group": "@tuya-miniapp/smart-ui/lib/radio-group/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`value`绑定值当前选中项的 name 。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1" custom-class="demo-radio-inline" />
+  <smart-radio name="2" custom-class="demo-radio-inline" />
+</smart-radio-group>
+```
+
+```css
+.demo-radio-inline {
+  margin: 10px 0 0 20px;
+  display: inline-block !important;
+}
+```
+
+```js
+Page({
+  data: {
+    radio: '1',
+  },
+
+  onChange(event) {
+    this.setData({
+      radio: event.detail,
+    });
+  },
+});
+```
+
+### 禁用状态
+
+通过`disabled`属性禁止选项切换，在`Radio`上设置`diabled`可以禁用单个选项。
+
+```html
+<smart-radio-group value="{{ radio }}" disabled bind:change="onChange">
+  <smart-radio name="1" custom-class="demo-radio-inline" />
+  <smart-radio name="2" custom-class="demo-radio-inline" />
+</smart-radio-group>
+```
+
+### 自定义形状
+
+将 `shape` 属性设置为 `square`，单选框的形状会变成方形。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1" shape="square" custom-class="demo-radio-inline" />
+  <smart-radio name="2" shape="square" custom-class="demo-radio-inline" />
+</smart-radio-group>
+```
+
+### 自定义颜色
+
+通过 `checked-color` 属性设置选中状态的图标颜色。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1" custom-class="demo-radio-inline" checked-color="#10D0D0" />
+  <smart-radio name="2" custom-class="demo-radio-inline" checked-color="#10D0D0" />
+</smart-radio-group>
+```
+
+### 自定义大小
+
+通过 `icon-size` 属性可以自定义图标的大小。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1" icon-size="28px" custom-class="demo-radio-inline" />
+  <smart-radio name="2" icon-size="28px" custom-class="demo-radio-inline" />
+</smart-radio-group>
+```
+
+### 自定义文本
+
+通过 slot 插槽子节点可以自定义文本内容。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1">Radio 单选框 1</smart-radio>
+  <smart-radio name="2">Radio 单选框 2</smart-radio>
+</smart-radio-group>
+```
+
+### 水平排列
+
+将`direction`属性设置为`horizontal`后，单选框组会变成水平排列。
+
+```html
+<smart-radio-group
+  value="{{ radio }}"
+  bind:change="onChange"
+  direction="horizontal"
+>
+  <smart-radio name="1">Radio 单选框 1</smart-radio>
+  <smart-radio name="2">Radio 单选框 2</smart-radio>
+</smart-radio-group>
+```
+
+### 自定义图标
+
+通过 `icon` 插槽自定义图标，需要设置 `use-icon-slot` 属性。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio use-icon-slot value="{{ radio }}" name="1">
+    自定义图标
+    <image slot="icon" src="{{ radio === '1' ? icon.active : icon.normal }}" />
+  </smart-radio>
+  <smart-radio use-icon-slot value="{{ radio }}" name="2">
+    自定义图标
+    <image slot="icon" src="{{ radio === '2' ? icon.active : icon.normal }}" />
+  </smart-radio>
+</smart-radio-group>
+```
+
+```js
+Page({
+  data: {
+    radio: true,
+    icon: {
+      normal: 'https://images.tuyacn.com/content-platform/hestia/1729664215ebd89f13e54.png',
+      active: 'https://images.tuyacn.com/content-platform/hestia/1730877912e76cbdb7563.png',
+    },
+  },
+  onChange(event) {
+    this.setData({
+      radio: event.detail,
+    });
+  },
+});
+```
+
+### 禁用文本点击
+
+通过设置`label-disabled`属性可以禁用单选框文本点击。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-radio name="1" label-disabled>单选框 1</smart-radio>
+  <smart-radio name="2" label-disabled>单选框 2</smart-radio>
+</smart-radio-group>
+```
+
+### 与 Cell 组件一起使用
+
+此时你需要再引入`Cell`和`CellGroup`组件。
+
+```html
+<smart-radio-group value="{{ radio }}" bind:change="onChange">
+  <smart-cell-group>
+    <smart-cell title="单选框 1" clickable data-name="1" bind:click="onClick">
+      <smart-radio slot="right-icon" name="1" />
+    </smart-cell>
+    <smart-cell title="单选框 2" clickable data-name="2" bind:click="onClick">
+      <smart-radio slot="right-icon" name="2" />
+    </smart-cell>
+  </smart-cell-group>
+</smart-radio-group>
+```
+
+```js
+Page({
+  data: {
+    radio: '1',
+  },
+
+  onChange(event) {
+    this.setData({
+      radio: event.detail,
+    });
+  },
+
+  onClick(event) {
+    const { name } = event.currentTarget.dataset;
+    this.setData({
+      radio: name,
+    });
+  },
+});
+```
+
+
+### 阻止默认的UI更新行为
+
+假如你的 `UI更新` 需要在特定情况下才允许更新，如 确认框/接口行为等才允许更新，可以开启 `prevent-default` 这个选项。
+
+```html
+<smart-radio-group prevent-default value="{{ radio }}" bind:change="onChange">
+    <smart-radio name="1">1</smart-radio>
+    <smart-radio name="2">2</smart-radio>
+  </smart-radio-group>
+```
+
+```js
+Page({
+  data: {
+    radio: '1',
+  },
+
+  onChange(event) {
+    ty.showModal({
+      content: `onChange name: ${event.detail}`,
+      showCancel: true,
+      success: (res) => {
+        if (res.confirm) {
+          this.setData({
+            radio: event.detail
+          })
+        }
+      }
+    })
+  },
+});
+```
+
+## API
+
+### RadioGroup Props
+
+| 参数               | 说明                            | 类型      | 默认值     |
+| ------------------ | ------------------------------- | --------- | ---------- |
+| direction | 排列方向，可选值为 `horizontal` | _string_  | `vertical` |
+| disabled           | 是否禁用所有单选框              | _boolean_ | `false`    |
+| name               | 在表单内提交时的标识符          | _string_  | -          |
+| value              | 当前选中项的标识符              | _any_     | -          |
+| prevent-default `v2.3.8`| 阻止默认的UI更新行为|_boolean_|`false`    |
+
+### Radio Props
+
+| 参数           | 说明                      | 类型               | 默认值    |
+| -------------- | ------------------------- | ------------------ | --------- |
+| checked-color  | 选中状态颜色              | _string_           | `#1989fa` |
+| disabled       | 是否为禁用状态            | _boolean_          | `false`   |
+| icon-size      | 图标大小，默认单位为`px`  | _string \| number_ | `24px`    |
+| label-disabled | 是否禁用文本内容点击      | _boolean_          | `false`   |
+| label-position | 文本位置，可选值为 `left` | _string_           | `right`   |
+| name           | 标识符                    | _string_           | -         |
+| shape          | 形状，可选值为 `square`   | _string_           | `round`   |
+| use-icon-slot  | 是否使用 icon 插槽        | _boolean_          | `false`   |
+
+### Radio Event
+
+| 事件名      | 说明                     | 回调参数          |
+| ----------- | ------------------------ | ----------------- |
+| bind:change | 当绑定值变化时触发的事件 | 当前选中项的 name |
+
+### Radio 外部样式类
+
+| 类名         | 说明           |
+| ------------ | -------------- |
+| custom-class | 根节点样式类   |
+| icon-class   | 图标样式类     |
+| label-class  | 描述信息样式类 |
+
+### RadioGroup Event
+
+| 事件名      | 说明                     | 回调参数          |
+| ----------- | ------------------------ | ----------------- |
+| bind:change | 当绑定值变化时触发的事件 | 当前选中项的 name |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --radio-size                  | _24px_                                 | 单选框的大小 |
+| --radio-border-color          | _var(--app-B6-N6, rgba(0, 0, 0, 0.2))_ | 单选框的边框颜色 |
+| --radio-border-radius         | _4px_                                  | 单选框的边框圆角 |
+| --radio-transition-duration   | _0.2s_                                 | 单选框的过渡持续时间 |
+| --radio-label-size            | _12px_                                 | 单选框标签的字体大小 |
+| --radio-label-margin          | _10px_                                 | 单选框标签的外边距 |
+| --radio-label-color           | _var(--app-B6-N1, rgba(0, 0, 0, 1))_   | 单选框标签的字体颜色 |
+| --radio-checked-icon-color    | _var(--app-M4, #1989fa)_               | 单选框选中状态的图标颜色 |
+| --radio-disabled-label-color  | _var(--app-B6-N5, rgba(0, 0, 0, 0.3))_ | 单选框禁用状态的标签颜色 |
+| --radio-disabled-opacity      | _0.3_                                  | 单选框禁用状态的透明度 |