分布式窗口：跨设备窗口投射

背景与动机

你有没有遇到过这种场景：在手机上看视频，突然想在大屏电视上继续看，但不想把整个手机界面都投射过去？或者在做演示时，只想把应用的某个窗口投射到大屏，而不是整个屏幕？

这就是分布式窗口要解决的问题——精确控制哪些窗口投射到哪些设备，实现"窗口级"的跨设备流转。

传统的屏幕投射是"全有或全无"——要么投射整个屏幕，要么什么都不投射。这种方式太粗暴了。想象一下，你只想把视频播放窗口投射到电视，结果连你的微信通知、系统状态栏都投射过去了，这就很尴尬。

HarmonyOS的分布式窗口能力，让你可以精确控制到窗口级别。你可以选择投射某个特定的窗口，甚至窗口内的某个组件。这种精细化的控制，让跨设备体验更加自然和专业。

核心原理

分布式窗口架构

分布式窗口基于以下几个核心概念：

1. WindowExtension：可投射的窗口扩展，声明窗口可以被投射
2. WindowProxy：窗口代理，在目标设备上代表源窗口
3. WindowMirror：窗口镜像，实时同步窗口内容和状态
4. DisplayManager：显示管理器，管理多个设备的显示

窗口投射模式

分布式窗口支持多种投射模式：

1. 镜像模式（Mirror）：源窗口和目标窗口完全同步，所见即所得
2. 扩展模式（Extend）：窗口扩展到目标设备，形成更大的显示区域
3. 独立模式（Independent）：目标窗口独立运行，只同步必要数据

窗口数据流

// 窗口数据传输结构
interface WindowTransferData {
    // 窗口标识
    windowId: string;
    
    // 窗口属性
    properties: {
        width: number;
        height: number;
        positionX: number;
        positionY: number;
        opacity: number;
        visible: boolean;
    };
    
    // UI树快照
    uiTree: UITreeNode;
    
    // 增量更新
    patches?: UIPatch[];
    
    // 时间戳
    timestamp: number;
}

代码实战

示例一：基础窗口投射

这是最基础的窗口投射示例，将一个视频播放窗口投射到电视设备。

// DistributedWindowManager.ets
import window from '@ohos.window';
import display from '@ohos.display';
import deviceManager from '@ohos.distributedDeviceManager';
import distributedWindow from '@ohos.distributedWindow';

export class DistributedWindowManager {
    private context: common.UIAbilityContext;
    private deviceManager: deviceManager.DeviceManager | null = null;
    
    // 源窗口
    private sourceWindow: window.Window | null = null;
    
    // 投射的窗口映射
    private mirroredWindows: Map<string, distributedWindow.WindowProxy> = new Map();

    constructor(context: common.UIAbilityContext) {
        this.context = context;
        this.initDeviceManager();
    }

    // 初始化设备管理器
    private async initDeviceManager(): Promise<void> {
        try {
            this.deviceManager = deviceManager.createDeviceManager(
                this.context.applicationInfo.name
            );
            console.info('[DistributedWindow] DeviceManager initialized');
        } catch (error) {
            console.error('[DistributedWindow] Init failed:', error);
        }
    }

    // 创建可投射的窗口
    async createProjectableWindow(options: WindowCreateOptions): Promise<window.Window> {
        console.info('[DistributedWindow] Creating projectable window');
        
        // 创建窗口配置
        const windowConfig: window.Configuration = {
            name: options.windowName,
            windowType: window.WindowType.TYPE_APP_MAIN_WINDOW,
            ctx: this.context
        };
        
        // 创建窗口
        this.sourceWindow = await window.createWindow(windowConfig);
        
        // 设置窗口属性
        await this.sourceWindow.setWindowProperties({
            windowRect: {
                left: options.x,
                top: options.y,
                width: options.width,
                height: options.height
            },
            isFullScreen: false,
            isKeepScreenOn: true
        });
        
        // 加载窗口内容
        await this.sourceWindow.loadContent(options.contentUrl, (err) => {
            if (err.code) {
                console.error('[DistributedWindow] Load content failed:', err);
                return;
            }
            console.info('[DistributedWindow] Content loaded');
        });
        
        // 显示窗口
        await this.sourceWindow.showWindow();
        
        // 注册为可投射窗口
        await this.registerAsProjectable(this.sourceWindow, options.windowName);
        
        return this.sourceWindow;
    }

