Xiaomi Vela JS

https://iot.mi.com/vela/quickapp/zh/
Admin
Xiaomi Vela JS is a developer-friendly, high-performance IoT cross-platform application framework...
Tokens:123,032
Snippets:1,207
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run Project Directly

Source: https://iot.mi.com/vela/quickapp/zh/tools/toolkit/start.html

Starts the development server for immediate testing. The first run will prompt for simulator setup.

```bash
aiot start
```

--------------------------------

### Automated Simulator Environment Setup

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/use-ide.html

AIoT-IDE can automatically install necessary simulator dependencies. Use the 'Check simulator environment, create simulator instance' button and select 'Automatic installation' for a streamlined setup.

```IDE Actions
Click 'Check simulator environment, create simulator instance'
Select 'Automatic installation' in the modal window
```

--------------------------------

### Full manifest.json Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/manifest.html

A comprehensive example of a manifest.json file, including package details, versioning, features, and router configuration. This serves as a template for project setup.

```json
{
  "package": "com.company.unit",
  "name": "appName",
  "icon": "/Common/icon.png",
  "versionName": "1.0",
  "versionCode": 1,
  "minPlatformVersion": 1000,
  "features": [{ "name": "system.network" }],
  "router": {
    "entry": "Hello",
    "pages": {
      "Hello": {
        "component": "hello",
        "path": "/"
      }
    }
  }
}
```

--------------------------------

### Install and Build Generated App

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

After generating a project, these commands install dependencies and build the rpk package. This is a standard procedure for running the generated application.

```bash
cd my-app
npm install
npm run build    # 构建 rpk 包

```

--------------------------------

### Bar Chart Example

Source: https://iot.mi.com/vela/quickapp/zh/components/basic/chart.html

Shows how to set up and render a bar chart using the Chart component. This example provides sample data and configuration for the axes.

```vue
<template>
  <chart type="bar" options="{{barOpts}}" datasets="{{barData}}"></chart>
</template>

<script>
  export default {
    data: {
      barData: [
        {
          fillColor: '#f07826',
          data: [763, 550, 551, 554, 731, 654, 525]
        },
        {
          fillColor: '#cce5ff',
          data: [535, 776, 615, 444, 694, 785, 677]
        }
      ],
      barOpts: {
        xAxis: {
          min: 0,
          max: 7,
          display: false,
          axisTick: 7
        },
        yAxis: {
          min: 0,
          max: 800,
          display: false,
        }
      }
    }
  }
</script>

```

--------------------------------

### Install Less and Less Loader

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Provides the npm command to install the necessary packages for using Less preprocessor.

```bash
npm i less less-loader

```

--------------------------------

### audio.play()

Source: https://iot.mi.com/vela/quickapp/zh/features/other/audio.html

Starts playing the audio. This method initiates audio playback.

```APIDOC
## audio.play()

### Description
Starts playing the audio.

### Method
Not specified (assumed to be a direct method call in the SDK)

### Endpoint
Not applicable (SDK method)

### Parameters
None

### Request Example
```javascript
audio.play()
```

### Response
None directly returned, but triggers audio playback.
```

--------------------------------

### DP Unit Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Shows how to use the dp unit for device-independent pixel sizing. The example defines a box with width, height, and margin using dp units.

```html
<style>
  .dp-box{
    width:360dp;
    height:360dp;
    background-color:green;
    margin-bottom:40px;
  }
</style>

```

--------------------------------

### record.start

Source: https://iot.mi.com/vela/quickapp/zh/features/system/record.html

Starts the audio recording process. It allows configuration of various recording parameters and provides callbacks for success, failure, and completion.

