Dela via

UI-automatisering av en anpassad WPF-kontroll

UI Automation tillhandahåller ett enda generaliserat gränssnitt som automationsklienter kan använda för att undersöka eller använda användargränssnitten för en mängd olika plattformar och ramverk. Med UI Automation kan både kvalitetssäkringskod (test) och hjälpmedelsprogram som skärmläsare undersöka användargränssnittselement och simulera användarinteraktion med dem från annan kod. Information om automatisering av användargränssnittet på alla plattformar finns i Hjälpmedel.

Det här avsnittet beskriver hur du implementerar en UI Automation-provider på serversidan för en anpassad kontroll som körs i ett WPF-program. WPF stöder UI Automation via ett träd med peer automation-objekt som paralleller trädet för användargränssnittselement. Testkod och applikationer som tillhandahåller hjälpmedelsfunktioner kan använda automationsobjekt direkt (för kod som körs i samma process) eller via det generaliserade gränssnitt som tillhandahålls av UI Automation.

Automation Peer-klasser

WPF-kontroller stöder UI Automation via ett träd med peer-klasser som härleds från AutomationPeer. Enligt konventionen börjar peer-klassnamn med kontrollklassnamnet och slutar med "AutomationPeer". Till exempel är ButtonAutomationPeer jämförelseklassen för kontrollklassen Button. Peer-klasserna motsvarar ungefär UI Automation-kontrolltyper men är specifika för WPF-element. Automationskod som kommer åt WPF-program via UI Automation-gränssnittet använder inte automationskolleger direkt, men automatiseringskod i samma processutrymme kan använda automationskolleger direkt.

Inbyggda Automation Peer-klasser

Element implementerar en peer-klass för automatisering om de accepterar gränssnittsaktivitet från användaren, eller om de innehåller information som krävs av användare av skärmläsarprogram. Inte alla visuella element i WPF har automationskolleger. Exempel på klasser som implementerar automationskollegor är Button, TextBoxoch Label. Exempel på klasser som inte implementerar automationskollegor är klasser som härleds från Decorator, till exempel Borderoch klasser baserat på Panel, till exempel Grid och Canvas.

Control Basklassen har ingen motsvarande peer-klass. Om du behöver en peer-klass för att motsvara en anpassad kontroll som härleds från Controlbör du härleda den anpassade peer-klassen från FrameworkElementAutomationPeer.

Säkerhetsöverväganden för härledda peer-datorer

Automation-peer-datorer måste köras i en delvis betrodd miljö. Kod i UIAutomationClient-sammansättningen är inte konfigurerad att köras i en partisk förtroendemiljö, och automations peer-kod bör inte referera till den sammansättningen. I stället bör du använda klasserna i UIAutomationTypes-sammansättningen. Du bör till exempel använda AutomationElementIdentifiers klassen från UIAutomationTypes-sammansättningen, som motsvarar AutomationElement klassen i UIAutomationClient-sammansättningen. Det är säkert att referera till UIAutomationTypes-sammansättningen i automations peer-kod.

Peernavigering

När du har lokaliserat en automations peer kan kod i processen navigera i peer-trädet genom att anropa objektets GetChildren och GetParent metoderna. Navigering mellan WPF-element i en kontroll stöds av peerens implementation av GetChildrenCore-metoden. UI Automation-systemet anropar den här metoden för att bygga upp ett träd med underelement som finns i en kontroll. Till exempel listobjekt i en listruta. UIElementAutomationPeer.GetChildrenCore Standardmetoden går igenom det visuella trädet av element för att bygga trädet av automationsreferenser. Anpassade kontroller åsidosätter den här metoden för att exponera underliggande element för automatiseringsklienter, vilket returnerar automatiseringskompisar för element som förmedlar information eller tillåter användarinteraktion.

Anpassningar i en härledd peer-enhet

Alla klasser som härleds från UIElement och ContentElement innehåller den skyddade virtuella metoden OnCreateAutomationPeer. WPF anropar OnCreateAutomationPeer för att hämta automationspeerobjektet för varje kontroll. Automation-kod kan använda peer-koden för att hämta information om en kontrolls egenskaper och funktioner och för att simulera interaktiv användning. En anpassad kontroll som stöder automatisering måste åsidosätta OnCreateAutomationPeer och returnera en instans av en klass som härleds från AutomationPeer. Om till exempel en anpassad kontroll härleds från ButtonBase -klassen ska objektet som returneras av OnCreateAutomationPeer härleda från ButtonBaseAutomationPeer.

När du implementerar en anpassad kontroll måste du åsidosätta "Core"-metoderna från peer-klassen för basautomatisering som beskriver beteendet som är unikt och specifikt för din anpassade kontroll.

