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

package/lib/collapse/README.md

@@ -0,0 +1,223 @@
+---
+category: 展示
+---
+
+# Collapse 折叠面板
+
+### 介绍
+
+将一组内容放置在多个折叠面板中，点击面板的标题可以展开或收缩其内容。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-collapse": "@tuya-miniapp/smart-ui/lib/collapse/index",
+  "smart-collapse-item": "@tuya-miniapp/smart-ui/lib/collapse-item/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+通过`value`控制展开的面板列表，`activeNames`为数组格式。
+
+```html
+<smart-collapse value="{{ activeNames }}" bind:change="onChange">
+  <smart-collapse-item title="标题1" name="1">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题2" name="2">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题3" name="3" disabled>
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+</smart-collapse>
+```
+
+```javascript
+Page({
+  data: {
+    activeNames: ['1'],
+  },
+  onChange(event) {
+    this.setData({
+      activeNames: event.detail,
+    });
+  },
+});
+```
+
+### 手风琴
+
+通过`accordion`可以设置为手风琴模式，最多展开一个面板，此时`activeName`为字符串格式。
+
+```html
+<smart-collapse accordion value="{{ activeName }}" bind:change="onChange">
+  <smart-collapse-item title="标题1" name="1">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题2" name="2">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题3" name="3">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+</smart-collapse>
+```
+
+```javascript
+Page({
+  data: {
+    activeName: '1',
+  },
+  onChange(event) {
+    this.setData({
+      activeName: event.detail,
+    });
+  },
+});
+```
+
+### 事件监听
+
+`smart-collapse` 提供了 `change`, `open` 和 `close` 事件。`change` 事件在面板切换时触发，`open` 事件在面板展开时触发，`close` 事件在面板关闭时触发。
+
+```html
+<smart-collapse
+  value="{{ activeNames }}"
+  bind:change="onChange"
+  bind:open="onOpen"
+  bind:close="onClose"
+>
+  <smart-collapse-item title="标题1" name="1">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题2" name="2">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题3" name="3">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+</smart-collapse>
+```
+
+```javascript
+Page({
+  data: {
+    activeNames: ['1'],
+  },
+  onChange(event) {
+    this.setData({
+      activeNames: event.detail,
+    });
+  },
+  onOpen(event) {
+    Toast(`展开: ${event.detail}`);
+  },
+  onClose(event) {
+    Toast(`关闭: ${event.detail}`);
+  },
+});
+```
+
+### 自定义标题内容
+
+```html
+<smart-collapse value="{{ activeNames }}" bind:change="onChange">
+  <smart-collapse-item name="1">
+    <view slot="title">标题1<smart-icon name="question-o" /></view>
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+  <smart-collapse-item title="标题2" name="2" icon="shop-o">
+    代码是写出来给人看的，附带能在机器上运行
+  </smart-collapse-item>
+</smart-collapse>
+```
+
+```javascript
+Page({
+  data: {
+    activeNames: ['1'],
+  },
+  onChange(event) {
+    this.setData({
+      activeNames: event.detail,
+    });
+  },
+});
+```
+
+## 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&appType=miniapp) | _string_           | -       |
+| is-link   | 是否展示标题栏右侧箭头并开启点击反馈                       | _boolean_          | `true`  |
+| label     | 标题栏描述信息                                             | _string_           | -       |
+| name      | 唯一标识符，默认为索引值                                   | _string \| number_ | `index` |
+| size      | 标题栏大小，可选值为`large`                                | _string_           | -       |
+| title     | 标题栏左侧内容                                             | _string \| number_ | -       |
+| value     | 标题栏右侧内容                                             | _string \| number_ | -       |
+
+### CollapseItem Slot
+
+| 名称       | 说明                                                                     |
+| ---------- | ------------------------------------------------------------------------ |
+| -          | 面板内容                                                                 |
+| icon       | 自定义`icon`                                                             |
+| right-icon | 自定义右侧按钮，默认是`arrow`, 需要将 `is-link` 设置为 `false`, 才会生效 |
+| title      | 自定义`title`                                                            |
+| value      | 自定义显示内容                                                           |
+
+### Collapse 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| custom-class | 根节点样式类 |
+
+### CollapseItem 外部样式类
+
+| 类名          | 说明         |
+| ------------- | ------------ |
+| content-class | 内容样式类   |
+| custom-class  | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                                          | 默认值                                       | 描述                                       |
+| --------------------------------------------- | -------------------------------------------- | ------------------------------------------ |
+| --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/lib/common/README.md

