@amazon-devices/kepler-system-info

Vega System Info API提供的功能让您能够查询有关正在运行的操作系统实例的基本系统级信息。这包括系统正常运行时间、操作系统详细信息、构建信息以及专为在Vega上运行的应用设计的硬件特性。该API提供以下关键功能：

系统正常运行时间监控：以纳秒级精度获得精确的系统正常运行时间
操作系统信息：提供对操作系统显示名称、版本和代号的访问权限
构建信息：检索详细的构建元数据和指纹
模拟器检测：确定应用是否在Vega虚拟设备 (VVD) 上运行
TypeScript支持：API完全支持TypeScript定义
错误处理：支持使用try-catch模式进行全面的错误处理

备注

API的核心接口如下所示。

接口	描述
`ISystemInfo`	主系统信息接口
`IOperatingSystemInfo`	操作系统详细信息
`IBuildInfo`	构建和版本信息

关键类型定义如下。

类型	描述
`MonotonicDuration`	系统正常运行持续时间
`RealTimeInstant`	精度为纳秒的时间戳
`RawTimeValue`	原始时间值（秒 + 纳秒）

开始使用

设置

将以下库依赖项添加到您的package.json文件中。

{
    "dependencies": {
        "@amazon-devices/kepler-system-info": "~1.0.5",
        "@amazon-devices/keplerscript-turbomodule-api": "~1.2.5"
    }
}

要安装依赖项，请运行以下命令。

npm install

用法示例

基本使用模式

以下代码示例显示了API的简短用法。

import { SystemInfoModule, ISystemInfo } from '@amazon-devices/kepler-system-info';

// 获取主SystemInfo接口
let systemInfo: ISystemInfo;
try {
    systemInfo = SystemInfoModule.getSystemInfo();
    console.log('SystemInfo成功初始化');
} catch (error) {
    console.error('SystemInfo初始化失败：', error);
    throw error;
}

ISystemInfo接口

系统正常运行时间

以下代码示例显示了如何以纳秒精度获得系统正常运行时间。

import { MonotonicDuration, RawTimeValue } from '@amazon-devices/kepler-system-info';

async function getSystemUptime() {
    try {
        const uptime: MonotonicDuration = await systemInfo.getUptime();
        const timeValue: RawTimeValue = uptime.time;

        console.log('系统正常运行时间：');
        console.log(`秒数：${timeValue.seconds}`);
        console.log(`纳秒数：${timeValue.nanoseconds}`);

        // 转换为人类可读的格式
        const totalSeconds = timeValue.seconds;
        const hours = Math.floor(totalSeconds / 3600);
        const minutes = Math.floor((totalSeconds % 3600) / 60);
        const seconds = totalSeconds % 60;

        console.log(`人类可读：${hours}h ${minutes}m ${seconds}s`);

        return uptime;
    } catch (error) {
        console.error('获取系统正常运行时间失败：', error);
        throw error;
    }
}

模拟器检测

以下示例代码显示如何检查应用是否在VVD上运行。

function checkEmulatorStatus() {
    try {
        const isEmulator = systemInfo.isEmulator();
        console.log(`正在在以下模拟器红运行：${isEmulator ? '是' : '否'}`);

        if (isEmulator) {
            console.log('检测到开发/测试环境');
        } else {
            console.log('检测到生产环境');
        }

        return isEmulator;
    } catch (error) {
        console.error('检查模拟器状态失败：', error);
        throw error;
    }
}

访问操作系统信息

以下示例代码显示如何使用IOperatingSystemInfo接口访问详细操作系统信息。

import { IOperatingSystemInfo } from '@amazon-devices/kepler-system-info';

function getOperatingSystemInfo() {
    try {
        const osInfo: IOperatingSystemInfo =
            systemInfo.getOperatingSystemInfo();

        // 获取操作系统详情
        const displayName = osInfo.getDisplayName();
        const codeName = osInfo.getCodeName();
        const version = osInfo.getVersion();

        console.log('Operating System Information:');
        console.log(`显示名称：${displayName}`);
        console.log(`代码名称：${codeName}`);
        console.log(`版本：${version}`);

        return {
            displayName,
            codeName,
            version,
            osInfo,
        };
    } catch (error) {
        console.error('获取操作系统信息失败：', error);
        throw error;
    }
}

检索构建信息

以下示例代码显示如何使用IBuildInfo接口检索全面的构建信息。

import {
    IBuildInfo,
    RealTimeInstant,
    RawTimeValue,
} from '@amazon-devices/kepler-system-info';

