Feishu Client API

https://open.feishu.cn/document/client-docs/
Admin
Provides comprehensive documentation and resources for developers to integrate with and extend...
Tokens:244,230
Snippets:2,128
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Project

Source: https://open.feishu.cn/document/client-docs/docs-add-on/03-cloud-document-widget-quick-developme

Navigate to the project root, install dependencies, and start the development server. This is the initial setup for local development.

```bash
cd demo
// 也可以选择其它包管理器（pnpm、yarn 等）
npm i
npm start
```

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

### Creator Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/config

Example of a creator's index.json file, specifying whether an interface is needed and if loading should be started.

```json
{
  "needInterface": true,
  "useStartLoading": true
}
```

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

### Basic app.json Configuration

Source: https://open.feishu.cn/document/client-docs/gadget/introduction/global-settings

This is an example of an app.json file with common configuration items, including pages, window settings, and tab bar setup.

```json
{
  "pages": [
    "pages/index/index",
    "pages/logs/index",
    "pages/home/index",
    "pages/help/index"
  ],
  "window": {
    "backgroundTextStyle":"light",
    "navigationBarBackgroundColor": "#fff",
    "navigationBarTitleText": "Mini App",
    "navigationBarTextStyle": "black"
  },
  "tabBar": {
    "list": [{
      "pagePath": "pages/home/index",
      "text": "主页"
    }, {
      "pagePath": "pages/help/index",
      "text": "帮助"
    }]
  }
}
```

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

### Get File Info Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/file/file_system_manager/file_system_manager_get_file_info

This example demonstrates how to get file information using FileSystemManager.getFileInfo. It first chooses an image, then retrieves its file path, and finally calls getFileInfo to log the file's size and other details. Ensure tt.getFileSystemManager() is called to initialize the manager.

```javascript
const fileSystemManager = tt.getFileSystemManager();

tt.chooseImage({
  success(res) {
    getFileInfo(res.tempFilePaths[0]);
  },
});

function getFileInfo(filePath) {
  fileSystemManager.getFileInfo({
    filePath,
    success(res) {
      console.log("文件信息:", res);
    },
    fail(res) {
      console.log("调用失败", res.errMsg);
    },
  });
}
```

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

### Stop Beacon Discovery Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ibeacon/stopbeacondiscovery

This example demonstrates how to stop beacon discovery after starting it. Ensure startBeaconDiscovery has been called prior to this.

```javascript
tt.startBeaconDiscovery({
    uuids: [
        "fda50693-a4e2-4fb1-afcf-c6eb07647825"
    ],
    ignoreBluetoothAvailable: true,
    success(res) {
      tt.stopBeaconDiscovery({
    	success(res) {
      	  console.log(JSON.stringify(res));
    	},
    	fail(res) {
      	  console.log(`stopBeaconDiscovery fail: ${JSON.stringify(res)}`);
    	}
	    });
    },
    fail(res) {
      console.log(`startBeaconDiscovery fail: ${JSON.stringify(res)}`);
    }
});
```

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

### Window Configuration Example

Source: https://open.feishu.cn/document/client-docs/gadget/introduction/global-settings

Example of window configuration, setting background color, navigation bar text style, and title.