@@ -0,0 +1,71 @@
+# 内置样式
+
+### 介绍
+
+Smart UI 中默认包含了一些常用样式，可以直接通过 className 的方式使用。
+
+### 引入
+
+在 app.wxss 中引入内置样式。
+
+```css
+@import '@tuya-miniapp/smart-ui/common/index.wxss';
+```
+
+## 代码演示
+
+### 文字省略
+
+当文本内容长度超过容器最大宽度时，自动省略多余的文本。
+
+```xml
+<view class="smart-ellipsis">
+  这是一段宽度限制 250px 的文字，后面的内容会省略。
+</view>
+
+<!-- 最多显示两行 -->
+<view class="smart-multi-ellipsis--l2">
+  这是一段最多显示两行的文字，后面的内容会省略。
+</view>
+
+<!-- 最多显示三行 -->
+<view class="smart-multi-ellipsis--l3">
+  这是一段最多显示三行的文字，后面的内容会省略。
+</view>
+```
+
+### 1px 边框
+
+为元素添加 Retina 屏幕下的 1px 边框（即 hairline），基于伪类 transform 实现。
+
+```xml
+<!-- 上边框 -->
+<view class="smart-hairline--top"></view>
+
+<!-- 下边框 -->
+<view class="smart-hairline--bottom"></view>
+
+<!-- 左边框 -->
+<view class="smart-hairline--left"></view>
+
+<!-- 右边框 -->
+<view class="smart-hairline--right"></view>
+
+<!-- 上下边框 -->
+<view class="smart-hairline--top-bottom"></view>
+
+<!-- 全边框 -->
+<view class="smart-hairline--surround"></view>
+```
+
+### 全局字体
+
+推荐在 app.wxss 中设置以下全局字体，以保证在不同设备上提供最佳的视觉体验。
+
+```css
+page {
+  font-family: -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Helvetica,
+    Segoe UI, Arial, Roboto, 'PingFang SC', 'miui', 'Hiragino Sans GB', 'Microsoft Yahei',
+    sans-serif;
+}
+```

package/lib/config-provider/README.md

