FrameworkElement.Name 속성

  • 참조

정의

네임스페이스:
Microsoft.UI.Xaml
편집

개체의 식별 이름을 가져오거나 설정합니다. XAML 프로세서가 XAML 태그에서 개체 트리를 만드는 경우 런타임 코드는 이 이름으로 XAML 선언 개체를 참조할 수 있습니다.

public:
 property Platform::String ^ Name { Platform::String ^ get(); void set(Platform::String ^ value); };
winrt::hstring Name();

void Name(winrt::hstring value);
public string Name { get; set; }
var string = frameworkElement.name;
frameworkElement.name = string;
Public Property Name As String
<frameworkElement Name="xamlNameString"/>

속성 값

String

Platform::String

winrt::hstring

XamlName 문법에서 유효한 문자열이어야 하는 개체의 이름입니다( x:Name 특성 참조의 표 참조). 기본값은 빈 문자열입니다.

예제

이 예제에서는 기존 개체에서 에 대한 Name 값을 가져오고 해당 이름을 사용하여 애니메이션의 대상을 다시 지정합니다. Storyboard.TargetName 연결된 속성을 설정하여 애니메이션을 대상으로 지정합니다.

private void Start_Animation(object sender, PointerRoutedEventArgs e)
{

    // If the Storyboard is running and you try to change
    // properties of its animation objects programmatically, 
    // an error will occur.
    myStoryboard.Stop();

    // Get a reference to the rectangle that was clicked.
    Rectangle myRect = (Rectangle)sender;

    // Change the TargetName of the animation to the name of the
    // rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name);

    // Begin the animation.
    myStoryboard.Begin();
}

설명

이 속성의 가장 일반적인 사용법은 XAML 태그에서 개체에 대한 x:Name 특성을 지정하거나 태그에 설정된 대로 해당 값을 읽는 것입니다. 대부분의 경우 x:Name 특성과 속성은 Name 동일합니다. 모든 단일 요소에서 x:Name 특성과 Name 속성은 XAML 특성으로 상호 배타적입니다. 태그에서 동일한 개체 요소에서 및 Name 를 모두 x:Name 설정하려고 하면 파서 오류가 throw됩니다.

XAML에 대한 기본 페이지 빌드 작업을 사용하는 경우 x:Name 특성 이 있거나 Name XAML이 로드될 InitializeComponent 때 결국 채워지는 필드 참조를 생성하는 모든 XAML 요소입니다. 필드 참조를 사용하면 XAML 개체 트리가 페이지 또는 앱에 로드되면 페이지별 코드 숨김에서 이름으로 개체를 직접 참조할 수 있는 프로그래밍 모델을 사용할 수 있습니다.

이름은 XAML 이름 범위에서 고유해야 합니다. 일반적으로 XAML 이름 범위는 XAML 페이지에서 정의되지만 템플릿 또는 XamlReader.Load 와 같은 API 호출과 같은 특정 기능은 별도의 XAML 이름 범위를 정의할 수 있습니다. 자세한 내용은 XAML 이름 범위를 참조하세요.

Name 는 지역화되지 않아야 합니다. Name 는 코드 숨김에서 필드 이름 변수로 사용됩니다. 이러한 코드는 일반적으로 배포 모델 및 지역화 절차에 따라 달라지지만 UI를 정의하는 XAML 파일에 액세스할 수 있는 지역화자에 액세스할 수 없습니다. 이는 앱 UI의 이름에서 제공되는 문자열을 표시하지 않아야 하는 이유 중 하나입니다.

이름 시나리오

UI 요소를 정의하는 XAML에서 또는 Name 를 설정 x:Name 하면 다음과 같은 몇 가지 주요 시나리오가 지원됩니다.

  • 애니메이션 대상 지정 개체 속성에 애니메이션을 적용하려면 특정 instance 대상으로 지정해야 합니다. 모든 타임라인에서 Storyboard.TargetName 연결된 속성을 설정하여 이 작업을 수행 합니다. 여기서 설정한 값은 또는 Name로 x:Name 할당한 문자열입니다. 자세한 내용은 스토리보드 애니메이션을 참조하세요.
  • 컨트롤 템플릿의 일부 시각적 상태 모델을 지원하고 초기화를 제어하려면 컨트롤 작성자가 템플릿화된 컨트롤의 핵심 부분에 대한 값을 지정 Name 해야 합니다. 자세한 내용은 XAML 컨트롤 템플릿을 참조하세요.
  • 일반 런타임 상호 작용 예를 들어 이벤트 처리기 내의 코드는 변경 UI를 제공하는 개체의 이벤트를 처리할 수 있지만 속성 변경은 근처의 다른 UI 요소에서 발생합니다. 이 상황에 대한 코드를 작성하는 가장 쉬운 방법은 에서 생성된 필드 참조를 사용하는 것입니다 Name.

