【Laya】Browser 使用说明

Laya.Browser API 文档

概述

Laya.Browser 是浏览器代理类，封装了浏览器及原生JavaScript提供的一些功能，也包括小游戏等运行环境的信息。通过这个类，开发者可以方便地获取设备信息、浏览器信息、屏幕尺寸等，并进行跨平台开发。

一、属性

1.1 设备和平台检测属性

属性名	类型	只读	描述
`userAgent`	`string`	✓	浏览器代理信息
`onMobile`	`boolean`	✓	当前环境是否为移动设备（iOS和Android）
`onIOS`	`boolean`	✓	当前环境是否在iOS设备内
`onMac`	`boolean`	✓	当前环境是否在Mac设备内
`onIPhone`	`boolean`	✓	当前环境是否在iPhone内
`onIPad`	`boolean`	✓	当前环境是否在iPad内
`onAndroid`	`boolean`	✓	当前环境是否在Android设备内
`onOpenHarmonyOS`	`boolean`	✓	当前环境是否在OpenHarmonyOS设备内
`onWP`	`boolean`	✓	当前环境是否在Windows Phone设备内
`onQQBrowser`	`boolean`	✓	当前环境是否在QQ浏览器内
`onMQQBrowser`	`boolean`	✓	当前环境是否在移动QQ或QQ浏览器内
`onSafari`	`boolean`	✓	当前环境是否在Safari内
`onChrome`	`boolean`	✓	当前环境是否在Chrome内
`onIE`	`boolean`	✓	当前环境是否在IE浏览器内
`onWeiXin`	`boolean`	✓	当前环境是否在微信内
`onPC`	`boolean`	✓	当前环境是否为PC
`onWXMiniGame`	`boolean`	✓	当前环境是否是微信小游戏
`onBDMiniGame`	`boolean`	✓	当前环境是否是百度小游戏
`onKGMiniGame`	`boolean`	✓	当前环境是否是小米小游戏
`onQGMiniGame`	`boolean`	✓	当前环境是否是OPPO小游戏
`onVVMiniGame`	`boolean`	✓	当前环境是否是vivo小游戏
`onAlipayMiniGame`	`boolean`	✓	当前环境是否是支付宝小游戏
`onQQMiniGame`	`boolean`	✓	当前环境是否是手机QQ小游戏
`onBLMiniGame`	`boolean`	✓	当前环境是否是BILIBILI小游戏
`onTTMiniGame`	`boolean`	✓	当前环境是否是抖音小游戏
`onHWMiniGame`	`boolean`	✓	当前环境是否是华为快游戏
`onTBMiniGame`	`boolean`	✓	当前环境是否是淘宝小游戏
`onFirefox`	`boolean`	✓	当前环境是否是Firefox浏览器
`onEdge`	`boolean`	✓	当前环境是否是Edge浏览器
`onLayaRuntime`	`boolean`	✓	当前环境是否运行在LayaAir Native Runtime
`onDevTools`	`boolean`	✓	当前环境是否运行在开发工具中

1.2 平台常量

常量名	值	描述
`Laya.Browser.PLATFORM_PC`	`0`	PC平台
`Laya.Browser.PLATFORM_ANDROID`	`1`	Android平台
`Laya.Browser.PLATFORM_IOS`	`2`	iOS平台

1.3 其他属性

属性名	类型	只读	描述
`platform`	`number`	✓	真实平台类型（通过UserAgent判断）
`platformName`	`string`	✓	平台的可读名称
`isTouchDevice`	`boolean`	✓	环境是否支持触摸输入
`isIOSHighPerformanceMode`	`boolean`	✓	环境是否支持iOS设备的高性能模式
`isIOSHighPerformanceModePlus`	`boolean`	✓	环境是否支持iOS设备的高性能+模式
`isDomSupported`	`boolean`	✓	环境是否支持DOM
`systemVersion`	`string`	✓	系统版本
`SDKVersion`	`string`	✓	平台SDK版本
`mainCanvas`	`HTMLCanvas`	✓	全局画布
`canvas`	`HTMLCanvas`	✓	全局离屏画布（用于测量文本和获取图像数据）
`context`	`CanvasRenderingContext2D`	✓	全局离屏画布上绘图的环境
`bundles`	`Map<string, any>`	✓	已载入的脚本集
`window`	`Window & typeof globalThis`	✓	原生window对象引用
`document`	`Document`	✓	原生document对象引用

二、方法

2.1 屏幕和尺寸相关

`clientWidth`

typescript 复制代码

static get clientWidth(): number

浏览器窗口的可视宽度。

返回值: 可视区域的宽度（像素）

typescript 复制代码

const width = Laya.Browser.clientWidth;
console.log("可视宽度:", width);

`clientHeight`

typescript 复制代码

static get clientHeight(): number

浏览器窗口的可视高度。

返回值: 可视区域的高度（像素）

typescript 复制代码

const height = Laya.Browser.clientHeight;
console.log("可视高度:", height);

