BindingGroup 類別

參考

定義

命名空間:: System.Windows.Data

組件:: PresentationFramework.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

包含用來驗證物件的系結和 ValidationRule 物件集合。

public ref class BindingGroup : System::Windows::DependencyObject

public class BindingGroup : System.Windows.DependencyObject

type BindingGroup = class
    inherit DependencyObject

Public Class BindingGroup
Inherits DependencyObject

繼承: Object

DispatcherObject

DependencyObject
BindingGroup

範例

下列範例會建立應用程式，提示使用者輸入專案的描述和價格，以及供應專案到期日期。應用程式會顯示表單下方專案的目前資訊。用戶可以提交或取消變更。

應用程式會執行下列動作來達成此行為。

建立 BindingGroup，並在建立應用程式的使用者介面（UI）時，將根 StackPanel 新增。
呼叫應用程式邏輯中的 BeginEdit、CommitEdit和 CancelEdit，以啟用回復變更。
在 Validate 方法中呼叫 TryGetValue，以取得使用者的輸入，然後確認至少 7 天內有超過 100 美元的專案可供使用。

下列範例會建立應用程式的使用者介面（UI）。根 StackPanel 具有 BindingGroup，其中包含驗證專案的 ValidationRule，如先前所述。 Price 屬性和 OfferExpires 屬性上的系結物件會成為 BindingGroup 的一部分，而且每個系結都有 ValidationRule，以確保價格和日期分別是有效的值。個別屬性的驗證規則會在 BindingGroup上的 ValidationRule 之前執行。

<StackPanel Name="stackPanel1"  Margin="10" Width="250"
            Loaded="stackPanel1_Loaded"
            Validation.Error="ItemError">

  <StackPanel.Resources>
    <Style TargetType="HeaderedContentControl">
      <Setter Property="Margin" Value="2"/>
      <Setter Property="Focusable" Value="False"/>
      <Setter Property="Template">
        <Setter.Value>
          <ControlTemplate TargetType="HeaderedContentControl">
            <DockPanel LastChildFill="False">
              <ContentPresenter ContentSource="Header" DockPanel.Dock="Left" Focusable="False" VerticalAlignment="Center"/>
              <ContentPresenter ContentSource="Content" Margin="5,0,0,0" DockPanel.Dock="Right" VerticalAlignment="Center"/>
            </DockPanel>

          </ControlTemplate>
        </Setter.Value>
      </Setter>
    </Style>

    <Style TargetType="Button">
      <Setter Property="Width" Value="100"/>
      <Setter Property="Margin" Value="10,15,15,15"/>

    </Style>

  </StackPanel.Resources>
  
  <StackPanel.BindingGroup>
    <BindingGroup NotifyOnValidationError="True">
      <BindingGroup.ValidationRules>
        <src:ValidateDateAndPrice ValidationStep="ConvertedProposedValue" />
      </BindingGroup.ValidationRules>
    </BindingGroup>
  </StackPanel.BindingGroup>
  
  <TextBlock FontSize="14" Text="Enter an item for sale"/>
  <HeaderedContentControl Header="Description">
    <TextBox Width="150" Text="{Binding Path=Description, Mode=TwoWay}"/>
  </HeaderedContentControl>
  <HeaderedContentControl Header="Price">
    <TextBox Name="priceField"  Width="150">
      <TextBox.Text>
        <Binding Path="Price" Mode="TwoWay" >
          <Binding.ValidationRules>
            <src:PriceIsAPositiveNumber/>
          </Binding.ValidationRules>
        </Binding>
      </TextBox.Text>
    </TextBox>
  </HeaderedContentControl>
  <HeaderedContentControl Header="Date Offer Ends">
    <TextBox Name="dateField" Width="150" >
      <TextBox.Text>
        <Binding Path="OfferExpires" StringFormat="d" >
          <Binding.ValidationRules>
            <src:FutureDateRule/>
          </Binding.ValidationRules>
        </Binding>
      </TextBox.Text>
    </TextBox>
  </HeaderedContentControl>
  <StackPanel Orientation="Horizontal">
    <Button IsDefault="True" Click="Submit_Click">_Submit</Button>
    <Button IsCancel="True" Click="Cancel_Click">_Cancel</Button>
  </StackPanel>
  <HeaderedContentControl Header="Description">
    <TextBlock Width="150" Text="{Binding Path=Description}"/>
  </HeaderedContentControl>
  <HeaderedContentControl Header="Price">
    <TextBlock Width="150" Text="{Binding Path=Price, StringFormat=c}"/>
  </HeaderedContentControl>
  <HeaderedContentControl Header="Date Offer Ends">
    <TextBlock Width="150" Text="{Binding Path=OfferExpires, StringFormat=d}"/>
  </HeaderedContentControl>
