@meituan-nocode/miniprogram-sdk/README.md

微信小程序 SDK 封装库

# NoCode 微信小程序 SDK

一个用于微信小程序开发的 SDK 封装库，提供了便捷的 API 接口和配置管理。支持微信小程序 web-view 组件 和 微信 H5 环境。

## 安装

```bash
npm install @meituan-nocode/miniprogram-sdk
# 或
yarn add @meituan-nocode/miniprogram-sdk
# 或
pnpm add @meituan-nocode/miniprogram-sdk
```

## 快速开始

### 基础使用

```typescript
import nocode from '@meituan-nocode/miniprogram-sdk';

// 初始化 SDK
await nocode.ready();

// 分享
nocode.share({
    url: 'https://nocode.host',
    title: 'NoCode Runtime 测试', // 分享标题
    description: '这是一个 NoCode Runtime 的测试页面', // 分享描述
    imageUrl: 'https://s3plus.meituan.net/nocode-external/assets/nocode-logo.png', // 分享图标
});
```

### 微信 JS SDK 配置

SDK 会自动处理微信 JS SDK 的加载和配置，包括：

- 动态加载微信 JS SDK
- 自动获取签名配置
- 智能缓存管理（7秒过期时间）
- 错误处理

## API 参考

### 核心方法

#### `ready(): Promise<void>`

初始化 SDK，准备运行环境。必须在使用其他功能前调用。

```typescript
try {
    await nocode.ready();
    console.log('SDK 初始化成功');
} catch (error) {
    console.error('SDK 初始化失败:', error);
}
```

### 导航方法

#### `navigateToHome(): void`

跳转到小程序首页。

```typescript
nocode.navigateToHome();
```

### 登录功能

#### `login(params: LoginParams): void`

用户登录。

```typescript
nocode.login({
    forceLogin: true,
    landingPage: '/pages/home/index',
    utmSource: 'share',
});
```

**参数说明：**

- `forceLogin`: 是否强制登录
- `landingPage`: 登录来源页面
- `utmSource`: 登录来源 utm_source

### 分享功能

#### `share(params: ShareParams): void`

智能分享功能，自动适配不同环境。

```typescript
nocode.share({
    title: '分享标题',
    url: 'https://example.com',
    imageUrl: 'https://example.com/image.jpg',
    description: '分享描述',
});
```

**参数说明：**

- `title`: 分享标题
- `url`: 分享链接
- `imageUrl`: 分享图片（可选）
- `description`: 分享描述（可选）

#### `sharePoster(params: ShareParams): void`

生成分享海报。

```typescript
nocode.sharePoster({
    title: '海报标题',
    url: 'https://example.com',
    imageUrl: 'https://example.com/poster.jpg',
});
```

### 链接操作

#### `openLink(params: OpenLinkParams): void`

在小程序中打开网页链接。

```typescript
nocode.openLink({
    url: 'https://example.com',
    title: '页面标题',
    navigationBar: {
        frontColor: '#ffffff',
        backgroundColor: '#000000',
        animation: {
            duration: 300,
            timingFunc: 'ease-in-out',
        },
    },
});
```

**参数说明：**

- `url`: 页面地址
- `title`: 页面标题
- `navigationBar`: 导航栏配置
    - `frontColor`: 前景颜色（#ffffff 或 #000000）
    - `backgroundColor`: 背景颜色
    - `animation`: 动画效果

#### `navigateToMiniProgram(params: NavigateToMiniProgramParams): void`

跳转到其他小程序。

```typescript
nocode.navigateToMiniProgram({
    appId: 'wx1234567890',
    path: '/pages/index/index',
    envVersion: 'release',
    extraData: { from: 'current_app' },
});
```

**参数说明：**

- `appId`: 要打开的小程序 appId
- `path`: 打开的页面路径
- `envVersion`: 小程序版本（develop/trial/release）
- `extraData`: 传递给目标小程序的数据

### UI 组件

#### `showToast(options: ToastOptions): void`

显示提示信息。

```typescript
nocode.showToast({
    title: '操作成功',
    icon: 'success',
    duration: 2000,
    mask: false,
});
```

