FrameworkElement.Name 屬性

  • 參考

定義

命名空間:
Windows.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();
}

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 屬性都相等。 在任何單一元素上， x：Name 屬性和 Name 屬性會互斥為 XAML 屬性;如果您嘗試在標記中的相同物件專案上同時設定 x：Name 和 Name ，則會擲回剖析器錯誤。

當您針對 XAML 使用預設 的 Page 建置動作時，任何具有 x：Name 屬性或 Name 的 XAML 元素都會在載入 XAML 時產生 最終由 InitializeComponent 填入的欄位參考。 欄位參考可啟用程式設計模型，一旦 XAML 物件樹狀結構載入至頁面或應用程式時，即可透過頁面特定程式碼後置的名稱直接參考物件。

名稱在 XAML 名稱範圍中必須是唯一的。 一般而言，XAML 名稱範圍是由 XAML 頁面所定義，但某些功能，例如範本或對 API 的呼叫，例如 XamlReader.Load 可以定義個別的 XAML 名稱範圍。 如需詳細資訊，請參閱 XAML 命名範圍。

名稱絕不應當地語系化。 Name 會當做程式碼後置中的功能變數名稱變數使用。 這類程式碼通常無法存取可能可存取定義 UI 的 XAML 檔案，不過這取決於您的部署模型和當地語系化程式。 這是您不應該在應用程式 UI 中顯示任何來自 Name 的字串的原因之一。

名稱的案例

在定義 UI 元素的 XAML 中設定 x：Name 或 Name 支援數個主要案例：+ 以動畫 為目標 若要將動畫套用至物件屬性，您必須以特定實例為目標。 您可以在任何時間軸上設定Storyboard.TargetName附加屬性來執行此動作。 您在這裡設定的值是您指派為 x：Name 或 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 尋找物件的欄位和名稱會有所不同，因為欄位會維持為標記定義的名稱。

為程式碼中建立的物件設定 Name 值，因此永遠不會有 XAML 定義的 Name 值適用于特定案例。 其中一個案例是，如果您想要使用 FindName 做為通用公用程式函式，在樹狀結構中尋找 XAML 建立或程式碼建立的物件。 為了讓該案例能夠運作，Windows 執行階段會繼續使用，並在執行時間新增至 XAML 名稱範圍雜湊表標記法。 如果您嘗試將新的具名物件新增至現有的大型 XAML 建立物件樹狀結構，則名稱必須是唯一的，否則會發生重複的名稱例外狀況。 嘗試設定 Name 時，可能不會發生重複的名稱例外狀況。 在您嘗試將重複命名的物件新增至主要物件樹狀結構之前，新物件有自己的獨立 XAML 名稱範圍。 只有當您將物件連接到較大的物件樹狀結構時，才能偵測到重複的名稱條件。 或者，在樹狀結構中連線物件的作業上可能會發生例外狀況，例如呼叫連接到主物件樹狀結構之集合的 Add 方法。

您稍後會將新物件新增至的 XAML 名稱範圍中，很難知道哪些 Name 值已經存在。 沒有特定 API 會報告 XAML 名稱範圍中現有名稱的完整雜湊表。 如果您廣泛地在程式碼中設定 Name 值，您可能需要產生執行時間使用方式唯一的名稱字串的技術，或者您可能需要包裝呼叫，以在 try-catch 區塊中新增新命名的物件，以攔截可能因重複名稱而產生的例外狀況。 或者，您可以將自己的程式碼新增至可讀取 XAML 產生名稱值的 InitializeComponent 實作。

請注意，您只能在執行時間為 FrameworkElement 或 內嵌的物件設定 Name。 如果物件沒有 Name 屬性，而且在 XAML 中設定名稱必須使用 x：Name 屬性而非 Name，則沒有任何執行時間 API 可用來設定這類物件的執行時間名稱。

適用於

另請參閱