@@ -0,0 +1,143 @@
+---
+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)
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-config-provider": "@tuya-miniapp/smart-ui/lib/config-provider/index"
+}
+```
+
+## 定制主题
+
+### 介绍
+
+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 覆盖
+
+你可以直接在代码中覆盖这些 CSS 变量，Button 组件的样式会随之发生改变：
+
+```css
+/* 添加这段样式后，Primary Button 会变成红色 */
+page {
+  --button-primary-background-color: red;
+}
+```
+
+#### 通过 ConfigProvider 覆盖
+
+`ConfigProvider` 组件提供了覆盖 CSS 变量的能力，你需要在组件节点外包裹一个 `ConfigProvider` 组件，并通过 `theme-vars` 属性来配置一些主题变量，其入参就是组件的CSS 变量变成驼峰形式。
+
+```html
+<view class="demo-buttons">
+  <smart-button type="primary" data-color="red" color="red" bind:click="onChange">
+    设置为红色
+  </smart-button>
+  <smart-button type="primary" data-color="green" color="green" bind:click="onChange">
+    设置为绿色
+  </smart-button>
+  <smart-button type="primary" data-color="blue" color="blue" bind:click="onChange">
+    设置为蓝色
+  </smart-button>
+</view>
+<smart-config-provider theme-vars="{{ themeVars }}">
+  <smart-button type="primary">主按钮</smart-button>
+</smart-config-provider>
+```
+
+```js
+Page({
+  data: {
+    themeVars: {
+      buttonPrimaryBorderColor: 'red',
+      buttonPrimaryBackgroundColor: 'red',
+    },
+  },
+
+  onChange(event) {
+    const { color } = event.currentTarget.dataset;
+    this.setData({
+      themeVars: {
+        buttonPrimaryBorderColor: color,
+        buttonPrimaryBackgroundColor: color,
+      },
+    });
+  },
+});
+```
+
+### 主题切换 `v2.8.0`
+
+`ConfigProvider` 组件支持通过 `theme` 属性来切换明暗主题，可选值为 `light` 和 `dark`。
+
+```html
+<view class="demo-buttons">
+  <smart-button type="primary" data-theme="light" bind:click="onThemeChange">
+    浅色主题
+  </smart-button>
+  <text>当前主题：{{ currentTheme }}</text>
+  <smart-button type="primary" data-theme="dark" bind:click="onThemeChange">
+    深色主题
+  </smart-button>
+</view>
+<smart-config-provider theme="{{ currentTheme }}">
+  <smart-cell-group>
+    <smart-cell title="标题" value="内容" />
+    <smart-cell title="标题" value="内容" label="详细信息" is-link />
+  </smart-cell-group>
+</smart-config-provider>
+```
+
+```js
+Page({
+  data: {
+    currentTheme: 'light',
+  },
+
+  onThemeChange(event) {
+    const { theme } = event.currentTarget.dataset;
+    this.setData({
+      currentTheme: theme,
+    });
+  },
+});
+```
+
+## API
+
+### Props
+
+| 参数       | 说明           | 类型     | 默认值 |
+| ---------- | -------------- | -------- | ------ |
+| theme-vars | 自定义主题变量 | _object_ | -      |
+| theme   `v2.8.0`      | 主题模式       | _'light'\/'dark'_ | -      |
+

package/lib/count-down/README.md

@@ -0,0 +1,194 @@
+---
+category: 反馈
+---
+
+# CountDown 倒计时
+
+### 介绍
+
+用于实时展示倒计时数值，支持毫秒精度。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-count-down": "@tuya-miniapp/smart-ui/lib/count-down/index"
+}
+```
+
+## 代码演示
+
+### 基本用法
+
+`time`属性表示倒计时总时长，单位为毫秒。
+
+```html
+<smart-count-down time="{{ time }}" />
+```
+
+```js
+Page({
+  data: {
+    time: 30 * 60 * 60 * 1000,
+  },
+});
+```
+
+### 自定义格式
+
+通过`format`属性设置倒计时文本的内容。
+
+```html
+<smart-count-down time="{{ time }}" format="DD 天 HH 时 mm 分 ss 秒" />
+```
+
+### 毫秒级渲染
+
+倒计时默认每秒渲染一次，设置`millisecond`属性可以开启毫秒级渲染。
+
+```html
+<smart-count-down millisecond time="{{ time }}" format="HH:mm:ss:SSS" />
+```
+
+### 自定义样式
+
+设置`use-slot`属性后可以自定义倒计时样式，需要通过`bind:change`事件获取`timeData`对象并自行渲染，格式见下方表格。
+
+```html
+<smart-count-down use-slot time="{{ time }}" bind:change="onChange">
+  <text class="item">{{ timeData.hours }}</text>
+  <text class="item">{{ timeData.minutes }}</text>
+  <text class="item">{{ timeData.seconds }}</text>
+</smart-count-down>
+```
+
+```js
+Page({
+  data: {
+    time: 30 * 60 * 60 * 1000,
+    timeData: {},
+  },
+
+  onChange(e) {
+    this.setData({
+      timeData: e.detail,
+    });
+  },
+});
+```
+
+```css
+.item {
+  display: inline-block;
+  width: 22px;
+  margin-right: 5px;
+  color: #fff;
+  font-size: 12px;
+  text-align: center;
+  background-color: #1989fa;
+  border-radius: 2px;
+}
+```
+
+### 手动控制
+
+通过 `selectComponent` 选择器获取到组件实例后，可以调用`start`、`pause`、`reset`方法。
+
+```html
+<smart-count-down
+  class="control-count-down"
+  millisecond
+  time="{{ 3000 }}"
+  auto-start="{{ false }}"
+  format="ss:SSS"
+  bind:finish="finished"
+/>
+
+<smart-grid clickable column-num="3">
+  <smart-grid-item text="开始" icon="{{PlayIcon}}" bindclick="start" />
+  <smart-grid-item text="暂停" icon="{{PauseIcon}}" bindclick="pause" />
+  <smart-grid-item text="重置" icon="{{ReplayIcon}}" bindclick="reset" />
+</smart-grid>
+```
+
+```js
+import PlayIcon from '@tuya-miniapp/icons/dist/svg/Play';
+import PauseIcon from '@tuya-miniapp/icons/dist/svg/Pause';
+import ReplayIcon from '@tuya-miniapp/icons/dist/svg/Refresh';
+Page({
+  data:{
+    PlayIcon,
+    PauseIcon,
+    ReplayIcon,
+  },
+  start() {
+    const countDown = this.selectComponent('.control-count-down');
+    countDown.start();
+  },
+
+  pause() {
+    const countDown = this.selectComponent('.control-count-down');
+    countDown.pause();
+  },
+
+  reset() {
+    const countDown = this.selectComponent('.control-count-down');
+    countDown.reset();
+  },
+
+  finished() {
+    Toast('倒计时结束');
+  },
+});
+```
+
+## API
+
+### Props
+
+| 参数        | 说明                                           | 类型      | 默认值     |
+| ----------- | ---------------------------------------------- | --------- | ---------- |
+| auto-start  | 是否自动开始倒计时                             | _boolean_ | `true`     |
+| format      | 时间格式，DD-日，HH-时，mm-分，ss-秒，SSS-毫秒 | _string_  | `HH:mm:ss` |
+| millisecond | 是否开启毫秒级渲染                             | _boolean_ | `false`    |
+| time        | 倒计时时长，单位毫秒                           | _number_  | -          |
+| use-slot    | 是否使用自定义样式插槽                         | _boolean_ | `false`    |
+
+### Events
+
+| 事件名      | 说明                                         | 回调参数 |
+| ----------- | -------------------------------------------- | -------- |
+| bind:change | 时间变化时触发，仅在开启`use-slot`后才会触发 | timeData |
+| bind:finish | 倒计时结束时触发                             | -        |
+
+### timeData 格式
+
+| 名称         | 说明     | 类型     |
+| ------------ | -------- | -------- |
+| days         | 剩余天数 | _number_ |
+| hours        | 剩余小时 | _number_ |
+| milliseconds | 剩余毫秒 | _number_ |
+| minutes      | 剩余分钟 | _number_ |
+| seconds      | 剩余秒数 | _number_ |
+
+### 方法
+
+通过 [selectComponent](/material/smartui?comId=faq&appType=miniapp) 可以获取到 CountDown 实例并调用实例方法。
+
+| 方法名 | 参数 | 返回值 | 介绍                                                       |
+| ------ | ---- | ------ | ---------------------------------------------------------- |
+| pause  | -    | -      | 暂停倒计时                                                 |
+| reset  | -    | -      | 重设倒计时，若`auto-start`为`true`，重设后会自动开始倒计时 |
+| start  | -    | -      | 开始倒计时                                                 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --count-down-text-color | _var(--app-B6-N2, rgba(0, 0, 0, 0.7))_ | 文本颜色 |
+| --count-down-font-size | _14px_ | 字体大小 |
+| --count-down-line-height | _20px_ | 行高 |