O arquivo do designer

Importante: este documento se refere a uma versão obsoleta do UiPath Activity Criador para Visual Studio. Consulte a nova documentação aqui.

Introdução

Uma atividade completa pode ser criada somente com o arquivo de definição da atividade, mas a experiência do usuário é quase sempre aprimorada com a adição de um designer ou de uma Interface Gráfica. Os designers são escritos em XAML, uma linguagem baseada em XML (descrita em mais detalhes aqui), e são usadas para criar front-ends para aplicativos do Windows Presentation Foundation (WPF).

Navegue até o arquivo ChildrenActivityDesigner.xaml e navegue por cada seção para entender melhor como aprimorar sua atividade com uma interface gráfica.

<sap:ActivityDesigner x:Class="MyCompany.MyProduct.Activities.Design.ChildActivityDesigner"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:sap="clr-namespace:System.Activities.Presentation;assembly=System.Activities.Presentation"
             xmlns:converters="clr-namespace:UiPath.Shared.Activities.Design.Converters">
    <a href="sap:ActivityDesigner.Resources">sap:ActivityDesigner.Resources</a>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="..\)\)Themes\)\)Generic.xaml" />
            </ResourceDictionary.MergedDictionaries>
            <converters:ActivityIconConverter x:Key="ActivityIconConverter" />
        </ResourceDictionary>
    </sap:ActivityDesigner.Resources>
    <a href="sap:ActivityDesigner.Icon">sap:ActivityDesigner.Icon</a>
        <DrawingBrush Stretch="Uniform" Drawing="{Binding Path=ModelItem, Converter={StaticResource ActivityIconConverter}, ConverterParameter=pack://application:\)\),\)\),\)\),/MyCompany.MyProduct.Activities.Design;component/themes/icons.xaml}" />
    </sap:ActivityDesigner.Icon>
</sap:ActivityDesigner>

Definição de classe

Todos os designers contêm um componente de nível superior no qual uma classe é declarada e namespaces complementares são importados. Este exemplo estende a classe ActivityDesigner , a classe base para todos esses componentes.

<sap:ActivityDesigner x:Class="MyCompany.MyProduct.Activities.Design.ChildActivityDesigner"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:sap="clr-namespace:System.Activities.Presentation;assembly=System.Activities.Presentation"
             xmlns:converters="clr-namespace:UiPath.Shared.Activities.Design.Converters">

Observe que cada um dos namespaces importados tem a forma xmlns:<prefix>. Esses prefixos são usados posteriormente no arquivo para fazer referência a componentes úteis.

Recursos

Recursos são componentes, estilos ou dados reutilizáveis disponibilizados para uso em um arquivo XAML por meio de um componente ResourceDictionary . Neste exemplo, dois tipos de recursos são fornecidos: um dicionário de estilos (Generic.xaml) e um componente conversor (ActivityIconConverter).

<a href="sap:ActivityDesigner.Resources">sap:ActivityDesigner.Resources</a>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="..\)\)Themes\)\)Generic.xaml" />
        </ResourceDictionary.MergedDictionaries>
        <converters:ActivityIconConverter x:Key="ActivityIconConverter" />
    </ResourceDictionary>
</sap:ActivityDesigner.Resources>

1. Generic.xaml é outro ResourceDictionary , que contém estilos UiPath padrão, ajudam a manter a consistência da aparência dos designers. Esperar dentro desse arquivo, você vê o seguinte estilo, que define uma altura padrão para todos os objetos ComboBox . Como incluímos esse dicionário no arquivo XAML, todas as caixas de combinação terão uma altura padrão de 23 px.

   <Style TargetType="{x:Type ComboBox}">
       <Setter Property="Height" Value="23" />
   </Style>

2. ActivityIconConverter é uma classe de utilitário que é fornecida por meio da pasta compartilhada e que permite que todos os ícones de atividades sejam especificados de uma maneira padrão. Consulte a seção Ícones abaixo para obter mais detalhes.

   
   

   

   
   

Ícones