    // 注册为可投射窗口
    private async registerAsProjectable(win: window.Window, name: string): Promise<void> {
        try {
            // 创建WindowExtension配置
            const extensionConfig: distributedWindow.WindowExtensionConfig = {
                windowName: name,
                // 支持的投射模式
                supportModes: [
                    distributedWindow.ProjectMode.MODE_MIRROR,
                    distributedWindow.ProjectMode.MODE_EXTEND
                ],
                // 窗口属性约束
                constraints: {
                    minWidth: 320,
                    minHeight: 240,
                    maxWidth: 3840,
                    maxHeight: 2160,
                    resizable: true,
                    movable: true
                }
            };
            
            // 注册窗口扩展
            await distributedWindow.registerWindowExtension(win, extensionConfig);
            
            console.info('[DistributedWindow] Window registered as projectable');
        } catch (error) {
            console.error('[DistributedWindow] Register failed:', error);
        }
    }

    // 投射窗口到目标设备
    async projectTo(targetDeviceId: string, options?: ProjectOptions): Promise<boolean> {
        console.info('[DistributedWindow] Projecting to:', targetDeviceId);
        
        if (!this.sourceWindow) {
            console.error('[DistributedWindow] No source window');
            return false;
        }
        
        try {
            // 构建投射配置
            const projectConfig: distributedWindow.ProjectConfig = {
                sourceWindow: this.sourceWindow,
                targetDeviceId: targetDeviceId,
                mode: options?.mode || distributedWindow.ProjectMode.MODE_MIRROR,
                // 目标窗口属性
                targetProperties: {
                    width: options?.width || 1920,
                    height: options?.height || 1080,
                    positionX: options?.x || 0,
                    positionY: options?.y || 0
                },
                // 同步配置
                syncConfig: {
                    syncContent: true,      // 同步内容
                    syncInput: true,        // 同步输入事件
                    syncState: true,        // 同步状态
                    frameRate: 30           // 帧率
                }
            };
            
            // 执行投射
            const windowProxy = await distributedWindow.projectWindow(projectConfig);
            
            // 保存投射映射
            this.mirroredWindows.set(targetDeviceId, windowProxy);
            
            // 监听投射状态
            this.setupProjectionListener(windowProxy, targetDeviceId);
            
            console.info('[DistributedWindow] Projection started');
            return true;
        } catch (error) {
            console.error('[DistributedWindow] Project failed:', error);
            return false;
        }
    }

    // 设置投射监听
    private setupProjectionListener(
        proxy: distributedWindow.WindowProxy, 
        deviceId: string
    ): void {
        // 监听目标窗口状态变化
        proxy.on('stateChange', (state: distributedWindow.WindowState) => {
            console.info('[DistributedWindow] Window state changed:', state);
            
            switch (state) {
                case distributedWindow.WindowState.STATE_CONNECTED:
                    console.info('[DistributedWindow] Connected to target device');
                    break;
                case distributedWindow.WindowState.STATE_DISCONNECTED:
                    console.info('[DistributedWindow] Disconnected from target device');
                    this.mirroredWindows.delete(deviceId);
                    break;
                case distributedWindow.WindowState.STATE_ERROR:
                    console.error('[DistributedWindow] Projection error');
                    this.handleProjectionError(deviceId);
                    break;
            }
        });
        
        // 监听目标窗口属性变化
        proxy.on('propertyChange', (properties: window.WindowProperties) => {
            console.info('[DistributedWindow] Target window properties changed');
            // 可以根据目标窗口变化调整源窗口
        });
        
        // 监听来自目标设备的事件
        proxy.on('remoteEvent', (event: distributedWindow.RemoteEvent) => {
            this.handleRemoteEvent(event);
        });
    }