**参数说明：**

- `title`: 提示文字
- `icon`: 图标类型（success/error/loading/none）
- `duration`: 显示时长（毫秒）
- `mask`: 是否显示遮罩

#### `hideToast(): void`

隐藏提示信息。

```typescript
nocode.hideToast();
```

### 分享引导

#### `showShareGuide(options?: ShareGuideOptions): void`

显示微信小程序分享引导弹层。

```typescript
nocode.showShareGuide({
    imageUrl: 'https://example.com/guide.png',
    text: '点击右上角分享给好友',
    maskClosable: true,
    topOffset: 20,
    rightOffset: 20,
    onClose: () => console.log('分享引导已关闭'),
});
```

**参数说明：**

- `imageUrl`: 引导图片URL
- `text`: 引导文案
- `maskClosable`: 点击遮罩是否关闭
- `topOffset`: 距离顶部的偏移量（px）
- `rightOffset`: 距离右边的偏移量（px）
- `onClose`: 关闭回调函数

#### `hideShareGuide(): void`

隐藏分享引导弹层。

```typescript
nocode.hideShareGuide();
```

#### `isShareGuideVisible(): boolean`

获取分享引导弹层显示状态。

```typescript
const isVisible = nocode.isShareGuideVisible();
```

### 数据转换工具

#### `arrayBufferToBase64(buffer: ArrayBuffer | Uint8Array): string`

将 ArrayBuffer 或 Uint8Array 转换为 Base64 字符串。

```typescript
const buffer = new ArrayBuffer(8);
const base64String = nocode.arrayBufferToBase64(buffer);
console.log(base64String); // 输出 Base64 编码的字符串
```

**参数说明：**

- `buffer`: 要转换的 ArrayBuffer 或 Uint8Array

#### `base64ToArrayBuffer(base64: string): ArrayBuffer`

将 Base64 字符串转换为 ArrayBuffer。

```typescript
const base64String = 'SGVsbG8gV29ybGQ=';
const buffer = nocode.base64ToArrayBuffer(base64String);
console.log(buffer); // 输出 ArrayBuffer 对象
```

**参数说明：**

- `base64`: Base64 编码的字符串

### 截图功能

#### `takeSnapshot(params: TakeSnapshotParams): Promise<string>`

对指定 DOM 元素进行截图，返回 Base64 格式的图片数据。

```typescript
const element = document.getElementById('my-element');
const imageData = await nocode.takeSnapshot({
    element: element,
    scale: 2, // 缩放比例
    backgroundColor: '#ffffff', // 背景色
    embedFonts: true, // 嵌入字体
});
console.log(imageData); // Base64 格式的图片数据
```

**参数说明：**

- `element`: 要截图的 DOM 元素
- `scale`: 缩放比例（可选，默认 1）
- `backgroundColor`: 背景颜色（可选，默认 '#ffffff'）
- `embedFonts`: 是否嵌入字体（可选，默认 true）
- `width`: 截图宽度（可选，默认使用元素实际宽度）
- `height`: 截图高度（可选，默认使用元素实际高度）

### 文件操作

#### `chooseImage(params: ChooseImageParams): Promise<Array<File>>`

选择图片文件。

```typescript
const files = await nocode.chooseImage({
    multiple: false, // 是否支持多选
});
console.log('选择的图片文件:', files);
```

**参数说明：**

- `multiple`: 是否支持多选（可选，默认 false）

#### `chooseFile(params: ChooseFileParams): Promise<Array<File>>`

选择文件。

```typescript
const files = await nocode.chooseFile({
    mimeTypes: ['image/*', 'application/pdf'], // 文件类型过滤
    multiple: true, // 是否支持多选
});
console.log('选择的文件:', files);
```

**参数说明：**

- `mimeTypes`: 允许选择的文件类型数组（可选，默认 ['*/*']）
- `multiple`: 是否支持多选（可选，默认 false）

#### `uploadFile(params: UploadFileParams): Promise<{url: string}>`

上传文件到服务器。