function getBuildInformation(osInfo: IOperatingSystemInfo) {
    try {
        const buildInfo: IBuildInfo = osInfo.getBuildInfo();

        // 基本构建信息
        const displayName = buildInfo.getDisplayName();
        const buildId = buildInfo.getId();
        const variant = buildInfo.getVariant();
        const fingerprint = buildInfo.getFingerprint();

        // 构建时间戳
        const timestamp: RealTimeInstant = buildInfo.getTimestamp();
        const timeValue: RawTimeValue = timestamp.time;
        const buildDate = new Date(timeValue.seconds * 1000);

        // 构建标记
        const tags: string[] = buildInfo.getTags();

        console.log('内部版本信息：');
        console.log(`显示名称：${displayName}`);
        console.log(`构建ID：${buildId}`);
        console.log(`变体：${variant}`);
        console.log(`指纹：${fingerprint}`);
        console.log(`构建日期：${buildDate.toISOString()}`);
        console.log(`标记：${JSON.stringify(tags, null, 2)}`);

        return {
            displayName,
            buildId,
            variant,
            fingerprint,
            buildDate,
            tags,
            buildInfo,
        };
    } catch (error) {
        console.error('获取构建信息失败：', error);
        throw error;
    }
}

示例

以下示例代码演示了API的所有主要功能。

import {
    SystemInfoModule,
    ISystemInfo,
    IOperatingSystemInfo,
    IBuildInfo,
    MonotonicDuration,
    RealTimeInstant,
    RawTimeValue,
} from '@amazon-devices/kepler-system-info';

class SystemInfoService {
    private systemInfo: ISystemInfo;

    constructor() {
        try {
            this.systemInfo = SystemInfoModule.getSystemInfo();
            console.log('SystemInfoService initialized');
        } catch (error) {
            console.error('初始化SystemInfoService失败：', error);
            throw error;
        }
    }

    async getCompleteSystemInfo() {
        try {
            // 系统级信息
            const uptime = await this.systemInfo.getUptime();
            const isEmulator = this.systemInfo.isEmulator();

            // 操作系统信息
            const osInfo = this.systemInfo.getOperatingSystemInfo();
            const osDisplayName = osInfo.getDisplayName();
            const osCodeName = osInfo.getCodeName();
            const osVersion = osInfo.getVersion();

            // 构建信息
            const buildInfo = osInfo.getBuildInfo();
            const buildDisplayName = buildInfo.getDisplayName();
            const buildId = buildInfo.getId();
            const buildVariant = buildInfo.getVariant();
            const buildFingerprint = buildInfo.getFingerprint();
            const buildTimestamp = buildInfo.getTimestamp();
            const buildTags = buildInfo.getTags();

            return {
                system: {
                    uptime: {
                        seconds: uptime.time.seconds,
                        nanoseconds: uptime.time.nanoseconds,
                        humanReadable: this.formatUptime(uptime.time.seconds),
                    },
                    isEmulator,
                },
                operatingSystem: {
                    displayName: osDisplayName,
                    codeName: osCodeName,
                    version: osVersion,
                },
                build: {
                    displayName: buildDisplayName,
                    id: buildId,
                    variant: buildVariant,
                    fingerprint: buildFingerprint,
                    timestamp: {
                        seconds: buildTimestamp.time.seconds,
                        nanoseconds: buildTimestamp.time.nanoseconds,
                        date: new Date(
                            buildTimestamp.time.seconds * 1000,
                        ).toISOString(),
                    },
                    tags: buildTags,
                },
            };
        } catch (error) {
            console.error('获取完整系统信息失败：', error);
            throw error;
        }
    }

    private formatUptime(seconds: number): string {
        const hours = Math.floor(seconds / 3600);
        const minutes = Math.floor((seconds % 3600) / 60);
        const secs = seconds % 60;
        return `${hours}h ${minutes}m ${secs}s`;
    }
}

// 用法
async function main() {
    try {
        const service = new SystemInfoService();
        const systemInfo = await service.getCompleteSystemInfo();

        console.log('完整系统信息：');
        console.log(JSON.stringify(systemInfo, null, 2));
    } catch (error) {
        console.error('应用错误：', error);
    }
}

main();

错误处理

该API使用标准JavaScript错误处理。务必将API调用包装在try-catch块中。

try {
    const systemInfo = SystemInfoModule.getSystemInfo();
    const uptime = await systemInfo.getUptime();
    // 进程正常运行时间...
} catch (error) {
    if (error instanceof Error) {
        console.error(`SystemInfo错误：${error.message}`);
        console.error(`堆栈跟踪：${error.stack}`);
    } else {
        console.error('发生未知错误：', error);
    }

    // 适当地处理应用的错误
    throw error; // 如果需要则重新引发
}

API参考

核心接口

接口	描述
`ISystemInfo`	主系统信息接口
`IOperatingSystemInfo`	操作系统详细信息
`IBuildInfo`	构建和版本信息

类型定义

类型	描述
`MonotonicDuration`	系统正常运行持续时间
`RealTimeInstant`	精度为纳秒的时间戳
`RawTimeValue`	原始时间值（秒 + 纳秒）

用法示例

基本设置

import { SystemInfoModule, ISystemInfo } from '@amazon-devices/kepler-system-info';

try {
    const systemInfo = SystemInfoModule.getSystemInfo();
    console.log('SystemInfo成功初始化');
} catch (error) {
    console.error('SystemInfo初始化失败：', error);
    throw error;
}

ISystemInfo接口

系统正常运行时间

以纳秒级精度获取精确的系统正常运行时间：

