다음을 통해 공유


바인딩 가능한 속성

.NET 다중 플랫폼 앱 UI(.NET MAUI) 바인딩 가능 속성은 필드가 아닌 형식으로 속성을 백업하여 CLR(공용 언어 런타임) 속성 BindableProperty 기능을 확장합니다. 바인딩 가능한 속성의 목적은 부모-자식 관계를 통해 설정된 데이터 바인딩, 스타일, 템플릿 및 값을 지원하는 속성 시스템을 제공하는 것입니다. 또한 바인딩 가능한 속성은 기본값, 속성 값의 유효성 검사 및 속성 변경 내용을 모니터링하는 콜백을 제공할 수 있습니다.

.NET MAUI 앱에서 속성은 다음 기능 중 하나 이상을 지원하기 위해 바인딩 가능한 속성으로 구현되어야 합니다.

  • 데이터 바인딩에 유효한 대상 속성 역할을 합니다. 대상 속성에 대한 자세한 내용은 기본 바인딩을 참조 하세요.
  • 스타일을 통해 속성을 설정합니다.
  • 속성 형식의 기본값과 다른 기본 속성 값을 제공합니다.
  • 속성 값의 유효성을 검사합니다.
  • 속성 변경 모니터링

.NET MAUI 바인딩 가능 속성의 예로는 Label.Text, Button.BorderRadiusStackLayout.Orientation. 각 바인딩 가능한 속성에는 동일한 클래스에 노출되고 바인딩 가능한 속성의 식별자인 해당 public static readonly 형식 BindableProperty 필드가 있습니다. 예를 들어 속성에 대한 Label.Text 해당 바인딩 가능한 속성 식별자는 .입니다 Label.TextProperty.

바인딩 가능한 속성 만들기

바인딩 가능한 속성을 만드는 프로세스는 다음과 같습니다.

  1. BindableProperty 메서드 오버로드 중 하나를 사용하여 인스턴스를 BindableProperty.Create 만듭니다.
  2. 인스턴스에 대한 속성 접근자를 정의합니다 BindableProperty .

모든 BindableProperty 인스턴스는 UI 스레드에서 만들어야 합니다. 즉, UI 스레드에서 실행되는 코드만 바인딩 가능한 속성의 값을 얻거나 설정할 수 있습니다. 그러나 BindableProperty UI 스레드로 마샬링하여 다른 스레드에서 인스턴스에 액세스할 수 있습니다. 자세한 내용은 UI 스레드에서 코드 실행을 참조 하세요.

속성 만들기

인스턴스를 BindableProperty 만들려면 포함하는 클래스가 클래스에서 BindableObject 파생되어야 합니다. 그러나 BindableObject 클래스 계층 구조에서 클래스가 높으므로 UI 기능에 사용되는 대부분의 클래스는 바인딩 가능한 속성을 지원합니다.

바인딩 가능한 속성은 형식BindableProperty의 속성을 선언하여 public static readonly 만들 수 있습니다. 바인딩 가능한 속성은 메서드 오버로드 중 하나의 반환된 값으로 BindableProperty.Create 설정해야 합니다. 선언은 파생 클래스의 BindableObject 본문 내에 있어야 하지만 멤버 정의 외부에 있어야 합니다.

최소한 다음 매개 변수와 함께 식별자를 만들 BindableProperty때 지정해야 합니다.

  • BindableProperty의 이름입니다.
  • 속성의 형식입니다.
  • 소유 개체의 형식입니다.
  • 속성의 기본값입니다. 이렇게 하면 속성이 설정되지 않은 경우 항상 특정 기본값을 반환하고 속성 형식의 기본값과 다를 수 있습니다. 바인딩 가능한 속성에서 메서드를 ClearValue 호출하면 기본값이 복원됩니다.

Important

바인딩 가능한 속성에 대한 명명 규칙은 바인딩 가능한 속성 식별자가 메서드에 Create 지정된 속성 이름과 일치해야 하며 "Property"가 추가되어야 한다는 것입니다.

다음 코드는 네 개의 필수 매개 변수에 대한 식별자와 값을 사용하여 바인딩 가능한 속성의 예를 보여 봅니다.

public static readonly BindableProperty IsExpandedProperty =
  BindableProperty.Create ("IsExpanded", typeof(bool), typeof(Expander), false);

그러면 형식bool의 이름이 BindableProperty/a0>인 IsExpandedProperty인스턴스가 만들어집니다. 이 속성은 클래스에서 Expander 소유하며 기본값 false은 .입니다.

참고 항목

Expander 는 .NET MAUI 커뮤니티 도구 키트의 컨트롤입니다. 자세한 내용은 Expander를 참조 하세요.