```json
{
  "backgroundTextStyle":"light",
  "navigationBarBackgroundColor": "#fff",
  "navigationBarTitleText": "Mini App",
  "navigationBarTextStyle": "black"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/system-authentication/startdevicecredential

This is an example of the JSON object returned when the `startDeviceCredential` API call is successful.

```json
{
    "errMsg": "startDeviceCredential:ok"
}
```

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

### Example Usage of getPerformanceRecorder()

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/performance/getperformancerecorder

Demonstrates how to get the performance recorder and use its methods like `mark`, `startStack`, `endStack`, `startParallel`, and `endParallel` within a Page lifecycle. It includes simulated heavy JS logic and data updates to trigger performance events.

```javascript
Page({
  data: {
    list: []
  },
  onShow() {
    this.makePageJank(5);
  },
  onLoad() {
    this.makePageJank(5);
    const p = tt.getPerformanceRecorder && tt.getPerformanceRecorder();

setInterval(() => {
      for (let i = 0; i < 10; i++) {
        tt.request({
          url: 'https://open.feishu.cn'
        });
      }

// 调用 mark 接口，记录一个时间点
      p && p.mark({
        // 时间点的 name，可以自定义
        name: 'T',
        // 时间点的 type，可以自定义
        type: 'ijkl',
        // 时间点的扩展信息，可以自定义
        extra: {
          g: 7,
          h: 8,
          i: 9
        }
      })
      // stack 表示有堆栈的，开始一段同步操作的记录
      const stackID = p && p.startStack({
        // name type extra 均可自定义
        name: 'myIntervalRender',
        type: 'abcd',
        extra: {
          a: 1,
          b: 2,
          c: 3
        }
      });

Promise.resolve().then(() => {
        // 用多次同步接口调用来模拟一些很耗时的 JS 逻辑
        this.makePageJank(10, 6);
      })

// parallel 表示可并行的，开始一段可以和其他异步逻辑并行的异步操作的记录
      const parallelID = p && p.startParallel({
        name: 'myIntervalSetData',
        type: 'efgh',
        extra: {
          d: 4,
          e: 5,
          f: 6
        }
      })
      this.setData({
        list: new Array(40).fill(0).map((item) => {
          return {
            a: randomString(2),
            b: randomString(18),
            c: randomString(40),
            d: randomString(30)
          }
        })
      }, () => {
        // 完成一段异步操作的记录
        p && p.endParallel(parallelID)
      });

Promise.reject(4).catch(() => {
        // 用多次同步接口调用来模拟一些很耗时的 JS 逻辑
        this.makePageJank(5);
      });
      // 完成一段同步操作的记录
      p && p.endStack(stackID);
    }, 2000);
  },
  makePageJank(n, r = 0) {
    for (let i = 0; i < n; i++) {
      tt.getSystemInfoSync();
    }
    r--;
    if (r > 0) {
      this.makePageJank(n, r)
    }
  },
})
```

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

### Project Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/config

Example of a project.config.json file, specifying application ID, project name, block paths, and build settings.

```json
{
  "appid": "cli_1234567890",
  "projectname": "Block Demo",
  "blocks": [
    "block/index"
  ],
  "setting": {
    "es6": true,
    "minified": true
  }
}
```

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

### Fetch Message Details in Mini-Program

Source: https://open.feishu.cn/document/client-docs/extensions/message-shortcut

This example demonstrates how to use tt.getHostLaunchQuery to get the trigger code and then pass it to tt.getBlockActionSourceDetail to fetch the message content. Includes error handling for missing trigger codes.

```javascript
// 代码示例
tt.getHostLaunchQuery({
    success(res) {
        if (res.launchQuery) {
            let json = JSON.parse(res.launchQuery)
            if (json && json.__trigger_id__) {
                // getHostLaunchQuery获取triggerCode的方法
                tt.getBlockActionSourceDetail({
                    triggerCode: json.__trigger_id__,
                    success(res) {
                        console.log('success', res)
                    },
                    fail(res) {
                        console.log('fail', res)
                    }
                })
            } else {
                tt.showToast({title: 'get code fail'})
            }
        } else {
            tt.showToast({title: 'get code fail'})
        }
    },
});
```

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

### Full app.json Theme Configuration Example

Source: https://open.feishu.cn/document/client-docs/gadget/introduction/darkmode

An example of `app.json` demonstrating how to configure various window and tabBar properties using theme variables for dark mode support.

```json
{
    "window": {
        "navigationBarBackgroundColor": "@navBgColor",
        "navigationBarTextStyle": "@navTxtStyle",
        "backgroundColor": "@bgColor",
        "backgroundTextStyle": "@bgTxtStyle",
        "backgroundColorTop": "@bgColorTop",
        "backgroundColorBottom": "@bgColorBottom"
    },
    "tabBar": {
        "color": "@tabFontColor",
        "selectedColor": "@tabSelectedColor",
        "backgroundColor": "@tabBgColor",
        "borderStyle": "@tabBorderStyle",
        "list": [{
            "iconPath": "@iconPath1",
            "selectedIconPath": "@selectedIconPath1"
        }, {
            "iconPath": "@iconPath2",
            "selectedIconPath": "@selectedIconPath2"
        }]
    }
}
```

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

### Full theme.json Configuration Example

Source: https://open.feishu.cn/document/client-docs/gadget/introduction/darkmode

A comprehensive `theme.json` example defining light and dark mode variables for navigation, background, and tabBar elements, including icon paths.

```json
{
    "light": {
        "navBgColor": "#f6f6f6",
        "navTxtStyle": "black",
        "bgColor": "#ffffff",
        "bgTxtStyle": "light",
        "bgColorTop": "#eeeeee",
        "bgColorBottom": "#efefef",
        "tabFontColor": "#000000",
        "tabSelectedColor": "#3cc51f",
        "tabBgColor": "#ffffff",
        "tabBorderStyle": "black",
        "iconPath1": "image/icon1_light.png",
        "selectedIconPath1": "image/selected_icon1_light.png",
        "iconPath2": "image/icon2_light.png",
        "selectedIconPath2": "image/selected_icon2_light.png"
    },
    "dark": {
        "navBgColor": "#191919",
        "navTxtStyle": "white",
        "bgColor": "#1f1f1f",
        "bgTxtStyle": "dark",
        "bgColorTop": "#191919",
        "bgColorBottom": "#1f1f1f",
        "tabFontColor": "#ffffff",
        "tabSelectedColor": "#51a937",
        "tabBgColor": "#191919",
        "tabBorderStyle": "white",
        "iconPath1": "image/icon1_dark.png",
        "selectedIconPath1": "image/selected_icon1_dark.png",
        "iconPath2": "image/icon2_dark.png",
        "selectedIconPath2": "image/selected_icon2_dark.png"
    }
}
```

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

### Get and Use RecorderManager

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/media/record/getrecordermanager

Obtain the global `recorderManager` instance and set up event listeners for recording lifecycle events. This snippet demonstrates how to start recording with specified options and log various events.

```javascript
const recorderManager = tt.getRecorderManager();

recorderManager.onStart(() => {
    console.log('recorder start')
});
recorderManager.onPause(() => {
    console.log('recorder pause')
});
recorderManager.onResume(() => {
    console.log('recorder onResume')
});
recorderManager.onStop((res) => {
    console.log('recorder stop', res)
    const { tempFilePath } = res
});
recorderManager.onFrameRecorded((res) => {
    const { frameBuffer } = res
    console.log('frameBuffer.byteLength', frameBuffer.byteLength)
});