`width`

typescript 复制代码

static get width(): number

浏览器窗口的物理宽度，考虑了设备像素比。

返回值: 物理宽度（像素）

typescript 复制代码

const physicalWidth = Laya.Browser.width;
console.log("物理宽度:", physicalWidth);

`height`

typescript 复制代码

static get height(): number

浏览器窗口的物理高度，考虑了设备像素比。

返回值: 物理高度（像素）

typescript 复制代码

const physicalHeight = Laya.Browser.height;
console.log("物理高度:", physicalHeight);

`pixelRatio`

typescript 复制代码

static get pixelRatio(): number

当前环境的设备像素比（DPR）。

返回值: 设备像素比（通常为1、2、3等）

typescript 复制代码

const dpr = Laya.Browser.pixelRatio;
console.log("设备像素比:", dpr);

2.2 DOM操作

`createElement`

typescript 复制代码

static createElement<K extends keyof HTMLElementTagNameMap>(tagName: K): HTMLElementTagNameMap[K]

创建指定类型的浏览器原生节点。

参数:

tagName: 要创建的节点类型

返回值: 创建的节点对象

typescript 复制代码

// 创建div元素
const div = Laya.Browser.createElement('div');
div.style.position = 'absolute';
div.style.width = '100px';
div.style.height = '100px';
div.style.backgroundColor = 'red';
Laya.Browser.document.body.appendChild(div);

// 创建iframe
const iframe = Laya.Browser.createElement('iframe');
iframe.style.position = 'absolute';
iframe.style.zIndex = "100";
iframe.src = 'http://ask.layaair.com/';
Laya.Browser.document.body.appendChild(iframe);

2.3 浏览器功能

`now`

typescript 复制代码

static now(): number

获取浏览器当前时间戳，单位为毫秒。等同于 performance.now()。

返回值: 时间戳（毫秒）

typescript 复制代码

const timestamp = Laya.Browser.now();
console.log("当前时间戳:", timestamp);

`getQueryString`

typescript 复制代码

static getQueryString(name: string): string

获取URL参数的值。

参数:

name: 参数名称

返回值: 参数值

typescript 复制代码

// URL: http://example.com/?name=John&age=25
const name = Laya.Browser.getQueryString('name');
const age = Laya.Browser.getQueryString('age');
console.log("姓名:", name);  // 输出: John
console.log("年龄:", age);   // 输出: 25

`loadLib`

typescript 复制代码

static loadLib(src: string, async?: boolean): Promise<void>

从指定源动态加载JavaScript库。

参数:

src: JavaScript库的URL
async: 是否异步加载（可选，默认为false）

返回值: Promise对象

typescript 复制代码

// 异步加载脚本
Laya.Browser.loadLib('https://cdn.example.com/library.js', true)
    .then(() => {
        console.log('脚本加载完成');
    })
    .catch(err => {
        console.error('脚本加载失败:', err);
    });

// 同步加载脚本
Laya.Browser.loadLib('https://cdn.example.com/library.js');

2.4 容器控制

`container`

typescript 复制代码

static get container(): HTMLElement

用来存放画布元素的容器。

返回值: 容器元素

typescript 复制代码

// 隐藏画布容器
Laya.Browser.container.style.display = 'none';

// 修改容器样式
Laya.Browser.container.style.backgroundColor = '#f0f0f0';

三、使用示例

3.1 屏幕适配

typescript 复制代码

// 获取屏幕信息
const screenWidth = Laya.Browser.clientWidth;
const screenHeight = Laya.Browser.clientHeight;
const physicalWidth = Laya.Browser.width;
const physicalHeight = Laya.Browser.height;
const dpr = Laya.Browser.pixelRatio;

console.log('逻辑分辨率:', screenWidth, 'x', screenHeight);
console.log('物理分辨率:', physicalWidth, 'x', physicalHeight);
console.log('设备像素比:', dpr);

// 根据设备像素比进行适配
if (dpr > 1) {
    console.log('检测到高DPI设备，已启用高清适配');
}

3.2 平台检测

typescript 复制代码

// 判断平台类型
function detectPlatform(): void {
    if (Laya.Browser.onMobile) {
        console.log('当前是移动设备');
        if (Laya.Browser.onIOS) {
            console.log('iOS设备');
            if (Laya.Browser.onIPhone) {
                console.log('iPhone');
            } else if (Laya.Browser.onIPad) {
                console.log('iPad');
            }
        } else if (Laya.Browser.onAndroid) {
            console.log('Android设备');
        }
    } else if (Laya.Browser.onPC) {
        console.log('PC设备');

        if (Laya.Browser.onChrome) {
            console.log('Chrome浏览器');
        } else if (Laya.Browser.onFirefox) {
            console.log('Firefox浏览器');
        } else if (Laya.Browser.onSafari) {
            console.log('Safari浏览器');
        }
    }
}

