API 參考

uni-app 提供了超豐富的 API 接口，讓開發者能夠輕鬆調用各種設備功能和平台服務。這章節將詳細介紹各類 API 的使用方法，讓你開發跨平台應用變得超簡單！

API 分類

基礎 API

網路請求

• uni.request() - 發起網路請求，輕鬆獲取資料
• uni.uploadFile() - 上傳檔案，支援多種格式
• uni.downloadFile() - 下載檔案，快速又方便
• uni.connectSocket() - 建立 WebSocket 連接，即時通訊超簡單

資料快取

• uni.setStorage() - 非同步儲存資料，不卡頓
• uni.setStorageSync() - 同步儲存資料，立即生效
• uni.getStorage() - 非同步獲取資料，流暢體驗
• uni.getStorageSync() - 同步獲取資料，即時響應
• uni.removeStorage() - 非同步刪除資料，清理空間
• uni.clearStorage() - 清空本地資料，重新開始

介面 API

互動回饋

• uni.showToast() - 顯示訊息提示框，溫馨提醒
• uni.showLoading() - 顯示載入提示框，等待不無聊
• uni.hideLoading() - 隱藏載入提示框，完成任務
• uni.showModal() - 顯示模態對話框，確認操作
• uni.showActionSheet() - 顯示操作選單，選擇超方便

導航列

• uni.setNavigationBarTitle() - 設定導航列標題，個性化顯示
• uni.setNavigationBarColor() - 設定導航列顏色，美觀大方
• uni.showNavigationBarLoading() - 顯示導航列載入動畫，視覺效果佳
• uni.hideNavigationBarLoading() - 隱藏導航列載入動畫，完成載入

背景

• uni.setBackgroundColor() - 設定視窗背景色，自訂風格
• uni.setBackgroundTextStyle() - 設定下拉背景字體樣式，細節滿分

路由 API

頁面跳轉

• uni.navigateTo() - 保留當前頁面，跳轉到應用內的某個頁面
• uni.redirectTo() - 關閉當前頁面，跳轉到應用內的某個頁面
• uni.reLaunch() - 關閉所有頁面，打開到應用內的某個頁面
• uni.switchTab() - 跳轉到 tabBar 頁面，切換超順暢
• uni.navigateBack() - 關閉當前頁面，返回上一頁面

設備 API

系統資訊

• uni.getSystemInfo() - 獲取系統資訊，了解設備狀況
• uni.getSystemInfoSync() - 同步獲取系統資訊，即時響應
• uni.canIUse() - 判斷應用的 API，回調，參數，組件等是否在當前版本可用

網路狀態

• uni.getNetworkType() - 獲取網路類型，連線狀況一目了然
• uni.onNetworkStatusChange() - 監聽網路狀態變化，即時反應

加速度計

• uni.onAccelerometerChange() - 監聽加速度資料，動態感應
• uni.startAccelerometer() - 開始監聽加速度資料，啟動感應
• uni.stopAccelerometer() - 停止監聽加速度資料，節省資源

羅盤

• uni.onCompassChange() - 監聽羅盤資料，方向感應
• uni.startCompass() - 開始監聽羅盤資料，啟動導航
• uni.stopCompass() - 停止監聽羅盤資料，結束使用

媒體 API

圖片

• uni.chooseImage() - 從本地相簿選擇圖片或使用相機拍照
• uni.previewImage() - 預覽圖片，瀏覽超方便
• uni.getImageInfo() - 獲取圖片資訊，了解圖片詳情
• uni.saveImageToPhotosAlbum() - 儲存圖片到系統相簿，永久保存

錄音

• uni.startRecord() - 開始錄音，記錄聲音
• uni.stopRecord() - 停止錄音，完成錄製

音訊播放控制

• uni.playVoice() - 開始播放語音，聆聽聲音
• uni.pauseVoice() - 暫停正在播放的語音，稍作休息
• uni.stopVoice() - 結束播放語音，停止播放

音樂播放控制

• uni.getBackgroundAudioManager() - 獲取全域唯一的背景音訊管理器
• uni.createAudioContext() - 建立並返回 audio 上下文 audioContext 物件

影片

• uni.chooseVideo() - 拍攝影片或從手機相簿中選影片
• uni.saveVideoToPhotosAlbum() - 儲存影片到系統相簿，珍藏回憶
• uni.createVideoContext() - 建立並返回 video 上下文 videoContext 物件

位置 API

獲取位置

• uni.getLocation() - 獲取當前的地理位置、速度
• uni.chooseLocation() - 開啟地圖選擇位置，精確定位

檢視位置

• uni.openLocation() - 使用應用內建地圖檢視位置，地圖瀏覽

檔案 API

檔案管理

• uni.saveFile() - 儲存檔案到本地，安全保存
• uni.getSavedFileList() - 獲取本地已儲存的檔案列表，一目了然
• uni.getSavedFileInfo() - 獲取本地檔案的檔案資訊，了解詳情
• uni.removeSavedFile() - 刪除本地儲存的檔案，清理空間
• uni.openDocument() - 新開頁面開啟文件，瀏覽文件

繪圖 API

Canvas

• uni.createCanvasContext() - 建立 canvas 繪圖上下文
• uni.canvasToTempFilePath() - 把當前畫布指定區域的內容匯出生成指定大小的圖片
• uni.canvasGetImageData() - 返回一個陣列，用來描述 canvas 區域隱含的像素資料
• uni.canvasPutImageData() - 將像素資料繪製到畫布