필요에 따라 인스턴스를 BindableProperty 만들 때 다음 매개 변수를 지정할 수 있습니다.

  • 바인딩 모드입니다. 속성 값 변경이 전파되는 방향을 지정하는 데 사용됩니다. 기본 바인딩 모드에서는 변경 내용이 원본에서 대상으로 전파됩니다. 자세한 내용은 기본 바인딩을 참조 하세요.
  • 속성 값이 설정될 때 호출될 유효성 검사 대리자입니다. 자세한 내용은 콜백 유효성 검사를 참조하세요.
  • 속성 값이 변경될 때 호출되는 속성 변경 대리자입니다. 자세한 내용은 속성 변경 내용 검색을 참조 하세요.
  • 속성 값이 변경될 때 호출되는 속성 변경 대리자입니다. 이 대리자는 속성이 변경된 대리자와 동일한 서명을 가합니다.
  • 속성 값이 변경될 때 호출될 강제 변환 값 대리자입니다. 자세한 내용은 값 콜백 강제 변환을 참조 하세요.
  • Func 기본 속성 값을 초기화하는 데 사용되는 A입니다. 자세한 내용은 Func를 사용하여 기본값 만들기를 참조하세요.

접근자 만들기

속성 접근자는 바인딩 가능한 속성에 액세스하기 위해 속성 구문을 사용해야 합니다. 접근자가 Get 해당 바인딩 가능한 속성에 포함된 값을 반환해야 합니다. 메서드를 GetValue 호출하고, 값을 가져올 바인딩 가능한 속성 식별자를 전달한 다음, 결과를 필요한 형식으로 캐스팅하여 이 작업을 수행할 수 있습니다. Set 접근자가 해당 바인딩 가능한 속성의 값을 설정해야 합니다. 이 작업은 메서드를 SetValue 호출하고 값을 설정할 바인딩 가능한 속성 식별자와 설정할 값을 전달하여 수행할 수 있습니다.

다음 코드 예제에서는 바인딩 가능한 속성에 대한 접근자를 IsExpanded 보여 줍니다.

public bool IsExpanded
{
    get => (bool)GetValue(IsExpandedProperty);
    set => SetValue(IsExpandedProperty, value);
}

바인딩 가능한 속성 사용

바인딩 가능한 속성이 만들어지면 XAML 또는 코드에서 사용할 수 있습니다. XAML에서는 접두사를 사용하여 네임스페이스를 선언하고 CLR 네임스페이스 이름을 나타내는 네임스페이스 선언과 어셈블리 이름을 선택적으로 선언합니다. 자세한 내용은 XAML 네임스페이스를 참조 하세요.

다음 코드 예제에서는 바인딩 가능한 속성을 포함하는 사용자 지정 형식에 대한 XAML 네임스페이스를 보여 줍니다. 이 네임스페이스는 사용자 지정 형식을 참조하는 애플리케이션 코드와 동일한 어셈블리 내에 정의됩니다.

<ContentPage ... xmlns:local="clr-namespace:DataBindingDemos" ...>
  ...
</ContentPage>

네임스페이스 선언은 다음 XAML 코드 예제와 같이 바인딩 가능한 속성을 설정할 IsExpanded 때 사용됩니다.

<Expander IsExpanded="true">
    ...
</Expander>

동등한 C# 코드는 다음 코드 예제와 같습니다.

Expander expander = new Expander
{
    IsExpanded = true
};

고급 시나리오

인스턴스를 BindableProperty 만들 때 고급 바인딩 가능한 속성 시나리오를 사용하도록 설정할 수 있는 여러 선택적 매개 변수가 있습니다. 이 섹션에서는 이러한 시나리오를 살펴봅니다.

속성 변경 검색

메서드에 static 대한 BindableProperty.Create 매개 변수를 지정 propertyChanged 하여 속성 변경 콜백 메서드를 바인딩 가능한 속성에 등록할 수 있습니다. 바인딩 가능한 속성의 값이 변경되면 지정된 콜백 메서드가 호출됩니다.

다음 코드 예제에서는 바인딩 가능한 속성 변경 콜백 메서드로 메서드를 등록 OnIsExpandedChanged 하는 방법을 IsExpanded 보여 줍니다.

public static readonly BindableProperty IsExpandedProperty =
    BindableProperty.Create(nameof(IsExpanded), typeof(bool), typeof(Expander), false, propertyChanged: OnIsExpandedChanged);
...

static void OnIsExpandedChanged (BindableObject bindable, object oldValue, object newValue)
{
  // Property changed implementation goes here
}