import { MonotonicDuration, RawTimeValue } from '@amazon-devices/kepler-system-info';

async function getSystemUptime() {
    try {
        const uptime: MonotonicDuration = await systemInfo.getUptime();
        const timeValue: RawTimeValue = uptime.time;
        
        console.log('系统正常运行时间：');
        console.log(`秒数：${timeValue.seconds}`);
        console.log(`纳秒数：${timeValue.nanoseconds}`);
        
        // 转换为人类可读的格式
        const totalSeconds = timeValue.seconds;
        const hours = Math.floor(totalSeconds / 3600);
        const minutes = Math.floor((totalSeconds % 3600) / 60);
        const seconds = totalSeconds % 60;
        
        console.log(`人类可读：${hours}h ${minutes}m ${seconds}s`);
        
        return uptime;
    } catch (error) {
        console.error('获取系统正常运行时间失败：', error);
        throw error;
    }
}

模拟器检测

检查应用是否在模拟器环境中运行：

function checkEmulatorStatus() {
    try {
        const isEmulator = systemInfo.isEmulator();
        console.log(`正在在以下模拟器红运行：${isEmulator ? '是' : '否'}`);
        
        if (isEmulator) {
            console.log('检测到开发/测试环境');
        } else {
            console.log('检测到生产环境');
        }
        
        return isEmulator;
    } catch (error) {
        console.error('检查模拟器状态失败：', error);
        throw error;
    }
}

IOperatingSystemInfo接口

访问详细的操作系统信息：

import { IOperatingSystemInfo } from '@amazon-devices/kepler-system-info';

function getOperatingSystemInfo() {
    try {
        const osInfo: IOperatingSystemInfo = systemInfo.getOperatingSystemInfo();
        
        // 获取操作系统详细信息
        const displayName = osInfo.getDisplayName();
        const codeName = osInfo.getCodeName();
        const version = osInfo.getVersion();
        
        console.log('Operating System Information:');
        console.log(`显示名称：${displayName}`);
        console.log(`代码名称：${codeName}`);
        console.log(`版本：${version}`);
        
        return {
            displayName,
            codeName,
            version,
            osInfo
        };
    } catch (error) {
        console.error('获取操作系统信息失败：', error);
        throw error;
    }
}

IBuildInfo接口

检索全面的构建信息：

import { IBuildInfo, RealTimeInstant, RawTimeValue } from '@amazon-devices/kepler-system-info';

function getBuildInformation(osInfo: IOperatingSystemInfo) {
    try {
        const buildInfo: IBuildInfo = osInfo.getBuildInfo();
        
        // 基本构建信息
        const displayName = buildInfo.getDisplayName();
        const buildId = buildInfo.getId();
        const variant = buildInfo.getVariant();
        const fingerprint = buildInfo.getFingerprint();
        
        // 构建时间戳
        const timestamp: RealTimeInstant = buildInfo.getTimestamp();
        const timeValue: RawTimeValue = timestamp.time;
        const buildDate = new Date(timeValue.seconds * 1000);
        
        // 构建标记
        const tags: string[] = buildInfo.getTags();
        
        console.log('构建信息：');
        console.log(`显示名称：${displayName}`);
        console.log(`内部版本ID：${buildId}`);
        console.log(`变体：${variant}`);
        console.log(`指纹：${fingerprint}`);
        console.log(`内部版本日期：${buildDate.toISOString()}`);
        console.log(`标记：${JSON.stringify(tags, null, 2)}`);
        
        return {
            displayName,
            buildId,
            variant,
            fingerprint,
            buildDate,
            tags,
            buildInfo
        };
    } catch (error) {
        console.error('获取内部版本信息失败：', error);
        throw error;
    }
}

API参考

类

MonotonicDuration—表示时间跨度。此类型遵循ISO 8601持续时间定义。
RawTimeValue—用于描述绝对时间和相对时间的基本类型。
RealTimeInstant—表示系统时钟中的时间点。用处
SystemInfo
SystemInfoModule—系统信息API

接口

IBuildInfo—特定于操作系统内部版本的信息。
IOperatingSystemInfo—操作系统信息。
ISystemInfo—用于查询系统信息的核心接口。

​备注

​开始使用

​设置

​用法示例

​基本使用模式

​ISystemInfo接口

​系统正常运行时间

​模拟器检测

​访问操作系统信息

​检索构建信息

​示例

​错误处理

​API参考

​核心接口

​类型定义

​用法示例

​基本设置

​ISystemInfo接口

​系统正常运行时间

​模拟器检测

​IOperatingSystemInfo接口

​IBuildInfo接口

​API参考

​类

​接口

备注

开始使用

设置

用法示例

基本使用模式

ISystemInfo接口

系统正常运行时间

模拟器检测

访问操作系统信息

检索构建信息

示例

错误处理

API参考

核心接口

类型定义

用法示例

基本设置

ISystemInfo接口

系统正常运行时间

模拟器检测

IOperatingSystemInfo接口

IBuildInfo接口

API参考

类

接口