```APIDOC
## record.start(OBJECT)

### Description
Starts the audio recording process with configurable parameters.

### Parameters
#### Object Parameters
- **duration** (Number) - Optional - Recording duration in milliseconds. If set to a valid value, recording stops at the specified duration. Defaults to 0, meaning recording continues until stopped manually.
- **sampleRate** (Number) - Optional - Sampling rate in Hz. Recommended values: 8000, 16000, 32000, 44100, 48000. Defaults to 8000.
- **numberOfChannels** (Number) - Optional - Number of recording channels. Valid values: 1 or 2. Defaults to 1.
- **encodeBitRate** (Number) - Optional - Encoding bitrate in bits per second. Defaults to 128000. Refer to the documentation for specific bitrate recommendations based on sample rate and channels.
- **frameSize** (Number) - Optional - PCM audio data frame size in bytes. If specified, the `onframerecorded` callback will be triggered for each recorded frame. If an invalid value is provided, `onframerecorded` will not be triggered and `success` will return the URI normally.
- **format** (String) - Optional - Audio format. Valid values: 'pcm', 'opus', 'wav'. Defaults to 'pcm'.
- **success** (Function) - Optional - Callback function invoked upon successful recording completion. Receives an object with the `uri` of the recorded file.
- **fail** (Function) - Optional - Callback function invoked if an error occurs during recording. Receives an error message and an error code.
- **complete** (Function) - Optional - Callback function invoked after recording ends, regardless of success or failure.

### PCM / WAV Bitrate Reference
| Sampling Rate (Hz) | Channels | Bitrate (bp/s) |
|---|---|---|
| 8000 | 1 | 128000 |
| 8000 | 2 | 256000 |
| 16000 | 1 | 256000 |
| 16000 | 2 | 512000 |
| 32000 | 1 | 512000 |
| 32000 | 2 | 1024000 |
| 44100 | 1 | 705600 |
| 44100 | 2 | 1411200 |
| 48000 | 1 | 768000 |
| 48000 | 2 | 1536000 |

### Opus Bitrate Reference
| Sampling Rate (Hz) | Channels | Bitrate (bp/s) |
|---|---|---|
| 8000 | 1 | 8363 ~ 12800 |
| 8000 | 2 | 13892 ~ 19200 |
| 12000 | 1 | 11975 ~ 20400 |
| 12000 | 2 | 25427 ~ 34400 |
| 16000 | 1 | 14221 ~ 22800 |
| 16000 | 2 | 31651 ~ 44000 |
| 24000 | 1 | 24892 ~ 34000 |
| 24000 | 2 | 47685 ~ 64800 |
| 48000 | 1 | 50077 ~ 67200 |
| 48000 | 2 | 98554 ~ 103600 |

### Success Response
- **uri** (String) - The storage path of the recorded audio file, located within the application's cache directory.

### Fail Error Codes
- **200**: Insufficient system space.
- **205**: Recording is already in progress.
- **202**: Invalid parameters.

### Example
```javascript
record.start({
  duration: 10000,
  sampleRate: 8000,
  numberOfChannels: 1,
  encodeBitRate: 128000,
  format: 'pcm',
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  },
  complete: function () {
    console.log(`handling complete`)
  }
})
```
```

--------------------------------

### Install Node-Sass and Sass-Loader

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Provides the npm command to install the necessary packages for using Sass preprocessor.

```bash
npm i node-sass sass-loader

```

--------------------------------

### Installing OpenSSL on Windows for Signing

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/use-ide.html

If you encounter issues with OpenSSL on Windows for automatic signing key generation, install OpenSSL and configure the system environment variables. Restart your computer and verify the installation by typing 'openssl' in the AIoT-IDE terminal.

```Instructions
Install OpenSSL and configure system environment variables.
Restart your computer.
Open a terminal in AIoT-IDE and type 'openssl' to verify installation.
```

--------------------------------

### Selector Specificity Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style

Provides an example of a component with inline style, ID, and class attributes to demonstrate selector specificity rules.

```html
<div id="sample" style="width: 200px;" class="class-div"></div>
```

--------------------------------

### Install cross-env

Source: https://iot.mi.com/vela/quickapp/zh/guide/multi-screens/conditional-compilation.html

Install cross-env to manage environment variables across different operating systems during the build process.

```bash
npm install cross-env -D

```

--------------------------------

### vibrator.start(OBJECT)

Source: https://iot.mi.com/vela/quickapp/zh/features/system/vibrator.html

Starts a vibration with custom duration, interval, and count. Includes success, fail, and complete callbacks.

