DesktopManager API 文档

概述

DesktopManager 是 ZerOS 内核的桌面管理器，负责沙盒环境的桌面实现，包括快捷方式、桌面图标排列、右键菜单、桌面组件等。

依赖

GUIManager - GUI 管理器（用于窗口管理）
ThemeManager - 主题管理器（用于主题和风格）
ApplicationAssetManager - 应用程序资源管理器（用于获取程序信息）
ContextMenuManager - 上下文菜单管理器（用于桌面右键菜单）
ProcessManager - 进程管理器（用于程序启动）
TaskbarManager - 任务栏管理器（用于获取任务栏位置）
LStorage - 本地存储（用于保存桌面配置）

初始化

桌面管理器在系统启动时自动初始化：

await DesktopManager.init();

API 方法

桌面快捷方式管理

`addShortcut(options)`

添加桌面快捷方式。

参数:

options (Object): 选项对象
- programName (string): 程序名称（必需）
- name (string): 显示名称（可选，默认使用 programName）
- icon (string): 图标路径（可选）
- description (string): 描述（可选）
- position (Object): 位置 {x, y}（可选，默认自动排列）

返回值: number - 图标 ID

示例:

// 直接调用
const iconId = DesktopManager.addShortcut({
    programName: 'filemanager',
    name: '文件管理器',
    icon: 'application/filemanager/filemanager.svg',
    description: '管理文件和文件夹',
    position: { x: 100, y: 100 }
});

// 通过 ProcessManager 调用（推荐）
const iconId = await ProcessManager.callKernelAPI(pid, 'Desktop.addShortcut', [{
    programName: 'filemanager',
    name: '文件管理器',
    icon: 'application/filemanager/filemanager.svg',
    description: '管理文件和文件夹',
    position: { x: 100, y: 100 }
}]);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

`removeShortcut(iconId)`

移除桌面快捷方式。

参数:

iconId (number): 图标 ID

示例:

// 直接调用
DesktopManager.removeShortcut(iconId);

// 通过 ProcessManager 调用（推荐）
await ProcessManager.callKernelAPI(pid, 'Desktop.removeShortcut', [iconId]);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

`addFileOrFolderIcon(options)`

添加文件/文件夹图标到桌面。

参数:

options (Object): 选项对象
- type (string): 类型，必须是 'file' 或 'directory'（必需）
- targetPath (string): 目标路径（文件或文件夹的完整路径）（必需）
- name (string): 显示名称（可选，默认使用文件名）
- icon (string): 图标路径（可选）
- description (string): 描述（可选）
- position (Object): 位置 {x, y}（可选，默认自动排列）

返回值: number - 图标 ID

示例:

// 直接调用
const iconId = DesktopManager.addFileOrFolderIcon({
    type: 'file',
    targetPath: 'C:/Documents/example.txt',
    name: '示例文件',
    description: '这是一个示例文件'
});

// 通过 ProcessManager 调用（推荐）
const iconId = await ProcessManager.callKernelAPI(pid, 'Desktop.addFileOrFolderIcon', [{
    type: 'directory',
    targetPath: 'C:/Users/Documents',
    name: '我的文档',
    description: '文档文件夹'
}]);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

`getIcons()`

获取桌面图标列表。

返回值: Array<Object> - 图标数据数组

图标数据对象结构:

{
    id: number,
    programName: string,  // 程序快捷方式才有此字段
    type: string,         // 文件/文件夹图标才有此字段：'file' 或 'directory'
    targetPath: string,   // 文件/文件夹图标才有此字段
    name: string,
    icon: string|null,
    description: string,
    position: Object|null,
    createdAt: number
}

示例:

// 直接调用
const icons = DesktopManager.getIcons();
icons.forEach(icon => {
    if (icon.programName) {
        console.log(`程序快捷方式: ${icon.name} -> ${icon.programName}`);
    } else if (icon.type) {
        console.log(`${icon.type === 'file' ? '文件' : '文件夹'}: ${icon.name} -> ${icon.targetPath}`);
    }
});

// 通过 ProcessManager 调用（推荐）
const icons = await ProcessManager.callKernelAPI(pid, 'Desktop.getIcons', []);

权限要求: 不需要权限（读取操作）

桌面配置管理

`getConfig()`