Åsidosätt onCreateAutomationPeer

OnCreateAutomationPeer Åsidosätt metoden för din anpassade kontroll så att den returnerar providerobjektet, som måste härledas direkt eller indirekt från AutomationPeer.

Åsidosätt GetPattern

Automationbryggor förenklar vissa implementeringsaspekter av UI-automationsleverantörer på serversidan, men anpassade automationbryggor måste fortfarande hantera mönstergränssnitt. Precis som icke-WPF-leverantörer stöder peers kontrollmönster genom att tillhandahålla implementeringar av gränssnitt i System.Windows.Automation.Provider-namnområdet, som IInvokeProvider. Kontrollmönstergränssnitten kan implementeras av själva peer-objektet eller av ett annat objekt. Peer-implementeringen av GetPattern returnerar det objekt som stöder det angivna mönstret. UI Automation-koden anropar GetPattern metoden och anger ett PatternInterface uppräkningsvärde. Åsidosättningen av GetPattern ska returnera det objekt som implementerar det angivna mönstret. Om kontrollen inte har en anpassad implementering av ett mönster kan du anropa bastypens implementering av GetPattern för att hämta antingen dess implementering eller null om mönstret inte stöds för den här kontrolltypen. Ett exempel på en anpassad NumericUpDown-kontroll kan vara att den sätts till ett värde inom ett intervall, och dess UI Automation-peer implementerar då gränssnittet IRangeValueProvider. I följande exempel visas hur den peer-metoden åsidosätts GetPattern för att svara på ett PatternInterface.RangeValue värde.

public override object GetPattern(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    return base.GetPattern(patternInterface);
}

Public Overrides Function GetPattern(ByVal patternInterface As PatternInterface) As Object
    If patternInterface = PatternInterface.RangeValue Then
        Return Me
    End If
    Return MyBase.GetPattern(patternInterface)
End Function

En GetPattern metod kan också ange ett underelement som en mönsterprovider. Följande kod visar hur ItemsControl överför hanteringen av rullningsmönster till peern för den interna ScrollViewer-kontrollen.

public override object GetPattern(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.Scroll)
    {
        ItemsControl owner = (ItemsControl) base.Owner;

        // ScrollHost is internal to the ItemsControl class
        if (owner.ScrollHost != null)
        {
            AutomationPeer peer = UIElementAutomationPeer.CreatePeerForElement(owner.ScrollHost);
            if ((peer != null) && (peer is IScrollProvider))
            {
                peer.EventsSource = this;
                return (IScrollProvider) peer;
            }
        }
    }
    return base.GetPattern(patternInterface);
}

Public Class Class1
    Public Overrides Function GetPattern(ByVal patternInterface__1 As PatternInterface) As Object
        If patternInterface1 = PatternInterface.Scroll Then
            Dim owner As ItemsControl = DirectCast(MyBase.Owner, ItemsControl)

            ' ScrollHost is internal to the ItemsControl class
            If owner.ScrollHost IsNot Nothing Then
                Dim peer As AutomationPeer = UIElementAutomationPeer.CreatePeerForElement(owner.ScrollHost)
                If (peer IsNot Nothing) AndAlso (TypeOf peer Is IScrollProvider) Then
                    peer.EventsSource = Me
                    Return DirectCast(peer, IScrollProvider)
                End If
            End If
        End If
        Return MyBase.GetPattern(patternInterface1)
    End Function
End Class

Om du vill ange ett underelement för mönsterhantering, hämtar den här koden underelementsobjektet, skapar en peer med hjälp av CreatePeerForElement-metoden, anger EventsSource-egenskapen för den nya peern till den aktuella peern och returnerar den nya peern. Inställningen EventsSource på ett underelement hindrar underelementet från att visas i peer-trädet för automatisering och anger alla händelser som genereras av underelementet som kommer från kontrollen som anges i EventsSource. Kontrollen ScrollViewer visas inte i automationsträdet, och rullningshändelser som den genererar verkar komma från ItemsControl objektet.

Åsidosätt "core"-metoder

Automationskoden hämtar information om din kontroll genom att anropa publika metoder i peer-klassen. Om du vill ange information om din kontroll åsidosätter du varje metod vars namn slutar med "Core" när din kontrollimplementering skiljer sig från den som tillhandahålls av peer-klassen för basautomatisering. Din kontroll måste minst implementera GetClassNameCore metoderna och GetAutomationControlTypeCore , som du ser i följande exempel.

protected override string GetClassNameCore()
{
    return "NumericUpDown";
}

protected override AutomationControlType GetAutomationControlTypeCore()
{
    return AutomationControlType.Spinner;
}