Os ícones, como aqueles vistos em todas as atividades da UiPath, podem ser adicionados diretamente a um arquivo do Designer no formato XAML, mas nosso método preferido é adicionar todos em um arquivo dedicado e usar o ActivityIconConverter mencionado acima para colocá-los em cada atividade. Dessa maneira, o arquivo principal do Designer permanece organizado por códigos de ícones, que geralmente são longos.

Icons.xaml

Dentro do seu projeto de design, navegue até Temas > Ícones.xaml.

Você verá que nesse arquivo há dois blocos de código que contêm os ícones do Escopo Pai e da Atividade Filho e que estão rotulados como tal. O conteúdo de cada ícone obviamente variará, mas o que deve permanecer constante é o atributo x:Key , que tem a forma <Activity Name>Icon. O código do ícone da Atividade Filho, por exemplo, tem o seguinte formato:

<DrawingBrush x:Key="ChildActivityIcon" Viewbox="0,0,52.706,14.497" ViewboxUnits="Absolute" Stretch="Uniform">
...        
</DrawingBrush>

Arquivo do Designer

Navegue de volta para seu arquivo de designer, ChildrenActivityDesigner.xaml. O seguinte bloco de código é responsável por adicionar um ícone ao designer e é uma constante em todas as atividades no pacote. Ele funciona pesquisando Ícones.xaml para uma chave com o mesmo nome da atividade em si e adiciona esse código XAML ao arquivo atual. Observe que o ConverterParameter faz referência ao seu projeto do Designer pelo nome.

<a href="sap:ActivityDesigner.Icon">sap:ActivityDesigner.Icon</a>
    <DrawingBrush Stretch="Uniform" Drawing="{Binding Path=ModelItem, Converter={StaticResource ActivityIconConverter}, ConverterParameter=pack://application:\)\),\)\),\)\),/MyCompany.MyProduct.Activities.Design;component/themes/icons.xaml}" />
</sap:ActivityDesigner.Icon>

Adicionando componentes

Agora você tem a base de um designer, mas ainda está completamente em branco! Vamos expandir isso e adicionar dois campos de texto, um para cada entrada da atividade Filho.

Activity Decorator

Comece dando uma aparência UiPath à atividade. Isso pode ser feito facilmente adicionando um ActivityDecoratorControl ao seu designer imediatamente abaixo do código do seu ícone. O Visual Studio pode solicitar que você importe o namespace UiPath.Shared.Activities.Design.Controls , mas se não importar, adicione isso à definição de classe na parte superior do arquivo também.

<sap:ActivityDesigner x:Class="MyCompany.MyProduct.Activities.Design.ChildActivityDesigner"
             ...
             xmlns:controls="clr-namespace:UiPath.Shared.Activities.Design.Controls">
<?comment-start?>
Resources
<?comment-end?>
<?comment-start?>
Icons
<?comment-end?>
    <controls:ActivityDecoratorControl Style="{StaticResource ActivityDecoratorStyle}">
        
    </controls:ActivityDecoratorControl>
</sap:ActivityDesigner>

Todos os componentes de designers devem ser envolvidos em um ActivityDecoratorControl, que fornece comportamentos de atividade padrão, como a capacidade de minimizar um designer grande e exibir a mensagem "Clique duas vezes para visualizar". em seu lugar. Detalhes como esse são pequenos, mas combinamos para dar uma aparência UiPath ao pacote de atividades geral.

Recrie seu pacote e veja que agora ele está um pouco diferente:

Layout em Grade

A seguir, vamos definir o layout da atividade para que ela possa exibir rótulos e campos de texto de forma atraente. O WPF tem 6 layouts principais, mas vamos usar um painel de Grade para manter nossos controles. A Grade funciona definindo primeiro um número de linhas e colunas, juntamente com suas alturas e larguras, respectivamente. Comece definindo duas linhas e duas colunas.

<controls:ActivityDecoratorControl Style="{StaticResource ActivityDecoratorStyle}">
    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
      
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*"/>
            <ColumnDefinition Width="3*"/>
        </Grid.ColumnDefinitions>
    </Grid>
</controls:ActivityDecoratorControl>