获取桌面配置。

返回值: Object - 配置对象

{
    arrangementMode: string,  // 'grid' | 'list' | 'auto'
    iconSize: string,         // 'small' | 'medium' | 'large'
    autoArrange: boolean,     // 是否自动排列
    iconSpacing: number       // 图标间距（像素）
}

示例:

// 直接调用
const config = DesktopManager.getConfig();
console.log(`排列模式: ${config.arrangementMode}`);
console.log(`图标大小: ${config.iconSize}`);

// 通过 ProcessManager 调用（推荐）
const config = await ProcessManager.callKernelAPI(pid, 'Desktop.getConfig', []);

权限要求: 不需要权限（读取操作）

`setArrangementMode(mode)`

设置排列模式。

参数:

mode (string): 排列模式 'grid'（网格）、'list'（列表）、'auto'（自动）

示例:

// 直接调用
DesktopManager.setArrangementMode('grid');

// 通过 ProcessManager 调用（推荐）
await ProcessManager.callKernelAPI(pid, 'Desktop.setArrangementMode', ['grid']);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

`setIconSize(size)`

设置图标大小。

参数:

size (string): 图标大小 'small'、'medium'、'large'

示例:

// 直接调用
DesktopManager.setIconSize('large');

// 通过 ProcessManager 调用（推荐）
await ProcessManager.callKernelAPI(pid, 'Desktop.setIconSize', ['large']);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

`setAutoArrange(autoArrange)`

设置自动排列。

参数:

autoArrange (boolean): 是否自动排列

示例:

// 直接调用
DesktopManager.setAutoArrange(true);

// 通过 ProcessManager 调用（推荐）
await ProcessManager.callKernelAPI(pid, 'Desktop.setAutoArrange', [true]);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

桌面组件管理

`createComponent(pid, options)`

创建桌面组件（供程序使用）。

参数:

pid (number): 进程 ID
options (Object): 选项对象
- type (string): 组件类型（可选，用于标识）
- position (Object): 位置 {x, y}（可选，默认自动避开图标）
- size (Object): 尺寸 {width, height}（可选）
- style (Object): 自定义样式（可选）
- persistent (boolean): 是否持久化（可选，默认 false）
- draggable (boolean): 是否可拖动（可选，默认 true）

返回值: string - 组件 ID

示例:

const componentId = DesktopManager.createComponent(pid, {
    type: 'widget',
    position: { x: 200, y: 200 },
    size: { width: 300, height: 200 },
    style: {
        backgroundColor: 'rgba(0, 0, 0, 0.5)',
        borderRadius: '8px',
        padding: '20px',
        color: 'white'
    },
    draggable: true,
    persistent: false
});

const container = DesktopManager.getComponentContentContainer(componentId);
if (container) {
    container.innerHTML = '<div>我的桌面组件</div>';
}

`removeComponent(componentId, force)`

移除桌面组件。

参数:

componentId (string): 组件 ID
force (boolean): 是否强制删除（可选，默认 false，用于删除持久化组件）

返回值: boolean - 是否成功

示例:

DesktopManager.removeComponent(componentId);

`getComponentContentContainer(componentId)`

获取组件内容容器（供程序使用）。

参数:

componentId (string): 组件 ID

返回值: HTMLElement|null - 内容容器元素

示例:

const container = DesktopManager.getComponentContentContainer(componentId);
if (container) {
    container.innerHTML = '<div>更新后的内容</div>';
}

`updateComponentPosition(componentId, position)`

更新组件位置。

参数:

componentId (string): 组件 ID
position (Object): 新位置 {x, y}

示例:

DesktopManager.updateComponentPosition(componentId, { x: 300, y: 300 });

`updateComponentSize(componentId, size)`

更新组件尺寸。

参数:

componentId (string): 组件 ID
size (Object): 新尺寸 {width, height}

示例:

DesktopManager.updateComponentSize(componentId, { width: 400, height: 300 });

`updateComponentStyle(componentId, style)`

更新组件样式。

参数:

componentId (string): 组件 ID
style (Object): 样式对象

示例:

DesktopManager.updateComponentStyle(componentId, {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    borderRadius: '8px'
});

`getComponentsByPid(pid)`

获取程序创建的所有组件 ID。

参数:

pid (number): 进程 ID

