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

package/dist/field/README.md

@@ -0,0 +1,439 @@
+---
+category: 数据录入
+---
+
+# Field 输入框
+
+### 介绍
+
+用户可以在文本框内输入或编辑文字。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-field": "@tuya-miniapp/smart-ui/lib/field/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+`hidden-label` 可以隐藏整个左侧内容。
+
+```html
+<smart-cell-group>
+  <smart-field 
+    value="{{ value }}" 
+    label="标题"
+    placeholder="请输入" 
+    bind:change="onChange"
+  />
+  <smart-field 
+    value="{{ value2 }}"
+    hidden-label
+    placeholder="{{I18n.t('pleaseEnter')}}" 
+  />
+</smart-cell-group>
+```
+
+```js
+Page({
+  data: {
+    value: '',
+    value2: '',
+  },
+
+  onChange(event) {
+    // event.detail 为当前输入的值
+    console.log(event.detail);
+  },
+  onChange2(event) {
+    this.setData({
+      value2: event.detail
+    })
+  }
+});
+```
+
+### 自定义类型
+
+根据`type`属性定义不同类型的输入框；`card-mode` 开启此模式可以开启卡片输入模式。
+
+```html
+<smart-cell-group>
+  <smart-field
+    value="{{ password }}"
+    type="password"
+    label="密码"
+    placeholder="请输入"
+  />
+  <smart-field
+    value="{{ num }}"
+    card-mode
+    type="number"
+    sub-label="副标题"
+    label="标题"
+    placeholder="请输入"
+  />
+</smart-cell-group>
+```
+
+### 禁用输入框
+
+`disabled` 可以设置整个输入框禁用。
+
+```html
+<smart-cell-group>
+  <smart-field
+    placeholder="输入框已禁用"
+    label="标题"
+    disabled
+  />
+  <smart-field
+    card-mode
+    disabled
+    sub-label="副标题"
+    label="标题"
+    placeholder="请输入"
+  />
+</smart-cell-group>
+```
+
+### 显示图标
+
+使用插槽 `left-icon` 可以插入左侧的图标。
+
+```html 
+<smart-cell-group>
+  <smart-field
+    label="标题"
+    placeholder="请输入"
+  >
+    <smart-icon name="{{ sunIcon }}" slot="left-icon" color="#3678E3" size="22" />
+  </smart-field>
+  <smart-field
+    value="{{ num }}"
+    card-mode
+    label="标题"
+    placeholder="请输入"
+  >
+    <image 
+      slot="left-icon"
+      style="height: 50px;width: 50px;"
+      src="https://images.tuyacn.com/rms-static/974a30f0-a624-11ef-be03-d1a4feb99779-1731986155903.png?tyName=light-img" 
+    />
+  </smart-field>
+</smart-cell-group>
+```
+
+### 错误提示
+
+通过`error-message`属性增加对应的错误提示;设置 `inter-error` 可以将错误信息覆盖 `placeholder` 的内容。
+
+```html
+<smart-cell-group>
+  <smart-field
+    label="标题"
+    error-message="请输入用户名"
+    inter-error
+    required
+  />
+  <smart-field
+    value="{{ value2 }}"
+    label="标题"
+    placeholder="请输入"
+    error-message="格式错误"
+    required
+  />
+  <smart-field
+    value="{{ num }}"
+    card-mod
+    label="标题"
+    sub-label="标题"
+    placeholder="请输入"
+    error-message="格式错误"
+    required
+  >
+    <image 
+      slot="left-icon"
+      style="height: 50px;width: 50px;"
+      src="https://images.tuyacn.com/rms-static/974a30f0-a624-11ef-be03-d1a4feb99779-1731986155903.png?tyName=light-img" 
+    />
+  </smart-field>
+</smart-cell-group>
+```
+
+### 插入按钮
+
+通过 button slot 可以在输入框尾部插入按钮。
+
+```html
+<smart-cell-group>
+  <smart-cell-group>
+    <smart-field
+      label="标题"
+      placeholder="请输入短信验证码"
+      type="number"
+      input-align="left"
+    >
+      <smart-button slot="button" type="info" custom-class="button">发送验证码</smart-button>
+    </smart-field>
+  </smart-cell-group>
+</smart-cell-group>
+```
+
+### 数字格式化 `v2.12.0`
+
+开启 `number-format` 后，组件会根据当前语言环境进行数字输入的千分位、小数位格式化展示；当然通过 `locale` 可指定地区格式（如 `de` 为德语 1.234,56，默认与英文为 1,234.56）。
+
+```html
+<smart-cell-group>
+  <smart-field
+    value="{{ numberFormatValue }}"
+    number-format
+    label="金额"
+    placeholder="请输入"
+  />
+  <smart-field
+    value="{{ numberFormatValueDe }}"
+    number-format
+    locale="de"
+    label="金额（德语格式）"
+    placeholder="请输入"
+  />
+</smart-cell-group>
+```
+
+### 留言
+
+设置 type 为 `textarea` 模式时，可以在末尾显示输入的字数数量和限制数量。
+
+```html
+<smart-field
+  value="{{ message }}"
+  label="事项"
+  type="textarea"
+  placeholder="请输入留言"
+  show-word-limit
+  maxlength="{{ 200 }}"
+/>
+```
+
+### 替换输入框值
+
+在微信小程序中，bind:input 事件可以通过返回字符串或者一个对象来替换输入框的值以及调整光标的位置，在 Smart UI 中，可以通过调用 change 或 input 参数中的 callback 函数，传入参数来实现
+
+```html
+<smart-field
+  value="{{ value }}"
+  placeholder="请输入用户名"
+  clearable
+  extra-event-params
+  bind:change="onChange"
+/>
+```
+
+```js
+Page({
+  data: {
+    value: '',
+  },
+  onChange(e) {
+    const { value, callback } = e.detail;
+
+    callback({
+      value: value + 1,
+      cursor: 0,
+    });
+  },
+});
+```
+
+## API
+
+### Props
+
+| 参数                          | 说明                                                                                                           | 类型                | 默认值  |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------- | ------- |
+| adjust-position               | 键盘弹起时，是否自动上推页面                                                                                   | _boolean_           | `true`  |
+| always-embed `v1.9.2`         | 强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效)                                | _boolean_           | `false` |
+| arrow-direction               | 箭头方向，可选值为 `left` `up` `down`                                                                          | _string_            | -       |
+| auto-focus  `@deprecated 小程序不支持`                | 自动聚焦，拉起键盘                                                                                             | _boolean_           | `false` |
+| autosize                      | 是否自适应内容高度，只对 textarea 有效，<br>可传入对象,如 { maxHeight: 100, minHeight: 50 }，<br>单位为`px`    | _boolean \| object_ | `false` |
+| border                        | 是否显示内边框                                                                                                 | _boolean_           | `false`  |
+| center                        | 是否使内容垂直居中                                                                                             | _boolean_           | `false` |
+| clear-icon-aria-label `v2.13.0` | 清除按钮的无障碍读屏文案，透传至清除图标的 `aria-label`                                                      | _string_            | -       |
+| clear-trigger `v1.8.4`        | 显示清除图标的时机，`always` 表示输入框不为空时展示，<br>`focus` 表示输入框聚焦且不为空时展示                  | _string_            | `focus` |
+| clearable                     | 是否启用清除控件                                                                                               | _boolean_           | `false` |
+| clickable                     | 是否开启点击反馈                                                                                               | _boolean_           | `false` |
+| confirm-hold                  | 点击键盘右下角按钮时是否保持键盘不收起，在 type='textarea' 时无效                                              | _boolean_           | `false` |
+| confirm-type                  | 设置键盘右下角按钮的文字，仅在 type='text' 时生效                                                              | _string_            | `done`  |
+| cursor                        | 指定 focus 时的光标位置                                                                                        | _number_            | `-1`    |
+| cursor-spacing                | 输入框聚焦时底部与键盘的距离                                                                                   | _number_            | `50`    |
+| custom-style                  | 自定义样式                                                                                                     | _string_            | -       |
+| disable-default-padding       | 是否去掉 iOS 下的默认内边距，只对 textarea 有效                                                                | _boolean_           | `true`  |
+| disabled                      | 是否禁用输入框                                                                                                 | _boolean_           | `false` |
+| error                         | 是否将输入内容标红                                                                                             | _boolean_           | `false` |
+| error-message                 | 底部错误提示文案，为空时不展示                                                                                 | _string_            | `''`    |
+| error-message-align           | 底部错误提示文案对齐方式，可选值为 `center` `right`                                                            | _string_            | `''`    |
+| extra-event-params `v1.10.12` | 开启事件增强模式，会在 input 和 change 事件额外提供 `cursor` 和 `keyCode` 参数，计划在下一个大版本作为默认行为 | _boolean_           | `false` |
+| fixed                         | 如果 type 为 `textarea` 且在一个 `position:fixed` 的区域，需要显示指定属性 fixed 为 true                       | _boolean_           | `false` |
+| focus `@deprecated 小程序不支持`     | 获取焦点                                                                                                       | _boolean_           | `false` |
+| hold-keyboard                 | focus 时，点击页面的时候不收起键盘                                                                             | _boolean_           | `false` |
+| input-align                   | 输入框内容对齐方式，可选值为 `center` `right`                                                                  | _string_            | -  |
+| is-link                       | 是否展示右侧箭头并开启点击反馈                                                                                 | _boolean_           | `false` |
+| label                         | 输入框左侧文本                                                                                                 | _string_            | -       |
+| left-icon                     | 左侧图标svg值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon&appType=miniapp)                                                           | _string_            | -       |
+| maxlength                     | 最大输入长度，设置为 -1 的时候不限制最大长度                                                                   | _number_            | `-1`    |
+| name                          | 在表单内提交时的标识符。可以通过配置 `name` 来扩大点击区域                                                     | _string_            | -       |
+| number-format `v2.12.0`       | 是否开启数字格式化（千分位、小数位按 locale 展示）                                                             | _boolean_           | `false` |
+| locale `v2.12.0`              | 数字格式化使用的地区，如 `de`、`fr`，空则跟随系统                                                               | _string_            | `''`    |
+| password                      | 是否是密码类型                                                                                                 | _boolean_           | `false` |
+| placeholder                   | 输入框为空时占位符                                                                                             | _string_            | -       |
+| placeholder-style             | 指定 placeholder 的样式                                                                                        | _string_            | -       |
+| readonly        | 是否只读                              | _boolean_           | `false` |
+| required                      | 是否显示表单必填星号                                                                                           | _boolean_           | `false` |
+| right-icon                    | 右侧图标svg值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon&appType=miniapp)                                                           | _string_            | -       |
+| right-icon-button-aria-label `v2.13.0` | 右侧图标按钮的无障碍读屏文案，设置在图标容器的 `aria-label` 上                                                | _string_            | -       |
+| selection-end                 | 光标结束位置，自动聚集时有效，需与 selection-start 搭配使用                                                    | _number_            | `-1`    |
+| selection-start               | 光标起始位置，自动聚集时有效，需与 selection-end 搭配使用                                                      | _number_            | `-1`    |
+| show-confirm-bar              | 是否显示键盘上方带有”完成“按钮那一栏，只对 textarea 有效                                                       | _boolean_           | `true`  |
+| show-word-limit               | 是否显示字数统计，需要设置`maxlength`属性                                                                      | _boolean_           | `false` |
+| size                          | 单元格大小，可选值为 `large`                                                                                   | _string_            | -       |
+| title-width                   | 标题宽度                                                                                                       | _string_            | `6.2em` |
+| type                          | 可设置为任意原生类型, 如 `number` `idcard` `textarea` `digit` `nickname`                                       | _string_            | `text`  |
+| value                         | 当前输入的值                                                                                                   | _string \| number_  | -       |
+| inter-error `v2.1.0`  | 错误信息是否在输入框内        | _boolean_  | -       |
+| sub-label `v2.1.0`  | 副标题        | _string_  | -       |
+| card-mode `v2.1.0`  | 卡片模式        | _boolean_  | -       |
+| hidden-label `v2.1.0`  | 隐藏左侧label相关内容        | _boolean_  | -       |
+
+### Events
+
+| 事件                          | 说明                                                   | 回调参数                                                                                                 |
+| ----------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| bind:blur                     | 输入框失焦时触发                                       | event.detail.value: 当前输入值; <br>event.detail.cursor: 游标位置(如果 `type` 不为 `textarea`，值为 `0`) |
+| bind:change                   | 输入内容时触发                                         | event.detail: 当前输入值; 在 extra-event-params 为 `true` 时为 [InputDetail](#InputDetail)        |
+| bind:clear                    | 点击清空控件时触发                                     | -                                                                                                        |
+| bind:click-icon               | 点击尾部图标时触发                                     | -                                                                                                        |
+| bind:click-input              | 点击输入区域时触发                                     | -                                                                                                        |
+| bind:confirm                  | 点击完成按钮时触发                                     | event.detail: 当前输入值                                                                                 |
+| bind:focus                    | 输入框聚焦时触发                                       | event.detail.value: 当前输入值; <br>event.detail.height: 键盘高度                                        |
+| bind:input                    | 输入内容时触发                                         | event.detail: 当前输入值; 在 extra-event-params 为 `true` 时为 [InputDetail](#InputDetail)        |
+| bind:keyboardheightchange     | 键盘高度发生变化的时候触发此事件                       | event.detail = { height: height, duration: duration }                                                    |
+| bind:linechange               | 输入框行数变化时调用，只对 textarea 有效               | event.detail = { height: 0, heightRpx: 0, lineCount: 0 }                                                 |
+| bind:nicknamereview `v1.11.5` | 用户昵称审核完毕后触发，仅在 type 为 "nickname" 时有效 | event.detail = { pass, timeout }                                                                         |
+
+### InputDetail
+
+| 参数     | 说明                                                                                                                                                                    | 类型       | 默认值 |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
+| callback | 调用该函数传 `{ value: string, cursor: number }` 来替换输入框的内容，具体用法可以参考 [wx-input](https://developers.weixin.qq.com/miniprogram/dev/component/input.html) | _function_ | -      |
+| cursor   | 光标位置                                                                                                                                                                | _number_   | -      |
+| keyCode  | 键值                                                                                                                                                                    | _number_   | -      |
+| value    | 当前输入值                                                                                                                                                              | _string_   | -      |
+
+### Slot
+
+| 名称       | 说明                                                       |
+| ---------- | ---------------------------------------------------------- |
+| button     | 自定义输入框尾部按钮                                       |
+| input      | 自定义输入框，使用此插槽后，与输入框相关的属性和事件将失效 |
+| label      | 自定义输入框标签，如果设置了`label`属性则不生效            |
+| left-icon  | 自定义输入框头部图标                                       |
+| right-icon | 自定义输入框尾部图标                                       |
+
+### 外部样式类
+
+| 类名                    | 说明           |
+| ----------------------- | -------------- |
+| custom-class `v1.10.21` | 根节点样式类   |
+| input-class             | 输入框样式类   |
+| label-class             | 左侧文本样式类 |
+| right-icon-class        | 右侧图标样式类 |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --field-label-color   | _var(--app-B6-N1, rgba(0, 0, 0, 1))_   | label颜色    |
+| --field-input-text-color  | _var(--app-B6-N1, rgba(0, 0, 0, 1))_  | input文字颜色    |
+| --field-input-text-font-size `v2.1.0`  | _16px_   | 输入框内的字体大小    |
+| --field-input-error-text-color  | _var(--app-M2, #f04c4c)_   | error模式文字颜色    |
+| --field-placeholder-text-color  | _var(--app-B6-N4, rgba(0, 0, 0, 0.4))_   | placeholder文字颜色    |
+| --field-icon-size  | _16px_   | icon字体大小    |
+| --field-clear-icon-size  | _16px_   | 清楚icon字体大小    |
+| --field-clear-icon-color  | _var(--app-B4-N4, rgba(0, 0, 0, 0.4))_   | 清除icon颜色    |
+| --field-icon-container-color  | _#969799_   | 右侧icon盒子字体颜色    |
+| --field-error-message-color  | _var(--app-M2, #f04c4c)_   | 错误提示文字颜色    |
+| --field-error-message-text-font-size  | _14px_   | 提示文字字体大小    |
+| --field-text-area-min-height  | _130px_   | textarea最小高度    |
+| --field-word-limit-color  | _var(--app-B6-N4, rgba(0, 0, 0, 0.4))_   | 输入长度限制文字颜色    |
+| --field-disabled-opacity `v2.1.0`  | _0.7_   | 禁用透明度    |
+| --field-label-font-size `v2.1.0`  | _16px_   | label字体大小    |
+| --field-label-line-height `v2.1.0`  | _18px_   | label标题字体高度    |
+| --field-sub-label-font-size `v2.1.0`  | _14px_   | 副标题字体大小    |
+| --field-sub-label-line-height `v2.1.0`  | _16px_   | 副标题字体高度    |
+| --field-error-message-text-line-height `v2.1.0`  | _16px_   | 错误提示字体高度    |
+| --field-subtitle-text-color `v2.1.0`  | _var(--app-B6-N3, rgba(0, 0, 0, 0.5))_   | 副标题颜色    |
+| --field-left-icon-margin-right `v2.1.0`  | _10px_   | icon的右侧外边距    |
+| --field-left-body-padding-right `v2.1.0`  | _16px_   | 左侧部分的右内边距    |
+
+#### card模式CSS变量
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --field-card-border-radius `v2.1.0`   | _8px_   | 卡片边框圆角    |
+| --field-card-background `v2.1.0`   | _var(--app-B6-N7, rgba(0, 0, 0, 0.1))_   | 卡片输入输背景色    |
+| --field-card-width `v2.1.0`   | _105px_   | 卡片输入宽度    |
+| --field-card-height `v2.1.0`   | _38px_   | 卡片输入高度    |
+| --field-card-padding `v2.1.0`   | _0 10px_   | 卡片输入框内部padding    |
+
+#### textarea CSS变量
+| 名称                          | 默认值                                 | 描述 |
+| ----------------------------- | -------------------------------------- | ---- |
+| --field-word-limit-font-size  | _10px_   | 输入长度限制文字字体大小    |
+| --field-word-limit-line-height  | _14px_   | 输入长度限制文字字体高度    |
+| --field-word-num-full-color  | _var(--app-M2, #f04c4c)_   | 输入长度超出限制文字颜色    |
+| --field-textarea-background `v2.1.0`   | _var(--app-B3, #ffffff)_   | 输入框背景色    |
+| --field-textarea-border-radius `v2.1.0`   | _8px_   | 输入框圆角    |
+| --field-textarea-padding `v2.1.0`   | _12px 8px_   | 输入内边距    |
+| --field-textarea-limit-padding-bottom `v2.1.0`   | _20px_   | 输入框底部显示限制字符串数量时的内边距    |
+
+
+## 常见问题
+
+### 真机上为什么会出现聚焦时 placeholder 加粗、闪烁的现象？
+
+由于微信小程序的 input 组件和 textarea 组件是原生组件，聚焦时会将原生的输入框覆盖在对应位置上，导致了这个现象的产生。
+
+相关的讨论可以查看[微信开放社区](https://developers.weixin.qq.com/community/search?query=placeholder%20%E9%97%AA%E7%83%81%20%E5%8A%A0%E7%B2%97)。
+
+### 真机上 placeholder 为什么会盖过 popup 等其它组件？
+
+由于微信小程序的 input 组件和 textarea 组件是原生组件，遵循原生组件的限制，详情可以查看[原生组件说明](https://developers.weixin.qq.com/miniprogram/dev/component/native-component.html)。
+
+### textarea 的 placeholder 在真机上为什么会偏移？
+
+微信小程序的 textarea 组件在 Android 和 iOS 中默认样式不同，在 iOS 中会有默认的 `padding`，且无法置 0。
+
+同时 `placeholder-style` 对 `vertical-align`、`line-height` 等大量 css 属性都不生效。
+
+这一系列的问题导致了 placeholder 在真机上可能会出现偏移。
+
+微信已经在 `2.10.0` 基础库版本后支持移除默认的 `padding`，但低版本仍有问题。详情可以查看 [微信开放社区](https://developers.weixin.qq.com/community/develop/issue/96)。
+
+### 手写输入法为什么会丢失部分字符 / 手写输入法为什么不会触发 input 事件？
+
+这是微信小程序的 input 组件本身的问题，如果需要兼容手写输入法的场景，可以在 `blur` 事件中取到输入的值。
+
+相关的讨论可以查看[微信开放社区](https://developers.weixin.qq.com/community/search?query=input%20%E6%89%8B%E5%86%99%E8%BE%93%E5%85%A5&page=1&block=1&random=1567079239098)。
+
+### 如何扩大点击区域？点击 label、错误信息 都能聚焦唤起键盘呢？
+
+升级至 1.10.21 版本及以上，配置 `name` 属性即可

package/dist/grid/README.md

@@ -0,0 +1,197 @@
+---
+category: 布局
+---
+
+# Grid 宫格
+
+### 介绍
+
+宫格可以在水平方向上把页面分隔成等宽度的区块，用于展示内容或进行页面导航。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-grid": "@tuya-miniapp/smart-ui/lib/grid/index",
+  "smart-grid-item": "@tuya-miniapp/smart-ui/lib/grid-item/index"
+}
+```
+
+## 代码演示
+
+### 基本用法
+
+通过`icon`属性设置格子内的图标，`text`属性设置文字内容。
+
+```html
+<smart-grid>
+  <smart-grid-item icon="photo-o" text="文字" />
+  <smart-grid-item icon="photo-o" text="文字" />
+  <smart-grid-item icon="photo-o" text="文字" />
+  <smart-grid-item icon="photo-o" text="文字" />
+</smart-grid>
+```
+
+### 自定义列数
+
+默认一行展示四个格子，可以通过`column-num`自定义列数。
+
+```html
+<smart-grid column-num="3">
+  <smart-grid-item icon="photo-o" text="文字" ty:for="{{ 6 }}" />
+</smart-grid>
+```
+
+### 自定义内容
+
+通过插槽可以自定义格子展示的内容。
+
+```html
+<smart-grid column-num="3" border="{{ false }}">
+  <smart-grid-item use-slot ty:for="{{ 3 }}" ty:for-item="index">
+    <image
+      style="width: 90px; height: 90px;"
+      src="https://static1.tuyacn.com/static/tuya-miniapp-doc/_next/static/images/logo-small.png"
+    />
+  </smart-grid-item>
+</smart-grid>
+```
+
+### 正方形格子
+
+设置`square`属性后，格子的高度会和宽度保持一致。
+
+```html
+<smart-grid square>
+  <smart-grid-item icon="photo-o" text="文字" ty:for="{{ 8 }}" />
+</smart-grid>
+```
+
+### 格子间距
+
+通过`gutter`属性设置格子之间的距离。
+
+```html
+<smart-grid gutter="{{ 10 }}">
+  <smart-grid-item icon="photo-o" text="文字" ty:for="{{ 8 }}" />
+</smart-grid>
+```
+
+### 内容横排
+
+将`direction`属性设置为`horizontal`，可以让宫格的内容呈横向排列。
+
+```html
+<smart-grid direction="horizontal" column-num="2">
+  <smart-grid-item icon="photo-o" text="文字" />
+  <smart-grid-item icon="photo-o" text="文字" />
+  <smart-grid-item icon="photo-o" text="文字" />
+</smart-grid>
+```
+
+### 页面跳转
+
+可以通过`url`属性进行页面跳转，通过`link-type`属性控制跳转类型。
+
+```html
+<smart-grid clickable column-num="2">
+  <smart-grid-item
+    icon="home-o"
+    link-type="navigateTo"
+    url="/pages/dashboard/index"
+    text="Navigate 跳转"
+  />
+  <smart-grid-item
+    icon="search"
+    link-type="reLaunch"
+    url="/pages/dashboard/index"
+    text="ReLaunch 跳转"
+  />
+</smart-grid>
+```
+
+### 提示信息
+
+设置`dot`属性后，会在图标右上角展示一个小红点。设置`badge`属性后，会在图标右上角展示相应的徽标。
+
+```html
+<smart-grid column-num="2">
+  <smart-grid-item icon="home-o" text="文字" dot />
+  <smart-grid-item icon="search" text="文字" badge="99+" />
+</smart-grid>
+```
+
+## API
+
+### Grid Props
+
+| 参数               | 说明                                      | 类型               | 默认值     |
+| ------------------ | ----------------------------------------- | ------------------ | ---------- |
+| border             | 是否显示边框                              | _boolean_          | `true`     |
+| center             | 是否将格子内容居中显示                    | _boolean_          | `true`     |
+| clickable          | 是否开启格子点击反馈                      | _boolean_          | `false`    |
+| column-num         | 列数                                      | _number_           | `4`        |
+| direction          | 格子内容排列的方向，可选值为 `horizontal` | _string_           | `vertical` |
+| gutter             | 格子之间的间距，默认单位为`px`            | _string \| number_ | `0`        |
+| icon-size `v1.3.2` | 图标大小，默认单位为`px`                  | _string_           | `28px`     |
+| reverse `v1.7.0`   | 是否调换图标和文本的位置                  | _boolean_          | `false`    |
+| square             | 是否将格子固定为正方形                    | _boolean_          | `false`    |
+| use-slot           | 是否使用自定义内容的插槽                  | _boolean_          | `false`    |
+
+### Grid 外部样式类
+
+| 类名         | 说明         |
+| ------------ | ------------ |
+| custom-class | 根节点样式类 |
+
+### GridItem Props
+
+| 参数                 | 说明                                                                                                                                       | 类型               | 默认值       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------ |
+| aria-label `v2.13.0` | 无障碍读屏文案，设置在根节点的 `aria-label` 上                                                                                            | _string_           | -            |
+| badge                | 图标右上角徽标的内容                                                                                                                       | _string \| number_ | -            |
+| dot                  | 是否显示图标右上角小红点                                                                                                                   | _boolean_          | `false`      |
+| icon                 | 图标 svg 值或图片链接，可选值见 [Icon 组件](/material/smartui?comId=icon&appType=miniapp)                                                  | _string_           | -            |
+| icon-color           | 图标颜色                                                                                                                                   | _string_           | -            |
+| icon-prefix `v1.7.0` | 第三方图标前缀                                                                                                                             | _string_           | `smart-icon` |
+| link-type            | 链接跳转类型，可选值为 `redirectTo` [`switchTab`](https://developers.weixin.qq.com/miniprogram/dev/api/route/wx.switchTab.html) `reLaunch` | _string_           | `navigateTo` |
+| text                 | 文字                                                                                                                                       | _string_           | -            |
+| url                  | 点击后跳转的链接地址                                                                                                                       | _string_           | -            |
+
+### GridItem Events
+
+| 事件名     | 说明           | 回调参数 |
+| ---------- | -------------- | -------- |
+| bind:click | 点击格子时触发 | -        |
+
+### GridItem Slots
+
+| 名称 | 说明                                                   |
+| ---- | ------------------------------------------------------ |
+| -    | 自定义宫格的所有内容，需要设置`use-slot`属性           |
+| icon | 自定义图标，如果设置了`use-slot`或者`icon`属性则不生效 |
+| text | 自定义文字，如果设置了`use-slot`或者`text`属性则不生效 |
+
+### GridItem 外部样式类
+
+| 类名          | 说明         |
+| ------------- | ------------ |
+| content-class | 内容样式类   |
+| custom-class  | 根节点样式类 |
+| icon-class    | 图标样式类   |
+| text-class    | 文本样式类   |
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](/material/smartui?comId=config-provider&appType=miniapp)。
+
+| 名称                                 | 默认值                                 | 描述         |
+| ------------------------------------ | -------------------------------------- | ------------ |
+| --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_                                 | 文本字体大小 |