Observe que as alturas e larguras não contêm valores reais; em vez disso, usam caracteres curinga (*). Você é livre para especificar valores numéricos exatos, mas essa notação permite que cada célula seja dimensionada dinamicamente em relação às que estão ao seu redor. As alturas RowDefinition são ambas * , então elas consumirão tanto o espaço vertical quanto existir. As larguras ColumnDefinition , no entanto, são * e 3*, o que significa que a primeira coluna consumirá 25% de qualquer espaço em branco disponível ao longo da largura e a segunda coluna 75%.

Adicionar uma caixa de texto

Agora que o layout está definido, adicionaremos duas caixas de texto com as quais o usuário pode acessar as duas propriedades de entrada da atividade filho: Primeiro número e Segundo número. Comece adicionando um Rótulo após as definições de grade para o Primeiro número.

Há 3 propriedades definidas como Label:

• Grid.Row: posiciona o rótulo na primeira linha da grade definida acima.
• Grid.Column: posiciona o rótulo na primeira coluna da grade definida acima.
• Conteúdo: define o texto exibido no rótulo.

Consulte aqui para obter uma lista completa de propriedades disponíveis para elementos WPF.

<Grid>
<?comment-start?>
Grid definitions
<?comment-end?>
    <Label Grid.Row="0" Grid.Column="0" 
           Content="First Number" />
</Grid>

Em seguida, vamos adicionar uma ExpressionTextBox para permitir a entrada do usuário. Se o Visual Studio não solicitar que você faça isso, você deve adicionar manualmente mais dois namespaces à definição de classe.

xmlns:view="http://schemas.microsoft.com/netfx/2009/xaml/activities/presentation"
xmlns:system="clr-namespace:System;assembly=mscorlib"

Há quatro propriedades definidas neste ExpressionTextBox:

• Grid.Row: posiciona o rótulo na primeira linha da grade definida acima.
• Grid.Column: posiciona o rótulo na segunda coluna da grade definida acima.
• TextoDa Dica: define o texto da dica de ferramenta que aparece dentro da caixa de texto quando vazia e também quando o mouse do usuário passa o mouse sobre este campo.
• TipoDeExpressão: define o tipo de dados permitido neste campo. Como nossa propriedade é um número do tipo int, ela é definida como Int32.

  <Grid>
  <?comment-start?>
  Grid definitions
  <?comment-end?>
      <Label Grid.Row="0" Grid.Column="0" 
             Content="First Number" />
      <view:ExpressionTextBox Grid.Row="0" Grid.Column="1" 
                              HintText="The first addend"
                              ExpressionType="system:Int32" />
  </Grid>

Recrie seu pacote e ele agora deve ficar assim:

Adicione outro Label e ExpressionTextBox para a propriedade Segundo Número, lembrando que esses controles agora estarão em Grid.Row="1". O resultado final deve ser semelhante a isto:

Vincular Designer à Atividade

Tente clicar em uma de suas caixas de texto e você descobrirá que ela não responde. Isso ocorre porque a ExpressionTextBox funciona de forma diferente de uma Caixa de texto normal. Onde as caixas de texto suportam String entradas, as caixas de texto de expressão permitem que o usuário insira expressões VB.Net complexas (por exemplo, Int32.MaxValue, 2+2, SomeUiPathVariable) e pode associar esse valor a uma propriedade na sua atividade.

Para vincular os campos do designer às propriedades da atividade, adicione mais duas propriedades a cada ExpressionTextBox:

• OwnerActivity: especifica um ViewModel usado pelo designer para vincular ao arquivo da atividade. Para nossos propósitos, será sempre ModelItem.
• Expressão: fornece a propriedade da atividade à qual este campo será associado. Há quatro componentes principais aqui:
• Associação: especifica pelo nome a propriedade da atividade à qual a associação. Se ModelItem contiver o conteúdo da sua atividade, ModelItem.FirstNumber vincula diretamente à propriedade First Number.
• Converter: fornece uma classe para conversão entre objetos de diferentes tipos. No nosso caso, o campo do designer contém um int, mas a propriedade da atividade é do tipo InArgument<int>, então adicionamos um ArgumentToExpressionConverter padrão para manusear a associação entre eles.
• ConverterParameter: especifica o tipo de argumento ao qual este campo está associado. Neste caso, estamos vinculando a InArgument<> propriedades, então o ConverterParameter é In, mas InOut e Out também são opções.
• Modo: indica se as alterações no campo do designer vão disparar atualizações ou a propriedade da atividade, e vice-versa. Defina isso como TwoWay para permitir que o usuário atualize o designer ou o painel de propriedades. Consulte aqui para todas as outras opções.

