@tuya-miniapp/smart-ui 2.3.8-beta-3 → 2.3.8-beta-5

package/packages/area/README.en.md

@@ -0,0 +1,184 @@
+# Area Province/City/District Selector
+
+### Introduction
+
+The Province/City/District Selector component is usually used with the [Popup](/material/smartui?comId=popup&appType=miniapp) component.
+
+### Import
+
+Import the component in `app.json` or `index.json`. For detailed instructions, see [Quick Start](/material/smartui?comId=help-getting-started&appType=miniapp).
+
+```json
+"usingComponents": {
+  "smart-area": "@tuya-miniapp/smart-ui/lib/area/index"
+}
+```
+
+## Code Examples
+
+### Basic Usage
+
+To initialize the Province/City/District component, you need to pass the Province/City/District data through the `area-list` attribute.
+
+```html
+<smart-area area-list="{{ areaList }}" />
+```
+
+### areaList Format
+
+areaList is an object structure that contains three keys: `province_list`, `city_list`, and `county_list`.
+
+Each item uses the area code as the key and the province/city/district name as the value. The area code is a 6-digit number, with the first two digits representing the province, the middle two digits representing the city, and the last two digits representing the district, padded with zeros to 6 digits. For example, the area code for Beijing is `11`, padded to 6 digits, it becomes `110000`.
+
+Example data:
+
+```js
+const areaList = {
+  province_list: {
+    110000: 'Beijing',
+    120000: 'Tianjin',
+  },
+  city_list: {
+    110100: 'Beijing',
+    120100: 'Tianjin',
+  },
+  county_list: {
+    110101: 'Dongcheng District',
+    110102: 'Xicheng District',
+    // ....
+  },
+};
+```
+
+### @tuya-miniapp/area-data
+
+MiniApp officially provides a default set of Province/City/District data, which can be imported via [@tuya-miniapp/area-data](TODO: url).
+
+```bash
+yarn add @tuya-miniapp/area-data
+```
+
+```ts
+import { areaList } from '@tuya-miniapp/area-data';
+
+Page({
+  data: {
+    areaList,
+  },
+});
+```
+
+### Select Province/City/District
+
+If you want to select a specific province/city/district, you need to pass a `value` attribute and bind it to the corresponding province/city/district `code`.
+
+```html
+<smart-area area-list="{{ areaList }}" value="110101" />
+```
+
+### Configure Display Columns
+
+You can configure the number of display columns of the Province/City/District using the `columns-num` attribute. By default, it displays province, city, and district. If you set it to `2`, only province and city will be displayed.
+
+```html
+<smart-area area-list="{{ areaList }}" columns-num="{{ 2 }}" title="Title" />
+```
+
+### Configure Placeholder Text for Columns
+
+You can configure the placeholder text for each column using the `columns-placeholder` attribute.
+
+```html
+<smart-area 
+  area-list="{{ areaList }}" 
+  columns-placeholder="{{ ['Please select', 'Please select', 'Please select'] }}" 
+  title="Title" 
+/>
+```
+
+## Cloud Development Example
+
+### Use Cloud Development to Get Province/City/District Data
+
+In actual projects, you can use the capabilities of [WeChat Mini Program Cloud Development](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html) to store the Province/City/District data in the cloud development database, and use the cloud development interface in the mini program to asynchronously fetch data.
+
+You need to call the `wx.cloud.init` method to complete the cloud capability initialization before using cloud capabilities in the mini program.
+
+```js
+const db = wx.cloud.database();
+
+db.collection('region')
+  .limit(1)
+  .get()
+  .then((res) => {
+    if (res.data && res.data.length > 0) {
+      this.setData({
+        areaList: res.data[0],
+      });
+    }
+  })
+  .catch((err) => {
+    console.log(err);
+  });
+```
+
+## API
+
+### Props
+
+| Parameter           | Description                              | Type       | Default  |
+| ------------------- | ---------------------------------------- | ---------- | -------- |
+| area-list           | Province/City/District data, see format below | _object_   | -        |
+| cancel-button-text  | Cancel button text                       | _string_   | `Cancel` |
+| columns-num         | Number of columns to display, 3-Provinces/Cities/Districts, 2-Provinces/Cities, 1-Provinces | _number_   | `3`      |
+| columns-placeholder | Placeholder text for columns             | _string[]_ | `[]`     |
+| confirm-button-text | Confirm button text                      | _string_   | `Confirm`|
+| item-height         | Option height                            | _number_   | `44`     |
+| loading             | Whether to show loading state            | _boolean_  | `false`  |
+| show-toolbar        | Whether to show the top toolbar          | _boolean_  | `true`   |
+| title               | Top toolbar title                        | _string_   | -        |
+| value               | Currently selected province/city/district `code` | _string_   | -        |
+| visible-item-count  | Number of visible items                  | _number_   | `6`      |
+
+### Events
+
+| Event         | Description             | Callback Parameters                         |
+| ------------- | ----------------------- | ------------------------------------------- |
+| bind:cancel   | Triggered when the cancel button is clicked | -                                           |
+| bind:change   | Triggered when the option changes | Picker instance, all selected values of the columns, the index corresponding to the current column |
+| bind:confirm  | Triggered when the confirm button in the top right corner is clicked | An array parameter, see the data format section below for details |
+
+### Methods
+
+You can get the Area instance and call instance methods through selectComponent.
+
+| Method Name | Parameter    | Return Value | Description |
+| ----------- | ------------ | ------------ | ----------- |
+| reset       | code: string | -            | Reset all options based on the code, if the code is not passed, it will reset to the first option |
+
+### Data Format when Clicking Confirm
+
+The data returned is an Object containing two keys: `values` and `index`.
+
+`values` is an array containing `columnsNum` pieces of data. Each piece of data corresponds to the data selected in each column of options.
+
+`code` represents the selected area code, `name` represents the selected area name.
+
+```javascript
+[
+  {
+    code: '110000',
+    name: 'Beijing',
+  },
+  {
+    code: '110100',
+    name: 'Beijing',
+  },
+  {
+    code: '110101',
+    name: 'Dongcheng District',
+  },
+];
+```
+
+`index` is an array containing `columnsNum` pieces of data. Each piece of data corresponds to the index of the selected item in each column of options.