    // 处理远程事件
    private handleRemoteEvent(event: distributedWindow.RemoteEvent): void {
        console.info('[DistributedWindow] Remote event:', event.type);
        
        switch (event.type) {
            case 'touch':
                // 触摸事件，转发到源窗口处理
                this.forwardTouchEvent(event.data);
                break;
            case 'key':
                // 按键事件
                this.forwardKeyEvent(event.data);
                break;
            case 'custom':
                // 自定义事件
                this.handleCustomEvent(event.data);
                break;
        }
    }

    // 转发触摸事件
    private forwardTouchEvent(touchData: TouchEventData): void {
        if (!this.sourceWindow) return;
        
        // 将目标设备的触摸坐标转换为源窗口坐标
        const sourceRect = this.sourceWindow.getWindowProperties().windowRect;
        const targetRect = touchData.windowRect;
        
        const scaleX = sourceRect.width / targetRect.width;
        const scaleY = sourceRect.height / targetRect.height;
        
        const convertedX = touchData.x * scaleX;
        const convertedY = touchData.y * scaleY;
        
        // 派发转换后的触摸事件
        this.sourceWindow.dispatchEvent({
            type: touchData.type,
            x: convertedX,
            y: convertedY,
            timestamp: touchData.timestamp
        });
    }

    // 转发按键事件
    private forwardKeyEvent(keyData: KeyEventData): void {
        if (!this.sourceWindow) return;
        this.sourceWindow.dispatchEvent(keyData);
    }

    // 处理自定义事件
    private handleCustomEvent(data: any): void {
        // 应用自定义逻辑
        console.info('[DistributedWindow] Custom event data:', data);
    }

    // 停止投射
    async stopProjection(targetDeviceId: string): Promise<void> {
        const proxy = this.mirroredWindows.get(targetDeviceId);
        if (!proxy) {
            console.warn('[DistributedWindow] No projection to stop');
            return;
        }
        
        try {
            await proxy.disconnect();
            this.mirroredWindows.delete(targetDeviceId);
            console.info('[DistributedWindow] Projection stopped');
        } catch (error) {
            console.error('[DistributedWindow] Stop failed:', error);
        }
    }

    // 处理投射错误
    private handleProjectionError(deviceId: string): void {
        console.error('[DistributedWindow] Handling error for:', deviceId);
        
        // 尝试重连
        setTimeout(async () => {
            const success = await this.projectTo(deviceId);
            if (!success) {
                this.mirroredWindows.delete(deviceId);
            }
        }, 3000);
    }

    // 获取可投射的设备列表
    async getProjectableDevices(): Promise<ProjectableDevice[]> {
        if (!this.deviceManager) return [];
        
        const devices = this.deviceManager.getTrustedDeviceListSync();
        
        return devices
            .filter(d => d.deviceState === deviceManager.DeviceState.ONLINE)
            .map(d => ({
                deviceId: d.deviceId,
                deviceName: d.deviceName,
                deviceType: this.mapDeviceType(d.deviceType),
                // 获取设备显示信息
                displayInfo: this.getDeviceDisplayInfo(d.deviceId)
            }));
    }

    // 获取设备显示信息
    private getDeviceDisplayInfo(deviceId: string): DisplayInfo {
        // 实际实现需要查询远程设备信息
        return {
            width: 1920,
            height: 1080,
            density: 2.0,
            refreshRate: 60
        };
    }

    // 设备类型映射
    private mapDeviceType(type: number): string {
        const types = ['unknown', 'phone', 'tablet', 'tv', 'watch'];
        return types[type] || 'unknown';
    }

