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 屬性;如果您嘗試在標記中的相同物件專案上設定 x:Name 和 Name ，則會擲回剖析器錯誤。

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

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

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

名稱的案例

在定義 UI 元素的 XAML 中設定 x:Name 或 Name 支援數個主要案例：

• 動畫目標 若要將動畫套用至物件屬性，您必須以特定實例為目標。 您可以藉由在任何Timeline上設定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 ，但您應該注意的一些重要考慮和限制。

Name如果物件在 XAML 中設定了先前 Name 的值，則通常不建議在執行時間變更 程式碼中的 值。 這是因為載入物件樹狀結構之後設定名稱將不會建立或變更對等欄位參考的識別名稱。 如果欄位參考已經存在，因為 x:Name 是在初始標記中提供，而且您變更 的值 Name ，則欄位和透過 FindName 尋找物件所需的名稱現在會不同，因為欄位會維持為標記定義的名稱。

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

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

請注意，您只能在執行時間設定 NameFrameworkElement 或 Inline的物件。 如果物件沒有 Name 屬性，而且在 x:Name XAML 中設定名稱需要使用 屬性而非 Name ，則沒有可用於設定這類物件執行時間名稱的執行時間 API。

另請參閱

• FindName(String)
• TargetName
• x:Name 屬性
• XAML 命名範圍
• XAML 概觀