</StackPanel>

下列範例顯示應用程式的事件處理程式。當使用者按兩下 [提交] 按鈕時，應用程式會呼叫 CommitEdit，以執行與 BindingGroup相關聯的每個 ValidationRule。如果每個 ValidationRule 成功，CommitEdit 會將值儲存至物件，並結束編輯交易。如果 CommitEdit 成功，應用程式會開始另一個編輯交易。當 ValidationRule 失敗時，會發生 Validation.Error 事件，因為應用程式會將 NotifyOnValidationError 設定為 BindingGroup 上的 true（在上一個範例中）。 ItemError 處理 Validation.Error 事件，並向使用者顯示驗證錯誤的相關信息。此範例也會處理的事件，以及 [取消] 按鈕事件。


private void Submit_Click(object sender, RoutedEventArgs e)
{
    if (stackPanel1.BindingGroup.CommitEdit())
    {
        MessageBox.Show("Item submitted");
        stackPanel1.BindingGroup.BeginEdit();
    }
}

// This event occurs when a ValidationRule in the BindingGroup
// or in a Binding fails.
private void ItemError(object sender, ValidationErrorEventArgs e)
{
    if (e.Action == ValidationErrorEventAction.Added)
    {
        MessageBox.Show(e.Error.ErrorContent.ToString());
    }
}

void stackPanel1_Loaded(object sender, RoutedEventArgs e)
{
    // Set the DataContext to a PurchaseItem object.
    // The BindingGroup and Binding objects use this as
    // the source.
    stackPanel1.DataContext = new PurchaseItem();

    // Begin an edit transaction that enables
    // the object to accept or roll back changes.
    stackPanel1.BindingGroup.BeginEdit();
}

private void Cancel_Click(object sender, RoutedEventArgs e)
{
    // Cancel the pending changes and begin a new edit transaction.
    stackPanel1.BindingGroup.CancelEdit();
    stackPanel1.BindingGroup.BeginEdit();
}


Private Sub Submit_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
    If stackPanel1.BindingGroup.CommitEdit() Then
        MessageBox.Show("Item submitted")
        stackPanel1.BindingGroup.BeginEdit()
    End If


End Sub

' This event occurs when a ValidationRule in the BindingGroup
' or in a Binding fails.
Private Sub ItemError(ByVal sender As Object, ByVal e As ValidationErrorEventArgs)
    If e.Action = ValidationErrorEventAction.Added Then
        MessageBox.Show(e.Error.ErrorContent.ToString())

    End If
End Sub

Private Sub stackPanel1_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
    ' Set the DataContext to a PurchaseItem object.
    ' The BindingGroup and Binding objects use this as
    ' the source.
    stackPanel1.DataContext = New PurchaseItem()

    ' Begin an edit transaction that enables
    ' the object to accept or roll back changes.
    stackPanel1.BindingGroup.BeginEdit()
End Sub

Private Sub Cancel_Click(ByVal sender As Object, ByVal e As RoutedEventArgs)
    ' Cancel the pending changes and begin a new edit transaction.
    stackPanel1.BindingGroup.CancelEdit()
    stackPanel1.BindingGroup.BeginEdit()
End Sub

下列範例顯示第一個範例中新增至 BindingGroup 的自定義 ValidationRuleValidateDateAndPrice。 ValidationRule 會使用其 Validate 方法中的 BindingGroup 來取得使用者輸入表單的值，並檢查專案是否超過 100 美元，它至少可以使用七天。

public class ValidateDateAndPrice : ValidationRule
{
    // Ensure that an item over $100 is available for at least 7 days.
    public override ValidationResult Validate(object value, CultureInfo cultureInfo)
    {
        BindingGroup bg = value as BindingGroup;

        // Get the source object.
        PurchaseItem item = bg.Items[0] as PurchaseItem;
        
        object doubleValue;
        object dateTimeValue;

        // Get the proposed values for Price and OfferExpires.
        bool priceResult = bg.TryGetValue(item, "Price", out doubleValue);
        bool dateResult = bg.TryGetValue(item, "OfferExpires", out dateTimeValue);

        if (!priceResult || !dateResult)
        {
            return new ValidationResult(false, "Properties not found");
        }

        double price = (double)doubleValue;
        DateTime offerExpires = (DateTime)dateTimeValue;

        // Check that an item over $100 is available for at least 7 days.
        if (price > 100)
        {
            if (offerExpires < DateTime.Today + new TimeSpan(7, 0, 0, 0))
            {
                return new ValidationResult(false, "Items over $100 must be available for at least 7 days.");
            }
        }

        return ValidationResult.ValidResult;
    }
}