    // 销毁
    destroy(): void {
        // 停止所有投射
        this.mirroredWindows.forEach((proxy, deviceId) => {
            proxy.disconnect().catch(err => {
                console.error('[DistributedWindow] Disconnect error:', err);
            });
        });
        this.mirroredWindows.clear();
        
        // 释放设备管理器
        if (this.deviceManager) {
            deviceManager.releaseDeviceManager(this.deviceManager);
            this.deviceManager = null;
        }
    }
}

// 接口定义
interface WindowCreateOptions {
    windowName: string;
    contentUrl: string;
    x: number;
    y: number;
    width: number;
    height: number;
}

interface ProjectOptions {
    mode?: distributedWindow.ProjectMode;
    width?: number;
    height?: number;
    x?: number;
    y?: number;
}

interface ProjectableDevice {
    deviceId: string;
    deviceName: string;
    deviceType: string;
    displayInfo: DisplayInfo;
}

interface DisplayInfo {
    width: number;
    height: number;
    density: number;
    refreshRate: number;
}

interface TouchEventData {
    type: string;
    x: number;
    y: number;
    timestamp: number;
    windowRect: { width: number; height: number };
}

interface KeyEventData {
    keyCode: number;
    action: number;
    timestamp: number;
}

示例二：多窗口投射管理

实际应用中，可能需要同时投射多个窗口到不同设备，或者一个窗口投射到多个设备。

// MultiWindowProjection.ets
import distributedWindow from '@ohos.distributedWindow';
import window from '@ohos.window';

export class MultiWindowProjection {
    // 窗口投射映射：windowId -> deviceId[]
    private windowToDeviceMap: Map<string, Set<string>> = new Map();
    
    // 设备窗口映射：deviceId -> windowId[]
    private deviceToWindowMap: Map<string, Set<string>> = new Map();
    
    // 窗口代理映射：windowId_deviceId -> WindowProxy
    private proxyMap: Map<string, distributedWindow.WindowProxy> = new Map();

    // 投射窗口到多个设备
    async projectToMultipleDevices(
        sourceWindow: window.Window,
        targetDevices: string[]
    ): Promise<Map<string, boolean>> {
        const results = new Map<string, boolean>();
        
        // 并行投射到所有目标设备
        const promises = targetDevices.map(async (deviceId) => {
            try {
                const proxy = await this.projectTo(sourceWindow, deviceId);
                results.set(deviceId, true);
                return { deviceId, proxy };
            } catch (error) {
                console.error('[MultiWindow] Project to', deviceId, 'failed:', error);
                results.set(deviceId, false);
                return null;
            }
        });
        
        await Promise.all(promises);
        
        return results;
    }

    // 投射单个窗口到单个设备
    private async projectTo(
        sourceWindow: window.Window, 
        deviceId: string
    ): Promise<distributedWindow.WindowProxy> {
        const windowId = sourceWindow.getWindowName();
        
        // 创建投射
        const proxy = await distributedWindow.projectWindow({
            sourceWindow: sourceWindow,
            targetDeviceId: deviceId,
            mode: distributedWindow.ProjectMode.MODE_MIRROR
        });
        
        // 更新映射
        this.updateMappings(windowId, deviceId, proxy);
        
        return proxy;
    }

    // 更新映射关系
    private updateMappings(
        windowId: string, 
        deviceId: string, 
        proxy: distributedWindow.WindowProxy
    ): void {
        // 窗口到设备的映射
        if (!this.windowToDeviceMap.has(windowId)) {
            this.windowToDeviceMap.set(windowId, new Set());
        }
        this.windowToDeviceMap.get(windowId)!.add(deviceId);
        
        // 设备到窗口的映射
        if (!this.deviceToWindowMap.has(deviceId)) {
            this.deviceToWindowMap.set(deviceId, new Set());
        }
        this.deviceToWindowMap.get(deviceId)!.add(windowId);
        
        // 代理映射
        const key = `${windowId}_${deviceId}`;
        this.proxyMap.set(key, proxy);
    }