package/packages/area/README.md

@@ -0,0 +1,184 @@
+# Area 省市区选择
+
+### 介绍
+
+省市区选择组件通常与 [弹出层](/material/smartui?comId=popup&appType=miniapp) 组件配合使用。
+
+### 引入
+
+在`app.json`或`index.json`中引入组件，详细介绍见[快速上手](/material/smartui?comId=help-getting-started&appType=miniapp)。
+
+```json
+"usingComponents": {
+  "smart-area": "@tuya-miniapp/smart-ui/lib/area/index"
+}
+```
+
+## 代码演示
+
+### 基础用法
+
+初始化省市区组件时，需要通过 `area-list` 属性传入省市区数据。
+
+```html
+<smart-area area-list="{{ areaList }}" />
+```
+
+### areaList 格式
+
+areaList 为对象结构，包含 `province_list`、`city_list`、`county_list` 三个 key。
+
+每项以地区码作为 key，省市区名字作为 value。地区码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。比如北京的地区码为 `11`，以 0 补足 6 位，为 `110000`。
+
+示例数据如下：
+
+```js
+const areaList = {
+  province_list: {
+    110000: '北京市',
+    120000: '天津市',
+  },
+  city_list: {
+    110100: '北京市',
+    120100: '天津市',
+  },
+  county_list: {
+    110101: '东城区',
+    110102: '西城区',
+    // ....
+  },
+};
+```
+
+### @tuya-miniapp/area-data
+
+MiniApp 官方提供了一份默认的省市区数据，可以通过 [@tuya-miniapp/area-data](TODO: url) 引入。
+
+```bash
+yarn add @tuya-miniapp/area-data
+```
+
+```ts
+import { areaList } from '@tuya-miniapp/area-data';
+
+Page({
+  data: {
+    areaList,
+  },
+});
+```
+
+### 选中省市区
+
+如果想选中某个省市区，需要传入一个`value`属性，绑定对应的省市区`code`。
+
+```html
+<smart-area area-list="{{ areaList }}" value="110101" />
+```
+
+### 配置显示列
+
+可以通过`columns-num`属性配置省市区显示的列数，默认情况下会显示省市区，当你设置为`2`，则只会显示省市选择。
+
+```html
+<smart-area area-list="{{ areaList }}" columns-num="{{ 2 }}" title="标题" />
+```
+
+### 配置列占位提示文字
+
+可以通过`columns-placeholder`属性配置每一列的占位提示文字。
+
+```html
+<smart-area
+  area-list="{{ areaList }}"
+  columns-placeholder="{{ ['请选择', '请选择', '请选择'] }}"
+  title="标题"
+/>
+```
+
+## 云开发示例
+
+### 使用云开发获取省市区数据
+
+实际项目中，可以通过[小程序云开发](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)的能力，将省市区数据保存在云开发的数据库中，并在小程序中使用云开发的接口异步获取数据。
+
+在小程序中使用云能力之前需要先调用`wx.could.init`方法完成云能力的初始化。
+
+```js
+const db = wx.cloud.database();
+
+db.collection('region')
+  .limit(1)
+  .get()
+  .then((res) => {
+    if (res.data && res.data.length > 0) {
+      this.setData({
+        areaList: res.data[0],
+      });
+    }
+  })
+  .catch((err) => {
+    console.log(err);
+  });
+```
+
+## API
+
+### Props
+
+| 参数                | 说明                                   | 类型       | 默认值  |
+| ------------------- | -------------------------------------- | ---------- | ------- |
+| area-list           | 省市区数据，格式见下方                 | _object_   | -       |
+| cancel-button-text  | 取消按钮文字                           | _string_   | `取消`  |
+| columns-num         | 省市区显示列数，3-省市区，2-省市，1-省 | _number_   | `3`     |
+| columns-placeholder | 列占位提示文字                         | _string[]_ | `[]`    |
+| confirm-button-text | 确认按钮文字                           | _string_   | `确认`  |
+| item-height         | 选项高度                               | _number_   | `44`    |
+| loading             | 是否显示加载状态                       | _boolean_  | `false` |
+| show-toolbar        | 是否显示顶部栏                         | _boolean_  | `true`  |
+| title               | 顶部栏标题                             | _string_   | -       |
+| value               | 当前选中的省市区`code`                 | _string_   | -       |
+| visible-item-count  | 可见的选项个数                         | _number_   | `6`     |
+
+### Events
+
+| 事件         | 说明               | 回调参数                                    |
+| ------------ | ------------------ | ------------------------------------------- |
+| bind:cancel  | 点击取消按钮时     | -                                           |
+| bind:change  | 选项改变时触发     | Picker 实例，所有列选中值，当前列对应的索引 |
+| bind:confirm | 点击右上方完成按钮 | 一个数组参数，具体格式看下方数据格式章节    |
+
+### 方法
+
+通过 selectComponent 可以获取到 Area 实例并调用实例方法。
+
+| 方法名 | 参数         | 返回值 | 介绍                                                |
+| ------ | ------------ | ------ | --------------------------------------------------- |
+| reset  | code: string | -      | 根据 code 重置所有选项，若不传 code，则重置到第一项 |
+
+### 点击完成时返回的数据格式
+
+返回的数据整体为一个 Object，包含 `values`, `index` 两个 key。
+
+`values` 整体为一个数组，数组内包含 `columnsNum` 个数据， 每个数据对应一列选项中被选中的数据。
+
+`code` 代表被选中的地区编码， `name` 代表被选中的地区名称。
+
+```javascript
+[
+  {
+    code: '110000',
+    name: '北京市',
+  },
+  {
+    code: '110100',
+    name: '北京市',
+  },
+  {
+    code: '110101',
+    name: '东城区',
+  },
+];
+```
+
+`index` 为一个数组，数组内包含 `columnsNum` 个数据， 每个数据对应一列选项中被选中项的序号。