Importe o ArgumentToExpressionConverter adicionando a seguinte linha ao seu ResourceDictionary e importando o namespace clr-namespace:System.Activities.Presentation.Converters;assembly=System.Activities.Presentation na sua definição de classe.

<converters1:ArgumentToExpressionConverter x:Key="ArgumentToExpressionConverter" />

Ao todo, o designer e o código da atividade filha devem aparecer como abaixo. Insira valores em cada campo e observe como as propriedades correspondentes são atualizadas.

<sap:ActivityDesigner x:Class="MyCompany.MyProduct.Activities.Design.ChildActivityDesigner"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:sap="clr-namespace:System.Activities.Presentation;assembly=System.Activities.Presentation"
             xmlns:converters="clr-namespace:UiPath.Shared.Activities.Design.Converters"
             xmlns:converters1="clr-namespace:System.Activities.Presentation.Converters;assembly=System.Activities.Presentation"
             xmlns:controls="clr-namespace:UiPath.Shared.Activities.Design.Controls"
             xmlns:view="http://schemas.microsoft.com/netfx/2009/xaml/activities/presentation"
             xmlns:system="clr-namespace:System;assembly=mscorlib">
    <a href="sap:ActivityDesigner.Resources">sap:ActivityDesigner.Resources</a>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="..\)\)Themes\)\)Generic.xaml" />
            </ResourceDictionary.MergedDictionaries>
            <converters1:ArgumentToExpressionConverter x:Key="ArgumentToExpressionConverter" />
            <converters:ActivityIconConverter x:Key="ActivityIconConverter" />
        </ResourceDictionary>
    </sap:ActivityDesigner.Resources>
    <a href="sap:ActivityDesigner.Icon">sap:ActivityDesigner.Icon</a>
        <DrawingBrush Stretch="Uniform" Drawing="{Binding Path=ModelItem, Converter={StaticResource ActivityIconConverter}, ConverterParameter=pack://application:\)\),\)\),\)\),/MyCompany.MyProduct.Activities.Design;component/themes/icons.xaml}" />
    </sap:ActivityDesigner.Icon>
    <controls:ActivityDecoratorControl Style="{StaticResource ActivityDecoratorStyle}">
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="*" />
                <RowDefinition Height="*" />
            </Grid.RowDefinitions>
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*"/>
                <ColumnDefinition Width="3*"/>
            </Grid.ColumnDefinitions>
            <Label Grid.Row="0" Grid.Column="0" 
                   Content="First Number" />
            <view:ExpressionTextBox Grid.Row="0"  Grid.Column="1" 
                                    OwnerActivity="{Binding Path=ModelItem}" 
                                    ExpressionType="system:Int32" 
                                    HintText="The first addend" 
                                    Expression="{Binding Path=ModelItem.FirstNumber,Converter={StaticResource ArgumentToExpressionConverter}, ConverterParameter=In, Mode=TwoWay}" />
            <Label Grid.Row="1" Grid.Column="0" 
                   Content="Second Number" />
            <view:ExpressionTextBox Grid.Row="1"  Grid.Column="1" 
                                    OwnerActivity="{Binding Path=ModelItem}" 
                                    ExpressionType="system:Int32" 
                                    HintText="The second addend" 
                                    Expression="{Binding Path=ModelItem.SecondNumber,Converter={StaticResource ArgumentToExpressionConverter}, ConverterParameter=In, Mode=TwoWay}" />
        </Grid>
    </controls:ActivityDecoratorControl>
</sap:ActivityDesigner>