    // 投射多个窗口到单个设备
    async projectMultipleWindows(
        sourceWindows: window.Window[],
        targetDeviceId: string
    ): Promise<Map<string, boolean>> {
        const results = new Map<string, boolean>();
        
        // 获取目标设备的显示信息
        const displayInfo = await this.getTargetDisplayInfo(targetDeviceId);
        
        // 计算窗口布局
        const layout = this.calculateWindowLayout(sourceWindows.length, displayInfo);
        
        // 并行投射所有窗口
        const promises = sourceWindows.map(async (win, index) => {
            const windowId = win.getWindowName();
            const position = layout[index];
            
            try {
                const proxy = await distributedWindow.projectWindow({
                    sourceWindow: win,
                    targetDeviceId: targetDeviceId,
                    mode: distributedWindow.ProjectMode.MODE_EXTEND,
                    targetProperties: {
                        width: position.width,
                        height: position.height,
                        positionX: position.x,
                        positionY: position.y
                    }
                });
                
                this.updateMappings(windowId, targetDeviceId, proxy);
                results.set(windowId, true);
            } catch (error) {
                console.error('[MultiWindow] Project window', windowId, 'failed:', error);
                results.set(windowId, false);
            }
        });
        
        await Promise.all(promises);
        
        return results;
    }

    // 计算窗口布局
    private calculateWindowLayout(
        windowCount: number, 
        displayInfo: DisplayInfo
    ): WindowPosition[] {
        const positions: WindowPosition[] = [];
        
        if (windowCount === 1) {
            // 单窗口：全屏
            positions.push({
                x: 0,
                y: 0,
                width: displayInfo.width,
                height: displayInfo.height
            });
        } else if (windowCount === 2) {
            // 双窗口：左右分屏
            positions.push({
                x: 0,
                y: 0,
                width: displayInfo.width / 2,
                height: displayInfo.height
            });
            positions.push({
                x: displayInfo.width / 2,
                y: 0,
                width: displayInfo.width / 2,
                height: displayInfo.height
            });
        } else {
            // 多窗口：网格布局
            const cols = Math.ceil(Math.sqrt(windowCount));
            const rows = Math.ceil(windowCount / cols);
            const cellWidth = displayInfo.width / cols;
            const cellHeight = displayInfo.height / rows;
            
            for (let i = 0; i < windowCount; i++) {
                const row = Math.floor(i / cols);
                const col = i % cols;
                positions.push({
                    x: col * cellWidth,
                    y: row * cellHeight,
                    width: cellWidth,
                    height: cellHeight
                });
            }
        }
        
        return positions;
    }

    // 停止窗口的所有投射
    async stopWindowProjection(windowId: string): Promise<void> {
        const devices = this.windowToDeviceMap.get(windowId);
        if (!devices) return;
        
        const promises = Array.from(devices).map(deviceId => {
            return this.stopSingleProjection(windowId, deviceId);
        });
        
        await Promise.all(promises);
        
        this.windowToDeviceMap.delete(windowId);
    }

    // 停止设备的所有投射
    async stopDeviceProjection(deviceId: string): Promise<void> {
        const windows = this.deviceToWindowMap.get(deviceId);
        if (!windows) return;
        
        const promises = Array.from(windows).map(windowId => {
            return this.stopSingleProjection(windowId, deviceId);
        });
        
        await Promise.all(promises);
        
        this.deviceToWindowMap.delete(deviceId);
    }

    // 停止单个投射
    private async stopSingleProjection(windowId: string, deviceId: string): Promise<void> {
        const key = `${windowId}_${deviceId}`;
        const proxy = this.proxyMap.get(key);
        
        if (proxy) {
            try {
                await proxy.disconnect();
                this.proxyMap.delete(key);
                
                // 更新映射
                this.windowToDeviceMap.get(windowId)?.delete(deviceId);
                this.deviceToWindowMap.get(deviceId)?.delete(windowId);
            } catch (error) {
                console.error('[MultiWindow] Stop projection failed:', error);
            }
        }
    }