const options = {
    duration: 10000,
    sampleRate: 44100,
    numberOfChannels: 1,
    format: 'aac',
    frameSize: 50
};

recorderManager.start(options);
```

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

### Workplace Host Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/config

Example of a block configuration for the Workplace host, including header settings, title, icons, links, and menu items.

```json
{
  "blockTypeID": "REPLACE_WITH_ACTUAL_BLOCK_TYPE_ID",
  "creator": "block/creator/index",
  "workplace": {
    "needHeader": true,
    "pcHeaderLink": "https://open.feishu.cn/",
    "mobileHeaderLink": "https://open.feishu.cn/m",
    "title": {
      "zh_cn": "工作台小组件",
      "en_us": "Workplace Widget"
    },
    "titleIconUrl": "https://sf3-scmcdn2-cn.feishucdn.com/ccm/pc/web/resource/bear/src/common/assets/favicons/icon_global_feishu_nor-256x256.e844bc748f30713db4b8.png",
    "menuItems": [
      {
        "key": "setting",
        "name": {
          "zh_cn": "设置",
          "en_us": "Settings"
        },
        "iconUrl": "https://sf3-cn.feishucdn.com/obj/eden-cn/eseh7nupevhps/block/setting.svg"
      },
      {
        "key": "copy",
        "name": {
          "zh_cn": "复制",
          "en_us": "Copy"
        },
        "iconUrl": "https://sf3-cn.feishucdn.com/obj/eden-cn/eseh7nupevhps/block/copy.svg"
      }
    ]
  }
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ibeacon/startbeacondiscovery

Example of the success response object returned by the startBeaconDiscovery API.

```json
{
    "errMsg": "startBeaconDiscovery:ok"
}
```

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

### CSS border-width Examples

Source: https://open.feishu.cn/document/client-docs/block/block-frame/code-components-and-structure/view-layer/ttss/attributes/border/border-width

Provides practical examples of setting border widths using different combinations of keywords and specific pixel values.

```css
border-width: thin;
border-width: thin medium;
border-width: thin medium thick;
border-width: thin medium thick 10px;
border-width: 5px 10px 15px 20px;
```

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

### Authorization Header Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/chat/getBlockActionSourceDetail

Example of the Authorization header required for downloading resources, using a tenant access token.

```markdown
| 参数         | 数据类型           | 必填        | 描述         | 实例       |
| --------- | --------------- | -------   | ----------- | --------- |
|`Authorization` | `string` | 是| tenant_access_token；注意内容不要漏了 "Bearer"| Bearer t-394890fdlkfjdajfljajdkf |
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/bluetooth/getbluetoothdevices

Example of a successful response from the getBluetoothDevices API, detailing discovered devices.

```json
{
    "devices": [
        {
            "RSSI": -97,
            "advertisData": {},
            "advertisServiceUUIDs": [],
            "deviceId": "FF:24:79:5D:6D:0C",
            "serviceData": {}
        }
]
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/accelerometer/startaccelerometer

An example of the success response object returned by the `startAccelerometer` API.

```json
{
    "errMsg": "startAccelerometer:ok"
}
```

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

### Button Examples

Source: https://open.feishu.cn/document/client-docs/gadget/component-component/basic-component/form/button

Demonstrates various button types, states (loading, disabled), and configurations like 'plain' and 'mini' size. Use these examples to see how different button styles and states are rendered.

```html
<view class="container">
  <view class="page-body">
    <view class="btn-area" id="buttonContainer">
      <button type="primary">{{main_operation_normal}}</button>
      <button type="primary" loading="true">{{main_operation_loading}}</button>
      <button type="primary" disabled="true">{{main_operation_disabled}}</button>

<button type="default">{{secondary_operation_normal}}</button>
      <button type="default" loading>{{secondary_operation_loading}}</button>
      <button type="default" disabled="true">{{secondary_operation_disabled}}</button>

<button type="warn">{{warning_operation_normal}}</button>
      <button type="warn" loading>{{warning_operation_loading}}</button>
      <button type="warn" disabled="true">{{warning_operation_disabled}}</button>

<view class="button-sp-area">
        <button type="primary" plain="true">{{button}}</button>
        <button type="primary" disabled="true" plain="true">{{disabled_button}}</button>

<button type="default" plain="true">{{button}}</button>
        <button type="default" disabled="true" plain="true">{{button}}</button>

<button class="mini-btn" type="primary" size="mini">{{button}}</button>
        <button class="mini-btn" type="default" size="mini">{{button}}</button>
        <button class="mini-btn" type="warn" size="mini">{{button}}</button>
      </view>
    </view>
  </view>

</view>
```

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

### Block Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/config

Example of a block's index.json file, defining block type ID, creator path, loading behavior, dark mode, and frame display.

```json
{
  "blockTypeID": "blk_6041a9c6c800001c53e5d34a",
  "creator": "blockA/creator/index",
  "useStartLoading": false,
  "darkmode": true,
  "showFrame": true,
  "schema": {
    "sourceData": {
      "type": "object",
      "properties": {
        "point": {
          "type": "integer"
        }
      }
    }
  }
}
```

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

### Save File Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/file/file_system_manager/file_system_manager_save_file

This snippet demonstrates how to save a temporary image file to a local user directory using FileSystemManager.saveFile. It first chooses an image, gets its temporary file path, and then calls saveFile with a specified local file path. If the filePath is not provided, a random path will be generated.

```javascript
const fileSystemManager = tt.getFileSystemManager();
tt.chooseImage({
  success(res) {
    const tempFilePath = res.tempFilePaths[0];
    fileSystemManager.saveFile({
      tempFilePath,
      filePath: "ttfile://user/feishu.png",
      success(res) {
        console.log(`${JSON.stringify(res)}`);
      },
      fail(res) {
        console.log(`saveFile fail: ${JSON.stringify(res)}`);
      },
    });
  },
});
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/bluetooth/openbluetoothadapter

Example of a successful response from the openBluetoothAdapter API.

```json
{
    "errMsg": "openBluetoothAdapter:ok"
}
```

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

### Download Progress Callback Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/network/download/downloadfile/onprogressupdate

An example of the JSON object received in the progress update callback, showing the downloaded bytes, current progress percentage, and total expected bytes.

```json
{
    "totalBytesWritten": 208788,
    "progress": 100,
    "totalBytesExpectedToWrite": 208788
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/system-information/getsysteminfo

An example of the JSON object returned upon successful execution of tt.getSystemInfo, detailing various system and device properties.

```json
{
  "errMsg": "getSystemInfo:ok",
  "system": "11.4.0",
  "platform": "darwin",
  "appName": "Feishu",
  "version": "5.1.0",
  "language": "zh_CN",
  "SDKVersion": "1.9.56",
  "screenWidth": 1322,
  "screenHeight": 913,
  "windowWidth": 1322,
  "windowHeight": 913,
  "pixelRatio": 2,
  "pageOrientation": "portrait",
  "statusBarHeight": 0,
  "safeArea": {
    "left": 0,
    "right": 1322,
    "top": 0,
    "bottom": 913,
    "width": 1322,
    "height": 913
  },
  "navigationBarSafeArea": {
    "left": 0,
    "right": 1268,
    "top": 0,
    "bottom": 36,
    "width": 1268,
    "height": 36
  },
  "brand": "PC",
  "model": "PC",
  "fontSizeSetting": 12,
  "theme": "light",
  "deviceType": "phone"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/window/setwindowsize

This is an example of a successful response from the setWindowSize API call, indicating the operation was completed successfully.

```json
{
  "errMsg": "setWindowSize:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ble/getbledevicecharacteristics

Example of a successful response when retrieving Bluetooth device characteristics.

```json
{
  "characteristics": {
    "characteristicId": "xxx",
    "serviceId": "xxx",
    "value": "xxx",
    "properties": {
      "write": false,
      "notify": false,
      "read": true,
      "indicate": false
    }
  },
  "errMsg": "getBLEDeviceCharacteristics:ok",
}
```

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

### Beacon Service Change Callback Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ibeacon/onbeaconservicechange

An example of the object returned by the `onBeaconServiceChange` callback, indicating the service status.

```json
{
    "available": false,
    "discovering": true
}
```

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

### Choose Chat Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/chat/choosechat

This example demonstrates how to use the `tt.chooseChat` method to open the chat selection interface. It includes options for allowing group creation, multi-select, ignoring self or bots, setting confirmation titles and descriptions, and enabling message input.

```APIDOC
## tt.chooseChat

### Description
Allows users to select a chat from a list. Supports options for group creation, multi-select, and message input.

### Method
`tt.chooseChat(options)`

### Parameters
#### Options
- **allowCreateGroup** (boolean) - Optional - Whether to allow the creation of new groups.
- **multiSelect** (boolean) - Optional - Whether to allow multiple chat selections.
- **ignoreSelf** (boolean) - Optional - Whether to ignore the current user in the selection.
- **ignoreBot** (boolean) - Optional - Whether to ignore bots in the selection.
- **selectType** (number) - Optional - Type of selection (e.g., 0 for default).
- **confirmTitle** (string) - Optional - The title for the confirmation dialog.
- **confirmDesc** (string) - Optional - The description for the confirmation dialog.
- **externalChat** (boolean) - Optional - Whether to allow selection of external chats.
- **showMessageInput** (boolean) - Optional - Whether to show a message input field.
- **success** (function) - Required - Callback function for successful selection. Receives a `res` object.
- **fail** (function) - Required - Callback function for failed selection. Receives a `res` object with error information.

### Success Response Example
```json
{
    "errMsg": "chooseChat:ok",
    "message": "",
    "data": [
        {
            "name": "飞书团队",
            "i18nNames": {
                "en_us": "Feishu Team",
                "zh_cn": "飞书团队",
                "ja_jp": "Feishu チーム"
            },
            "id": "oc_a88923604e75701a65980f8d1a1dxxxx",
            "avatarUrls": [
                "https://s3-imfile.feishucdn.com/static-resource/v1/v2_d6e145c6-f7bb-492b-9743-5a0d1d6843eg~?image_size=72x72&cut_type=&quality=&format=png&sticker_format=.webp",
                "https://s1-imfile.feishucdn.com/static-resource/v1/v2_d6e145c6-f7bb-492b-9743-5a0d1d6843eg~?image_size=240x240&cut_type=&quality=&format=png&sticker_format=.webp",
                "https://s3-imfile.feishucdn.com/static-resource/v1/v2_d6e145c6-f7bb-492b-9743-5a0d1d6843eg~?image_size=noop&cut_type=&quality=&format=png&sticker_format=.webp",
                "https://s1-imfile.feishucdn.com/static-resource/v1/v2_d6e145c6-f7bb-492b-9743-5a0d1d6843eg~?image_size=640x640&cut_type=&quality=&format=png&sticker_format=.webp"
            ],
            "chatType": 0,
            "userType": 1
        }
    ]
}
```

### Error Handling
Refer to [Errno 错误码](https://open.feishu.cn/document/uYjL24iN/uAjMuAjMuAjM/errno) for detailed error code explanations.
```

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

### onResize callback return object example

Source: https://open.feishu.cn/document/client-docs/gadget/open-capabilities/autorotate/onresize

This is an example of the object structure returned by the onResize callback. It includes the page orientation and the new screen and window dimensions.

```json
{
	"pageOrientation": "landscape",
	"size": {
	   "windowWidth": 812,
	   "windowHeight": 375,
	   "screenWidth": 812,
	   "screenHeight": 375
	}
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/screen-brightness/get-screen-brightness

This is an example of the success response object returned by the getScreenBrightness API, containing the 'errMsg' and the 'value' of the screen brightness.

```json
{
    "errMsg": "getScreenBrightness:ok",
    "value": 0.8206081986427307
}
```

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

### Login API Success Response Example

Source: https://open.feishu.cn/document/client-docs/block/api/user/login

An example of a successful response from the login API, containing the temporary login credential.

```json
{
  "errMsg": "login:ok",
  "code": "46c725e3d6fa545b"
}
```

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

### Failure Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/bluetooth/getbluetoothdevices

Example of a failure response from the getBluetoothDevices API, indicating an issue like the Bluetooth module not being initialized.

```json
{
    "errMsg": "getBluetoothDevices:fail not init",
    "errCode": 10000
}
```

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

### Example Cold Launch Parameters

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/feishu-launch-parameters/getlaunchoptionssync

This JSON object illustrates the structure of the return value from getLaunchOptionsSync(), showing the path, scene, query parameters, and mode (for PC).

```json
//Example:when the opened Applink is:
//https://applink.feishu.cn/client/mini_program/open?appId=<your appId>&mode=window&path=src/page/api/index?foo=bar
{
    "path": "src/page/api/index",
    "scene": "1011",
    "query": {
      "foo": "bar"
    }
}
```

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

### getUserInfo API Response Example

Source: https://open.feishu.cn/document/client-docs/block/api/user/getuserinfo

This is an example of the successful response from the getUserInfo API, showing the structure of user information, encrypted data, and signature.

```json
{
  "errMsg": "getUserInfo:ok",
  "encryptedData": "Otonx45hSc9CnIAOK8jFKfpnvM+oEIti8h9oKIRyeMOmAnmjT5vMEQtK8itF/leoTKefOo6I0gKUj4fkRkGpLSAB5CwAT5FpcX93O7WTcfatZ0G+wecXGIrpNI8tm4KpElNNUSRsXw2fK+ll/wP87S4KsM6HB+uLObEo+3JW7D0WwzyIBZ0Y2OgeQ0lVrZayn66HkEx3+ZQIfR6lqcHYmZHBhMJ4mKXJPgwervA2pTc=",
  "iv": "5ef0f7127289c52cf09f58a078f1f709",
  "rawData": "{\"nickName\":\"潘二铭\",\"avatarUrl\":\"https://p6-lark-file.byteimg.com/img/lark.avatar/437b7334-de49-40f8-b3e2-69ee357e40bg~72x72.png\",\"gender\":\"male\",\"city\":\"\",\"province\":\"\",\"country\":\"\",\"language\":\"\",\"i18nName\":{\"en_us\":\"Erming Pan\",\"ja_jp\":\"\",\"zh_cn\":\"\"}}",
  "signature": "afee7903abad25f71d9248467e2202a853ef6a14",
  "userInfo": {
    "avatarUrl": "https://p6-lark-file.byteimg.com/img/lark.avatar/437b7334-de49-40f8-b3e2-69ee357e40bg~72x72.png",
    "city": "",
    "country": "",
    "gender": "male",
    "i18nName": {
      "en_us": "Erming Pan",
      "ja_jp": "",
      "zh_cn": ""
    },
    "language": "",
    "nickName": "潘二铭",
    "province": ""
  }
}
```

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

### Get Local Cache Information

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/cache/getstorageinfosync

Call getStorageInfoSync to retrieve information about local cache data. This example demonstrates how to use the API and log the results or any errors.

```javascript
try {
    let result = tt.getStorageInfoSync();
    console.log(`getStorageInfoSync success: ${JSON.stringify(result)}`);
} catch (error) {
    console.log(`getStorageInfoSync fail: ${JSON.stringify(error)}`);
}
```

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

### Background Audio Playback Event Listener

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/media/backgroundaudio/backgroundaudiomanager/onplay

Register a callback to log a message when background audio playback starts. Ensure `tt.getBackgroundAudioManager()` is called to get the manager instance.

```javascript
const bam = this.backgroundAudioManager = tt.getBackgroundAudioManager();
bam.src = 'https://someaudiourl';
bam.onCanplay(()=>{innerAudioContext.play()});
bam.onPlay(() => {
    console.log('开始播放');
});
```

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

### Responsive Data Binding Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/block-framework-introduction

Demonstrates how data in the logic layer is bound to the view layer. When data changes via `setData`, the view updates automatically. This example shows a text element that updates from 'hello' to 'world' upon tapping.

```html
<view>
    <text bindtap="onTap">{{test}}</text>
</view>
```

```javascript
// test.js
Block({
    data: {
        test: 'hello'
    },

methods: {
        onTap() {
            this.setData({
                test: 'world'
            });
        }
    }
})
```

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

### Get Network Type Call Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/network-status/getnetworktype

This snippet demonstrates how to call the getNetworkType API and handle both success and failure responses. It's used to retrieve the device's current network status.

```javascript
tt.getNetworkType({
    success(res) {
      console.log(JSON.stringify(res));
    },
    fail(res) {
      console.log(`getNetworkType fail: ${JSON.stringify(res)}`);
    }
});
```

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

### PC Mini Program Default Startup Pages

Source: https://open.feishu.cn/document/client-docs/gadget/introduction/global-settings

Configure default startup pages for different PC mini program modes within the 'ext' field. Ensure that pages specified in 'defaultPages' are also defined in the 'pages' array to avoid compilation errors.

```json
{
  "pages": [
    "pages/index/index",
    "pages/logs/index",
    "pages/order/index",
    "pages/chat/index"
  ],
  "ext": {
    "defaultPages": {
      "sidebarMode": "pages/order/index",
      "PCMode": "pages/chat/index"
    }
  }
}
```

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

### End Parallel Operation Recording

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/performance/PerformanceRecorder/endparallel

Starts and ends the recording of a parallel asynchronous operation. This example demonstrates how to use `startParallel` to begin recording and `endParallel` to complete it within a `setData` callback. Ensure the performance analysis mode is enabled for this to work.

```javascript
const p = tt.getPerformanceRecorder && tt.getPerformanceRecorder();
// parallel 表示可并行的，开始一段可以和其他异步逻辑并行的异步操作的记录
const parallelID = p && p.startParallel({
  name: 'myIntervalSetData',
  type: 'efgh',
  extra: {
    d: 4,
    e: 5,
    f: 6
  }
})
this.setData({
  list: new Array(40).fill(0).map((item) => {
    return {
      a: randomString(2),
      b: randomString(18),
      c: randomString(40),
      d: randomString(30)
    }
  })
}, () => {
  // 完成一段异步操作的记录
  p && p.endParallel(parallelID)
});
```

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

### getLaunchOptionsSync

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/feishu-launch-parameters/getlaunchoptionssync

Retrieves the cold launch parameters for a mini program. This method is synchronous and returns the same parameters as the App.onLaunch callback.

```APIDOC
## getLaunchOptionsSync()

### Description
Retrieves the cold launch parameters for a mini program. This method is synchronous and returns the same parameters as the App.onLaunch callback.

### Method
Synchronous

### Endpoint
N/A (Client-side API)

### Parameters
This method takes no input parameters.

### Output
Returns an object containing launch options:

- **data** (object) - The main object containing launch options.
  - **path** (string) - The launch page path of the mini program.
  - **query** (object) - The launch parameters of the mini program.
    - **scene** (number | string) - The scene value. The data type is number for PC and string for Android/iOS. Refer to [Scene Values](https://open.feishu.cn/document/uYjL24iN/uQzMzUjL0MzM14CNzMTN) for details.
    - **mode** (string) - The mini program open mode (only returned for PC mini programs).

### Request Example
```js
try {
    let result = tt.getLaunchOptionsSync();
    console.log(`getLaunchOptionsSync success: ${JSON.stringify(result)}`);
} catch (error) {
    console.log(`getLaunchOptionsSync fail: ${JSON.stringify(error)}`);
}
```

### Response Example
```json
{
    "path": "src/page/api/index",
    "scene": "1011",
    "query": {
      "foo": "bar"
    }
}
```
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ble/writeblecharacteristicvalue

Example of a successful response from the writeBLECharacteristicValue API call.

```json
{
	"errMsg": "writeBLECharacteristicValue:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/share/hidesharemenu

This is an example of the success response object returned by the hideShareMenu API.

```json
{
    "errMsg": "hideShareMenu:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/navigation/exitminiprogram

This is an example of the success response object returned by the exitMiniProgram API.

```json
{
    "errMsg": "exitMiniProgram:ok"
}
```

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

### project.config.json Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/directory-structure

Configuration file for a block component project, specifying project settings and the path to the block.

```json
{
  "setting": {
    "es6": true,
    "minified": true,
  },
  "appid": "",
  "projectname": "testblock",
  "blocks": [
    "block/index"
  ]
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/tab-bar/settabbaritem

This is an example of the success response object returned by the setTabBarItem API.

```json
{
    "errMsg": "setTabBarItem:ok"
}
```

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

### block.json Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/directory-structure

Configuration file for a specific block component, defining its type, creator path, and other properties.

```json
{
  "blockTypeID": "REPLACE_WITH_ACTUAL_BLOCK_TYPE_ID",
  "creator": "blockFirst/creator/index", // 此处为 creator 的索引地址
  "useStartLoading": true,
  "actions": []
}
```

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

### Success Response Example for getSetting

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/setting/getsetting

This JSON object illustrates a typical success response from the getSetting API, showing the user's authorization settings.

```json
{
    "authSetting": {
        "scope.clipboard": true,
        "scope.userInfo": true
    },
    "errMsg": "getSetting:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/tab-bar/hidetabbar

This is an example of the success response object returned by the hideTabBar API.

```json
{
    "errMsg": "hideTabBar:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/tab-bar/addtabbaritem

This is an example of the success response object returned by the addTabBarItem API.

```json
{
	"errMsg":"addTabBarItem:ok"
}
```

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

### Start Recording with Options

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/media/record/recordermanager/start

Initiates audio recording with specified parameters such as duration, sample rate, number of channels, and frame size. Ensure the recorderManager is obtained using tt.getRecorderManager().

```js
const recorderManager = tt.getRecorderManager();
const options = {
  duration: 100000,
  sampleRate: 44100,
  numberOfChannels: 2,
  frameSize: 50
};

recorderManager.start(options);
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/navigation/setnavigationbarcolor

This is an example of the success response object returned by the setNavigationBarColor API.

```json
{
    "errMsg": "setNavigationBarColor:ok"
}
```

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

### Example Usage

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/ttml/createselectorquery

Demonstrates how to use createSelectorQuery to select nodes and retrieve their bounding rectangles and viewport scroll offsets.

```APIDOC
## Example Code

```js
const query = tt.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function(res){
  res[0].top       // The top boundary coordinate of the #the-id node
  res[1].scrollTop // The vertical scroll position of the viewport
})
```
```

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

### CSS border-width Syntax Examples

Source: https://open.feishu.cn/document/client-docs/block/block-frame/code-components-and-structure/view-layer/ttss/attributes/border/border-width

Demonstrates various ways to set border widths using keywords and lengths. Supports setting individual widths for top, right, bottom, and left borders.

```css
border-width: thin;
/* 四个边框都是细边框 */
```

```css
border-width: thin medium;
/* 上边框是细边框 | 右边框是中等边框 | 下边框缺省与上边框相同 | 左边框缺省与右边框相同 */
```

```css
border-width: thin medium thick;
/* 上边框是细边框 | 右边框是中等边框 | 下边框是粗边框 | 左边框缺省与右边框相同 */
```

```css
border-width: thin medium thick 10px;
/* 上边框是细边框 | 右边框是中等边框 | 下边框是粗边框 ｜ 左边框是10px宽的边框 */
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/clipboard/setclipboarddata

This is an example of the success response object returned by the setClipboardData API.

```json
{
    "errMsg": "setClipboardData:ok"
}
```

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

### Block Lifecycle Hooks Example

Source: https://open.feishu.cn/document/client-docs/block/block-frame/lifecycle

Demonstrates how to implement onLoad and onActivate hooks to initialize event listeners and restore data and listeners upon activation.

```javascript
function init() {
  tt.onViewResize(console.log);
}
Block({
  onLoad() {
    init();
  },
  onActivate(activeState) {
    this.setData(activeState);  // 恢复数据
    init();  // 恢复事件监听
  },
});
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ble/disconnectbledevice

This is an example of the success response object returned by the disconnectBLEDevice API.

```json
{
  "errMsg": "connectBLEDevice:ok"
}
```

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

### Uni-app Watcher with Immediate Option

Source: https://open.feishu.cn/document/client-docs/gadget/framework/new-framework/breaking-changes

Vue 3 setup function using 'watch' with `{ immediate: true }` to ensure the callback runs immediately upon watcher creation.

```javascript
export default defineComponent({
    name: 'container',
    // ...
    setup(props) {
        watch(() => props.create, (v) => {
            if (v === 'true') {
                // ... 更新逻辑
            }
        }, { immediate: true });
    }
})
```

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

### Login API Call Example

Source: https://open.feishu.cn/document/client-docs/block/api/user/login

Demonstrates how to call the login API and handle success and failure callbacks. Ensure the `tt.login` function is available in your environment.

```javascript
tt.login({
  success (res) {
    console.log('login 调用成功', res.code);
  },
  fail (res) {
    console.log('login 调用失败', res.errMsg);
  },
  complete (res) {
    console.log('login 调用结束', res.errMsg);
  }
});
```

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

### Choose Location Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/location/chooselocation

Demonstrates how to call the chooseLocation API. Requires 'scope.userLocation' authorization. Success and failure callbacks log the results.

```javascript
tt.chooseLocation({
    "type": "gcj02",
    success(res) {
      console.log(JSON.stringify(res));
    },
    fail(res) {
      console.log(`chooseLocation fail: ${JSON.stringify(res)}`);
    }
});
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/interaction-feedback/hidetoast

This is an example of the response object returned on successful execution of the hideToast function.

```json
{
  errMsg: "hideToast:ok"
}
```

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

### Get Cold Launch Options Synchronously

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/feishu-launch-parameters/getlaunchoptionssync

Call this method to retrieve the parameters passed during a mini program's cold launch. It's recommended to use a try-catch block to handle potential errors.

```javascript
try {
    let result = tt.getLaunchOptionsSync();
    console.log(`getLaunchOptionsSync success: ${JSON.stringify(result)}`);
} catch (error) {
    console.log(`getLaunchOptionsSync fail: ${JSON.stringify(error)}`);
}
```

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

### Signature Error Response Example

Source: https://open.feishu.cn/document/client-docs/h5/development-guide/step-2:-call-jsapi(optional)

Example JSON response returned when a signature validation failure occurs.

```json
{
	"errorCode": 333441,
	"errorMessage": "invalid signature: signature: c872b****, jsticket: g1014****, nonce_str: zdcW****, url: https://www.example.com, timestamp: %!s(int64=1234)"}
```

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

### Location Change Callback Object Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/location/onlocationchange

An example of the data structure returned by the onLocationChange callback function.

```json
{
    "longitude": 120.02278184678819,
    "latitude": 30.28898898654514,
    "accuracy": 148,
    "verticalAccuracy": 11.42357063293457,
    "horizontalAccuracy": 148,
    "timestamp": 1637497698313
}
```

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

### setStorage Configuration Example

Source: https://open.feishu.cn/document/client-docs/block/api/data-cache/setstorage

This JSON object shows the configuration for calling the setStorage API, including source data, title, and minimum required client versions.

```json
{
  "sourceData":{
          "tab": "api",
          "item": "setStorage"
  },
    "openDetail": 1, 
    "title": "setStorage", 
    "list_page_url": "https://applink.feishu.cn/client/block/workplace/open?appId=cli_a00834ec56f8d01b%26blockTypeId=blk_610a40455f800004c32b6bb6%26sourceData=%7B%22tab%22%3A%22api%22%2C%22item%22%3A%22login%22%7D", 
    "min_lk_ver": {
        "pc": "5.10.0", 
        "mobile": "5.11.0"
    },
    "blockEntity": {
        "sourceData": {
            "type": "api",
            "item": "setStorage",
            "isNew": true
        },
                  "blockID": "mock-block"
    }
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/interface/tab-bar/showtabbarreddot

This is an example of the success response object returned by the showTabBarRedDot API when the operation is successful.

```json
{
    "errMsg": "showTabBarRedDot:ok"
}
```

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

### Failure Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/device/ble/writeblecharacteristicvalue

Example of a failed response from the writeBLECharacteristicValue API call, including error code.

```json
{
    "errMsg": "writeBLECharacteristicValue:fail device not found",
    "errCode": 10002
}
```

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

### Check for Updates and Apply

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/update/getUpdateManager/applyupdate

This snippet demonstrates how to get the update manager, check for updates, handle the update ready event by applying the update, and manage update failures. It also includes a periodic check for updates.

```javascript
try {
      const updateManager = tt.getUpdateManager()
      updateManager.onCheckForUpdate(function (res) {
      	// 请求完新版本信息的回调
     	 console.log(res.hasUpdate)
      })
      updateManager.onUpdateReady(function () {
       // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
       	updateManager.applyUpdate()
      })
      updateManager.onUpdateFailed(function () {
     	// 新版本下载失败
      	console.log('download error');
      })
      // 每隔一个小时主动检查更新一次
      setInterval(() => updateManager.triggerCheckUpdate(), 60*60*1000)
	} catch (error) {
	    console.log(`getUpdateManager fail: ${JSON.stringify(error)}`);
	}
```

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

### CSS top Attribute Syntax Examples

Source: https://open.feishu.cn/document/client-docs/block/block-frame/code-components-and-structure/view-layer/ttss/attributes/position/top

Demonstrates various ways to set the 'top' attribute using different units and functions.

```css
top: 3px;
top: 2rpx;
top: 2.4em;
top: 3rem;
```

```css
top: 10%;
```

```css
top: auto;
```

```css
top: calc(1px + 1px);
```

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

### Error Handling and Retry Logic for Start

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/media/record/recordermanager/start

Implements a retry mechanism for the start method when specific errors occur on iOS, such as 'OperateRecorder start failed'. It listens for errors and attempts to restart the recording up to a maximum of 3 times with a short delay.

```js
/// 假定，最多重试 3 次
  var leftRetryTimes = 3

recorderManager.onError((error) => {
     this.onRecordError(error)
  });

onRecordError(error) {
    console.log('onError:', error);
    /// 如果是start失败报错
    const _this = this
    if (error.errno === 1305003 && error.errString.includes('OperateRecorder start failed')) {
      if (this.data.leftRetryTimes > 0) {
        _this.recorderManager.stop();
        setTimeout( () => {
          console.log('retry start record, left times: ', _this.data.leftRetryTimes)
          _this.data.leftRetryTimes -= 1;
          _this.startRecord()
        }, 500)
      } else {
        console.log('retry start record failed')
      }
    }
  },
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/sport-and-health/getstepcount

An example of a successful response from the getStepCount API, containing the step count and a success message.

```json
{
    "stepCount": 8,
    "errMsg": "getStepCount:ok"
}
```

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

### Success Response Example

Source: https://open.feishu.cn/document/client-docs/gadget/-web-app-api/open-ability/chat/enterbot

This is an example of the success response object returned by the enterBot API upon successful execution.

```json
{
  "errMsg": "enterBot:ok"
}
```
Tokens:
Raw