返回值: Array<string> - 组件 ID 数组

示例:

const componentIds = DesktopManager.getComponentsByPid(pid);

`getComponentInfo(componentId)`

获取组件信息。

参数:

componentId (string): 组件 ID

返回值: Object|null - 组件信息或 null

示例:

const info = DesktopManager.getComponentInfo(componentId);

`getAllComponents(pid)`

获取所有组件信息。

参数:

pid (number|null): 可选，传入时仅返回该程序的组件

返回值: Array<Object> - 组件信息数组

示例:

const allComponents = DesktopManager.getAllComponents();

`cleanupProgramComponents(pid)`

清理程序创建的所有非持久化组件。

参数:

pid (number): 进程 ID

示例:

DesktopManager.cleanupProgramComponents(pid);

`hasComponent(componentId)`

检查组件是否存在。

参数:

componentId (string): 组件 ID

返回值: boolean

示例:

const exists = DesktopManager.hasComponent(componentId);

其他方法

`refresh()`

刷新桌面（重新加载图标和更新样式）。

示例:

// 直接调用
DesktopManager.refresh();

// 通过 ProcessManager 调用（推荐）
await ProcessManager.callKernelAPI(pid, 'Desktop.refresh', []);

权限要求: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）

通过 ProcessManager 调用

桌面图标与配置相关 API 可通过 ProcessManager.callKernelAPI 调用，并自动进行权限检查。桌面组件相关 API 仅支持直接调用 DesktopManager。

// 添加桌面快捷方式
const iconId = await ProcessManager.callKernelAPI(pid, 'Desktop.addShortcut', [{
    programName: 'filemanager',
    name: '文件管理器',
    icon: 'application/filemanager/filemanager.svg',
    description: '管理文件和文件夹'
}]);

// 添加文件图标
const fileIconId = await ProcessManager.callKernelAPI(pid, 'Desktop.addFileOrFolderIcon', [{
    type: 'file',
    targetPath: 'C:/Documents/example.txt',
    name: '示例文件'
}]);

// 移除快捷方式
await ProcessManager.callKernelAPI(pid, 'Desktop.removeShortcut', [iconId]);

// 获取桌面图标列表
const icons = await ProcessManager.callKernelAPI(pid, 'Desktop.getIcons', []);

// 设置排列模式
await ProcessManager.callKernelAPI(pid, 'Desktop.setArrangementMode', ['grid']);

// 设置图标大小
await ProcessManager.callKernelAPI(pid, 'Desktop.setIconSize', ['large']);

// 设置自动排列
await ProcessManager.callKernelAPI(pid, 'Desktop.setAutoArrange', [true]);

// 刷新桌面
await ProcessManager.callKernelAPI(pid, 'Desktop.refresh', []);

权限要求:

Desktop.addShortcut: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）
Desktop.addFileOrFolderIcon: 需要 DESKTOP_MANAGE 权限
Desktop.removeShortcut: 需要 DESKTOP_SHORTCUT 权限（普通权限，自动授予）
Desktop.getIcons: 不需要权限（读取操作）
Desktop.getConfig: 不需要权限（读取操作）
Desktop.setArrangementMode: 需要 DESKTOP_MANAGE 权限
Desktop.setIconSize: 需要 DESKTOP_MANAGE 权限
Desktop.setAutoArrange: 需要 DESKTOP_MANAGE 权限
Desktop.refresh: 需要 DESKTOP_MANAGE 权限

使用示例

示例 1: 添加桌面快捷方式

// 添加程序快捷方式
const iconId = DesktopManager.addShortcut({
    programName: 'filemanager',
    name: '文件管理器',
    icon: 'application/filemanager/filemanager.svg',
    description: '管理文件和文件夹'
});

// 稍后移除
DesktopManager.removeShortcut(iconId);

示例 2: 配置桌面

// 获取当前配置
const config = DesktopManager.getConfig();
console.log(`当前排列模式: ${config.arrangementMode}`);

// 设置网格排列
DesktopManager.setArrangementMode('grid');

// 设置大图标
DesktopManager.setIconSize('large');

// 启用自动排列
DesktopManager.setAutoArrange(true);

示例 3: 创建桌面组件

