# Rox Utils 工具库说明文档

`RoxUtils` 是一个整合 App、微信小程序、H5 三端工具方法的工具库，包含环境判断、用户登录、签名 Header、页面跳转、地图能力、App 文件下载/分享、数组工具、图片计算工具等能力。

---

# 📑 目录（TOC）

-   [Rox Utils 工具库说明文档](#rox-utils-工具库说明文档)
-   [📌 功能总览](#-功能总览)
-   [🚀 快速开始](#-快速开始)
-   [🧩 功能说明](#-功能说明)

    -   [1. 环境判断](#1-环境判断)
    -   [2. 用户登录能力](#2-用户登录能力)
    -   [3. Header 生成（带签名）](#3-header-生成带签名)
    -   [4. 页面跳转](#4-页面跳转)
    -   [5. 返回上一页](#5-返回上一页)
    -   [6. 地图能力](#6-地图能力)
    -   [7. App 下载 / 分享](#7-app-下载--分享)
    -   [8. API 域名配置](#8-api-域名配置)
    -   [9. 数组 / 随机工具](#9-数组--随机工具)
    -   [10. 图片位置计算](#10-图片位置计算)
    -   [11. 其他工具](#11-其他工具)

---

# 📌 功能总览

| 分类     | 方法                                                                  |
| -------- | --------------------------------------------------------------------- |
| 环境判断 | `isMiniProgram`、`isWechat`                                           |
| 登录     | `isLogin`、`enhanceIsLogin`、`getAppUserInfo`、`getEnhanceUserPhone`  |
| Header   | `getHeaders`、`getMiniProgramHeaders`、`getAppHeaders`                |
| 跳转     | `toLoginPage`、`toHomePage`、`jumpToAppPage`、`jumpToMiniProgramPage` |
| 返回     | `goBack`                                                              |
| 地图     | `openLocationMap`                                                     |
| App 专用 | `appDownloadFile`、`showAppSharePopup`                                |
| API 环境 | `getApiBaseUrl`                                                       |
| 数组     | `shuffleArray`、`fillArray`                                           |
| 图片计算 | `getBoxSize`                                                          |
| 其他     | `registerMethod`、`sortJson`                                          |

---

# 🚀 快速开始

```ts
import { roxUtils } from "./utils";

// 调用
const logged = await roxUtils.isLogin();
```

适用于 App + 微信小程序 + H5 三端环境。

---

# 🧩 功能说明

---

## 1. 环境判断

### `isMiniProgram()`

判断当前是否为微信小程序环境。

### `isWechat()`

判断是否为微信浏览器（公众号/H5）环境。

---

## 2. 用户登录能力

### `isLogin(urlLoginField?, debug?)`

环境自动判断是否登录。

### `enhanceIsLogin()`

更严格的登录判断。

### `getAppUserInfo(toLoginPage?)`

App 中获取登录信息（UIKit 封装）。

### `getEnhanceUserPhone()`

部分苹果手机无手机号时的兼容逻辑。

---

## 3. Header 生成（带签名）

### `getHeaders(method, data, key, debug, headers)`

---

## 4. 页面跳转

### `toLoginPage()`

跳转到对应环境的登录页。

### `toHomePage()`

跳转首页。

### `jumpToAppPage(options)`

App 内跳转任意页面。

### `jumpToMiniProgramPage(url, isTabBar, reStart)`

小程序跳转封装。

---

## 5. 返回上一页

### `goBack({ isShared, homePath })`

---

## 6. 地图能力

### `openLocationMap(location)`

---

## 7. App 下载 / 分享

### `appDownloadFile(base64OrBlob)`

App 内调用原生下载能力。

### `showAppSharePopup(base64OrBlob)`

调用 App 内分享弹窗。

---

## 8. API 域名配置

### `getApiBaseUrl({ mode, buildModule })`

## 9. 数组 / 随机工具

### `shuffleArray(array)`

随机乱序数组。

### `fillArray({ arr, count, fallbackValue })`

把数组填充至固定长度。

---

## 10. 图片位置计算

### `getBoxSize 注: 相对于视口宽高，盒子位置等比缩放`

计算图片盒子真实位置（H5）。

### `getImageBoxSize 注: 并非相对于视口宽高，而是相对于图片(图片有可能高于或者低于视口高度)， 盒子位置等比缩放`

计算图片内盒子的真实位置 (H5)。

---

## 11. 其他工具

### `registerMethod(eventName, data)`

App 调用 JS 的注册方法。

### `sortJson(json)`

按 key 排序。