@tarojs/taro 3.4.1 → 3.4.2

package/types/api/network/udp.d.ts

@@ -2,53 +2,84 @@ import Taro from '../../index'
 
 declare module '../../index' {
   /** 一个 UDP Socket 实例，默认使用 IPv4 协议。
+   * @supported weapp
    * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.html
    */
   interface UDPSocket {
-    /** 关闭 UDP Socket 实例，相当于销毁。 在关闭之后，UDP Socket 实例不能再发送消息，每次调用 `UDPSocket.send` 将会触发错误事件，并且 message 事件回调函数也不会再也执行。在 `UDPSocket` 实例被创建后将被 Native 强引用，保证其不被 GC。在 `UDPSocket.close` 后将解除对其的强引用，让 UDPSocket 实例遵从 GC。
+    /** 绑定一个系统随机分配的可用端口，或绑定一个指定的端口号
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.close.html
+     * @example
+     * ```tsx
+     * const udp = Taro.createUDPSocket()
+     * udp.close()
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.bind.html
      */
-    close(): void
-    /** 取消监听关闭事件
+    bind(
+      /** 指定要绑定的端口号，不传则返回系统随机分配的可用端口 */
+      port: number,
+    ): number
+    /** 设置 IP_TTL 套接字选项，用于设置一个 IP 数据包传输时允许的最大跳步数
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offClose.html
+     * @example
+     * ```tsx
+     * const udp = Taro.createUDPSocket()
+     * udp.onListening(function () {
+     *   udp.setTTL(64)
+     * })
+     * udp.bind()
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.setTTL.html
      */
-    offClose(
-      /** 关闭事件的回调函数 */
-      callback: UDPSocket.OffCloseCallback,
+    setTTL(
+      /** ttl 参数可以是 0 到 255 之间 */
+      ttl: number
     ): void
-    /** 取消监听错误事件
+    /** 向指定的 IP 和 port 发送消息
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offError.html
+     * @example
+     * ```tsx
+     * const udp = Taro.createUDPSocket()
+     * udp.bind()
+     * udp.send({
+     *   address: '192.168.193.2',
+     *   port: 8848,
+     *   message: 'hello, how are you'
+     * })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.send.html
      */
-    offError(
-      /** 错误事件的回调函数 */
-      callback: UDPSocket.OffErrorCallback,
-    ): void
-    /** 取消监听开始监听数据包消息的事件
+    send(option: UDPSocket.send.Option): void
+    /** 预先连接到指定的 IP 和 port，需要配合 write 方法一起使用
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offListening.html
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.connect.html
      */
-    offListening(
-      /** 开始监听数据包消息的事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
-    ): void
-    /** 取消监听收到消息的事件
+    connect(option: UDPSocket.connect.Option): void
+    /** 用法与 send 方法相同，如果没有预先调用 connect 则与 send 无差异（注意即使调用了 connect 也需要在本接口填入地址和端口参数）
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offMessage.html
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.write.html
      */
-    offMessage(
-      /** 收到消息的事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
-    ): void
+    write(): void
+    /** 关闭 UDP Socket 实例，相当于销毁。 在关闭之后，UDP Socket 实例不能再发送消息，每次调用 `UDPSocket.send` 将会触发错误事件，并且 message 事件回调函数也不会再也执行。在 `UDPSocket` 实例被创建后将被 Native 强引用，保证其不被 GC。在 `UDPSocket.close` 后将解除对其的强引用，让 UDPSocket 实例遵从 GC。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.close.html
+     */
+    close(): void
     /** 监听关闭事件
      * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.onClose.html
      */
     onClose(
       /** 关闭事件的回调函数 */
-      callback: UDPSocket.OnCloseCallback,
+      callback: UDPSocket.onClose.Callback,
+    ): void
+    /** 取消监听关闭事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offClose.html
+     */
+    offClose(
+      /** 关闭事件的回调函数 */
+      callback: UDPSocket.onClose.Callback,
     ): void
     /** 监听错误事件
      * @supported weapp
@@ -56,15 +87,31 @@ declare module '../../index' {
      */
     onError(
       /** 错误事件的回调函数 */
-      callback: UDPSocket.OnErrorCallback,
+      callback: UDPSocket.onError.Callback,
+    ): void
+    /** 取消监听错误事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offError.html
+     */
+    offError(
+      /** 错误事件的回调函数 */
+      callback: UDPSocket.onError.Callback,
     ): void
     /** 监听开始监听数据包消息的事件
      * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.onListening.html
      */
     onListening(
-      /** 开始监听数据包消息的事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
+      /** 监听开始监听数据包消息的事件 */
+      callback: UDPSocket.onListening.Callback,
+    ): void
+    /** 取消监听开始监听数据包消息的事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offListening.html
+     */
+    offListening(
+      /** 监听开始监听数据包消息的事件 */
+      callback: UDPSocket.onListening.Callback,
     ): void
     /** 监听收到消息的事件
      * @supported weapp
@@ -72,68 +119,92 @@ declare module '../../index' {
      */
     onMessage(
       /** 收到消息的事件的回调函数 */
-      callback: UDPSocket.OnMessageCallback,
+      callback: UDPSocket.onMessage.Callback,
     ): void
-    /** 向指定的 IP 和 port 发送消息
-     * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.send.html
-     */
-    send(option: UDPSocket.SendOption): void
-    /** 绑定一个系统随机分配的可用端口，或绑定一个指定的端口号
+    /** 取消监听收到消息的事件
      * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.bind.html
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/udp/UDPSocket.offMessage.html
      */
-    bind(
-      /** 指定要绑定的端口号 */
-      port: number,
-    ): number
+    offMessage(
+      /** 收到消息的事件的回调函数 */
+      callback: UDPSocket.onMessage.Callback,
+    ): void
   }
 
   namespace UDPSocket {
-    /** 关闭事件的回调函数 */
-    type OffCloseCallback = (res: TaroGeneral.CallbackResult) => void
-    /** 错误事件的回调函数 */
-    type OffErrorCallback = (res: TaroGeneral.CallbackResult) => void
-    /** 关闭事件的回调函数 */
-    type OnCloseCallback = (res: TaroGeneral.CallbackResult) => void
-    /** 错误事件的回调函数 */
-    type OnErrorCallback = (
-        result: OnErrorCallbackResult,
-    ) => void
-    /** 收到消息的事件的回调函数 */
-    type OnMessageCallback = (
-        result: OnMessageCallbackResult,
-    ) => void
-    interface OnErrorCallbackResult extends TaroGeneral.CallbackResult {
-      /** 错误信息 */
-      errMsg: string
+    namespace connect {
+      interface Option {
+        /** 要发消息的地址 */
+        address: string
+        /** 要发送消息的端口号 */
+        port: number
+      }
     }
-    interface OnMessageCallbackResult {
-      /** 收到的消息 */
-      message: ArrayBuffer
-      /** 消息来源的结构化信息 */
-      remoteInfo: RemoteInfo
+    namespace onClose {
+      /** 当一个 socket 完全关闭就发出该事件的回调函数 */
+      type Callback = (...args: unknown[]) => void
     }
-    /** 消息来源的结构化信息 */
-    interface RemoteInfo {
-      /** 发送消息的 socket 的地址 */
-      address: string
-      /** 使用的协议族，为 IPv4 或者 IPv6 */
-      family: string
-      /** 端口号 */
-      port: number
-      /** message 的大小，单位：字节 */
-      size: number
+    namespace onError {
+      /** 错误事件的回调函数 */
+      type Callback = (result: CallbackResult) => void
+      interface CallbackResult extends TaroGeneral.CallbackResult {
+        /** 错误信息 */
+        errMsg: string
+      }
+    }
+    namespace onListening {
+      /** 监听开始监听数据包消息的事件 */
+      type Callback = (...args: unknown[]) => void
+    }
+    namespace onMessage {
+      /** 收到消息的事件的回调函数 */
+      type Callback = (result: CallbackResult) => void
+      interface CallbackResult extends TaroGeneral.CallbackResult {
+        /** 收到的消息 */
+        message: ArrayBuffer
+        /** 发送端地址信息 */
+        remoteInfo: RemoteInfo
+        /** 接收端地址信息 */
+        localInfo: LocalInfo
+      }
+      /** 发送端地址信息 */
+      interface RemoteInfo {
+        /** 发送消息的 socket 的地址 */
+        address: string
+        /** 使用的协议族，为 IPv4 或者 IPv6 */
+        family: string
+        /** 端口号 */
+        port: number
+      }
+      /** 接收端地址信息 */
+      interface LocalInfo {
+        /** 接收消息的 socket 的地址 */
+        address: string
+        /** 使用的协议族，为 IPv4 或者 IPv6 */
+        family: string
+        /** 端口号 */
+        port: number
+        /** message 的大小，单位：字节 */
+        size: number
+      }
     }
-    interface SendOption {
-      /** 需要发送的内容 */
-      data: string | ArrayBuffer
-      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
-      complete?: (res: TaroGeneral.CallbackResult) => void
-      /** 接口调用失败的回调函数 */
-      fail?: (res: TaroGeneral.CallbackResult) => void
-      /** 接口调用成功的回调函数 */
-      success?: (res: TaroGeneral.CallbackResult) => void
+    namespace send {
+      interface Option {
+        /** 要发消息的地址。在基础库 <= 2.9.3 版本必须是和本机同网段的 IP 地址，或安全域名列表内的域名地址；之后版本可以是任意 IP 和域名 */
+        address: string
+        /** 要发送消息的端口号 */
+        port: number
+        /** 要发送的数据 */
+        message: string | ArrayBuffer
+        /** 发送数据的偏移量，仅当 message 为 ArrayBuffer 类型时有效
+         * @default 0
+         */
+        offset?: number
+        /** 发送数据的长度，仅当 message 为 ArrayBuffer 类型时有效
+         * @default message.byteLength
+         */
+        length?: number
+      }
     }
   }
 

package/types/api/network/upload.d.ts

@@ -76,24 +76,48 @@ declare module '../../index' {
   }
 
   /** 一个可以监听上传进度变化事件，以及取消上传任务的对象
+   * @supported weapp, swan, alipay, h5, rn
+   * @example
+   * ```tsx
+   * const uploadTask = Taro.uploadFile({
+   *   url: 'http://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
+   *   filePath: tempFilePaths[0],
+   *   name: 'file',
+   *   formData:{
+   *     'user': 'test'
+   *   },
+   *   success (res){
+   *     const data = res.data
+   *     //do something
+   *   }
+   * })
+   *
+   * uploadTask.onProgressUpdate((res) => {
+   *   console.log('上传进度', res.progress)
+   *   console.log('已经上传的数据长度', res.totalBytesSent)
+   *   console.log('预期需要上传的数据总长度', res.totalBytesExpectedToSend)
+   * })
+   *
+   * uploadTask.abort() // 取消上传任务
+   * ```
    * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.html
    */
   interface UploadTask {
     /** 中断上传任务
-     * @supported weapp
+     * @supported weapp, h5
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.abort.html
      */
     abort(): void
-    /** 取消监听 HTTP Response Header 事件
-     * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.offHeadersReceived.html
+    /** 监听上传进度变化事件
+     * @supported weapp, h5
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.onProgressUpdate.html
      */
-    offHeadersReceived(
-      /** HTTP Response Header 事件的回调函数 */
-      callback: UploadTask.OffHeadersReceivedCallback,
+    onProgressUpdate(
+      /** 上传进度变化事件的回调函数 */
+      callback: UploadTask.OnProgressUpdateCallback,
     ): void
     /** 取消监听上传进度变化事件
-     * @supported weapp
+     * @supported weapp, h5
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.offProgressUpdate.html
      */
     offProgressUpdate(
@@ -101,34 +125,26 @@ declare module '../../index' {
       callback: UploadTask.OffProgressUpdateCallback,
     ): void
     /** 监听 HTTP Response Header 事件。会比请求完成事件更早
-     * @supported weapp
+     * @supported weapp, h5
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.onHeadersReceived.html
      */
     onHeadersReceived(
       /** HTTP Response Header 事件的回调函数 */
       callback: UploadTask.OnHeadersReceivedCallback,
     ): void
-    headersReceived(
-      /** HTTP Response Header 事件的回调函数 */
-      callback: UploadTask.OnHeadersReceivedCallback,
-    ): void
-    /** 监听上传进度变化事件
-     * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.onProgressUpdate.html
+    /** 取消监听 HTTP Response Header 事件
+     * @supported weapp, h5
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/upload/UploadTask.offHeadersReceived.html
      */
-    onProgressUpdate(
-      /** 上传进度变化事件的回调函数 */
-      callback: UploadTask.OnProgressUpdateCallback,
-    ): void
-    progress(
-      /** 上传进度变化事件的回调函数 */
-      callback: UploadTask.OnProgressUpdateCallback,
+    offHeadersReceived(
+      /** HTTP Response Header 事件的回调函数 */
+      callback: UploadTask.OffHeadersReceivedCallback,
     ): void
   }
 
   interface TaroStatic {
     /** 将本地资源上传到服务器。客户端发起一个 HTTPS POST 请求，其中 `content-type` 为 `multipart/form-data`。使用前请注意阅读[相关说明](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html)。
-     * @supported weapp, swan, alipay, h5
+     * @supported weapp, swan, alipay, h5, rn
      * @example
      * ```tsx
      * Taro.chooseImage({
@@ -152,7 +168,7 @@ declare module '../../index' {
      * @example
      * ```tsx
      * const uploadTask = Taro.uploadFile({
-     *   url: 'http://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
+     *   url: 'https://example.weixin.qq.com/upload', //仅为示例，非真实的接口地址
      *   filePath: tempFilePaths[0],
      *   name: 'file',
      *   formData:{

package/types/api/network/websocket.d.ts

@@ -137,15 +137,29 @@ declare module '../../index' {
     }
   }
 
-  /** WebSocket 任务，可通过 [Taro.connectSocket()](https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.html) 接口创建返回。
+  /** WebSocket 任务，可通过 [Taro.connectSocket()](/docs/apis/network/websocket/SocketTask) 接口创建返回。
+   * @supported weapp, h5, rn, alipay, swan
    * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.html
    */
   interface SocketTask {
+    /** 通过 WebSocket 连接发送数据
+     * @supported weapp, h5, rn, alipay, swan
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.send.html
+     */
+    send(option: SocketTask.SendOption): void
     /** 关闭 WebSocket 连接
      * @supported weapp, h5, rn, alipay, swan
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.close.html
      */
     close(option: SocketTask.CloseOption): void
+    /** 监听 WebSocket 连接打开事件
+     * @supported weapp, h5, rn, alipay, swan
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.onOpen.html
+     */
+    onOpen(
+      /** WebSocket 连接打开事件的回调函数 */
+      callback: SocketTask.OnOpenCallback
+    ): void
     /** 监听 WebSocket 连接关闭事件
      * @supported weapp, h5, rn, alipay, swan
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.onClose.html
@@ -170,19 +184,6 @@ declare module '../../index' {
       /** WebSocket 接受到服务器的消息事件的回调函数 */
       callback: SocketTask.OnMessageCallback<T>
     ): void
-    /** 监听 WebSocket 连接打开事件
-     * @supported weapp, h5, rn, alipay, swan
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.onOpen.html
-     */
-    onOpen(
-      /** WebSocket 连接打开事件的回调函数 */
-      callback: SocketTask.OnOpenCallback
-    ): void
-    /** 通过 WebSocket 连接发送数据
-     * @supported weapp, h5, rn, alipay, swan
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/network/websocket/SocketTask.send.html
-     */
-    send(option: SocketTask.SendOption): void
 
     /** websocket 当前的连接 ID。 */
     readonly socketTaskId: number
@@ -287,7 +288,7 @@ declare module '../../index' {
      */
     onSocketError(
       /** WebSocket 错误事件的回调函数 */
-      callback: (result: onSocketError.Callback) => void
+      callback: onSocketError.Callback
     ): void
 
     /** 监听 WebSocket 连接关闭事件

package/types/api/open-api/authorize.d.ts

@@ -1,9 +1,31 @@
 import Taro from '../../index'
 
 declare module '../../index' {
+  namespace authorizeForMiniProgram {
+    interface Option {
+      /** 需要获取权限的 scope，详见 [scope 列表](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html#scope-%E5%88%97%E8%A1%A8) */
+      scope: keyof Scope | string
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: TaroGeneral.CallbackResult) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: TaroGeneral.CallbackResult) => void
+      /** 接口调用成功的回调函数 */
+      success?: (res: TaroGeneral.CallbackResult) => void
+    }
+
+    /** scope 合法值
+     * @see https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html#scope-%E5%88%97%E8%A1%A8
+     */
+    interface Scope {
+      'scope.record'
+      'scope.writePhotosAlbum'
+      'scope.camera'
+    }
+  }
+
   namespace authorize {
     interface Option {
-      /** 需要获取权限的 scope，详见 [scope 列表]((authorize#scope-列表)) */
+      /** 需要获取权限的 scope，详见 [scope 列表](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html#scope-%E5%88%97%E8%A1%A8) */
       scope: string
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
@@ -15,6 +37,23 @@ declare module '../../index' {
   }
 
   interface TaroStatic {
+    /** **仅小程序插件中能调用该接口**，用法同 [Taro.authorize](./authorize)。目前仅支持三种 scope
+     * @supported weapp
+     * @example
+     * ```tsx
+     * // 可以通过 Taro.getSetting 先查询一下用户是否授权了 "scope.record" 这个 scope
+     * Taro.authorizeForMiniProgram({
+     *   scope: 'scope.record',
+     *   success () {
+     *     // 用户已经同意小程序使用录音功能，后续调用 Taro.startRecord 接口不会弹窗询问
+     *     Taro.startRecord()
+     *   }
+     * })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorizeForMiniProgram.html
+     */
+     authorizeForMiniProgram(option: authorizeForMiniProgram.Option): Promise<TaroGeneral.CallbackResult>
+
     /** 提前向用户发起授权请求。调用后会立刻弹窗询问用户是否同意授权小程序使用某项功能或获取用户的某些数据，但不会实际调用对应接口。如果用户之前已经同意授权，则不会出现弹窗，直接返回成功。更多用法详见 [用户授权](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html)。
      * @supported weapp
      * @example
@@ -36,6 +75,6 @@ declare module '../../index' {
      * ```
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/open-api/authorize/wx.authorize.html
      */
-    authorize(option: authorize.Option): Promise<TaroGeneral.CallbackResult>
+     authorize(option: authorize.Option): Promise<TaroGeneral.CallbackResult>
   }
 }