__init__: async function(pid, initArgs) {
    this.pid = pid;
    
    // 添加到桌面
    this.componentId = DesktopManager.createComponent(pid, {
        type: 'widget',
        position: { x: 100, y: 100 },
        size: { width: 300, height: 200 },
        style: {
            backgroundColor: 'rgba(0, 0, 0, 0.5)',
            borderRadius: '8px',
            padding: '20px',
            color: 'white'
        },
        draggable: true,
        persistent: false
    });
    
    // 获取内容容器并更新内容
    const container = DesktopManager.getComponentContentContainer(this.componentId);
    if (container) {
        container.innerHTML = '<h3>我的桌面组件</h3><p>这是一个桌面组件示例</p>';
    }
}

__exit__: function() {
    // 移除组件
    if (this.componentId) {
        DesktopManager.removeComponent(this.componentId);
    }
}

示例 4: 动态更新组件

// 更新组件位置
DesktopManager.updateComponentPosition(componentId, { x: 200, y: 200 });

// 更新组件尺寸
DesktopManager.updateComponentSize(componentId, { width: 400, height: 300 });

// 更新组件样式
DesktopManager.updateComponentStyle(componentId, {
    backgroundColor: 'rgba(139, 92, 246, 0.3)',
    borderRadius: '12px',
    boxShadow: '0 4px 12px rgba(0, 0, 0, 0.3)'
});

排列模式

grid（网格）

图标按网格排列
自动对齐到网格
不支持拖拽移动

list（列表）

图标按列表排列
自动对齐到列表
不支持拖拽移动

auto（自动）

图标自由排列
支持拖拽移动
位置可自定义

存储键

DesktopManager.STORAGE_KEY_ICONS = 'desktop.icons';
DesktopManager.STORAGE_KEY_ARRANGEMENT = 'desktop.arrangement';
DesktopManager.STORAGE_KEY_ICON_SIZE = 'desktop.iconSize';
DesktopManager.STORAGE_KEY_AUTO_ARRANGE = 'desktop.autoArrange';

注意事项

初始化: 桌面管理器在系统启动时自动初始化，通常不需要手动调用 init()
快捷方式: 桌面快捷方式会自动保存到 LStorage，下次启动时自动恢复
组件清理: 程序退出时，其创建的桌面组件会自动清理（除非标记为 persistent）
图标位置: 在 auto 模式下，图标位置可以自由拖拽；在 grid 或 list 模式下，图标自动排列
组件拖动: 桌面组件默认可拖动，可以通过 draggable: false 禁用
避开图标: 桌面组件会自动避开图标区域，避免重叠

DesktopManager API 文档

概述

依赖

初始化

API 方法

桌面快捷方式管理

addShortcut(options)

removeShortcut(iconId)

addFileOrFolderIcon(options)

getIcons()

桌面配置管理

getConfig()

setArrangementMode(mode)

setIconSize(size)

setAutoArrange(autoArrange)

桌面组件管理

createComponent(pid, options)

removeComponent(componentId, force)

getComponentContentContainer(componentId)

updateComponentPosition(componentId, position)

updateComponentSize(componentId, size)

updateComponentStyle(componentId, style)

getComponentsByPid(pid)

getComponentInfo(componentId)

getAllComponents(pid)

cleanupProgramComponents(pid)

hasComponent(componentId)

其他方法

refresh()

通过 ProcessManager 调用

使用示例

示例 1: 添加桌面快捷方式

示例 2: 配置桌面

示例 3: 创建桌面组件

示例 4: 动态更新组件

排列模式

grid（网格）

list（列表）

auto（自动）

存储键

注意事项

相关文档

`addShortcut(options)`

`removeShortcut(iconId)`

`addFileOrFolderIcon(options)`

`getIcons()`

`getConfig()`

`setArrangementMode(mode)`

`setIconSize(size)`

`setAutoArrange(autoArrange)`

`createComponent(pid, options)`

`removeComponent(componentId, force)`

`getComponentContentContainer(componentId)`

`updateComponentPosition(componentId, position)`

`updateComponentSize(componentId, size)`

`updateComponentStyle(componentId, style)`

`getComponentsByPid(pid)`

`getComponentInfo(componentId)`

`getAllComponents(pid)`

`cleanupProgramComponents(pid)`

`hasComponent(componentId)`

`refresh()`