    // 获取窗口的投射状态
    getProjectionStatus(windowId: string): ProjectionStatus {
        const devices = this.windowToDeviceMap.get(windowId);
        
        return {
            windowId: windowId,
            isActive: devices !== undefined && devices.size > 0,
            targetDevices: devices ? Array.from(devices) : [],
            deviceCount: devices ? devices.size : 0
        };
    }

    // 获取设备的投射状态
    getDeviceStatus(deviceId: string): DeviceProjectionStatus {
        const windows = this.deviceToWindowMap.get(deviceId);
        
        return {
            deviceId: deviceId,
            isActive: windows !== undefined && windows.size > 0,
            projectedWindows: windows ? Array.from(windows) : [],
            windowCount: windows ? windows.size : 0
        };
    }

    // 辅助方法
    private async getTargetDisplayInfo(deviceId: string): Promise<DisplayInfo> {
        // 实际实现需要查询远程设备
        return { width: 1920, height: 1080, density: 2.0, refreshRate: 60 };
    }
}

// 接口定义
interface WindowPosition {
    x: number;
    y: number;
    width: number;
    height: number;
}

interface ProjectionStatus {
    windowId: string;
    isActive: boolean;
    targetDevices: string[];
    deviceCount: number;
}

interface DeviceProjectionStatus {
    deviceId: string;
    isActive: boolean;
    projectedWindows: string[];
    windowCount: number;
}

示例三：窗口内容增量同步

为了提高性能，窗口投射时应该使用增量同步，只传输变化的部分。

// WindowContentSync.ets
import distributedWindow from '@ohos.distributedWindow';

export class WindowContentSync {
    private proxy: distributedWindow.WindowProxy;
    
    // 上次同步的UI树版本
    private lastSyncVersion: number = 0;
    
    // 脏区域标记
    private dirtyRegions: DirtyRegion[] = [];
    
    // 是否正在同步
    private isSyncing: boolean = false;
    
    // 同步队列
    private syncQueue: SyncTask[] = [];

    constructor(proxy: distributedWindow.WindowProxy) {
        this.proxy = proxy;
        this.setupSyncScheduler();
    }

    // 设置同步调度器
    private setupSyncScheduler(): void {
        // 每16ms检查一次是否需要同步（约60fps）
        setInterval(() => {
            if (!this.isSyncing && this.syncQueue.length > 0) {
                this.processSyncQueue();
            }
        }, 16);
    }

    // 标记区域为脏（需要更新）
    markDirty(region: DirtyRegion): void {
        // 合并重叠的脏区域
        const merged = this.mergeDirtyRegions([...this.dirtyRegions, region]);
        this.dirtyRegions = merged;
        
        // 添加同步任务
        this.syncQueue.push({
            type: 'dirty_update',
            regions: merged,
            timestamp: Date.now()
        });
    }

    // 合并脏区域
    private mergeDirtyRegions(regions: DirtyRegion[]): DirtyRegion[] {
        if (regions.length <= 1) return regions;
        
        const merged: DirtyRegion[] = [];
        const sorted = regions.sort((a, b) => a.y - b.y);
        
        let current = sorted[0];
        
        for (let i = 1; i < sorted.length; i++) {
            const next = sorted[i];
            
            // 检查是否可以合并
            if (this.canMerge(current, next)) {
                current = this.mergeTwo(current, next);
            } else {
                merged.push(current);
                current = next;
            }
        }
        
        merged.push(current);
        return merged;
    }

    // 检查两个区域是否可以合并
    private canMerge(a: DirtyRegion, b: DirtyRegion): boolean {
        return !(a.x + a.width < b.x || 
                 b.x + b.width < a.x || 
                 a.y + a.height < b.y || 
                 b.y + b.height < a.y);
    }

    // 合并两个区域
    private mergeTwo(a: DirtyRegion, b: DirtyRegion): DirtyRegion {
        const x = Math.min(a.x, b.x);
        const y = Math.min(a.y, b.y);
        const width = Math.max(a.x + a.width, b.x + b.width) - x;
        const height = Math.max(a.y + a.height, b.y + b.height) - y;
        
        return { x, y, width, height };
    }

