Manifesto de componente

Configurar o manifesto do componente é uma etapa essencial na criação de um componente de código. O arquivo ControlManifest.Input.xml é inicializado com algumas de suas escolhas, como nome e tipo de componente, quando você usa o comando pac pcf init. Você ainda deve personalizar o arquivo para especificar quaisquer propriedades e recursos que estiver usando e para ativar qualquer um dos recursos da estrutura usados no componente.

Propriedades do componente

As propriedades definem um contrato entre o componente de código e o aplicativo de hospedagem. Eles devem abstrair o criador de como você implementa o componente, mas ainda fornecer recursos configuráveis para o criador que usa o componente. Veja a seguir alguns dos tipos comuns de propriedade que talvez você precise adicionar a um componente:

• Permitir que dados de negócios transitem bidirecionalmente no componente de código. Por exemplo, ao passar uma geolocalização para o componente, o componente pode mostrar um mapa realçando um local específico.
• Permitir controlar recursos e comportamentos dos componentes. Por exemplo, usando nosso exemplo de mapa, poderia ser adicionada uma propriedade que indica se o usuário pode aumentar ou diminuir o zoom no mapa.
• Permitir que alguns aspectos do estilo do componente sejam personalizados. Por exemplo, no mapa, o componente pode permitir que você personalize a cor do fixador, fornecendo uma propriedade que o criador pode configurar.

A captura de tela a seguir é um exemplo de manifesto que mostra as propriedades definidas para um componente indicador de progresso.

Quando um criador configura um componente de código, as propriedades definidas no manifesto ficam disponíveis para configuração. Esta imagem mostra como o manifesto acima para um componente indicador de progresso é mostrado a um criador no designer do aplicativo. Permite ver as propriedades disponíveis e personalizá-las.

Atributos da propriedade

Há vários atributos em uma propriedade que você pode configurar dependendo de suas necessidades. A seguir estão os mais comuns que você deve considerar:

• of-type: esse atributo define o tipo de dados da propriedade. Há muitos tipos para escolher, como SingleLine.Text para Enum. Alguns tipos, como Enum, oferecem uma experiência de configuração mais avançada para o criador, fornecendo uma lista fixa para seleção. Outros limitam o conteúdo dos dados com base no tipo que pode passar do aplicativo de hospedagem. Alguns são mais apropriados para associação de dados, como Lookup.Simple. Sempre tente evitar alterar os tipos de dados após publicar seu componente.

• usage: esse atributo identifica se a propriedade é de entrada, saída ou vinculada. Aplica-se aos aplicativos baseados em modelo. A opção vinculada espera ter uma coluna de dados da tabela associada para fornecer o valor dos dados.

• required: indica se um valor é obrigatório para a propriedade. Quando você adiciona novas propriedades após a publicação de um componente, considere o impacto de tornar a propriedade obrigatória em aplicativos existentes que usam o componente.

• default-value: esse atributo tem o valor padrão fornecido ao componente. Em aplicativos baseados em modelo, essa propriedade só é permitida em propriedades com um tipo de uso de entrada. Fornecer um default-value pode ser útil para os criadores fornecerem uma ideia de como você pretende que a propriedade seja definida. Quando você adiciona uma nova propriedade a um componente existente, o default-value geralmente é definido como o valor que o componente usou antes de se tornar configurável por meio da propriedade.

Ao avaliar as propriedades que planeja adicionar, aqui estão alguns itens a serem considerados:

• Evite ter muitas propriedades em seu componente, exigindo que o criador navegue por uma longa lista de opções.
• Use nomes de propriedade que sejam claros. Quando possível, forneça detalhes suficientes na descrição para informar o criador sobre sua finalidade.
• Considere a adição de algumas propriedades para permitir que os criadores estilizem seu componente. Essas propriedades podem ser importantes quando você pode usar o componente em uma ampla variedade de aplicativos.
• Evite renomear ou remover propriedades após publicar seu componente, pois isso será uma alteração significativa para os aplicativos de consumo existentes.

Recursos de componentes

O nó de recurso no manifesto identifica os arquivos de recursos exigidos pelo componente. Em um novo componente, inicialmente isso contém apenas o elemento de código necessário. Você pode adicionar outros recursos necessários ao seu componente. Os mais comuns são css e resx.

O elemento css permite identificar um arquivo CSS (Folha de Estilos em Cascata) que deve ser carregado. Opcionalmente, você poderá especificar uma ordem para carregamento, caso esteja carregando vários. O código a seguir é um exemplo de carregamento de dois arquivos CSS.

<css path="css/ComponentCommon.css" order="1" />
<css path="css/ProgressIndicator.css" order="2" />

O nó resx no manifesto identifica o arquivo usado para gerenciar as strings localizadas que você define. Se você pretende localizar, é mais fácil adicionar isso em um novo componente e atualizar à medida que adiciona propriedades. As propriedades no valor manifesto dos atributos display-name-key e description-key são usadas para pesquisar o valor localizado, se ele puder ser localizado em um arquivo de recurso resx carregado.

Por exemplo, examine a definição de propriedade a seguir e a maneira como esses atributos são definidos.

 <property name="PercentComplete" description-key="PercentComplete_Desc" display-name-key="PercentComplete" required="true" usage="input" of-type="Whole.None" default-value="40" />

Em um arquivo resx, um arquivo XML que usa o Microsoft ResX Schema, você definiria os elementos de dados a seguir para as chaves de propriedade.

<data name="PercentComplete" xml:space="preserve">
        <value>Percent Complete</value>
</data>
<data name="PercentComplete_Desc" xml:space="preserve">
        <value>Percent Complete is the current value for how much has been completed.</value>
</data>

Você criaria então um arquivo resx separado para cada idioma compatível.

Em seguida, em seu nó de recurso de manifesto, você adicionaria os nós resx a seguir para carregar os arquivos quando o componente fosse usado.

<resx path="strings/ProgressIndicator.1033.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.1035.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.3082.resx" version="1.0.0" />

Uso de recursos de componentes

Os recursos de dispositivo, utilitário e WebAPI da estrutura estão disponíveis para uso por componentes usados em um aplicativo baseado em modelo. Para usar um desses recursos, você deve declará-lo no manifesto no nó feature-usage adicionando um nó uses-feature. O código a seguir é um exemplo de ativação do uso do recurso WebAPI.

<feature-usage>
    <uses-feature name="WebAPI" required="true" />
 </feature-usage>