Public Class ValidateDateAndPrice
    Inherits ValidationRule
    ' Ensure that an item over $100 is available for at least 7 days.
    Public Overrides Function Validate(ByVal value As Object, ByVal cultureInfo As CultureInfo) As ValidationResult
        Dim bg As BindingGroup = TryCast(value, BindingGroup)

        ' Get the source object.
        Dim item As PurchaseItem = TryCast(bg.Items(0), PurchaseItem)

        Dim doubleValue As Object = Nothing
        Dim dateTimeValue As Object = Nothing

        ' Get the proposed values for Price and OfferExpires.
        Dim priceResult As Boolean = bg.TryGetValue(item, "Price", doubleValue)
        Dim dateResult As Boolean = bg.TryGetValue(item, "OfferExpires", dateTimeValue)

        If (Not priceResult) OrElse (Not dateResult) Then
            Return New ValidationResult(False, "Properties not found")
        End If

        Dim price As Double = CDbl(doubleValue)
        Dim offerExpires As Date = CDate(dateTimeValue)

        ' Check that an item over $100 is available for at least 7 days.
        If price > 100 Then
            If offerExpires < Date.Today + New TimeSpan(7, 0, 0, 0) Then
                Return New ValidationResult(False, "Items over $100 must be available for at least 7 days.")
            End If
        End If

        Return ValidationResult.ValidResult

    End Function
End Class

備註

BindingGroup 會建立多個系結之間的關聯性，這些系結可以一起驗證和更新。例如，假設應用程式提示使用者輸入位址。然後，應用程式會填入類型為 Address的物件，其屬性 Street、City、ZipCode和 Country，以及使用者所提供的值。應用程式有一個面板，其中包含四個 TextBox 控件，每個控件都是系結至其中一個物件屬性的數據。您可以使用 BindingGroup 中的 ValidationRule 來驗證 Address 物件。如果系結參與相同的 BindingGroup，您可以確定郵遞區編碼對位址的國家/地區有效。

您可以在 FrameworkElement 或 FrameworkContentElement上設定 BindingGroup 屬性。子專案會從其父元素繼承 BindingGroup，就像任何其他可繼承的屬性一樣。如果發生下列其中一種情況，子代元素上的系結會新增至 BindingGroup：

系結的來源和具有 BindingGroup 之專案的 DataContext 是相同的物件，而且未設定 BindingGroupName 屬性。
系結的 BindingGroupName 屬性等於 BindingGroup 的 Name，而且不會明確設定為 null。

在位址的範例中，假設 Panel 的 DataContext 設定為類型 Address的物件。每個 TextBox 的系結都會新增至面板的 BindingGroup。

您可以將 ValidationRule 物件新增至 BindingGroup。當 ValidationRule 執行時，BindingGroup 會當做 Validate 方法的第一個參數傳遞。您可以在該 BindingGroup 上使用 TryGetValue 或 GetValue(Object, String) 方法來取得對象的建議值，以及取得系結來源的 Items 屬性。

BindingGroup 會同時更新系結的來源，而不是個別更新每個系結。當您呼叫其中一個方法來驗證數據時（ValidateWithoutUpdate、UpdateSources或 CommitEdit），範例中每個 TextBox 的系結都會經過驗證並可能更新。當系結是 BindingGroup的一部分時，除非明確設定 UpdateSourceTrigger 屬性，否則系結的來源不會更新，除非您在 BindingGroup上呼叫 UpdateSources 或 CommitEdit。

建構函式

BindingGroup()

初始化 BindingGroup 類別的新實例。

屬性

