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

package/dist/icon/README.md

@@ -0,0 +1,143 @@
+---
+category: 展示
+---
+
+# Icon 图标
+
+### 介绍
+
+基于字体的图标集，可以通过 Icon 组件使用，也可以在其他组件中通过 icon 属性引用。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-icon": "@tuya-miniapp/smart-ui/lib/icon/index"
+}
+```
+
+在`index.ts`中引入 icon svg
+
+```js
+import warningIcon from '@tuya-miniapp/icons/dist/svg/Warning';
+```
+
+## 代码演示
+
+### 基础用法
+
+`Icon`的`name`属性支持传入图标名称或图片链接。
+
+```html
+<smart-icon name="{{ warningIcon }}" />
+<smart-icon name="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png" />
+```
+
+### 提示信息
+
+设置`dot`属性后，会在图标右上角展示一个小红点。设置`info`属性后，会在图标右上角展示相应的徽标。
+
+```html
+<smart-icon name="{{ warningIcon }}" dot />
+<smart-icon name="{{ warningIcon }}" info="9" />
+<smart-icon name="{{ warningIcon }}" info="99+" />
+```
+
+### 图标颜色
+
+设置`color`属性来控制图标颜色。
+
+```html
+<smart-icon name="{{ warningIcon }}" color="red" />
+```
+
+### 图标大小
+
+设置`size`属性来控制图标大小。
+
+```html
+<smart-icon name="{{ warningIcon }}" size="50px" />
+```
+
+### 自定义图标
+
+如果需要在现有 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';
+}
+```
+
+```html
+<!-- 通过 class-prefix 指定类名为 my-icon -->
+<smart-icon class-prefix="my-icon" name="extra" />
+```
+
+### Svg Path `v2.3.3`
+
+组件现在也支持传入path的方式渲染
+```html
+<smart-icon 
+  name="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" 
+  size="36"
+  color="#1989fa"
+/>
+```
+
+
+## API
+
+### Props
+
+| 参数         | 说明                                       | 类型               | 默认值       |
+| ------------ | ------------------------------------------ | ------------------ | ------------ |
+| aria-label `v2.13.0` | 无障碍读屏文案；非空时根节点 `aria-role` 为 `button` | _string_           | -            |
+| aria-role `v2.13.0` | 无障碍 `aria-role` | _string_           | -            |
+| class-prefix | 类名前缀                                   | _string_           | `smart-icon` |
+| color        | 图标颜色                                   | _string_           | `inherit`    |
+| custom-style | 自定义样式                                 | _string_           | -            |
+| dot          | 是否显示图标右上角小红点                   | _boolean_          | `false`      |
+| info         | 图标右上角文字提示                         | _string \| number_ | -            |
+| name         | 图标名称或 Svg URL 或图片链接              | _string_           | -            |
+| size         | 图标大小，如 `20px`，`2em`，默认单位为`px` | _string \| number_ | `inherit`    |
+
+### Events
+
+| 事件名     | 说明           | 参数 |
+| ---------- | -------------- | ---- |
+| bind:click | 点击图标时触发 | -    |
+
+### 外部样式类
+
+| 类名         | 说明                 |
+| ------------ | -------------------- |
+| custom-class | 根节点样式类         |
+| info-class   | 图标右上角文字样式类 |
+
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --icon-color | _var(--app-B4-N2, rgba(0, 0, 0, 0.7))_ | 图标颜色 |
+
+## 常见问题
+
+### 开发者工具上提示 Failed to load font 是什么情况？
+
+这个是开发者工具本身的问题，可以忽略，具体可以查看[微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/font/wx.loadFontFace.html) - 注意事项第 5 条。

package/dist/image/README.md

