UI上下文异常调试
=========

本指导主要介绍如何解决因使用无效的[UIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext-uicontext)导致文本显示异常的问题。当开发者使用了已失效的UIContext对象（通常是因为对应的UI实例已被销毁），可能导致后续UI操作无效。此类问题常见于多窗口场景。从API version 12开始，该问题也见于调用[setSupportedProcessCache](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-inner-application-applicationcontext#applicationcontextsetsupportedprocesscache12)打开进程缓存后快速启动的情形。

#### 定位UIContext错误问题

出现以下异常或系统日志时，可能存在UIContext无效的问题：

*   存在JS异常："Node Constructor error, param uiContext error"。
    
    产生该异常的原因通常是在[自定义节点](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-user-defined-node)中使用了无效的UIContext，这可能导致后续UI操作被错误关联到该无效UIContext。
    
*   存在实例状态更新时，上下文实例ID大于等于100000且小于1000000的日志：
    
    实例状态更新的日志格式为：
    
    ({currentId}:{trackedId}:{trackedReason})\]\[{bundleName}\]\[{moduleName}\]\[{thisInstanceId}\]: window {status}
    
    各字段含义为：
    
    **表1** 实例状态更新日志字段含义
    
    | 字段名 | 类型 | 典型值 | 说明 |
    | :-- | :-- | :-- | :-- |
    | {currentId} | 整数 | \-1 | 上下文实例ID，应用正常的情况下，该字段应该为负数。 |
    | {trackedId} | 整数 | 100000 | 当前可间接跟踪的实例ID，通常为正数，开发者可忽略。 |
    | {trackedReason} | 字符串 | singleton | 间接跟踪的原因，开发者可不关注该字段。 |
    | {bundleName} | 字符串 | com.example.helloworld | 应用的bundleName。 |
    | {moduleName} | 字符串 | entry | 当前模块的moduleName。 |
    | {thisInstanceId} | 正数 | 100000 | 被通知UI实例的ID。 |
    | {status} | 实例被通知的状态 | focus | 
    可选值为:
    
    \- focus：获焦
    
    \- unfocus：失焦
    
    \- foreground：前台
    
    \- background：后台
    
    \- destroy：销毁
    
     |
    
    可使用如下正则表达式匹配相关日志：
    
    \\(-?\\d+:-?\\d+:(scope|active|default|singleton|foreground|undefined)\\)\\\] \\\[\[a-z0-9.\]+\\\]\\\[\[a-zA-Z\]\[0-9a-zA-Z\_.\]\*\\\]\\\[\\d+\\\]: window (focus|unfocus|foreground|background|destroy)
    
    **示例说明**
    
    *   正确日志示例：
        
        (-2:100000:singleton)\] \[com.example.helloworld\]\[entry\]\[100000\]: window foreground
        
    *   异常日志示例：
        
        (100000:100000:scoped)\] \[com.example.helloworld\]\[entry\]\[100001\]: window background
        
        该异常日志说明存在错误跟踪ID为100000的UI实例。
        
    *   若前文出现以下特定格式的日志：
        
        (-2:100000:singleton)\] \[com.example.helloworld\]\[entry\]\[100000\]: window destroy
        
        表示ID为100000的UI实例已销毁，后续UI操作可能受其上下文影响。
        

#### 实例详细信息

某些实例相关接口的报错信息会包含对应实例的信息，仅有缓存列表中的实例会输出详细信息。缓存列表仅保存被销毁的实例的信息。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b8/v3/uTKdiFk8Rq-CcwV5bly_CA/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132324Z&HW-CC-Expire=86400&HW-CC-Sign=D4380A5F3BEB6C3996CE3A55971C5853ABC70858ED0C9C5C32070484711FC6B2)

*   当前缓存列表大小为10，采用LRU（最近最少使用）机制进行淘汰。

#### \[h2\]缓存命中

异常实例命中缓存时，详细信息的输出格式如下：

DestroyedUIContextCacheInfo: instanceInfo: \[instanceId:<instanceId\_>, createTime:<createTime\_>, destroyTime:<destroyTime\_>\], windowInfo: \[windowId: <windowId\_>, windowName: <windowName\_>\]

#### \[h2\]缓存未命中

当请求的实例在缓存中不存在（从未被缓存、或已因超出缓存大小被移除）时，详细信息的输出格式如下：

InstanceId not found in destroyed cache.

#### \[h2\]完整消息示例

被缓存的已销毁的实例详细信息按照如下格式进行输出，包括实例ID、创建时间、销毁时间、窗口ID、窗口名称字段：

UI execution context not found.InstanceId: 100001,

Reason to get the instance: The instance is determined by the caller,

DestroyedUIContextCacheInfo: instanceInfo: \[instanceId:100001, createTime:2026-04-14 10:30:00.123, destroyTime:2026-04-14 10:35:22.456\], windowInfo: \[windowId: 1001, windowName: EntryAbility\]

消息中各字段含义如下：

*   instanceId:100001：表示请求的是100001号实例。
*   Reason to get the instance: The instance is determined by the caller：表示由调用方显式指定了实例ID。
*   createTime:2026-04-14 10:30:00.123：表示该实例创建时间为2026-04-14 10:30。
*   destroyTime:2026-04-14 10:35:22.456：表示该实例销毁时间为2026-04-14 10:35，存活了约5分22秒。
*   windowId: 1001：表示该实例关联窗口ID为1001。
*   windowName: EntryAbility：表示该实例关联窗口名为EntryAbility。

**表2** 完整消息字段含义说明

| 属性 | 说明 |
| :-- | :-- |
| instanceId | 实例ID。由系统在创建实例时分配。 |
| Reason to get the instance | 获得对应实例的原因，详见表3实例指定原因说明。 |
| createTime | 实例创建的时刻。 |
| destroyTime | 实例销毁的时刻。 |
| windowId | 实例对应的窗口的ID。 |
| windowName | 实例对应的窗口的名称。 |

**表3** 实例指定原因说明

| 描述 | 说明 |
| :-- | :-- |
| The instance is determined by the caller. | 在调用过程中显式指定了实例ID。应用侧通常是通过[UIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-uicontext)接口进行指定。 |
| No specific instance was specified, so the most recently active instance was retrieved. | 未显式指定实例ID，系统返回最近活跃的实例。 |
| No specific instance was specified, return the foreground instance. | 未显式指定实例ID，系统返回前台实例。 |
| No specific instance was specified, return the only remaining instance. | 未显式指定实例ID，系统返回唯一的实例（仅存在一个UI实例时）。 |
| No specific instance was specified, using default. | 未显式指定实例ID，使用默认实例（最后创建的实例）。 |
| No valid instance exists. | 不存在有效的UI实例。 |

#### 解决UIContext错误导致的显示异常问题

**问题现象**

当发生以下问题时，可根据上文的关键日志或异常进行判断：

1.  使用[setStyledString](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-text#setstyledstring12)方法设置字体大小时，字体大小未发生预期变化。
2.  使用UIContext成员方法时，界面没有响应或显示异常。

**解决措施**

重新获取有效的UIContext对象。可通过以下方式获取：

*   使用自定义组件的[getUIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-custom-component-api#getuicontext)方法获取。
*   通过窗口的[getUIContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#getuicontext10)方法获取。