FrameworkElement.Name プロパティ
定義
重要
一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。
オブジェクトの識別名を取得または設定します。 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"/>
プロパティ値
オブジェクトの名前。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();
}
Private Sub Start_Animation(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
' 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.
Dim myRect As Rectangle = CType(sender, Rectangle)
' 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()
End Sub
注釈
このプロパティの最も一般的な使用方法は、XAML マークアップでオブジェクトの x:Name 属性 を指定するか、マークアップで設定された値を読み取る方法です。 ほとんどの場合、 x:Name 属性と Name プロパティは同等です。 任意の 1 つの要素で、 x:Name 属性と Name プロパティは XAML 属性として相互に排他的です。マークアップ内の同じオブジェクト要素に x:Name と Name の両方を設定しようとすると、パーサー エラーがスローされます。
XAML の既定の ページ ビルド アクションを使用すると、 x:Name 属性 または Name を持つ XAML 要素は、XAML の読み込み時に InitializeComponent によって最終的に設定されるフィールド参照を生成します。 フィールド参照を使用すると、XAML オブジェクト ツリーがページまたはアプリに読み込まれると、ページ固有の分離コード内の名前でオブジェクトを直接参照できるプログラミング モデルが可能になります。
名前は XAML 名前スコープで一意である必要があります。 一般に、XAML 名前スコープは XAML ページによって定義されますが、テンプレートや XamlReader.Load などの API の呼び出しなどの特定の機能では、別の XAML 名前スコープを定義できます。 詳しくは、「XAML 名前スコープ」をご覧ください。
名前をローカライズしないでください。 Name は、分離コードのフィールド名変数として使用されます。 このようなコードは通常、UI を定義する XAML ファイルにアクセスできる可能性があるローカライザーにはアクセスできませんが、これはデプロイ モデルとローカライズ手順によって異なります。 これは、アプリ UI で Name から取得した文字列を表示しない理由の 1 つです。
名前のシナリオ
UI 要素を定義する XAML で x:Name または Name を設定すると、いくつかの主要なシナリオがサポートされます。+ アニメーションターゲット オブジェクト プロパティにアニメーションを適用するには、特定のインスタンスをターゲットにする必要があります。 これを行うには、任意のタイムラインで Storyboard.TargetName 添付プロパティを設定します。 ここで設定する値は、 x:Name または Name として割り当てた文字列です。 詳しくは、「ストーリーボードに設定されたアニメーション」をご覧ください。
- コントロール テンプレートのパーツ ビジュアル状態モデルとコントロールの初期化をサポートするには、コントロール作成者は、テンプレート化されたコントロールの主要な部分に 名前 の値を指定する必要があります。 詳細については、「 クイック スタート: コントロール テンプレート」を参照してください。
- 一般的な実行時の対話 たとえば、イベント ハンドラー内のコードでは、変更 UI を提供するオブジェクトのイベントを処理できますが、プロパティの変更は、近くの別の UI 要素で行われます。 この状況のコードを記述する最も簡単な方法は、Name から生成されたフィールド参照を使用 することです。
FindName
任意の FrameworkElement から使用できるユーティリティ メソッド FindName は、現在の XAML 名前スコープ内にある限り、オブジェクト ツリー内の名前でオブジェクトを検索できます。 FindName は、XAML で作成されたオブジェクト ツリー全体を検索します。 技術的には、 FindName が実際に検索しているのは、ツリーメタファーを保持せず、代わりに名前のハッシュ テーブルとして表される XAML 名前スコープです。 FindName は、適用されたテンプレートで定義されている名前を見つけることができません。 適用されたテンプレート内の項目を検索するには、 VisualTreeHelper.GetChild を 使用して、適用されたテンプレート ルート オブジェクトを取得します。 その後、そのルート オブジェクトで FindName を 呼び出すと、大きなページではなく、テンプレートの XAML 名前スコープを検索します。
名前とデータ バインディング
Name の文字列値をデータ バインディング ソースの直接ソース値として使用することはできません。 バインドを使用して UI の Name と同じ文字列値を表示する必要がある場合は、同じ値を Tag プロパティにレプリケートする必要があります。これは、プロパティ バインド ソースとして使用できます。 また、バインド ターゲットとして Name を使用しないでください。
x:Name または Name の値は、ElementName バインドのソース要素を識別するために使用する識別子です。 詳細については、「 データ バインディングの詳細」を参照してください。
コード内の名前の設定
実行時にオブジェクトの Name の値を設定できますが、注意すべき重要な考慮事項と制限事項がいくつかあります。
オブジェクトに XAML で以前の Name 値が設定されている場合、実行時にコード内の Name の 値を変更することは一般に推奨されません。 これは、オブジェクト ツリーの読み込み後に名前を設定しても、同等のフィールド参照の識別名が作成または変更されないためです。 最初のマークアップに x:Name が指定されているためにフィールド参照が既に存在し、 Name の値を変更すると、フィールドがマークアップ定義名のままであるため、 FindName を使用してオブジェクトを検索するために使用する必要があるフィールドと名前が異なります。
コードで作成され、XAML 定義の Name 値を持たなかったオブジェクトの Name 値を設定することは、特定のシナリオに適しています。 このようなシナリオの 1 つは、共通ユーティリティ関数として FindName を使用して、XAML で作成されたオブジェクトまたはコードで作成されたオブジェクトをツリー内で検索できるようにする場合です。 そのシナリオを機能させるために、Windows ランタイムは実行時に XAML 名前スコープハッシュテーブル表現を引き続き使用して追加します。 既存の主に XAML で作成されたオブジェクト ツリーに新しい名前付きオブジェクトを追加する場合は、名前が一意である必要があります。そうしないと、重複する名前の例外が発生します。 Name を設定しようとすると、重複する名前の例外が発生しない可能性があります。 重複する名前付きオブジェクトを メイン オブジェクト ツリーに追加するまで、新しいオブジェクトには独自の自己完結型 XAML 名前スコープがあります。 重複する名前の条件を検出できるのは、オブジェクトを大きなオブジェクト ツリーに接続した時点だけです。 または、ツリー内のオブジェクトを接続した操作 (たとえば、メイン オブジェクト ツリーに接続するコレクションの Add メソッドの呼び出し) で例外が発生する可能性があります。
後で新しいオブジェクトを追加する XAML 名前スコープに既に存在する Name 値を知りにくい場合があります。 XAML 名前スコープ内の既存の名前の完全なハッシュテーブルを報告する特定の API はありません。 コードで名前の値を広範囲に設定する場合は、実行時の使用状況に固有の名前文字列を生成する手法が必要な場合や、新しい名前付きオブジェクトを try-catch ブロックに追加する呼び出しをラップして、重複する名前から発生する可能性のある例外をキャッチする必要がある場合があります。 または、XAML で生成された名前値を読み取る InitializeComponent 実装に独自のコードを追加することもできます。
Name は、 実行時に FrameworkElement または Inline オブジェクトに対してのみ設定できることに注意してください。 オブジェクトに Name プロパティがなく、XAML で名前を設定する必要がある場合は、Name ではなく x:Name 属性を使用する必要があります。このようなオブジェクトの実行時名を設定するために使用できるランタイム API はありません。