```typescript
const file = new File(['content'], 'test.txt', { type: 'text/plain' });
const result = await nocode.uploadFile({
    file: file,
    fileName: 'test.txt',
});
console.log('上传成功，文件URL:', result.url);
```

**参数说明：**

- `file`: 要上传的文件对象
- `fileName`: 文件名

### 分享功能扩展

#### `shareImage(params: ShareImageParams): Promise<void>`

分享图片。

```typescript
// 分享网络图片
await nocode.shareImage({
    imageUrl: 'https://example.com/image.jpg',
});

// 分享本地文件
const file = new File(['image data'], 'image.png', { type: 'image/png' });
await nocode.shareImage({
    imageUrl: file,
});
```

**参数说明：**

- `imageUrl`: 图片 URL 或 File 对象

#### `shareFile(params: ShareFileParams): Promise<void>`

分享文件。

```typescript
// 分享网络文件
await nocode.shareFile({
    filePath: 'https://example.com/document.pdf',
    fileName: 'document.pdf',
});

// 分享本地文件
const file = new File(['file content'], 'document.pdf', { type: 'application/pdf' });
await nocode.shareFile({
    filePath: file,
    fileName: 'document.pdf',
});
```

**参数说明：**

- `filePath`: 文件路径或 File 对象
- `fileName`: 文件名

### 文档操作

#### `openDocument(params: OpenDocumentParams): Promise<void>`

打开文档。

```typescript
await nocode.openDocument({
    filePath: 'https://example.com/document.pdf',
    fileType: 'pdf',
    showMenu: true, // 是否显示菜单
});
```

**参数说明：**

- `filePath`: 文档地址
- `fileType`: 文档类型（pdf, doc, docx, xls, xlsx, ppt, pptx）
- `showMenu`: 是否显示菜单（可选，默认 false）

### 用户授权

#### `requestAuthUserInfo(params: RequestAuthUserInfoParams): Promise<void>`

请求用户授权获取用户信息。

```typescript
await nocode.requestAuthUserInfo({});
```

#### `onAuthUserInfoConfirm(callback: (params: AuthUserInfo) => void): void`

监听用户确认授权事件。

```typescript
nocode.onAuthUserInfoConfirm(userInfo => {
    console.log('用户信息:', userInfo);
    console.log('头像:', userInfo.avatarUrl);
    console.log('昵称:', userInfo.nickname);
    console.log('OpenID:', userInfo.openId);
});
```

**回调参数说明：**

- `avatarUrl`: 用户头像 URL
- `nickname`: 用户昵称
- `openId`: 用户 OpenID
- `token`: 用户访问令牌

#### `onAuthUserInfoCancel(callback: () => void): void`

监听用户取消授权事件。

```typescript
nocode.onAuthUserInfoCancel(() => {
    console.log('用户取消了授权');
});
```

### 环境检测

SDK 提供了环境检测工具函数，可以通过两种方式使用：

```typescript
import nocode from '@meituan-nocode/miniprogram-sdk';

// 检查是否在小程序 web-view 组件中
if (nocode.isWeChatMiniProgram()) {
    console.log('当前在小程序环境中');
}

// 检查是否在微信 H5 环境中
if (nocode.isWechatH5()) {
    console.log('当前在微信 H5 环境中');
}

// 检查是否在微信环境中（包括 H5 和小程序）
if (nocode.isWechatEnv()) {
    console.log('当前在微信环境中');
}
```

## 配置选项

### 支持的 JS API

SDK 默认支持以下微信 JS API：

- 基础接口：`checkJsApi`
- 分享接口：`updateAppMessageShareData`, `updateTimelineShareData` 等
- 图片接口：`chooseImage`, `previewImage`, `uploadImage` 等
- 音频接口：`startRecord`, `stopRecord`, `playVoice` 等
- 设备信息：`getNetworkType`
- 位置接口：`openLocation`, `getLocation`
- 界面操作：`closeWindow`, `hideMenuItems` 等
- 微信扫一扫：`scanQRCode`
- 微信卡券：`chooseCard`, `openCard`, `addCard`
- 快速输入：`openAddress`

## 许可证

MIT License