    // 处理同步队列
    private async processSyncQueue(): Promise<void> {
        if (this.syncQueue.length === 0) return;
        
        this.isSyncing = true;
        
        // 合并队列中的任务
        const task = this.mergeSyncTasks(this.syncQueue);
        this.syncQueue = [];
        
        try {
            await this.executeSync(task);
        } catch (error) {
            console.error('[WindowSync] Sync failed:', error);
            // 重试
            this.syncQueue.unshift(task);
        }
        
        this.isSyncing = false;
    }

    // 合并同步任务
    private mergeSyncTasks(tasks: SyncTask[]): SyncTask {
        // 收集所有脏区域
        const allRegions: DirtyRegion[] = [];
        for (const task of tasks) {
            if (task.regions) {
                allRegions.push(...task.regions);
            }
        }
        
        return {
            type: 'dirty_update',
            regions: this.mergeDirtyRegions(allRegions),
            timestamp: Date.now()
        };
    }

    // 执行同步
    private async executeSync(task: SyncTask): Promise<void> {
        if (!task.regions || task.regions.length === 0) return;
        
        // 收集脏区域的内容
        const patches: ContentPatch[] = [];
        
        for (const region of task.regions) {
            const content = await this.captureRegionContent(region);
            patches.push({
                region: region,
                content: content,
                encoding: 'jpeg',
                quality: 80
            });
        }
        
        // 发送增量更新
        await this.proxy.sendUpdate({
            type: 'incremental',
            version: ++this.lastSyncVersion,
            patches: patches,
            timestamp: Date.now()
        });
        
        // 清空脏区域
        this.dirtyRegions = [];
    }

    // 捕获区域内容
    private async captureRegionContent(region: DirtyRegion): Promise<ArrayBuffer> {
        // 实际实现需要截取指定区域的UI内容
        // 可以使用组件快照API
        return new ArrayBuffer(0);
    }

    // 全量同步（用于初始化或恢复）
    async fullSync(): Promise<void> {
        console.info('[WindowSync] Starting full sync');
        
        try {
            // 捕获完整窗口内容
            const fullContent = await this.captureFullContent();
            
            await this.proxy.sendUpdate({
                type: 'full',
                version: ++this.lastSyncVersion,
                content: fullContent,
                timestamp: Date.now()
            });
            
            console.info('[WindowSync] Full sync completed');
        } catch (error) {
            console.error('[WindowSync] Full sync failed:', error);
            throw error;
        }
    }

    // 捕获完整内容
    private async captureFullContent(): Promise<FullContent> {
        // 实际实现需要序列化完整的UI树
        return {
            uiTree: {},
            resources: [],
            styles: {}
        };
    }

    // 强制同步（忽略队列，立即执行）
    async forceSync(): Promise<void> {
        // 清空队列
        this.syncQueue = [];
        
        // 执行全量同步
        await this.fullSync();
    }
}

// 接口定义
interface DirtyRegion {
    x: number;
    y: number;
    width: number;
    height: number;
}

interface SyncTask {
    type: string;
    regions?: DirtyRegion[];
    timestamp: number;
}

interface ContentPatch {
    region: DirtyRegion;
    content: ArrayBuffer;
    encoding: string;
    quality: number;
}

interface FullContent {
    uiTree: any;
    resources: any[];
    styles: any;
}

踰坑与注意事项

坑一：窗口尺寸不匹配

问题描述：源窗口和目标设备分辨率差异大，直接投射导致内容变形或模糊。

解决方案：根据目标设备调整内容缩放

