@tuya-miniapp/smart-ui 2.13.1 → 2.13.2-beta-1

package/lib/cascader/README.md

@@ -0,0 +1,235 @@
+---
+category: 数据录入
+---
+
+# Cascader 级联选择
+
+### 介绍
+
+级联选择框，用于多层级数据的选择，典型场景为省市区选择。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-cascader": "@tuya-miniapp/smart-ui/lib/cascader/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+级联选择组件可以搭配 Field 和 Popup 组件使用，示例如下：
+
+```html
+<smart-field
+  value="{{ fieldValue }}"
+  is-link
+  readonly
+  label="地区"
+  placeholder="请选择所在地区"
+  bind:tap="onClick"
+/>
+<smart-bottom-sheet show="{{ show }}" max-height="100%">
+  <smart-cascader
+    ty:if="{{ show }}"
+    value="{{ cascaderValue }}"
+    title="请选择所在地区"
+    options="{{ options }}"
+    bind:close="onClose"
+    bind:finish="onFinish"
+  />
+</smart-bottom-sheet>
+```
+
+```js
+
+const options = [
+  {
+    text: '浙江省',
+    value: '330000',
+    children: [{ text: '杭州市', value: '330100' }],
+  },
+  {
+    text: '江苏省',
+    value: '320000',
+    children: [{ text: '南京市', value: '320100' }],
+  },
+];
+
+Page({
+  data: {
+    show: false,
+    options,
+    fieldValue: '',
+    cascaderValue: '',
+  },
+
+  onClick() {
+    this.setData({
+      show: true,
+    });
+  },
+
+  onClose() {
+    this.setData({
+      show: false,
+    });
+  },
+
+  onFinish(e) {
+    const { selectedOptions, value } = e.detail;
+    const fieldValue = selectedOptions
+        .map((option) => option.text || option.name)
+        .join('/');
+    this.setData({
+      fieldValue,
+      cascaderValue: value,
+    })
+  },
+});
+```
+
+### 自定义颜色
+
+通过 `active-color` 属性来设置选中状态的高亮颜色。
+
+```html
+<smart-cascader
+  value="{{ cascaderValue }}"
+  title="请选择所在地区"
+  options="{{ options }}"
+  active-color="#ee0a24"
+  bind:close="onClose"
+  bind:finish="onFinish"
+/>
+```
+
+### 异步加载选项
+
+可以监听 `change` 事件并动态设置 `options`，实现异步加载选项。
+
+```html
+<smart-field
+  value="{{ fieldValue }}"
+  is-link
+  readonly
+  label="地区"
+  placeholder="请选择所在地区"
+  bind:tap="onClick"
+/>
+<smart-bottom-sheet show="{{ show }}" max-height="100%">
+  <smart-cascader
+    ty:if="{{ show }}"
+    value="{{ cascaderValue }}"
+    title="请选择所在地区"
+    options="{{ options }}"
+    bind:close="onClose"
+    bind:change="onChange"
+    bind:finish="onFinish"
+  />
+</smart-bottom-sheet>
+```
+
+```js
+Page({
+  data: {
+    options: [
+      {
+        text: '浙江省',
+        value: '330000',
+        children: [],
+      }
+    ];
+  },
+  onChange(e) {
+    const { value } = e.detail;
+    if (value === this.data.options[0].value) {
+      setTimeout(() => {
+        const children = [
+          { text: '杭州市', value: '330100' },
+          { text: '宁波市', value: '330200' },
+        ];
+        this.setData({
+          'options[0].children': children,
+        })
+      }, 500);
+    }
+  },
+});
+
+```
+
+## API
+
+### Props
+
+| 参数            | 说明                                                           | 类型               | 默认值    |
+| --------------- | -------------------------------------------------------------- | ------------------ | --------- |
+| active-color    | 选中状态的高亮颜色                                             | _string_           | `#1989fa` |
+| close-icon      | 关闭图标svg值或图片链接，等同于 Icon 组件的 [name 属性](/material/smartui?comId=icon&appType=miniapp) | _string_           | `cross`   |
+| close-icon-aria-label `v2.13.0` | 关闭按钮的无障碍读屏文案，透传至内部 `smart-icon` 的 `aria-label` | _string_           | -         |
+| closeable       | 是否显示关闭图标                                               | _boolean_          | `true`    |
+| ellipsis        | 是否省略过长的标题文字, 关闭后文字过长会出现横向滚动           | _boolean_          | `true`    |
+| options         | 可选项数据源                                                   | _CascaderOption[]_ | `[]`      |
+| placeholder     | 未选中时的提示文案                                             | _string_           | `请选择`  |
+| show-header     | 是否展示标题栏                                                 | _boolean_          | `true`    |
+| swipe-threshold | 滚动阈值，标签数量超过阈值且总宽度超过标签栏宽度时开始横向滚动 | _number_           | `5`       |
+| swipeable       | 是否开启手势左右滑动切换                                       | _boolean_          | `false`   |
+| title           | 顶部标题                                                       | _string_           | -         |
+| use-title-slot  | 是否使用自定义标题的插槽                                       | _boolean_          | `false`   |
+| value           | 选中项的值                                                     | _string \| number_ | -         |
+
+### CascaderOption 数据结构
+
+`options` 属性是一个由对象构成的数组，数组中的每个对象配置一个可选项，对象可以包含以下值：
+
+| 键名      | 说明                     | 类型                        |
+| --------- | ------------------------ | --------------------------- |
+| className | 为对应列添加额外的 class | _string \| Array \| object_ |
+| color     | 选项文字颜色             | _string_                    |
+| disabled  | 是否禁用选项             | _boolean_                   |
+| options   | 子选项列表               | _CascaderOption[]_          |
+| text      | 选项文字（必填）         | _string_                    |
+| value     | 选项对应的值（必填）     | _string \| number_          |
+
+### Events
+
+| 事件           | 说明                   | 回调参数                                                                                         |
+| -------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| bind:change    | 选中项变化时触发       | event.detail：_{ value: string \| number, selectedOptions: CascaderOption[], tabIndex: number }_ |
+| bind:click-tab | 点击标签时触发         | event.detail：_{ tabIndex: number, title: string }_                                              |
+| bind:close     | 点击关闭图标时触发     | -                                                                                                |
+| bind:finish    | 全部选项选择完成后触发 | event.detail：_{ value: string \| number, selectedOptions: CascaderOption[], tabIndex: number }_ |
+
+### Slots
+
+| 名称  | 说明           | 参数 |
+| ----- | -------------- | ---- |
+| title | 自定义顶部标题 | -    |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                                  | 默认值                                   | 描述                                     |
+| ------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| --cascader-header-height              | _48px_                                   | 级联选择器头部高度                       |
+| --cascader-header-padding             | _0 16px_                                 | 级联选择器头部内边距                     |
+| --cascader-title-font-size            | _16px_                                   | 级联选择器标题字体大小                   |
+| --cascader-title-line-height          | _20px_                                   | 级联选择器标题行高                       |
+| --cascader-close-icon-size            | _22px_                                   | 级联选择器关闭图标大小                   |
+| --cascader-close-icon-color           | _#c8c9cc_                                | 级联选择器关闭图标颜色                   |
+| --cascader-selected-icon-size         | _18px_                                   | 级联选择器选中图标大小                   |
+| --cascader-tabs-height                | _48px_                                   | 级联选择器标签栏高度                     |
+| --cascader-active-color               | _#1989fa_                                | 级联选择器激活项颜色                     |
+| --cascader-options-height             | _384px_                                  | 级联选择器选项高度                       |
+| --cascader-option-disabled-color      | _#c8c9cc_                                | 级联选择器禁用选项颜色                   |
+| --cascader-tab-color                  | _var(--app-B6-N1, rgba(0, 0, 0, 1))_     | 级联选择器标签颜色                       |
+| --cascader-unselected-tab-color       | _#969799_                                | 级联选择器未选中标签颜色                 |
+| --cascader-tab-inactive-color         | _var(--app-B6-N5, rgba(0, 0, 0, 0.3))_   | 级联选择器标签未激活颜色                 |
+| --cascader-text-color                 | _var(--app-B6-N5, rgba(0, 0, 0, 0.3))_   | 级联选择器文本颜色                       |
+| --cascader-active-background-color `v2.8.0` | _var(--app-B1, #f6f7fb)_   | 级联选择器列点击时背景色   |

package/lib/cell/README.md

@@ -0,0 +1,240 @@
+---
+category: 展示
+---
+
+# Cell 单元格
+
+### 介绍
+
+单元格为列表中的单个展示项。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-cell": "@tuya-miniapp/smart-ui/lib/cell/index",
+  "smart-cell-group": "@tuya-miniapp/smart-ui/lib/cell-group/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+`Cell`可以单独使用，也可以与`CellGroup`搭配使用。`CellGroup`可以为`Cell`提供上下外边框。
+
+```html
+<smart-cell-group>
+  <smart-cell title="单元格" value="内容" is-link />
+  <smart-cell title="单元格" value="内容" label="描述信息" is-link />
+</smart-cell-group>
+```
+
+### 卡片风格
+
+通过 `CellGroup` 的 `inset` `v1.7.2` 属性，可以将单元格转换为圆角卡片风格, `inset-border-radius` `v2.6.2` 可以设置圆角的值。
+
+```html
+<smart-cell-group inset inset-border-radius="{{ 12 }}">
+  <smart-cell title="单元格" value="内容" is-link />
+  <smart-cell title="单元格" value="内容" label="描述信息" is-link />
+</smart-cell-group>
+```
+
+### 展示图标
+
+通过`icon`属性在标题左侧展示图标。
+
+```html
+<smart-cell-group>
+  <smart-cell title="单元格" value="内容" icon="{{ sunMaxFill }}" is-link />
+  <smart-cell title="自定义 Icon" value="内容" is-link>
+    <smart-icon class="cell-icon" slot="icon" name="{{ sunMaxFill }}" size="24px" color="#3678E3" />
+  </smart-cell>
+</smart-cell-group>
+```
+
+### 展示箭头
+
+设置`is-link`属性后会在单元格右侧显示箭头，并且可以通过`arrow-direction`属性控制箭头方向。
+
+```html
+<smart-cell-group>
+  <smart-cell title="单元格" is-link />
+  <smart-cell title="单元格" is-link value="内容" />
+  <smart-cell title="单元格" is-link value="内容" arrow-direction="down" />
+</smart-cell-group>
+```
+
+### 页面跳转
+
+可以通过`url`属性进行页面跳转，通过`link-type`属性控制跳转类型。
+
+```html
+<smart-cell-group>
+  <smart-cell title="URL跳转(navigateTo)" is-link url="/pages/dashboard/index" />
+  <smart-cell
+    title="URL重定向(redirectTo)"
+    is-link
+    url="/pages/dashboard/index"
+    link-type="redirectTo"
+  />
+  <smart-cell title="打开H5容器(openInnerH5)" is-link bind:click="onNavTo" />
+</smart-cell-group>
+```
+
+### 分组标题
+
+通过`CellGroup`的`title`属性可以指定分组标题。
+
+```html
+<smart-cell-group title="分组 1">
+  <smart-cell title="单元格" is-link />
+</smart-cell-group>
+<smart-cell-group title="分组 2">
+  <smart-cell title="单元格" is-link />
+</smart-cell-group>
+```
+
+### 其他类型
+
+也可配合其他组件进行展示
+
+```html
+<smart-cell-group>
+  <smart-cell title="Title">
+    <smart-switch checked="{{ true }}" size="24px" />
+  </smart-cell>
+  <smart-cell title="Title">
+    <smart-icon name="{{ checkMark }}" color="#3678E3" size="28px" />
+  </smart-cell>
+  <smart-cell title="Title">
+    <smart-checkbox value="{{ false }}" shape="square" />
+  </smart-cell>
+  <smart-cell title="Title">
+    <smart-checkbox value="{{ false }}" />
+  </smart-cell>
+  <smart-cell title="Title" label="Bedroom" is-link>
+    <smart-icon
+      class="cell-icon"
+      slot="icon"
+      name="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+      size="50px"
+    />
+  </smart-cell>
+</smart-cell-group>
+```
+
+### 使用插槽
+
+如以上用法不能满足你的需求，可以使用插槽来自定义内容。
+
+```html
+<smart-cell-group>
+  <smart-cell value="内容" icon="{{ sunMaxFill }}" is-link>
+    <view slot="title">
+      <view class="title">单元格</view>
+      <smart-tag type="danger">标签</smart-tag>
+    </view>
+  </smart-cell>
+  <smart-cell title="单元格">
+    <smart-icon slot="right-icon" name="search" />
+  </smart-cell>
+</smart-cell-group>
+```
+
+## API
+
+### CellGroup Props
+
+| 参数                         | 说明                   | 类型               | 默认值  |
+| ---------------------------- | ---------------------- | ------------------ | ------- |
+| border                       | 是否显示外边框         | _boolean_          | `true`  |
+| inset                        | 是否展示为圆角卡片风格 | _boolean_          | `false` |
+| title                        | 分组标题               | _string_           | `-`     |
+| inset-border-radius `v2.6.2` | 圆角卡片风格时的圆角值 | _string \| number_ | `-`     |
+
+### CellGroup 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| custom-class | 根节点样式类 |
+
+### Cell Props
+
+| 参数            | 说明                                                                                                                                       | 类型               | 默认值       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------ |
+| arrow-direction | 箭头方向，可选值为 `left` `up` `down`                                                                                                      | _string_           | -            |
+| border          | 是否显示下边框                                                                                                                             | _boolean_          | `true`       |
+| clickable       | 是否开启点击反馈                                                                                                                           | _boolean_          | `false`      |
+| icon            | 左侧图标 svg 值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon&appType=miniapp)                                              | _string_           | -            |
+| is-link         | 是否展示右侧箭头并开启点击反馈                                                                                                             | _boolean_          | `false`      |
+| label           | 标题下方的描述信息                                                                                                                         | _string_           | -            |
+| link-type       | 链接跳转类型，可选值为 `redirectTo` [`switchTab`](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.switchTab.html) `reLaunch` | _string_           | `navigateTo` |
+| required        | 是否显示表单必填星号                                                                                                                       | _boolean_          | `false`      |
+| title           | 左侧标题                                                                                                                                   | _string \| number_ | -            |
+| title-style     | 标题样式                                                                                                                                   | _string_           | -            |
+| title-width     | 标题宽度，须包含单位                                                                                                                       | _string_           | -            |
+| url             | 点击后跳转的链接地址                                                                                                                       | _string_           | -            |
+| use-label-slot  | 是否使用 label slot                                                                                                                        | _boolean_          | `false`      |
+| value           | 右侧内容                                                                                                                                   | _string \| number_ | -            |
+
+### Cell Event
+
+| 事件名     | 说明             | 参数 |
+| ---------- | ---------------- | ---- |
+| bind:click | 点击单元格时触发 | -    |
+
+### Cell Slot
+
+| 名称       | 说明                                                           |
+| ---------- | -------------------------------------------------------------- |
+| -          | 自定义`value`显示内容，如果设置了`value`属性则不生效           |
+| icon       | 自定义`icon`显示内容，如果设置了`icon`属性则不生效             |
+| label      | 自定义`label`显示内容，需要设置 `use-label-slot`属性           |
+| right-icon | 自定义右侧按钮，默认是`arrow`，如果设置了`is-link`属性则不生效 |
+| title      | 自定义`title`显示内容，如果设置了`title`属性则不生效           |
+
+### Cell 外部样式类
+
+| 类名         | 说明           |
+| ------------ | -------------- |
+| custom-class | 根节点样式类   |
+| label-class  | 描述信息样式类 |
+| title-class  | 标题样式类     |
+| value-class  | 右侧内容样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                                  | 默认值                                            | 描述                     |
+| ------------------------------------- | ------------------------------------------------- | ------------------------ |
+| --cell-font-size                      | _16px_                                            | 单元格字体大小           |
+| --cell-line-height                    | _24px_                                            | 单元格行高               |
+| --cell-vertical-padding               | _16px_                                            | 单元格垂直内边距         |
+| --cell-horizontal-padding             | _16px_                                            | 单元格水平内边距         |
+| --cell-text-color                     | _var(--app-B6-N1, rgba(0, 0, 0, 1))_              | 单元格文字颜色           |
+| --cell-background-color               | _var(--app-B6, #fff)_                             | 单元格背景颜色           |
+| --cell-active-color                   | _var(--app-B1, #f6f7fb)_                          | 单元格激活颜色           |
+| --cell-required-color                 | _var(--app-M2, #f04c4c)_                          | 单元格必填项颜色         |
+| --cell-label-color                    | _var(--app-B6-N3, rgba(0, 0, 0, 0.5))_            | 单元格标签文字颜色       |
+| --cell-label-font-size                | _14px_                                            | 单元格标签字体大小       |
+| --cell-label-line-height              | _18px_                                            | 单元格标签行高           |
+| --cell-label-margin-top               | _3px_                                             | 单元格标签上边距         |
+| --cell-value-color                    | _var(--app-B6-N3, rgba(0, 0, 0, 0.5))_            | 单元格值文字颜色         |
+| --cell-icon-size                      | _24px_                                            | 单元格图标大小           |
+| --cell-right-icon-color               | _var(--app-B6-N6, rgba(0, 0, 0, 0.2))_            | 单元格右侧图标颜色       |
+| --cell-border-color `v2.1.4`          | _var(--app-B6-N7, rgba(0, 0, 0, 0.1))_            | 单元格边框颜色           |
+| --cell-border-left-position `v2.1.4`  | _16px_                                            | 单元格左边框位置         |
+| --cell-border-right-position `v2.1.4` | _16px_                                            | 单元格右边框位置         |
+| --cell-group-background-color         | _var(--app-B6, #fff)_                             | 单元格组背景颜色         |
+| --cell-group-title-color              | _var(--app-B6-N3, rgba(0, 0, 0, 0.5))_            | 单元格组标题颜色         |
+| --cell-group-title-padding            | _@padding-md @padding-md @padding-xs_             | 单元格组标题内边距       |
+| --cell-group-title-font-size          | _16px_                                            | 单元格组标题字体大小     |
+| --cell-group-title-line-height        | _16px_                                            | 单元格组标题行高         |
+| --cell-group-inset-padding            | _0 @padding-md_                                   | 单元格组嵌入内边距       |
+| --cell-group-inset-border-radius      | _16px_                                            | 单元格组嵌入边框圆角半径 |
+| --cell-group-inset-title-padding      | _@padding-md @padding-md @padding-xs @padding-xl_ | 单元格组嵌入标题内边距   |