package/packages/area/demo/index.json

@@ -0,0 +1,8 @@
+{
+  "component": true,
+  "usingComponents": {
+    "smart-area": "../../area/index",
+    "smart-toast": "../../toast/index",
+    "demo-block": "../../../example/components/demo-block/index"
+  }
+}

package/packages/area/demo/index.ts

@@ -0,0 +1,52 @@
+import { SmartComponent } from '../../common/component';
+import Toast from '../../toast/toast';
+
+const db = wx.cloud?.database();
+
+SmartComponent({
+  data: {
+    areaList: {},
+    loading: true,
+    value: 330302,
+  },
+
+  mounted() {
+    db?.collection('region')
+      .limit(1)
+      .get()
+      .then((res) => {
+        if (res.data && res.data.length > 0) {
+          this.setData({
+            loading: false,
+            areaList: res.data[0],
+          });
+        }
+      })
+      .catch((err) => {
+        console.log(err);
+        this.setData({
+          loading: false,
+        });
+      });
+  },
+
+  methods: {
+    onChange(event) {
+      const { values } = event.detail;
+
+      Toast({
+        context: this,
+        selector: '#smart-toast-area',
+        message: values.map((item) => item.name).join('-'),
+      });
+    },
+
+    onConfirm(event) {
+      console.log(event);
+    },
+
+    onCancel(event) {
+      console.log(event);
+    },
+  },
+});

package/packages/area/demo/index.wxml

@@ -0,0 +1,11 @@
+<demo-block title="{{I18n.t('basicUsage')}}">
+  <smart-area
+    value="{{ value }}"
+    loading="{{ loading }}"
+    area-list="{{ areaList }}"
+    bind:change="onChange"
+    bind:confirm="onConfirm"
+    bind:cancel="onCancel"
+  />
+</demo-block>
+<smart-toast id="smart-toast-area" />

package/packages/area/index.json

@@ -0,0 +1,6 @@
+{
+  "component": true,
+  "usingComponents": {
+    "smart-picker": "../picker/index"
+  }
+}

package/packages/area/index.less

@@ -0,0 +1 @@
+// empty