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 1 つの要素で、 属性と Name プロパティは XAML 属性として相互に排他的です。マークアップ内の同じオブジェクト要素に と Name の両方x:Nameを設定しようとすると、パーサー エラーがスローされます。

XAML の既定の ページ ビルド アクションを使用する場合、 x:Name 属性 を持つ XAML 要素、または Name XAML が読み込まれるときに最終的に設定される InitializeComponent フィールド参照を生成する XAML 要素。 フィールド参照を使用すると、XAML オブジェクト ツリーがページまたはアプリに読み込まれると、オブジェクトをページ固有の分離コード内の名前で直接参照できるプログラミング モデルが可能になります。

名前は XAML 名前スコープで一意である必要があります。 一般に、XAML 名前スコープは XAML ページによって定義されますが、テンプレートや XAMLReader.Load などの API の呼び出しなどの特定の機能では、別の XAML 名前スコープを定義できます。 詳しくは、「XAML 名前スコープ」をご覧ください。

Name はローカライズしないでください。 Name は、分離コードのフィールド名変数として使用されます。 このようなコードは通常、UI を定義する XAML ファイルにアクセスできる可能性があるローカライザーにはアクセスできませんが、これはデプロイ モデルとローカライズ手順によって異なります。 これは、アプリ UI で Name から取得された文字列を表示しない理由の 1 つです。

名前のシナリオ

UI 要素を定義する XAML で または Name を設定x:Nameすると、いくつかの主要なシナリオがサポートされます。

  • アニメーションのターゲット設定 オブジェクト プロパティにアニメーションを適用するには、特定のインスタンスをターゲットにする必要があります。 これを行うには、任意のタイムラインで 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 値を持たなかったことは、特定のシナリオに適しています。 このようなシナリオの 1 つは、共通ユーティリティ関数として FindName を使用して、XAML で作成されたオブジェクトまたはコードで作成されたオブジェクトをツリー内で検索できるようにする場合です。 そのシナリオを機能させるために、Windows ランタイムは実行時に XAML 名前スコープハッシュテーブル表現を引き続き使用して追加します。 既存の主に XAML で作成されたオブジェクト ツリーに新しい名前付きオブジェクトを追加しようとすると、名前が一意である必要があります。それ以外の場合は、重複する名前の例外が発生します。 を設定 Nameしようとすると、重複する名前の例外が発生しない可能性があります。 重複する名前付きオブジェクトを メイン オブジェクト ツリーに追加するまで、新しいオブジェクトには独自の自己完結型 XAML 名前スコープがあります。 重複する名前の条件を検出できるのは、オブジェクトを大きなオブジェクト ツリーに接続した時点だけです。 または、ツリー内のオブジェクトを接続した操作 (たとえば、メイン オブジェクト ツリーに接続するコレクションの メソッドのAdd呼び出し) で例外が発生する可能性があります。

後で新しいオブジェクトを追加する XAML 名前スコープに既に存在する Name 値を知りにくい場合があります。 XAML 名前スコープ内の既存の名前の完全なハッシュテーブルを報告する特定の API はありません。 コードで Name 値を広範囲に設定する場合は、実行時の使用に固有の名前文字列を生成する手法が必要な場合や、新しい名前付きオブジェクトを try-catch ブロックに追加する呼び出しをラップして、重複する名前から発生する可能性のある例外をキャッチする必要がある場合があります。 または、XAML で生成された名前の値を InitializeComponent 読み取る実装に独自のコードを追加することもできます。

実行時に設定 Name できるのは、 FrameworkElement または Inline オブジェクトのみです。 オブジェクトに プロパティがなくName、XAML で名前を設定する場合は、 ではなく Name属性をx:Name使用する必要があります。このようなオブジェクトの実行時名を設定するために使用できるランタイム API はありません。

適用対象

こちらもご覧ください