@@ -0,0 +1,171 @@
+---
+category: 展示
+---
+
+# Image 图片
+
+### 介绍
+
+增强版的 img 标签，提供多种图片填充模式，支持图片懒加载、加载中提示、加载失败提示。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-image": "@tuya-miniapp/smart-ui/lib/image/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+基础用法与原生 [image](<(https://developers.weixin.qq.com/miniprogram/dev/component/image.html)>) 标签一致，可以设置`src`、`width`、`height`等原生属性。
+
+```html
+<smart-image width="100" height="100" src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png" />
+```
+
+### 填充模式
+
+通过`fit`属性可以设置图片填充模式，可选值见下方表格。
+
+```html
+<smart-image
+  width="10rem"
+  height="10rem"
+  fit="contain"
+  src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+/>
+```
+
+### 圆形图片
+
+通过`round`属性可以设置图片变圆，注意当图片宽高不相等且`fit`为`contain`或`scale-down`时，将无法填充一个完整的圆形。
+
+```html
+<smart-image
+  round
+  width="10rem"
+  height="10rem"
+  src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+/>
+```
+
+### 图片懒加载
+
+图片懒加载，在即将进入一定范围（上下三屏）时才开始加载。
+
+```html
+<smart-image
+  width="100"
+  height="100"
+  lazy-load
+  src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+/>
+```
+
+### 加载中提示
+
+`Image`组件提供了默认的加载中提示，支持通过`loading`插槽自定义内容。
+
+```html
+<smart-image show-loading use-loading-slot>
+  <smart-loading slot="loading" type="spinner" size="20" vertical />
+</smart-image>
+```
+
+### 加载失败提示
+
+`Image`组件提供了默认的加载失败提示，支持通过`error`插槽自定义内容。
+
+```html
+<smart-image use-error-slot>
+  <text slot="error">加载失败</text>
+</smart-image>
+```
+
+### 修改图片颜色 `v2.3.3`
+
+`tint-color`属性可以直接修改图片的颜色，类似RN的tintColor属性，原理是通过css mask实现的，所以使用之前要做好用户兼容性调查哦。
+
+```html
+<smart-image 
+  width="100" 
+  height="100" 
+  src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png" 
+  tint-color="rgba(255, 255, 25, 0.4)"
+/>
+```
+
+## API
+
+### Props
+
+| 参数                   | 说明                                 | 类型               | 默认值  |
+| ---------------------- | ------------------------------------ | ------------------ | ------- |
+| alt                    | 替代文本                             | _string_           | -       |
+| fit                    | 图片填充模式                         | _string_           | _fill_  |
+| height                 | 高度，默认单位为`px`                 | _string \| number_ | -       |
+| lazy-load              | 是否懒加载                           | _boolean_          | `false` |
+| radius                 | 圆角大小，默认单位为`px`             | _string \| number_ | `0`     |
+| round                  | 是否显示为圆形                       | _boolean_          | `false` |
+| show-error             | 是否展示图片加载失败提示             | _boolean_          | `true`  |
+| show-loading           | 是否展示图片加载中提示               | _boolean_          | `true` `v2.0.0` `false` `v2.7.0`  |
+| show-menu-by-longpress | 是否开启长按图片显示识别小程序码菜单 | _boolean_          | `false` |
+| src                    | 图片链接                             | _string_           | -       |
+| use-error-slot         | 是否使用 error 插槽                  | _boolean_          | `false` |
+| use-loading-slot       | 是否使用 loading 插槽                | _boolean_          | `false` |
+| webp `v1.10.11`        | 是否解析 webp 格式                   | _boolean_          | `false` |
+| width                  | 宽度，默认单位为`px`                 | _string \| number_ | -       |
+| tint-color `v2.3.3`                  |     修改图片颜色，类似RN的tintColor，采用css mask实现        | _string_ | -       |
+
+### 图片填充模式
+
+| 名称      | 含义                                                   |
+| --------- | ------------------------------------------------------ |
+| contain   | 保持宽高缩放图片，使图片的长边能完全显示出来           |
+| cover     | 保持宽高缩放图片，使图片的短边能完全显示出来，裁剪长边 |
+| fill      | 拉伸图片，使图片填满元素                               |
+| heightFix | 缩放模式，高度不变，宽度自动变化，保持原图宽高比不变   |
+| none      | 保持图片原有尺寸                                       |
+| widthFix  | 缩放模式，宽度不变，高度自动变化，保持原图宽高比不变   |
+
+### Events
+
+| 事件名     | 说明               | 回调参数     |
+| ---------- | ------------------ | ------------ |
+| bind:click | 点击图片时触发     | event: Event |
+| bind:error | 图片加载失败时触发 | event: Event |
+| bind:load  | 图片加载完毕时触发 | event: Event |
+
+### Slots
+
+| 名称    | 说明                       |
+| ------- | -------------------------- |
+| error   | 自定义加载失败时的提示内容 |
+| loading | 自定义加载中的提示内容     |
+
+### 外部样式类
+
+| 类名          | 说明           |
+| ------------- | -------------- |
+| custom-class  | 根节点样式类   |
+| error-class   | error 样式类   |
+| image-class   | 图片样式类     |
+| loading-class | loading 样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --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_       | 图片加载错误时默认图片    |

package/dist/index-bar/README.md

@@ -0,0 +1,189 @@
+---
+category: 导航
+---
+
+# IndexBar 索引栏
+
+### 介绍
+
+用于列表的索引分类显示和快速定位。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-index-bar": "@tuya-miniapp/smart-ui/lib/index-bar/index",
+  "smart-index-anchor": "@tuya-miniapp/smart-ui/lib/index-anchor/index"
+}
+```
+
+```warning:⚠️注意
+组件是监听整个page 滚动事件来做动态的 fixed 标题元素，所以渲染此组件的页面必须配置 页面可滚动。
+
+index.config.ts:
+
+export default {
+  navigationBarTitleText: 'Home',
+  disableScroll: false,
+};
+```
+
+## 代码演示
+
+### 基础用法
+
+点击索引栏时，会自动跳转到对应的`IndexAnchor`锚点位置。设置 `scrollable` 后可滑动定位；设置 `show-move-tip`（`v2.12.0`）可在拖动侧边栏时显示跟随手指的提示气泡。
+
+```html
+<smart-index-bar scrollable show-move-tip>
+  <view wx:for="{{ indexList }}" wx:for-item="item" wx:key="item">
+    <smart-index-anchor index="{{ item }}" />
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+  </view>
+</smart-index-bar>
+```
+
+```javascript
+const indexList = [];
+const charCodeOfA = 'A'.charCodeAt(0);
+
+for (let i = 0; i < 26; i++) {
+  indexList.push(String.fromCharCode(charCodeOfA + i));
+}
+
+Page({
+  data: {
+    indexList, // A-Z 字母列表
+  },
+});
+```
+
+### 自定义索引列表
+
+可以通过`index-list`属性自定义展示的索引字符列表。
+
+```html
+<smart-index-bar index-list="{{ customIndexList }}">
+  <view wx:for="{{ customIndexList }}" wx:key="index">
+    <smart-index-anchor use-slot index="{{ item }}">
+      <text>标题{{ item }}</text>
+    </smart-index-anchor>
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+  </view>
+</smart-index-bar>
+```
+
+```javascript
+Page({
+  data: {
+    customIndexList: [1, 2, 3, 4, 5, 6, 8, 9, 10],
+  },
+});
+```
+
+### 自定义侧边栏样式 `v2.11.0`
+
+`sidebar-font-size` 和 `sidebar-line-height` 属性可以设置侧边栏的字体样式
+
+```html
+<smart-index-bar sidebar-font-size="16px" sidebar-line-height="20px">
+  <view wx:for="{{ indexList }}" wx:for-item="item" wx:key="item">
+    <smart-index-anchor index="{{ item }}" />
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+    <smart-cell title="文本" />
+  </view>
+</smart-index-bar>
+```
+
+```javascript
+const indexList = [];
+const charCodeOfA = 'A'.charCodeAt(0);
+
+for (let i = 0; i < 26; i++) {
+  indexList.push(String.fromCharCode(charCodeOfA + i));
+}
+
+Page({
+  data: {
+    indexList, // A-Z 字母列表
+  },
+});
+```
+
+## API
+
+### IndexBar Props
+
+| 参数                          | 说明                       | 类型                   | 默认值    |
+| ----------------------------- | -------------------------- | ---------------------- | --------- |
+| highlight-color               | 索引字符高亮颜色           | _string_               | `#07c160` |
+| index-list                    | 索引字符列表               | _string[] \| number[]_ | `A-Z`     |
+| sticky                        | 是否开启锚点自动吸顶       | _boolean_              | `true`    |
+| sticky-push `v2.13.0`         | 滚动时是否开启上一个吸顶锚点的上推动画效果 | _boolean_ | `true`    |
+| sticky-offset-top             | 锚点自动吸顶时与顶部的距离 | _number_               | `0`       |
+| z-index                       | z-index 层级               | _number_               | `1`       |
+| scrollable `v2.1.7`           | SideBar 是否可滚动定位     | _boolean_              | `false`   |
+| show-move-tip `v2.12.0`       | 是否在拖动侧边栏时显示跟随手指的提示气泡 | _boolean_ | `false`   |
+| sidebar-font-size `v2.11.0`   | SideBar 字体大小           | _string_               | -         |
+| sidebar-line-height `v2.11.0` | SideBar 字体行高           | _string_               | -         |
+
+### IndexAnchor Props
+
+| 参数     | 说明                     | 类型               | 默认值  |
+| -------- | ------------------------ | ------------------ | ------- |
+| index    | 索引字符                 | _string \| number_ | -       |
+| use-slot | 是否使用自定义内容的插槽 | _boolean_          | `false` |
+
+### IndexBar Events
+
+| 事件名 | 说明           | 回调参数        |
+| ------ | -------------- | --------------- |
+| select | 选中字符时触发 | index: 索引字符 |
+
+### IndexAnchor Slots
+
+| 名称 | 说明                             |
+| ---- | -------------------------------- |
+| -    | 锚点位置显示内容，默认为索引字符 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+**IndexBar**
+
+| 名称                                      | 默认值       | 描述                   |
+| ----------------------------------------- | ------------ | ---------------------- |
+| --index-bar-index-font-size               | _10px_        | 侧边栏索引字体大小     |
+| --index-bar-index-line-height             | _14px_ `v2.0.0` _16px_ `v2.12.0` | 侧边栏索引行高     |
+| --index-bar-move-tip-text-padding `v2.12.0` | _0 10px 0 0_ | 拖动提示文字内边距     |
+| --index-bar-move-tip-text-font-size `v2.12.0`     | _24px_   | 拖动提示文字字体大小   |
+| --index-bar-move-tip-text-line-height `v2.12.0`   | _32px_   | 拖动提示文字行高       |
+| --index-bar-move-tip-text-color `v2.12.0`        | _#fff_   | 拖动提示文字颜色       |
+
+**IndexAnchor**
+
+| 名称                                    | 默认值        | 描述               |
+| --------------------------------------- | ------------- | ------------------ |
+| --index-anchor-padding                  | _0 16px_      | 锚点内边距         |
+| --index-anchor-text-color               | _rgba(0,0,0,1)_ | 锚点文字颜色     |
+| --index-anchor-font-weight              | _500_         | 锚点字重           |
+| --index-anchor-font-size                | _14px_        | 锚点字体大小       |
+| --index-anchor-line-height              | _32px_        | 锚点行高           |
+| --index-anchor-background-color         | _transparent_ | 锚点背景色         |
+| --index-anchor-active-background-color  | _#ffffff_     | 锚点吸顶时背景色   |
+| --index-anchor-active-text-color        | _#3678e3_     | 锚点吸顶时文字颜色 |
+| --index-anchor-index-padding            | _0 4px 0 20px_ | 锚点右侧索引内边距 |
+
+## 常见问题
+
+### 嵌套在滚动元素中 IndexAnchor 失效？
+
+由于 `<IndexBar />` 内部使用 ty.pageScrollTo 滚动到指定位置，因此只支持页面级滚动，无法在滚动元素中嵌套使用，例如：`view` 使用 `overflow: scroll;` 或者 `scroll-view`，具体可查看[微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/api/ui/scroll/ty.pageScrollTo.html)。

package/dist/loading/README.md

@@ -0,0 +1,86 @@
+---
+category: 展示
+---
+
+# Loading 加载
+
+### 介绍
+
+加载图标，用于表示加载中的过渡状态。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-loading": "@tuya-miniapp/smart-ui/lib/loading/index"
+}
+```
+
+## 代码演示
+
+### 加载类型
+
+```html
+<smart-loading /> 
+<smart-loading type="spinner" />
+```
+
+### 自定义颜色
+
+```html
+<smart-loading color="red" /> 
+<smart-loading type="spinner" color="green" />
+```
+
+### 加载文案
+
+```html
+<smart-loading size="24px">加载中...</smart-loading>
+<smart-loading color="var(--app-B1-N1)" icon-color="#1989FA" size="24px">加载中...</smart-loading>
+```
+
+### 垂直排列
+
+```html
+<smart-loading size="24px" vertical>加载中...</smart-loading>
+```
+
+## API
+
+### Props
+
+| 参数               | 说明                          | 类型               | 默认值     |
+| ------------------ | ----------------------------- | ------------------ | ---------- |
+| color              | 整体颜色                          | _string_           | `var(--loading-text-color, #1989FA)`  |
+| size               | 加载图标大小，默认单位为 `px` | _string \| number_ | `30px`     |
+| text-size `v1.0.0` | 文字大小，默认单位为为 `px`   | _string \| number_ | `14px`     |
+| type               | 类型，可选值为 `spinner`      | _string_           | `circular` |
+| vertical `v1.0.0`  | 是否垂直排列图标和文字内容    | _boolean_          | `false`    |
+| icon-color `v2.8.0` | 单独控制icon的颜色 | _string_          | `var(--loading-spinner-color, #1989FA)`    |
+
+### Slots
+
+| 名称 | 说明     |
+| ---- | -------- |
+| -    | 加载文案 |
+
+### 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| custom-class | 根节点样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --loading-text-color | _#969799_ | 文本颜色 |
+| --loading-text-font-size | _14px_ | 文本字体大小 |
+| --loading-text-line-height | _20px_ | 文本行高 |
+| --loading-spinner-color | _#1989FA_ | 加载器颜色 |
+| --loading-spinner-size | _30px_ | 加载器大小 |
+| --loading-spinner-animation-duration | _0.8s_ | 加载动画持续时间 |