Protected Overrides Function GetClassNameCore() As String
    Return "NumericUpDown"
End Function

Protected Overrides Function GetAutomationControlTypeCore() As AutomationControlType
    Return AutomationControlType.Spinner
End Function

Implementeringen av GetAutomationControlTypeCore beskriver din kontroll genom att returnera ett ControlType värde. Även om du kan returnera ControlType.Custombör du returnera en av de mer specifika kontrolltyperna om den beskriver din kontroll korrekt. Ett returvärde av ControlType.Custom kräver extra arbete för att leverantören ska implementera UI Automation, och UI Automation-klientprodukter kan inte förutse kontrollstrukturen, tangentbordsinteraktionen och möjliga kontrollmönster.

Implementera metoderna IsContentElementCore och IsControlElementCore för att ange om kontrollen innehåller data eller har en interaktiv roll i användargränssnittet (eller båda). Som standard returnerar båda metoderna true. De här inställningarna förbättrar användbarheten för automatiseringsverktyg som skärmläsare, som kan använda dessa metoder för att filtrera automationsträdet. Om din GetPattern metod överför mönsterhantering till en peer för underelement kan underelementets IsControlElementCore peer-metod returnera false för att dölja underelementets peer från automationsträdet. Till exempel hanteras rullning i en ListBox av en ScrollViewer, och automation peer för PatternInterface.Scroll returneras av GetPattern metoden av ScrollViewerAutomationPeer som är associerad med ListBoxAutomationPeer. Därför returneras av IsControlElementCore metoden av ScrollViewerAutomationPeerfalse, så att den ScrollViewerAutomationPeer inte visas i automationsträdet.

Din automation-peer ska ange lämpliga standardvärden för din styrning. Observera att XAML som refererar till din kontroll kan åsidosätta dina peer-implementeringar av kärnmetoder genom att inkludera AutomationProperties attribut. Följande XAML skapar till exempel en knapp som har två anpassade UI Automation-egenskaper.

<Button AutomationProperties.Name="Special"
    AutomationProperties.HelpText="This is a special button."/>

Implementera mönsterleverantörer

Gränssnitten som implementeras av en anpassad tjänsteleverantör deklareras uttryckligen om det ägande elementet härleds direkt från Control. Följande kod deklarerar till exempel en peer för en Control som implementerar ett intervallvärde.

public class RangePeer1 : FrameworkElementAutomationPeer, IRangeValueProvider { }

Public Class RangePeer1
    Inherits FrameworkElementAutomationPeer
    Implements IRangeValueProvider
End Class

Om ägandekontrollen härleds från en viss typ av kontroll, till exempel RangeBase, kan peer-objektet härledas från en motsvarande härledd peer-klass. I det här fallet skulle peer-filen härledas från RangeBaseAutomationPeer, som tillhandahåller en basimplementering av IRangeValueProvider. Följande kod visar hur man deklarerar en sådan peer.

public class RangePeer2 : RangeBaseAutomationPeer { }

Public Class RangePeer2
    Inherits RangeBaseAutomationPeer
End Class

Ett exempel på implementering finns i C# eller Visual Basic-källkoden som implementerar och använder en anpassad NumericUpDown-kontroll.

Utlösa händelser

Automation-klienter kan prenumerera på automationshändelser. Anpassade kontroller måste rapportera ändringar i kontrolltillståndet RaiseAutomationEvent genom att anropa metoden. På samma sätt anropar du RaisePropertyChangedEvent-metoden när ett egenskapsvärde ändras. Följande kod visar hur du hämtar peer-objektet inifrån kontrollkoden och anropar en metod för att skapa en händelse. Som en optimering avgör koden om det finns några lyssnare för den här händelsetypen. Att höja händelsen endast när det finns lyssnare undviker onödiga omkostnader och hjälper kontrollen att förbli responsiv.

if (AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged))
{
    NumericUpDownAutomationPeer peer =
        UIElementAutomationPeer.FromElement(nudCtrl) as NumericUpDownAutomationPeer;

    if (peer != null)
    {
        peer.RaisePropertyChangedEvent(
            RangeValuePatternIdentifiers.ValueProperty,
            (double)oldValue,
            (double)newValue);
    }
}

If AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged) Then
    Dim peer As NumericUpDownAutomationPeer = TryCast(UIElementAutomationPeer.FromElement(nudCtrl), NumericUpDownAutomationPeer)

    If peer IsNot Nothing Then
        peer.RaisePropertyChangedEvent(RangeValuePatternIdentifiers.ValueProperty, CDbl(oldValue), CDbl(newValue))
    End If
End If

Se även