wpf 控件开发中，OnApplyTemplate 和 OnContentRendered区别

OnApplyTemplate 与 OnContentRendered 的区别及使用场景

在 WPF 控件开发中，OnApplyTemplate 和 OnContentRendered 是两个重要的生命周期方法，它们有不同的用途和调用时机，适合不同的操作场景。

一、核心区别对比

这两个方法在控件初始化过程中的典型调用顺序：

构造函数 → 2. OnApplyTemplate → 3. 布局测量/排列 → 4. 渲染 → 5. OnContentRendered

1. OnApplyTemplate 阶段

• 触发时机：在以下情况后立即调用：
  • 控件首次创建
  • 控件的 Template 属性被显式更改
  • 应用了新的样式（包含不同模板）
• 关键特征：
  • 视觉树已创建但尚未布局
  • ActualWidth/ActualHeight 等属性通常为 0 或 NaN
  • 是获取 GetTemplateChild 的主要位置

2. 布局阶段

• 发生在 OnApplyTemplate 之后
• 包含 Measure 和 Arrange 两个过程
• 此时计算控件的实际尺寸和位置

3. OnContentRendered 阶段

• 触发时机：在以下条件满足后调用：
  • 布局已完成（Measure 和 Arrange）
  • 所有可视化内容已完成首次渲染
• 关键特征：
  • ActualWidth/ActualHeight 已有正确值
  • 所有子元素已完成布局
  • 通常只调用一次（除非内容完全重建）

public class LifecycleDemoControl : Control
{
    public LifecycleDemoControl()
    {
        Debug.WriteLine("1. 构造函数执行");
    }
    
    public override void OnApplyTemplate()
    {
        base.OnApplyTemplate();
        Debug.WriteLine("2. OnApplyTemplate执行");
        Debug.WriteLine($"   当前尺寸: {ActualWidth}x{ActualHeight}"); // 通常输出 0x0
    }
    
    protected override void OnContentRendered(EventArgs e)
    {
        base.OnContentRendered(e);
        Debug.WriteLine("5. OnContentRendered执行");
        Debug.WriteLine($"   当前尺寸: {ActualWidth}x{ActualHeight}"); // 输出实际值
    }
    
    protected override Size MeasureOverride(Size constraint)
    {
        Debug.WriteLine("3. 测量阶段(Measure)");
        return base.MeasureOverride(constraint);
    }
    
    protected override Size ArrangeOverride(Size arrangeBounds)
    {
        Debug.WriteLine("4. 排列阶段(Arrange)");
        return base.ArrangeOverride(arrangeBounds);
    }
}

输出：

1. 构造函数执行
2. OnApplyTemplate执行
   当前尺寸: 0x0
3. 测量阶段(Measure)
4. 排列阶段(Arrange)
5. OnContentRendered执行
   当前尺寸: 150x50

4. 特殊场景

4.1 模板动态变更的情况

如果运行时更改了控件的 Template 属性：

1. OnApplyTemplate (旧模板清理)
2. OnApplyTemplate (新模板应用)
3. 布局过程
4. OnContentRendered (通常不会再次触发)

4.2 延迟加载的场景

对于虚拟化容器（如 ListBox），子项的 OnContentRendered 可能在实际显示时才会触发。

4.3 Visibility 变化

当控件从 Collapsed 变为 Visible 时：

不会触发 OnApplyTemplate
可能触发新的布局和渲染
但不会再次触发 OnContentRendered

二、详细解析

1. OnApplyTemplate - 模板应用通知

public override void OnApplyTemplate()
{
    // 必须先调用基类实现
    base.OnApplyTemplate();
    
    // 安全获取模板部件的最佳位置
    _myButton = GetTemplateChild("PART_Button") as Button;
    
    // 典型用途：
    // - 缓存模板部件引用
    // - 绑定事件处理器
    // - 初始化部件状态
    if (_myButton != null)
    {
        _myButton.Click += OnButtonClick;
    }
    
    // 注意：此时布局尚未计算完成
    // 不要依赖ActualWidth/ActualHeight等属性
}

关键特点：

• WPF 在应用模板后立即调用
• 是获取 GetTemplateChild 的主要位置
• 可能被多次调用（当控件模板被替换时）
• 应在此清理之前模板的事件绑定等