```APIDOC
## vibrator.start(OBJECT)

### Description
Starts a vibration with configurable parameters and callbacks for different stages of the vibration process.

### Method
Not applicable (SDK method)

### Parameters
#### Object Parameters
- **duration** (Number) - Required - Vibration duration in milliseconds. Must be a positive integer.
- **interval** (Number) - Required - Vibration interval in milliseconds. Must be a positive integer.
- **count** (Number) - Required - Number of vibrations. Must be a positive integer.
- **success** (Function) - Optional - Callback function executed upon successful vibration start.
- **fail** (Function) - Optional - Callback function executed if vibration fails.
- **complete** (Function) - Optional - Callback function executed when the vibration process completes.

#### Success Response (from success callback)
- **id** (Number) - A unique ID identifying the vibration task.

#### Fail Response (from fail callback)
- **data** (Any) - Error message or details.
- **code** (Number) - Error code. 205: Task already exists. 202: Parameter error.

### Request Example
```javascript
vibrator.start({
  duration: 1000,
  interval: 1000,
  count: 10,
  success: function (data) {
    console.log(`handling success, id = ${data.id}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  },
  complete: function () {
    console.log(`handling complete`)
  }
})
```
```

--------------------------------

### Application Info Structure

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/app.html

An example of the JSON structure returned by app.getInfo(), detailing application properties and source information.

```json
{
  // 应用包名
  "packageName": "com.example.demo",
  // 应用名称
  "name": "demo",
  // 应用版本名称
  "versionName": "1.0.0",
  // 应用版本号
  "versionCode": 1,
  // 应用图片
  "icon": "/common/logo.png",
  // log 级别
  "logLevel": "debug",
  // 应用来源
  "source": {
    // 来源app的包名
    "packageName": "",
    // 来源类型
    "type": "shortcut"
  }
}
```

--------------------------------

### Media Query Examples

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/media-query.html

Illustrates different ways to write media queries, including level 3 and level 4 syntax for single and multiple conditions.

```css
@media (max-width: 30) { ... }
```

```css
@media (width <= 30) { ... }
```

```css
@media screen and (min-width: 400) and (max-width: 700) { ... }
```

```css
@media (400 <= width <= 700) { ... }
```

--------------------------------

### Get Supported Platforms

Source: https://iot.mi.com/vela/quickapp/zh/tools/toolkit/start.html

Retrieves a list of platforms supported by the AIoT toolkit.

```bash
aiot getPlatforms
```

--------------------------------

### Get Connected Devices

Source: https://iot.mi.com/vela/quickapp/zh/tools/toolkit/start.html

Lists all devices currently connected to the development environment.

```bash
aiot getConnectedDevices
```

--------------------------------

### Line Chart Example

Source: https://iot.mi.com/vela/quickapp/zh/components/basic/chart.html

Demonstrates how to configure and display a line chart using the Chart component. It includes sample data and options for axes and line styles.

```vue
<template>
  <chart type="line" options="{{lineOpts}}" datasets="{{lineData}}"></chart>
</template>

<script>
  export default {
    data: {
      lineData: [
        {
          strokeColor: '#f07826',
          data: [763, 550, 551, 554, 731, 654, 525, 696, 595, 628],
        },
        {
          strokeColor: '#cce5ff',
          fillColor: '#cce5ff',
          data: [535, 776, 615, 444, 694, 785, 677, 609, 562, 410],
        },
        {
          strokeColor: '#ff88bb',
          data: [673, 500, 574, 483, 702, 583, 437, 506, 693, 657]
        },
      ],
      lineOpts: {
        xAxis: {
          min: 0,
          max: 10,
          display: true,
          axisTick: 10
        },
        yAxis: {
          min: 400,
          max: 900,
          display: true,
        }
      }
    }
  }
</script>

```

--------------------------------

### Get Application Info

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/app.html

Retrieves detailed information about the current application, including package name, version, icon, and source.

```javascript
console.log(JSON.stringify(app.getInfo()))
```

--------------------------------

### Start Vibration

Source: https://iot.mi.com/vela/quickapp/zh/features/system/vibrator.html

Initiate vibration with specified duration, interval, and count. Includes success, fail, and complete callbacks.

```javascript
vibrator.start({
  duration: 1000,
  interval: 1000,
  count: 10,
  success: function (data) {
    console.log(`handling success, id = ${data.id}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  },
  complete: function () {
    console.log(`handling complete`)
  }
})
```

--------------------------------

### List Item Example

Source: https://iot.mi.com/vela/quickapp/zh/components/container/list-item.html

Demonstrates how to use the list-item component to display a list of products. Ensure that list-items with the same type have identical DOM structures to avoid errors.

```html
<template>
  <div class="page">
    <list class="list">
      <list-item for="{{productList}}" class="item" type="list-item">
        <text>{{$item.name}}: {{$item.price}}</text>
      </list-item>
    </list>
  </div>
</template>

<script>
  export default {
    data: {
      productList: [
        { name: '衣服', price: '100' },
        { name: '裤子', price: '200' }
      ],
    }
  }
</script>

<style>
  .page {
    padding: 30px;
    background-color: white;
  }

  .list {
    width: 100%;
    height: 100%;
  }

  .item {
    height: 40px;
  }
</style>

```

--------------------------------

### Basic Div Layout Example

Source: https://iot.mi.com/vela/quickapp/zh/components/container/div.html

Demonstrates a simple layout using nested Div components with text elements. Shows how to apply styles for alignment and background colors.

```html
<template>
  <div class="page">
    <div style="flex-direction: row;">
      <text class="item color-1">1</text>
      <text class="item color-2">2</text>
      <text class="item color-3">3</text>
    </div>
  </div>
</template>
<style>
  .page {
    margin: 20px;
    flex-direction: column;
    background-color: white;
  }

  .item {
    height: 100px;
    width: 100px;
    text-align: center;
    margin-right: 10px;
  }
  
  .color-1 {
    background-color: #09ba07;
  }
  
  .color-2 {
    background-color: #f76160;
  }
  
  .color-3 {
    background-color: #0faeff;
  }
</style>

```

--------------------------------

### Input Component Examples

Source: https://iot.mi.com/vela/quickapp/zh/components/form/input.html

Demonstrates the usage of input components for buttons, checkboxes, and radio buttons. Includes event handling for user interactions.

```vue
<template>
  <div class="page">
    <div class="section">
      <text class="title">input-button 组件</text>
      <input class="button" type="button" value="按钮" @click="onButtonClick" />
      <text>{{ buttonText }}</text>
    </div>
    <div class="section">
      <text class="title">input-checkbox 组件</text>
      <input class="checkbox" type="checkbox" checked="{{ checkboxChecked }}" @change="onCheckboxChange" />
      <text>我的勾选状态: {{ checkboxChecked }}</text>
    </div>
    <div class="section">
      <text class="title">input-radio 组件</text>
      <div>
        <input class="radio" type="radio" name="radio" value="1" checked="{{radioValue === '1'}}" @change="onRadioChange" />
        <input class="radio" type="radio" name="radio" value="2" checked="{{radioValue === '2'}}" @change="onRadioChange" />
        <input class="radio" type="radio" name="radio" value="3" checked="{{radioValue === '3'}}" @change="onRadioChange" />
      </div>
      <text>当前选中第{{ radioValue }}个</text>
    </div>
  </div>
</template>

<script>
  export default {
    private: {
      buttonText: '',
      checkboxChecked: true,
      radioValue: '1'
    },
    onTextChange(e) {
      this.textValue = e.value
    },
    onButtonClick() {
      this.buttonText = '按钮被点击了'
    },
    onCheckboxChange(e) {
      this.checkboxChecked = e.checked
    },
    onRadioChange(e) {
      this.radioValue = e.value
    }
  }
</script>

<style>
  .page {
    flex-direction: column;
    padding: 30px;
    background-color: #ffffff;
  }

  .section {
    flex-direction: column;
    margin-bottom: 30px;
  }

  .title {
    font-weight: bold;
  }

  .button {
    width: 140px;
    height: 50px;
    font-size: 25px;
    color: white;
  }

  .checkbox, .radio {
    width: 40px;
    height: 40px;
    margin-right: 10px;
  }
</style>

```

--------------------------------

### Start BLE Scan

Source: https://iot.mi.com/vela/quickapp/zh/features/system/bluetooth.html

Initiate a BLE scan with specified filters and options. Handles success, failure, and completion callbacks.

```javascript
let scanner = bluetoothBLE.createScanner();
scanner.startBLEScan({
  filters: [
    {
      deviceId: "XX:XX:XX:XX:XX:XX",
      name: "test",
      serviceUuid: "00001888-0000-1000-8000-00805f9b34fb",
    }
  ],
  options: {
    dutyMode: ScanDuty.SCAN_MODE_LOW_POWER,
  },
  success: function () {
    console.log(`startBLEScan success`);
  },
  fail: function (data, code) {
    console.log(`startBLEScan fail, code = ${code}`);
  },
  complete: function () {
    console.log(`startBLEScan complete`);
  },
});
```

--------------------------------

### Slider Component Example

Source: https://iot.mi.com/vela/quickapp/zh/components/form/slider.html

Demonstrates the basic usage of the slider component, including setting min, max, step, and initial value, and handling the change event.

```html
<template>
  <div class="page">
    <text class="title">slider 组件</text>
    <slider class="slider" min="0" max="100" step="10" value="{{ initialSliderValue }}" onchange="onSliderChange"></slider>
    <text>slider的值：{{ sliderValue }}</text>
  </div>
</template>

<script>
  export default {
    private: {
      initialSliderValue: 10,
      sliderValue: null
    },
    onSliderChange (e) {
      this.sliderValue = e.progress
    }
  }
</script>

<style>
  .page {
    flex-direction: column;
    padding: 30px;
    background-color: #ffffff;
  }

  .title {
    font-weight: bold;
  }

  .slider {
    margin-top: 20px;
    margin-bottom: 20px;
    padding-left: 0;
    padding-right: 0;
  }
</style>
```

--------------------------------

### Create and Connect GATT Client Device

Source: https://iot.mi.com/vela/quickapp/zh/features/system/bluetooth.html

Initializes a GATT client device and attempts to establish a connection. Use this to start communication with a BLE device.

```javascript
let gattClientDevice = bluetoothBLE.createGattClientDevice("XX:XX:XX:XX:XX:XX");
gattClientDevice.connect({
  success: function () {
    console.log(`send connect success`);
  },
  fail: function (data, code) {
    console.log(`connect fail, code = ${code}`);
  },
  complete: function () {
    console.log(`connect complete`);
  }
});

```

--------------------------------

### Quick Mode: Create a Music Player with Design Mockup

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

This example shows the quick mode for creating a music player using a Figma design link. The AI parses the design, exports resources, and generates code while adhering to the design's styling.

```markdown
用户: 帮我做一个音乐播放器
      设计稿: https://www.figma.com/design/xxxxx

AI:   🎨 解析设计稿...
      ✅ 检测到 2 个页面、8 个图标
      🖼️ 导出 PNG 资源到 src/common/images/

      📂 npx create-aiot ux --name music-player
      📄 生成播放器主页 + 歌单列表页
      🎨 样式严格还原设计稿（颜色、字号、间距）
      ✅ 代码生成完成！


```

--------------------------------

### View All Available Build Parameters

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/toolkit-params.html

Run this command to display all supported build parameters and their descriptions.

```bash
npx aiot build -h
```

--------------------------------

### Animation Name Examples

Source: https://iot.mi.com/vela/quickapp/zh/components/general/animation-style.html

Applies single or multiple animations to an element. Multiple animations start simultaneously.

```css
/* 单个动画 */
animation-name: Color;
animation-name: translate;
animation-name: rotate;

/* 多个动画 1070+ */
animation-name: Color, Opacity;
animation-name: Width, translate, rotate;
```

--------------------------------

### Less Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Demonstrates the basic structure for using Less with the framework. It shows how to import an external Less file and apply styles within a style block tagged with lang="less".

```html
<template>
  <div class="page">
    <text id="title">less示例!</text>
  </div>
</template>
<style lang="less">
  /* 引入外部less文件 */
  @import './style.less';
  /* 使用less */
</style>

```

--------------------------------

### Resolving npm Installation Failures

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/use-ide.html

If npm installation fails during project setup, create or update the .npmrc file in your project's root directory to specify a reliable npm registry. This is crucial for downloading project dependencies correctly.

```Configuration
registry="https://registry.npmmirror.com/"
```

--------------------------------

### Install conditional-compilation-webpack-plugin

Source: https://iot.mi.com/vela/quickapp/zh/guide/multi-screens/conditional-compilation.html

Install the necessary webpack plugin for conditional compilation as a development dependency.

```bash
npm install conditional-compilation-webpack-plugin -D

```

--------------------------------

### 启动 Kiro Workflow

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

在 Kiro IDE 中通过对话框引用 workflow_starter.md 来启动 AI 工作流。支持多种需求输入方式和设计稿集成。

```bash
@.workflow/workflow_starter.md

```

--------------------------------

### Create a New Project

Source: https://iot.mi.com/vela/quickapp/zh/tools/toolkit/start.html

Use this command to initialize a new Xiaomi Vela JS project.

```bash
npm create aiot
```

--------------------------------

### Build Project for Distribution

Source: https://iot.mi.com/vela/quickapp/zh/tools/toolkit/start.html

Compiles the project into a distributable rpk file.

```bash
aiot build
```

--------------------------------

### Install PostCSS Loader and PreCSS

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Install the necessary npm packages for PostCSS processing. This includes the postcss-loader and a specific version of precss.

```bash
npm i postcss-loader precss@3.1.2 -D
```

--------------------------------

### Starting a Recording

Source: https://iot.mi.com/vela/quickapp/zh/features/system/record.html

Initiates an audio recording with specified parameters. Use this to begin capturing audio. The success callback provides the URI of the recorded file, while fail and complete handle errors and general completion.

```javascript
record.start({
  duration: 10000,
  sampleRate: 8000,
  numberOfChannels: 1,
  encodeBitRate: 128000,
  format: 'pcm',
  success: function(data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  },
  complete: function () {
    console.log(`handling complete`)
  }
})
```

--------------------------------

### Template Expression Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/template/computed.html

Avoid complex expressions directly in templates. This example shows a common scenario where a computed property would be more maintainable.

```html
<text> {{ message.split('').reverse().join('') }} </text>

```

--------------------------------

### Router Configuration Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/manifest.html

Defines the application's entry page and a list of other pages with their component mappings and optional path configurations. Ensures pages are correctly registered and accessible.

```json
"router": {
  "entry": "Demo",
  "pages": {
    "Demo": {
      "component": "index"
    }
  }
}
```

--------------------------------

### Typical Project Directory Structure

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/project-structure.html

This is the standard directory layout for a QuickApp project, including manifest, app.ux, pages, i18n, and common resource directories.

```directory
src/
├── manifest.json
├── app.ux
├── pages
│   ├── index
|   |   └── index.ux
│   └── detail
|       └── detail.ux
├── i18n
|   ├── defaults.json
|   ├── zh-CN.json
|   └── en-US.json
└── common
    ├── style.css
    ├── utils.js
    └── logo.png

```

--------------------------------

### Creating a New Simulator Instance

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/use-ide.html

To create a new simulator instance, navigate to the device management section, click 'New', fill in the simulator details, and click 'Create'. The plugin will download the Vela image and complete the creation process.

```IDE Actions
Click 'New' in Device Management
Fill in simulator form details
Click 'Create'
```

--------------------------------

### Full Workflow: Develop an Accounting App

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

This example demonstrates the full workflow for developing an accounting app. It shows the interaction between the user and AI through PRD generation, technical solution design, and code generation.

```markdown
用户: 开发一个记账应用，支持添加收支记录和查看月度统计

AI:   📝 需求已收到
      📐 屏幕规格: 480×480 圆屏（默认）

      ❓ 请选择工作流模式:
        [1] 完整流程  [2] 直接生成代码

用户: 1

AI:   🚀 S1 - PRD 生成...
      ━━━━━━━━━━━━━━━━━━━━
      📄 功能清单:
        • 首页: 收支概览 + 快捷记账按钮
        • 记账页: 金额输入 + 分类选择
        • 统计页: 月度收支图表
      ❓ [y] 确认  [e] 修改  [n] 重做

用户: y

AI:   🚀 S2 - 技术方案...
      ━━━━━━━━━━━━━━━━━━━━
      📄 页面路由: 3 个页面
      📄 数据存储: @system.storage
      📄 图表: 内置 chart 组件
      ❓ [y] 确认  [e] 修改  [n] 重做

用户: y

AI:   🚀 S3 - 代码生成...
      ━━━━━━━━━━━━━━━━━━━━
      📂 npx create-aiot ux --name accounting-app
      📄 生成 3 个页面 + manifest 配置
      ✅ 质量校验通过

      🎉 项目已创建完成！


```

--------------------------------

### Scroll Component Example

Source: https://iot.mi.com/vela/quickapp/zh/components/container/scroll.html

This snippet shows a basic implementation of a scrollable container with items and demonstrates how to use its methods like getScrollRect, scrollTo, and scrollBy. It also includes an example of handling the scroll top event.

```vue
<template>
  <div class="page">
      <scroll id="scrollId" scroll-y="true" onscrolltop="handleScrollTop">
          <div class="item">
             <text>北京</text>
          </div>
          <div class="item">
             <text>上海</text>
          </div>
          <div class="item">
             <text>广州</text>
          </div>
          <div class="item">
             <text>深圳</text>
          </div>
       </scroll>
  </div>
</template>

<script>
  export default {
    onShow() {
      this.$element('scrollId').getScrollRect({
        success({ width, height }) {
          console.log('宽度', width);
          console.log('高度', height);  
        }
      })

      // this.scrollTo()
      // this.scrollBy()
    },
    handleScrollTop() {
      console.info('scrolled top.')
    },
    scrollTo() {
      this.$element('scrollId').scrollTo({
        top: 1000,
        left: 0,
        behavior: 'smooth'
      })
    },
    scrollBy() {
      this.$element('scrollId').scrollBy({
        top: 1000,
        left: 0,
        behavior: 'smooth'
      })
    }
  }
</script>
<style>
  .page {
    justify-content: center;
    align-items: center;
  }

  #scrollId {
    width: 50%;
    height: 100px;
    flex-direction: column;
    background-color: yellowgreen;
  }

  .item {
    width: 100%;
    height: 50px;
    justify-content: center;
  }
</style>
```

--------------------------------

### Importing the Storage Module

Source: https://iot.mi.com/vela/quickapp/zh/features/data/storage.html

Demonstrates how to import the storage module using either ES module syntax or CommonJS.

```javascript
import storage from '@system.storage'
// 或 
const storage = require('@system.storage')
```

--------------------------------

### Sass Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Demonstrates the basic structure for using Sass with the framework. It shows how to import an external Sass file and apply styles within a style block tagged with lang="scss".

```html
<template>
  <div class="page">
    <text id="title">less示例!</text>
  </div>
</template>

<style lang="scss">
  /* 引入外部scss文件 */
  @import './style.scss';
  /* 使用scss */
</style>

```

--------------------------------

### device.getAvailableStorage

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/device.html

Gets the available storage size of the device in bytes.

```APIDOC
## device.getAvailableStorage(OBJECT)

### Description
Gets the available storage size of the device in bytes.

### Parameters
#### Success Callback Parameters
- **availableStorage** (Number) - The available storage size in bytes.

### Example
```javascript
device.getAvailableStorage({
    success: (data) => {
        console.log(`handling success: ${data.availableStorage}`)
    },
    fail: (data, code) => {
        console.log(`handling fail, code = ${code}`)
    }
})
```
```

--------------------------------

### PX Unit Conversion Example

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style/page-style-and-layout.html

Demonstrates two methods for converting design稿 (design draft) px to framework px based on project configuration. Method one involves setting the project's designWidth to match the design draft's base width. Method two calculates the framework px based on the existing project designWidth.

```json
{
  "config": {
    "designWidth": 640
  }
}

```

```css
width: 100px;

```

```css
width: 75px;

```

--------------------------------

### device.getTotalStorage

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/device.html

Gets the total storage size of the device in bytes.

```APIDOC
## device.getTotalStorage(OBJECT)

### Description
Gets the total storage size of the device in bytes.

### Parameters
#### Success Callback Parameters
- **totalStorage** (Number) - The total storage size in bytes.

### Example
```javascript
device.getTotalStorage({
    success: (data) => {
        console.log(`handling success: ${data.totalStorage}`)
    },
    fail: (data, code) => {
        console.log(`handling fail, code = ${code}`)
    }
})
```
```

--------------------------------

### Importing the File Module

Source: https://iot.mi.com/vela/quickapp/zh/features/data/file.html

Demonstrates how to import the file module using either ES module syntax or CommonJS.

```javascript
import file from '@system.file'
// 或 
const file = require('@system.file')
```

--------------------------------

### Importing the Device Module

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/device.html

Demonstrates how to import the device module using either ES6 import or CommonJS require.

```javascript
import device from '@system.device'
// 或 
const device = require('@system.device')
```

--------------------------------

### Get Interconnect Instance

Source: https://iot.mi.com/vela/quickapp/zh/features/network/interconnect.html

Obtain the singleton connection instance for data transmission.

```javascript
const connect = interconnect.instance()
```

--------------------------------

### Get System Default Mode

Source: https://iot.mi.com/vela/quickapp/zh/features/system/vibrator.html

Retrieve the system's default vibration mode.

```javascript
vibrator.getSystemDefaultMode()
```

--------------------------------

### connect.getReadyState()

Source: https://iot.mi.com/vela/quickapp/zh/features/network/interconnect.html

Gets the current connection status between the device app and the paired mobile app.

```APIDOC
## connect.getReadyState(OBJECT)

### Description
Gets the current connection status between the device app and the paired mobile app.

### Parameters
#### Object Parameters
- **success** (Function, Optional): Callback function invoked upon successful retrieval of the connection status.
  - **data** (Object):
    - **status** (Number): The connection status. `1` indicates connected, `2` indicates disconnected.
- **fail** (Function, Optional): Callback function invoked if an error occurs.
  - **data** (String): Error message.
  - **code** (Number): Error code.

### Returns
- On success: An object with a `status` property indicating the connection state.
- On failure: An object with `data` (error message) and `code` (error code).

### Error Codes
- `1006`: Connection lost.

### Example
```javascript
connect.getReadyState({
  success: (data) => {
    if (data.status === 1) {
      console.log('Connection successful')
    } else if (data.status === 2) {
      console.log('Connection failed')
    }
  },
  fail: (data, code) => {
    console.log(`Handling fail, code = ${code}`)
  }
})
```
```

--------------------------------

### Get Page Stack Length

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/router.html

Use router.getLength() to retrieve the number of pages currently in the page stack.

```javascript
var length = router.getLength()
console.log(`page's length = ${length}`)
```

--------------------------------

### Less Pre-compilation with External Files

Source: https://iot.mi.com/vela/quickapp/zh/guide/framework/style

Shows how to import and use Less files for styling, either by replacing internal styles or merging them using @import.

```html
<!-- Import external file, replacing style internal styles -->
<style lang="less" src="./lessFile.less"></style>

<!-- Merge external file -->
<style lang="less">
  @import './lessFile.less';
  .less-font-text, .less-font-comma {
    font-size: 60px;
  }
</style>
```

--------------------------------

### Set Source Map Output via Configuration File

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/toolkit-params.html

Configure the source map output format in the `quickapp.config.js` file for persistent settings.

```javascript
module.exports = {
  cli: {
    devtool: "source-map",
  },
};
```

--------------------------------

### Get Device ID

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/device.html

Fetches the unique device identifier. Requires the 'hapjs.permission.DEVICE_INFO' permission to be declared in manifest.json.

```javascript
device.getDeviceId({
  success: function (data) {
    console.log(`handling success: ${data.deviceId}`)
  },
  fail: function (data, code) {
    console.log(`handling fail, code = ${code}`)
  },
})
```

--------------------------------

### Get Application Locale

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/configuration.html

Retrieve the current language and region settings of the application. The locale can change dynamically.

```javascript
const locale = configuration.getLocale()
console.log(locale.language)
```

--------------------------------

### Import Crypto Module

Source: https://iot.mi.com/vela/quickapp/zh/features/security/crypto.html

Demonstrates how to import the crypto module using either ES module syntax or CommonJS.

```javascript
import crypto from '@system.crypto'
// 或 
const crypto = require('@system.crypto')
```

--------------------------------

### Basic Text Usage

Source: https://iot.mi.com/vela/quickapp/zh/components/basic/text.html

A simple example demonstrating the basic usage of the text component within a Vue template.

```html
<template>
  <div>
    <text>这是一段文本</text>
  </div>
</template>
```

--------------------------------

### Get BLE Scan State

Source: https://iot.mi.com/vela/quickapp/zh/features/system/bluetooth.html

Retrieve the current scanning state of the Scanner. Provides success and failure callbacks.

```javascript
scanner.getScanState({
  success: function (data) {
    console.log(`getScanState success, state = ${data.scanState}`);
  },
  fail: function (data, code) {
    console.log(`getScanState fail, code = ${code}`);
  },
  complete: function () {
    console.log(`getScanState complete`);
  },
});
```

--------------------------------

### file.readArrayBuffer

Source: https://iot.mi.com/vela/quickapp/zh/features/data/file.html

Reads a portion or the entirety of a file as a Buffer. Allows specifying the starting position and length of the data to read.

```APIDOC
## file.readArrayBuffer(OBJECT)

Reads a Buffer from a file.

#### Parameters:

| Parameter Name | Type | Required | Description |
|---|---|---|---|
| uri | String | Yes | Local file path, supports application resource paths, e.g., '/Common/demo.txt'. |
| position | Number | No | The starting position for reading, defaults to the file's starting position. |
| length | Number | No | The length to read, if not specified, reads to the end of the file. |
| success | Function | No | Success callback. |
| fail | Function | No | Failure callback. |
| complete | Function | No | Callback after execution completes. |

#### Success Return Value:

| Parameter Name | Type | Description |
|---|---|---|
| buffer | Uint8Array | The read file content. |

#### Fail Return Error Codes:

| Error Code | Description |
|---|---|
| 202 | Parameter error |
| 300 | I/O error |
| 301 | File does not exist |

#### Example:

```javascript
file.readArrayBuffer({
  uri: 'internal://files/work/demo',
  position: 100,
  length: 100,
  success: function(data) {
    console.log('buffer.length: ' + data.buffer.length)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})
```
```

--------------------------------

### 使用 Figma 桌面版 MCP 生成项目

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

在已连接 Figma 桌面版 MCP 的环境中，使用 '@sym:Figma Desktop' 命令并提供设计稿，让 AI 生成对应的 Vela 快应用。

```bash
@sym:Figma Desktop 帮我根据当前打开的设计稿里的内容，生成对应的vela快应用

```

--------------------------------

### Enable Protobuf Binary Packaging

Source: https://iot.mi.com/vela/quickapp/zh/guide/start/toolkit-params.html

Use this boolean flag to enable Protobuf binary packaging for performance gains during server commands.

```bash
aiot server --enable-protobuf
```

--------------------------------

### 使用 Figma 链接生成项目 (VS Code)

Source: https://iot.mi.com/vela/quickapp/zh/tools/dev/official-site-tutorial.html

在 Copilot 对话中粘贴 Figma 链接，让 AI 读取设计稿内容并生成项目。适用于已配置 Figma MCP 的 VS Code 环境。

```bash
生成vela快应用，根据设计稿：https://www.figma.com/design/dhoPQU6dFpV5TDI7BnUAjU/APP?XXXX

```

--------------------------------

### Transform and Transform-Origin Example

Source: https://iot.mi.com/vela/quickapp/zh/components/general/animation-style.html

Applies a 30-degree rotation to an element and sets its transform origin using percentage and pixel values.

```css
/* 使用 % 值 */
div {
  transform: rotate(30deg); 
  transform-origin: 20% 40%;
}
/* 使用 px 值 */
div {
  transform: rotate(30deg);
  transform-origin: 100px 100px;
}
```

--------------------------------

### Get All Pages in Stack

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/router.html

Use router.getPages() to retrieve a list of all pages currently in the page stack, including their names and paths.

```javascript
var stacks = router.getPages()
console.log('栈底页面名称为：', stacks[0].name) // 如 list、detail 等
console.log('栈底页面路径为：', stacks[0].path) // 如 /list、/detail、/home/preview
```

--------------------------------

### Importing the System Zip Module

Source: https://iot.mi.com/vela/quickapp/zh/features/system/zip.html

Shows how to import the zip module using either ES module syntax or CommonJS require.

```javascript
import zip from '@system.zip'
// 或
const zip = require('@system.zip')
```

--------------------------------

### Get Available Storage

Source: https://iot.mi.com/vela/quickapp/zh/features/basic/device.html

Fetches the available storage space on the device in Bytes. The success callback returns the availableStorage value.

```javascript
device.getAvailableStorage({
    success: (data) => {
        console.log(`handling success: ${data.availableStorage}`)
    },
    fail: (data, code) => {
        console.log(`handling fail, code = ${code}`)
    }
})
```
Tokens:
Raw