FindName

모든 FrameworkElement에서 사용할 수 있는 유틸리티 메서드 FindName은 현재 XAML 이름 범위에 있는 한 개체 트리에서 이름으로 개체를 찾을 수 있습니다. FindName 는 XAML에서 만든 개체 트리 전체를 검색합니다. 기술적으로 실제로 검색하는 것은 FindName 트리 은유를 보존하지 않고 대신 이름의 해시 테이블로 표현되는 XAML 이름 범위입니다. FindName 적용된 템플릿에 정의된 이름을 찾을 수 없습니다. 적용된 템플릿에서 항목을 찾으려면 VisualTreeHelper.GetChild 를 사용하여 적용된 템플릿 루트 개체를 가져옵니다. 그런 다음 해당 루트 개체에서 를 호출 FindName 할 수 있으며, 더 큰 페이지가 아닌 템플릿의 XAML 이름 범위를 검색합니다.

이름 및 데이터 바인딩

의 문자열 값을 Name 데이터 바인딩 원본의 직접 원본 값으로 사용할 수 없습니다. 바인딩을 사용하여 UI에서와 Name 동일한 문자열 값을 표시해야 하는 경우 속성 바인딩 원본으로 사용할 수 있는 Tag 속성에 동일한 값을 복제해야 합니다. 바인딩 대상으로도 사용하지 Name 마세요.

또는 Name 값 x:Name 은 ElementName 바인딩의 원본 요소를 식별하는 데 사용하는 식별자입니다. 자세한 내용은 데이터 바인딩을 자세히 참조하세요.

코드에서 이름 설정

런타임에 개체의 Name 값을 설정할 수 있지만 알아야 할 몇 가지 중요한 고려 사항과 제한 사항이 있습니다.

개체에 XAML에 설정된 이전 Name 값 Name 이 있는 경우 런타임에 코드의 값을 변경하는 것은 일반적으로 권장되지 않습니다. 이는 개체 트리가 로드된 후 이름을 설정해도 해당하는 필드 참조의 식별 이름을 만들거나 변경하지 않기 때문입니다. 가 초기 태그에 제공되었기 때문에 x:Name 필드 참조가 이미 있고 값을 변경 Name하면 필드가 태그 정의 이름으로 유지되기 때문에 FindName 을 통해 개체를 찾는 데 사용해야 하는 필드와 이름이 다릅니다.

Name 코드에서 생성되었으므로 XAML 정의 Name 값이 없는 개체의 값을 설정하는 것은 특정 시나리오에 적합합니다. 이러한 시나리오 중 하나는 FindName 을 공통 유틸리티 함수로 사용하여 트리에서 XAML에서 만든 개체 또는 코드로 만든 개체를 찾으려는 경우입니다. 이 시나리오가 작동하도록 하기 위해 Windows 런타임 런타임에 XAML 이름 범위 해시 테이블 표현을 계속 사용하고 추가합니다. 기존 XAML에서 만든 개체 트리에 새 명명된 개체를 추가하려는 경우 이름은 고유해야 합니다. 그렇지 않으면 중복 이름 예외가 발생합니다. 를 설정 Name하려고 할 때 중복 이름 예외가 발생하지 않을 수 있습니다. 기본 개체 트리에 중복 명명된 개체를 추가하려고 시도할 때까지 새 개체에는 자체 포함된 XAML 이름 범위가 있습니다. 개체를 더 큰 개체 트리에 연결하는 순간에만 중복 이름 조건을 검색할 수 있습니다. 또는 트리에서 개체를 연결하는 작업(예: 기본 개체 트리에 연결하는 컬렉션의 메서드 호출)에서 Add 예외가 발생할 수 있습니다.

나중에 새 개체를 추가할 XAML 이름 범위에 이미 있는 Name 값을 알기 어려울 수 있습니다. XAML 이름 범위에서 기존 이름의 전체 해시 테이블을 보고하는 특정 API는 없습니다. 코드에서 이름 값을 광범위하게 설정하는 경우 런타임 사용량에 고유한 이름 문자열을 생성하는 기술이 필요하거나, 중복된 이름으로 인해 발생할 수 있는 예외를 catch하기 위해 try-catch 블록에 새로 명명된 개체를 추가하는 호출을 래핑해야 할 수 있습니다. 또는 XAML에서 생성된 이름 값을 읽는 구현에 사용자 고유의 코드를 InitializeComponent 추가할 수 있습니다.

FrameworkElement 또는 인라인 개체에 대해서만 런타임에 설정할 Name 수 있습니다. 개체에 속성이 Name 없고 XAML에서 이름을 설정하려면 가 아닌 Name특성을 사용해야 x:Name 하는 경우 이러한 개체의 런타임 이름을 설정하는 데 사용할 수 있는 런타임 API가 없습니다.

적용 대상

추가 정보