第三方平台 API

登入

• uni.login() - 呼叫介面獲取登入憑證
• uni.checkSession() - 檢查登入狀態是否過期

授權

• uni.authorize() - 提前向用戶發起授權請求
• uni.getSetting() - 獲取用戶的當前設定

用戶資訊

• uni.getUserInfo() - 獲取用戶資訊

微信支付

• uni.requestPayment() - 發起微信支付

模板訊息

• uni.addTemplate() - 組合模板並新增至帳號下的個人模板庫
• uni.deleteTemplate() - 刪除帳號下的某個模板
• uni.getTemplateLibraryById() - 獲取模板庫某個模板標題下關鍵詞庫
• uni.getTemplateLibraryList() - 獲取小程序模板庫標題列表
• uni.getTemplateList() - 獲取帳號下已存在的模板列表
• uni.sendTemplateMessage() - 發送模板訊息

API 使用範例

網路請求範例

// 發起 GET 請求
uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  data: {
    id: 1
  },
  success: (res) => {
    console.log('請求成功', res.data)
  },
  fail: (err) => {
    console.error('請求失敗', err)
  }
})

// 發起 POST 請求
uni.request({
  url: 'https://api.example.com/submit',
  method: 'POST',
  data: {
    name: '張三',
    age: 25
  },
  header: {
    'Content-Type': 'application/json'
  },
  success: (res) => {
    console.log('提交成功', res.data)
  }
})

資料儲存範例

// 非同步儲存資料
uni.setStorage({
  key: 'userInfo',
  data: {
    name: '張三',
    age: 25
  },
  success: () => {
    console.log('儲存成功')
  }
})

// 同步儲存資料
try {
  uni.setStorageSync('token', 'abc123')
  console.log('儲存成功')
} catch (e) {
  console.error('儲存失敗', e)
}

// 非同步獲取資料
uni.getStorage({
  key: 'userInfo',
  success: (res) => {
    console.log('獲取成功', res.data)
  }
})

// 同步獲取資料
try {
  const token = uni.getStorageSync('token')
  console.log('獲取成功', token)
} catch (e) {
  console.error('獲取失敗', e)
}

頁面跳轉範例

// 跳轉到新頁面
uni.navigateTo({
  url: '/pages/detail/detail?id=123'
})

// 重新導向到新頁面
uni.redirectTo({
  url: '/pages/login/login'
})

// 返回上一頁
uni.navigateBack({
  delta: 1
})

// 跳轉到 tabBar 頁面
uni.switchTab({
  url: '/pages/index/index'
})

互動回饋範例

// 顯示提示框
uni.showToast({
  title: '操作成功',
  icon: 'success',
  duration: 2000
})

// 顯示載入框
uni.showLoading({
  title: '載入中...'
})

// 隱藏載入框
setTimeout(() => {
  uni.hideLoading()
}, 2000)

// 顯示模態對話框
uni.showModal({
  title: '提示',
  content: '確定要刪除這條記錄嗎？',
  success: (res) => {
    if (res.confirm) {
      console.log('用戶點擊確定')
    } else if (res.cancel) {
      console.log('用戶點擊取消')
    }
  }
})

系統資訊範例

// 獲取系統資訊
uni.getSystemInfo({
  success: (res) => {
    console.log('設備品牌：', res.brand)
    console.log('設備型號：', res.model)
    console.log('操作系統：', res.platform)
    console.log('系統版本：', res.system)
    console.log('螢幕寬度：', res.screenWidth)
    console.log('螢幕高度：', res.screenHeight)
  }
})

// 同步獲取系統資訊
try {
  const res = uni.getSystemInfoSync()
  console.log('系統資訊：', res)
} catch (e) {
  console.error('獲取系統資訊失敗', e)
}

選擇圖片範例

// 選擇圖片
uni.chooseImage({
  count: 1,
  sizeType: ['original', 'compressed'],
  sourceType: ['album', 'camera'],
  success: (res) => {
    const tempFilePaths = res.tempFilePaths
    console.log('選擇的圖片：', tempFilePaths)
    
    // 預覽圖片
    uni.previewImage({
      urls: tempFilePaths
    })
  }
})

API 相容性

不同平台對 API 的支援程度可能不同，使用前請檢視具體 API 的相容性說明：

API 類別	H5	小程序	App
網路請求	✅	✅	✅
資料快取	✅	✅	✅
介面互動	✅	✅	✅
路由跳轉	✅	✅	✅
設備資訊	部分	✅	✅
媒體功能	部分	✅	✅
位置服務	部分	✅	✅
檔案操作	部分	✅	✅
第三方平台	❌	✅	部分

注意事項

1. 非同步 API：大部分 API 都是非同步的，需要透過 success、fail、complete 回調函數處理結果
2. 同步 API：同步 API 通常以 Sync 結尾，會阻塞當前線程，謹慎使用
3. 平台差異：不同平台對 API 的支援可能不同，開發時需要注意相容性
4. 權限申請：某些 API 需要用戶授權才能使用，如位置、相機、麥克風等
5. 錯誤處理：建議為每個 API 呼叫新增錯誤處理邏輯

相關連結

• 快速上手 - 學習如何建立和執行 uni-app 專案
• 網路請求 - 詳細了解網路請求的使用方法
• 資料儲存 - 學習本地資料儲存的最佳實踐
• 常見問題 - 檢視 API 使用中的常見問題和解決方案