2. OnContentRendered - 内容渲染完成通知

protected override void OnContentRendered(EventArgs e)
{
    base.OnContentRendered(e);
    
    // 此时布局和渲染已完成
    // 可以安全使用ActualWidth/ActualHeight等属性
    
    // 可以获取模板部件，但需注意模板可能已变更
    var button = GetTemplateChild("PART_Button") as Button;
    if (button != null)
    {
        // 执行依赖布局完成的操作
        Debug.WriteLine($"按钮实际宽度：{button.ActualWidth}");
    }
    
    // 典型用途：
    // - 执行依赖最终布局的计算
    // - 启动动画
    // - 执行一次性初始化
}

关键特点：

• 在内容完成布局和渲染后调用
• 通常只调用一次（除非内容被完全重建）
• 适合执行需要知道最终尺寸的操作
• 调用时可能已经过一段时间（等待渲染)

三、何时使用 GetTemplateChild

推荐在 OnApplyTemplate 中调用：

public override void OnApplyTemplate()
{
    base.OnApplyTemplate();
    
    // 最佳实践：在此获取并缓存模板部件
    _header = GetTemplateChild("PART_Header") as Border;
    _content = GetTemplateChild("PART_Content") as ContentPresenter;
    
    // 初始化部件状态
    if (_header != null)
    {
        _header.Visibility = ShowHeader ? Visibility.Visible : Visibility.Collapsed;
    }
}

也可以在 OnContentRendered 中调用（但有注意事项）：

protected override void OnContentRendered(EventArgs e)
{
    base.OnContentRendered(e);
    
    // 可以调用，但需要考虑：
    // 1. 模板可能在OnApplyTemplate后被替换
    // 2. 性能考虑，避免重复查找
    
    var button = GetTemplateChild("PART_Submit") as Button;
    if (button != null && button.ActualWidth > 100)
    {
        // 根据实际尺寸调整
    }
}

四、典型使用场景对比

OnApplyTemplate 适用场景：

1. 获取和缓存模板部件引用
2. 绑定事件处理器
3. 初始化模板部件的基本状态
4. 验证模板是否包含必需部件

OnContentRendered 适用场景：

1. 执行依赖实际尺寸的计算
2. 启动初始动画或过渡效果
3. 执行需要知道最终布局的调整
4. 收集渲染性能数据

五、综合示例

public class AdvancedControl : Control
{
    private Border _headerPart;
    private ContentPresenter _contentPart;
    
    static AdvancedControl()
    {
        DefaultStyleKeyProperty.OverrideMetadata(typeof(AdvancedControl),
            new FrameworkPropertyMetadata(typeof(AdvancedControl)));
    }
    
    public override void OnApplyTemplate()
    {
        // 清理旧模板的绑定
        if (_headerPart != null)
        {
            _headerPart.MouseEnter -= OnHeaderMouseEnter;
        }
        
        base.OnApplyTemplate();
        
        // 获取新模板的部件
        _headerPart = GetTemplateChild("PART_Header") as Border;
        _contentPart = GetTemplateChild("PART_Content") as ContentPresenter;
        
        // 验证必需部件
        if (_contentPart == null)
        {
            throw new Exception("必需包含PART_Content部件");
        }
        
        // 初始化事件
        if (_headerPart != null)
        {
            _headerPart.MouseEnter += OnHeaderMouseEnter;
        }
    }
    
    protected override void OnContentRendered(EventArgs e)
    {
        base.OnContentRendered(e);
        
        // 执行依赖布局完成的操作
        if (_headerPart != null && _headerPart.ActualHeight > 50)
        {
            // 大标题特殊处理
            _headerPart.Background = Brushes.LightYellow;
        }
        
        // 启动初始动画
        StartEntranceAnimation();
    }
    
    private void StartEntranceAnimation()
    {
        // 动画实现...
    }
}

六、最佳实践建议

1. 主要模板操作：在 OnApplyTemplate 中获取和缓存模板部件
2. 布局相关操作：在 OnContentRendered 中执行依赖尺寸的操作
3. 事件清理：在 OnApplyTemplate 开始时清理之前模板的绑定
4. 性能考虑：避免在 OnContentRendered 中执行耗时操作
5. 异常处理：在 OnApplyTemplate 中验证关键模板部件