async projectWithAdaptation(
    sourceWindow: window.Window,
    targetDeviceId: string
): Promise<void> {
    // 获取目标设备分辨率
    const targetDisplay = await this.getTargetDisplayInfo(targetDeviceId);
    const sourceRect = sourceWindow.getWindowProperties().windowRect;
    
    // 计算缩放比例
    const scale = Math.min(
        targetDisplay.width / sourceRect.width,
        targetDisplay.height / sourceRect.height
    );
    
    // 投射时应用缩放
    await distributedWindow.projectWindow({
        sourceWindow: sourceWindow,
        targetDeviceId: targetDeviceId,
        targetProperties: {
            width: sourceRect.width * scale,
            height: sourceRect.height * scale,
            positionX: (targetDisplay.width - sourceRect.width * scale) / 2,
            positionY: (targetDisplay.height - sourceRect.height * scale) / 2
        },
        contentScale: scale  // 内容缩放
    });
}

坑二：输入事件坐标转换错误

问题描述：目标设备上的触摸事件，转换到源窗口时坐标错误。

解决方案：正确计算坐标映射

private convertCoordinates(
    sourceRect: window.Rect,
    targetRect: window.Rect,
    touchPoint: { x: number; y: number }
): { x: number; y: number } {
    // 计算缩放比例
    const scaleX = sourceRect.width / targetRect.width;
    const scaleY = sourceRect.height / targetRect.height;
    
    // 计算偏移（如果目标窗口有偏移）
    const offsetX = sourceRect.left;
    const offsetY = sourceRect.top;
    
    return {
        x: touchPoint.x * scaleX + offsetX,
        y: touchPoint.y * scaleY + offsetY
    };
}

坑三：网络延迟导致画面卡顿

问题描述：网络延迟时，窗口内容同步不及时，导致画面卡顿。

解决方案：实现预测渲染和插值

// 预测下一帧
private predictNextFrame(currentFrame: Frame, velocity: Velocity): Frame {
    const deltaTime = 16; // 假设16ms一帧
    
    return {
        ...currentFrame,
        x: currentFrame.x + velocity.x * deltaTime,
        y: currentFrame.y + velocity.y * deltaTime
    };
}

HarmonyOS 6适配

新增窗口组投射

HarmonyOS 6支持将多个窗口作为一个组投射：

// 创建窗口组
const windowGroup = await distributedWindow.createWindowGroup({
    groupId: 'video_group',
    windows: [videoWindow, controlWindow],
    layout: 'horizontal'  // 水平布局
});

// 投射窗口组
await windowGroup.projectTo(targetDeviceId);

增强的编码选项

const projectConfig: distributedWindow.ProjectConfig = {
    // ... 其他配置
    encodingConfig: {
        codec: 'h265',           // 使用H.265编码
        bitrate: 8000000,        // 8Mbps码率
        frameRate: 60,           // 60fps
        latency: 'low',          // 低延迟模式
        adaptiveBitrate: true    // 自适应码率
    }
};

窗口投射质量监控

// 监听投射质量
proxy.on('qualityMetrics', (metrics: QualityMetrics) => {
    console.info('FPS:', metrics.fps);
    console.info('Latency:', metrics.latency, 'ms');
    console.info('Bitrate:', metrics.bitrate, 'kbps');
    console.info('PacketLoss:', metrics.packetLoss, '%');
    
    // 根据质量调整编码参数
    if (metrics.fps < 30) {
        this.adjustEncodingForBetterPerformance();
    }
});

总结

分布式窗口是HarmonyOS分布式能力的重要组成部分，它让窗口级别的跨设备流转成为可能。相比全屏投射，窗口级投射提供了更精细的控制和更灵活的应用场景。

核心要点：

1. 窗口级控制：精确控制哪些窗口投射到哪些设备
2. 多种投射模式：镜像、扩展、独立模式适应不同场景
3. 增量同步：只传输变化的部分，提高性能
4. 事件路由：正确处理来自目标设备的输入事件

最佳实践：

• 根据目标设备能力调整投射参数
• 实现增量同步减少数据传输
• 正确处理坐标转换和事件路由
• 监控投射质量并动态调整
• 处理网络延迟和设备断线等异常情况

分布式窗口打开了跨设备展示的大门，下一篇我们将探讨分布式屏幕，看看如何实现更底层的屏幕镜像能力。