API 基本概要

概念说明
API（应用程序接口）是预先定义的方法集合，用于实现特定功能。在 uni-app 中，通过全局对象 uni 调用 API，例如 uni.getSystemInfoSync 获取设备信息。

API 分类与调用规则

1. 事件监听型
   • 以 on 开头，如 uni.onNetworkStatusChange 监听网络变化。
2. 数据操作型
   • 获取数据：以 get 开头，如 uni.getStorage 读取本地缓存。
   • 设置数据：以 set 开头，如 uni.setNavigationBarTitle 修改导航栏标题。

同步与异步 API 的本质区别

• 同步 API：执行时阻塞后续代码，需等待操作完成才能继续执行。
  • 特征：方法名以 Sync 结尾，如 uni.getSystemInfoSync。
  • 适用场景：轻量级操作（如读取缓存）。
• 异步 API：执行时不阻塞后续代码，通过回调函数或 Promise 返回结果。
  • 特征：无特殊后缀，如 uni.request 发起网络请求。
  • 适用场景：耗时操作（如网络请求、文件读写）。

Promise 化调用机制

• Promise 核心作用：标准化异步操作管理，解决回调嵌套问题。

• uni-app 的 Promise 化规则：

  • 大部分异步 API 支持 .then() 链式调用（需注意：同步方法及特定 API 如 create*/*Manager 不支持）。

• 代码对比示例

  // 传统回调写法  
  const task = uni.connectSocket({  
    success(res) { console.log(res); }  
  });  
  
  // Promise 化写法  
  uni.connectSocket().then(res => {  
    console.log(res); // 此处 res 与 success 回调参数一致  
  }).catch(err => {  
    console.error(err); // 异常捕获  
  });  
  

  优势：代码结构扁平化，逻辑更清晰，便于异常统一处理。

Promise 化注意事项

1. 不支持的 API 类型：
   • 同步方法（如 *Sync 结尾的 API）。
   • 上下文创建型（如 uni.createMapContext）。
   • 管理器类（如 uni.getBackgroundAudioManager）。
2. 兼容性处理：
   • 可通过 uni-promisify 库手动封装非 Promise 化 API。

计时器API

定时器基础操作

创建定时器

• 单次执行：setTimeout(callback, delay, ...args)

  • delay：延迟时间（毫秒单位）
  • args：可选参数，传递给回调函数

  const timerId = setTimeout(() => {  
    console.log('延迟2秒执行');  
  }, 2000);  
  

• 重复执行：setInterval(callback, interval, ...args)

  • interval：间隔时间（毫秒单位）

  const intervalId = setInterval(() => {  
    console.log('每隔1秒执行一次');  
  }, 1000);  
  

取消定时器

• clearTimeout(timeoutID) 或 clearInterval(intervalID)

  clearTimeout(timerId);  // 取消单次定时器  
  clearInterval(intervalId); // 取消重复定时器  
  

注意事项

• 跨平台差异：小程序环境中定时器不会随页面销毁自动清除，需在onUnload生命周期手动清理。
• 性能优化：避免频繁创建定时器，防止内存泄漏。

---

界面交互 API

1. 消息提示框

显示提示：uni.showToast({ ... })

• 关键参数：

  uni.showToast({  
    title: '操作成功',  
    icon: 'success',     // 可选值：success/loading/none  
    duration: 2000,      // 默认1500ms  
    mask: true           // 是否禁止穿透点击（防误触）  
  });  
  

隐藏提示：uni.hideToast()

---

2. 加载状态提示

显示加载：uni.showLoading({ ... })

• 典型场景：网络请求等待

  uni.showLoading({  
    title: '加载中...',  
    mask: true  
  });  
  
  // 请求完成后调用  
  uni.hideLoading();  
  

---

3. 模态对话框

显示模态框：uni.showModal({ ... })

• 参数与回调：

  uni.showModal({  
    title: '确认删除',  
    content: '删除后无法恢复',  
    editable: true,       // 是否显示输入框  
    placeholderText: '请输入备注',  
    success: (res) => {  
      if (res.confirm) {  
        console.log('用户点击确定', res.content);  
      } else if (res.cancel) {  
        console.log('用户点击取消');  
      }  
    }  
  });  
  

---

4. 操作菜单

显示菜单：uni.showActionSheet({ ... })

• 交互逻辑：

  uni.showActionSheet({  
    itemList: ['保存草稿', '发布文章', '取消'],  
    success: (res) => {  
      const index = res.tapIndex;  
      if (index === 0) console.log('保存草稿');  
      else if (index === 1) console.log('发布文章');  
    },  
    fail: () => console.log('菜单调用失败')  
  });  
  

---