속성 변경 콜백 메서드 BindableObject 에서 매개 변수는 소유 클래스의 인스턴스가 변경 사항을 보고했음을 나타내는 데 사용되며 두 object 매개 변수의 값은 바인딩 가능한 속성의 이전 값과 새 값을 나타냅니다.

유효성 검사 콜백

메서드에 static 대한 BindableProperty.Create 매개 변수를 지정하여 바인딩 가능한 속성에 유효성 검사 콜백 메서드를 validateValue 등록할 수 있습니다. 바인딩 가능한 속성의 값이 설정되면 지정된 콜백 메서드가 호출됩니다.

다음 코드 예제에서는 바인딩 가능한 속성 유효성 검사 콜백 메서드로 메서드를 등록 IsValidValue 하는 방법을 Angle 보여 줍니다.

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, validateValue: IsValidValue);
...

static bool IsValidValue(BindableObject view, object value)
{
    double result;
    double.TryParse(value.ToString(), out result);
    return (result >= 0 && result <= 360);
}

유효성 검사 콜백은 값과 함께 제공되며 값이 속성에 유효한 경우 반환되어야 합니다. 그렇지 않으면 false반환 true 해야 합니다. 유효성 검사 콜백이 처리해야 하는 반환 false되는 경우 예외가 발생합니다. 유효성 검사 콜백 메서드의 일반적인 사용은 바인딩 가능한 속성이 설정 될 때 정수 또는 double의 값을 제한 합니다. 예를 들어 이 메서드는 IsValidValue double 속성 값이 0~360 범위 내에 있는지 확인합니다.

값 콜백 강제 변환

static 강제 변환 값 콜백 메서드는 메서드에 대한 BindableProperty.Create 매개 변수를 지정하여 coerceValue 바인딩 가능한 속성에 등록할 수 있습니다. 바인딩 가능한 속성의 값이 변경될 때 지정된 콜백 메서드가 호출되므로 새 값이 적용되기 전에 조정할 수 있습니다.

Important

바인딩 가능한 속성 엔진에 의해 트리거되는 것 외에도 코드에서 강제 변환-값 콜백을 호출할 수 있습니다. 형식에는 BindableObject CoerceValue 강제 변환 값 콜백을 호출하여 인수의 값을 BindableProperty 강제로 다시 평가하도록 호출할 수 있는 메서드가 있습니다.

강제 변환 값 콜백은 속성 값이 변경되려고 할 때 바인딩 가능한 속성의 재평가를 강제로 적용하는 데 사용됩니다. 예를 들어 강제 변환 값 콜백을 사용하여 바인딩 가능한 한 속성의 값이 다른 바인딩 가능한 속성의 값보다 크지 않은지 확인할 수 있습니다.

다음 코드 예제에서는 바인딩 가능 속성이 메서드를 CoerceAngle 강제 변환 값 콜백 메서드로 등록하는 방법을 Angle 보여 줍니다.

public static readonly BindableProperty AngleProperty =
    BindableProperty.Create("Angle", typeof(double), typeof(MainPage), 0.0, coerceValue: CoerceAngle);
public static readonly BindableProperty MaximumAngleProperty =
    BindableProperty.Create("MaximumAngle", typeof(double), typeof(MainPage), 360.0, propertyChanged: ForceCoerceValue);
...

static object CoerceAngle(BindableObject bindable, object value)
{
    MainPage page = bindable as MainPage;
    double input = (double)value;

    if (input > page.MaximumAngle)
    {
        input = page.MaximumAngle;
    }

    return input;
}

static void ForceCoerceValue(BindableObject bindable, object oldValue, object newValue)
{
    bindable.CoerceValue(AngleProperty);
}

메서드는 CoerceAngle 속성 값을 MaximumAngle 확인하고 속성 값이 속성 값보다 크면 Angle 해당 값을 속성 값으로 강제 변환 MaximumAngle 합니다. 또한 속성이 MaximumAngle 변경되면 메서드를 호출하여 속성에서 Angle 강제 변환 값 콜백이 CoerceValue 호출됩니다.

Func를 사용하여 기본값 만들기

다음 예제와 같이 바인딩 가능한 속성의 기본값을 초기화하는 데 A Func 를 사용할 수 있습니다.

public static readonly BindableProperty DateProperty =
    BindableProperty.Create ("Date", typeof(DateTime), typeof(MyPage), default(DateTime), BindingMode.TwoWay, defaultValueCreator: bindable => DateTime.Today);

매개 defaultValueCreator 변수는 오늘 날짜를 나타내는 값을 반환 DateTime 하는 매개 변수로 설정 Func 됩니다.