// 判断小游戏平台
function detectMiniGame(): void {
    if (Laya.Browser.onWXMiniGame) {
        console.log('微信小游戏环境');
        // 微信小游戏特定代码
    } else if (Laya.Browser.onTTMiniGame) {
        console.log('抖音小游戏环境');
        // 抖音小游戏特定代码
    } else if (Laya.Browser.onKGMiniGame) {
        console.log('小米小游戏环境');
        // 小米小游戏特定代码
    }
}

detectPlatform();
detectMiniGame();

3.3 创建自定义对话框

typescript 复制代码

function createCustomDialog(title: string, content: string): HTMLElement {
    // 创建对话框容器
    const dialog = Laya.Browser.createElement('div');
    dialog.style.position = 'fixed';
    dialog.style.left = '50%';
    dialog.style.top = '50%';
    dialog.style.transform = 'translate(-50%, -50%)';
    dialog.style.padding = '20px';
    dialog.style.backgroundColor = 'white';
    dialog.style.borderRadius = '8px';
    dialog.style.boxShadow = '0 4px 6px rgba(0, 0, 0, 0.1)';
    dialog.style.zIndex = '1000';

    // 创建标题
    const titleElement = Laya.Browser.createElement('h3');
    titleElement.textContent = title;
    titleElement.style.margin = '0 0 10px 0';
    dialog.appendChild(titleElement);

    // 创建内容
    const contentElement = Laya.Browser.createElement('p');
    contentElement.textContent = content;
    contentElement.style.margin = '0 0 20px 0';
    dialog.appendChild(contentElement);

    // 创建按钮
    const button = Laya.Browser.createElement('button');
    button.textContent = '确定';
    button.style.padding = '8px 16px';
    button.style.border = 'none';
    button.style.borderRadius = '4px';
    button.style.backgroundColor = '#007AFF';
    button.style.color = 'white';
    button.style.cursor = 'pointer';

    button.onclick = () => {
        Laya.Browser.document.body.removeChild(dialog);
    };

    dialog.appendChild(button);

    // 添加到页面
    Laya.Browser.document.body.appendChild(dialog);

    return dialog;
}

// 使用示例
createCustomDialog('提示', '这是一个自定义对话框！');

3.4 全屏控制

typescript 复制代码

const FullscreenUtil = {
    // 进入全屏
    enter(): void {
        const elem = Laya.Browser.container;
        if (elem.requestFullscreen) {
            elem.requestFullscreen();
        } else if ((elem as any).webkitRequestFullscreen) {
            (elem as any).webkitRequestFullscreen();
        } else if ((elem as any).msRequestFullscreen) {
            (elem as any).msRequestFullscreen();
        }
    },

    // 退出全屏
    exit(): void {
        if (document.exitFullscreen) {
            document.exitFullscreen();
        } else if ((document as any).webkitExitFullscreen) {
            (document as any).webkitExitFullscreen();
        } else if ((document as any).msExitFullscreen) {
            (document as any).msExitFullscreen();
        }
    },

    // 判断是否全屏
    isFullscreen(): boolean {
        return !!(
            document.fullscreenElement ||
            (document as any).webkitFullscreenElement ||
            (document as any).msFullscreenElement
        );
    },

    // 监听全屏变化
    onChange(callback: () => void): void {
        document.addEventListener('fullscreenchange', callback);
        document.addEventListener('webkitfullscreenchange', callback);
        document.addEventListener('msfullscreenchange', callback);
    }
};

// 使用示例
FullscreenUtil.onChange(() => {
    console.log('全屏状态改变:', FullscreenUtil.isFullscreen());
});

四、平台兼容性

4.1 浏览器兼容性

浏览器	版本支持	备注
Chrome	60+	完全支持
Firefox	55+	完全支持
Safari	12+	完全支持
Edge	79+	完全支持
IE	11	部分支持，推荐升级

4.2 小游戏平台支持

平台	支持状态
微信小游戏	完全支持
抖音小游戏	完全支持
小米小游戏	完全支持
OPPO小游戏	完全支持
vivo小游戏	完全支持
百度小游戏	完全支持
支付宝小游戏	完全支持
手机QQ小游戏	完全支持
华为快游戏	完全支持
淘宝小游戏	完全支持
BILIBILI小游戏	完全支持

4.3 注意事项

DOM操作限制: 小游戏环境中，某些DOM操作可能受到限制
性能考虑: 频繁调用某些API可能影响性能，建议合理使用缓存
触摸事件: 移动端要注意触摸事件的兼容性处理
屏幕适配: 不同设备的屏幕尺寸和像素比差异较大，需要做好适配

五、最佳实践

使用 Laya. 前缀 : 始终使用 Laya.Browser 访问API，确保命名空间规范
平台检测: 在关键功能前进行平台检测，确保代码在目标平台正常运行
性能优化: 缓存频繁使用的属性值，避免重复计算
错误处理: 对可能失败的API调用进行错误处理
版本适配: 关注不同平台的版本差异，做好兼容性处理