FrameworkElement.EffectiveViewportChanged 事件

定義

命名空間:

Windows.UI.Xaml

發生于 FrameworkElement的有效檢視區 變更時。

// Register
event_token EffectiveViewportChanged(TypedEventHandler<FrameworkElement, EffectiveViewportChangedEventArgs const&> const& handler) const;

// Revoke with event_token
void EffectiveViewportChanged(event_token const* cookie) const;

// Revoke with event_revoker
FrameworkElement::EffectiveViewportChanged_revoker EffectiveViewportChanged(auto_revoke_t, TypedEventHandler<FrameworkElement, EffectiveViewportChangedEventArgs const&> const& handler) const;

public event TypedEventHandler<FrameworkElement,EffectiveViewportChangedEventArgs> EffectiveViewportChanged;

function onEffectiveViewportChanged(eventArgs) { /* Your code */ }
frameworkElement.addEventListener("effectiveviewportchanged", onEffectiveViewportChanged);
frameworkElement.removeEventListener("effectiveviewportchanged", onEffectiveViewportChanged);
- or -
frameworkElement.oneffectiveviewportchanged = onEffectiveViewportChanged;

Public Custom Event EffectiveViewportChanged As TypedEventHandler(Of FrameworkElement, EffectiveViewportChangedEventArgs) 

事件類型

TypedEventHandler<FrameworkElement,EffectiveViewportChangedEventArgs>

Windows 需求

裝置系列	Windows 10, version 1809 (已於 10.0.17763.0 引進)
API contract	Windows.Foundation.UniversalApiContract (已於 v7.0 引進)

備註

捲動控制項可讓使用者移動流覽/捲動佔用比 UI 中可用空間更多的內容。 使用者看到的內容部分稱為 檢視區。

EffectiveViewportChanged 事件提供多個資訊片段：

1. 實際 EffectiveViewport
2. MaxViewport的計算
3. BringIntoViewDistanceX和BringIntoViewDistanceY的純量值

EffectiveViewport

EffectiveViewport是所有已知檢視區的交集，其中包含其子樹狀結構中的FrameworkElement。 例如，如果有兩個以上的檢視區 (，另一個ScrollViewer內巢狀的ScrollViewer) 不會重迭，則 EffectiveViewport 是空的Rect。

注意

若要讓架構 知道 捲動控制項的檢視區，控制項先前必須使用 UIElement.RegisterAsScrollPort 方法註冊它。 架構會在判斷有效的檢視區時，使用已註冊專案的 Clip 。

當捲動控制項的檢視區變更時，它必須叫用 其 InvalidateViewport 方法，以通知架構其檢視區已變更，以及接聽有效檢視區的任何子項目都必須收到變更的通知。

EffectiveViewport會在FrameworkElement的座標空間中提供。 不需要使用檢視區Rect執行TransformToVisual。

在包含單一元素的 ScrollViewer 簡單案例中，EffectiveViewportChanged 事件會提供類似 ViewChanged 事件的檢視區更新。 主要差異在於 EffectiveViewportChanged 事件是在配置排列階段 之後 引發。

例如，這個 ...

<ScrollViewer>
    <Grid Height="4000" Width="4000"
          EffectiveViewportChanged="Grid_EffectiveViewportChanged"/>
</ScrollViewer>

...提供類似的檢視區資訊，如下所示...

<ScrollViewer ViewChanged="ScrollViewer_ViewChanged">
    <Grid Height="4000" Width="4000"/>
</ScrollViewer>

MaxViewport

MaxViewport類似于EffectiveViewport，但不是代表已知檢視區的簡單交集，而是代表檢視區的交集，就像每個檢視區都已帶入任何外部檢視區的檢視中一樣。 產生的 Rect 代表兩件事：

1. 如果目前的檢視區大小) ，則 EffectiveViewport 可以 (的大小上限，以及
2. 相對於 FrameworkElement的最大有效檢視區位置。

這項資訊可用來測量 FrameworkElement 在捲動到檢視 區之前 ，應該預先產生多少內容來填入檢視區。

注意

透過直接輸入捲動，例如觸控或手寫筆，是由系統在不同的進程中處理。 根據預設，捲動會以非同步方式處理至 UI 執行緒。 由於元素建立的固有成本，執行虛擬化的控制項可能需要預先產生內容，才能進入檢視區。

延遲所有內容準備，直到進入檢視為止，可能會導致使用者的捲動體驗不佳。 使用者可能會看到空白或雜亂，UI 執行緒的兩個徵兆都無法跟上移動流覽的速度。

MaxViewport的位置會在FrameworkElement的座標空間中報告。 如果 MaxViewport 已轉換成 FrameworkElement上階鏈結中第一個檢視區的座標空間， Rect 會位於該第一個檢視區的界限內。

BringIntoViewDistanceX 和 Y

這些值表示 FrameworkElement 在其所有檢視區中，要以最大方式顯示FrameworkElement。

如果值大於零，但小於ActualWidth / ActualHeight，則元素會部分位於使用者可見檢視區內。 當值為零時， FrameworkElement 會完全在使用者可見的檢視區內。

提示

這不保證使用者可以看到元素，因為具有較高 Z 順序的其他元素仍可能會遮蔽 FrameworkElement。

更正式表示，這些值是當滿足StartBringIntoView呼叫時，FrameworkElement將轉譯的絕對距離總和。 值不會考慮捲動控制項已停用捲動的可能性。

<ListView x:Name="lv">
    <ListView.ItemTemplate>
        <DataTemplate x:DataType="x:String">
            <UserControl Tag="{x:Bind}"
                         EffectiveViewportChanged="Item_EffectiveViewportChanged"/>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

private void Item_EffectiveViewportChanged(FrameworkElement sender, EffectiveViewportChangedEventArgs args)
{
    // If we wanted to know if a list item (w/ vertical scrolling only) is partially within the viewport
    // then we can just check the BringIntoViewDistanceY of the event args.  If the distance is 0 then the item is fully within
    // the effective viewport.  If the BringIntoViewDistanceY is less than the sender's ActualHeight, then its
    // partially within the effective viewport.
    // The EffectiveViewport rect is relative to the sender, so we can use it to know where the element is within the viewport.  
    // NOTE: "Within the viewport" != visible to the user's eye, since another element may overlap and obscure it.
    if (args.BringIntoViewDistanceY < sender.ActualHeight)
    {
        Debug.WriteLine($"Item: {sender.Tag} has {sender.ActualHeight - args.BringIntoViewDistanceY} pixels within the viewport");
    }
    else
    {
        Debug.WriteLine($"Item: {sender.Tag} has {args.BringIntoViewDistanceY - sender.ActualHeight} pixels to go before it is even partially visible");
    }

    // Consider disconnecting from the effective viewport when not needed.  Otherwise, it is called on every viewport change.
    //lv.EffectiveViewportChanged -= Item_EffectiveViewportChanged;
}

行為

• 如果父系和子系的有效檢視區同時變更，父系就會在子系之前收到通知。
• 事件只會針對參與配置之 UI 樹狀結構中的元素引發。 例如，如果專案不在即時樹狀結構中，或是元素的 Visibility 屬性或其任何上階設定為 Collapsed，則不會引發此事件。
• 雖然有效的檢視區會考慮轉譯所有元素上階的轉換，但它不會考慮裁剪 (除了捲動控制項所註冊之元素剪輯以外的效果，做為其檢視區) 。
• 有效的檢視區不會考慮遮蔽，因為其他元素具有較高的 Z 順序。

另請參閱

• UIElement.RegisterAsScrollPort
• FrameworkElement.InvalidateViewport