BindingExpressions	取得 BindingExpression 物件的集合，其中包含 BindingGroup中每個 Binding 的資訊。
CanRestoreValues	取得系結中的每個來源是否可以捨棄暫止的變更，並還原原始值。
DependencyObjectType	取得包裝這個實例 CLR 類型的 DependencyObjectType。 (繼承來源 DependencyObject)
Dispatcher	取得與這個 DispatcherObject 相關聯的 Dispatcher。 (繼承來源 DispatcherObject)
HasValidationError	取得值，這個值表示 BindingGroup 是否有失敗的驗證規則。
IsDirty	取得或設定值，這個值表示 BindingGroup 是否包含尚未寫入來源的建議值。
IsSealed	取得值，這個值表示這個實例目前是否為密封狀態（只讀）。 (繼承來源 DependencyObject)
Items	取得 BindingGroup中 Binding 物件所使用的來源。
Name	取得或設定識別 BindingGroup的名稱，這個名稱可用來在 BindingGroup中包含和排除 Binding 物件。
NotifyOnValidationError	取得或設定當 ValidationRule 的狀態變更時，是否發生 Error 事件。
Owner	取得這個 BindingGroup 指派的物件。
SharesProposedValues	取得或設定值，這個值表示 BindingGroup 是否重複使用尚未認可至來源的目標值。
ValidatesOnNotifyDataError	取得或設定值，這個值表示是否要包含 NotifyDataErrorValidationRule。
ValidationErrors	取得導致 BindingGroup 無效之 ValidationError 物件的集合。
ValidationRules	取得 ValidationRule 物件的集合，這些物件會驗證 BindingGroup中的來源物件。

方法

BeginEdit()	開始 BindingGroup中來源的編輯交易。
CancelEdit()	結束編輯交易，並捨棄暫止的變更。
CheckAccess()	判斷呼叫端線程是否可存取此 DispatcherObject。 (繼承來源 DispatcherObject)
ClearValue(DependencyProperty)	清除屬性的本機值。要清除的屬性是由 DependencyProperty 識別碼所指定。 (繼承來源 DependencyObject)
ClearValue(DependencyPropertyKey)	清除唯讀屬性的本機值。要清除的屬性是由 DependencyPropertyKey指定。 (繼承來源 DependencyObject)
CoerceValue(DependencyProperty)	強制指定相依性屬性的值。這可藉由叫用在相依性屬性的屬性元數據中指定的任何 CoerceValueCallback 函式來完成，因為它存在於呼叫 DependencyObject上。 (繼承來源 DependencyObject)
CommitEdit()	執行所有 ValidationRule 物件，並在所有驗證規則都成功時更新系結來源。
Equals(Object)	判斷提供的 DependencyObject 是否相當於目前的 DependencyObject。 (繼承來源 DependencyObject)
GetHashCode()	取得這個 DependencyObject的哈希碼。 (繼承來源 DependencyObject)
GetLocalValueEnumerator()	建立特製化列舉值，以判斷哪些相依性屬性在此 DependencyObject上設定值。 (繼承來源 DependencyObject)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
GetValue(DependencyProperty)	傳回 DependencyObject這個實例上相依性屬性的目前有效值。 (繼承來源 DependencyObject)
GetValue(Object, String)	傳回指定之屬性和項目的建議值。
InvalidateProperty(DependencyProperty)	重新評估指定相依性屬性的有效值。 (繼承來源 DependencyObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
OnPropertyChanged(DependencyPropertyChangedEventArgs)	每當更新此 DependencyObject 上任何相依性屬性的有效值時叫用。變更的特定相依性屬性會在事件數據中報告。 (繼承來源 DependencyObject)
ReadLocalValue(DependencyProperty)	如果相依性屬性存在，則傳回本機值。 (繼承來源 DependencyObject)
SetCurrentValue(DependencyProperty, Object)	設定相依性屬性的值，而不變更其值來源。 (繼承來源 DependencyObject)
SetValue(DependencyProperty, Object)	設定相依性屬性的本機值，其相依性屬性標識符所指定。 (繼承來源 DependencyObject)
SetValue(DependencyPropertyKey, Object)	設定只讀相依性屬性的本機值，由相依性屬性 DependencyPropertyKey 標識碼所指定。 (繼承來源 DependencyObject)
ShouldSerializeProperty(DependencyProperty)	傳回值，這個值表示串行化進程是否應該串行化所提供相依性屬性的值。 (繼承來源 DependencyObject)
ToString()	傳回表示目前物件的字串。 (繼承來源 Object)
TryGetValue(Object, String, Object)	嘗試取得指定屬性和項目的建議值。
UpdateSources()	在系結和 ValidationRule 對象上執行轉換子，其中 ValidationStep 屬性設定為 RawProposedValue、ConvertedProposedValue或 UpdatedValue，並在所有驗證規則成功時，將目標的值儲存至來源物件。
ValidateWithoutUpdate()	在系結上執行轉換器，以及將 ValidationStep 屬性設定為 RawProposedValue 或 ConvertedProposedValue的 ValidationRule 物件。
VerifyAccess()	強制呼叫線程可以存取此 DispatcherObject。 (繼承來源 DispatcherObject)

適用於

共用方式為

BindingGroup 類別

定義

範例

備註

建構函式

屬性

方法

適用於

其他資源