Criação de uma experiência de pesquisa orientada por configurações

Crie uma experiência de pesquisa completa usando um único arquivo de configuração JSON. Essa abordagem cria a página de pesquisa, a página de resultados, a tabela e um serviço de API opcional, o que ajuda a reduzir a configuração manual e a manter um comportamento consistente entre os recursos.

Visão geral

O esquema "Search From Config" é um gerador de código baseado em JSON que cria uma funcionalidade de pesquisa completa com o mínimo de configuração. O esquema gera os seguintes componentes.

Componente de painel de pesquisa com campos personalizáveis.
Componente de resultados de pesquisa com trilha de navegação.
Componente de tabela com paginação (no lado do cliente ou no lado do servidor).
Serviço de API para obtenção de dados (opcional).
Arquivos de configuração JSON para campos de pesquisa e colunas de tabela.
Arquivos de tradução com rótulos de trilha de navegação.

Principais benefícios

A criação de uma experiência de pesquisa utilizando este esquema apresenta as seguintes vantagens principais.

Reduza o código repetitivo em até 80%.
Controle o comportamento por meio de um único arquivo de configuração JSON.
Flexibilidade no suporte à paginação do lado do cliente e do lado do servidor.
Recursos adicionais, como ativar ou desativar o salvamento da pesquisa e a atualização.

Procedimento

No seu repositório, crie um arquivo de configuração, como order-search.json.
No arquivo, defina os metadados necessários.
Opcionalmente, adicione uma seção oms-api para configurar a integração com a API.
Opcionalmente, adicione uma seção de pesquisa para configurar a página de pesquisa.
Opcionalmente, adicione uma seção de resultados de pesquisa para configurar a página de resultados.
Na linha de comando, execute o esquema com o arquivo de configuração.
```
ng g @buc/schematics:search-from-config --config=order-search.json
```
Verifique os componentes e arquivos de configuração gerados.
Atualize a lógica do espaço reservado para que ela construa corretamente a consulta da API com base nos campos de pesquisa selecionados.
Se o roteamento não for registrado automaticamente, adicione rotas no seu módulo de roteamento.

Referência de comando

Use as seguintes variações de comando para executar o esquema em diferentes cenários.

Gerar usando um arquivo de configuração.

ng g @buc/schematics:search-from-config --config=config/my-search.json

Visualize as alterações sem criar arquivos.

ng g @buc/schematics:search-from-config --config=config/my-search.json --dry-run

Use um caminho personalizado para o arquivo de configuração.

ng g @buc/schematics:search-from-config --config=../configs/my-search.json

Convenções de nomenclatura de arquivos

Utilize padrões de nomenclatura consistentes para ajudar a garantir nomes previsíveis para componentes e configurações.

Tabela 1. Convenções de nomenclatura de arquivos
Tipo de componente	Padrão de nomenclatura	Exemplo
Painel de Busca	`{name}-search`	`order-new-search`
Resultados da procura	`{name}-search-result`	`order-new-search-result`
Tabela	`{name}-table`	`order-new-search-table`
Serviço	`{name}.service`	`order-new-search.service`
Chave JSON dos campos de pesquisa	`{name}-search`	`order-new-search`
Chave JSON de configuração da tabela	`{name}-table`	`order-new-search-table`

A estrutura JSON completa

{
  "metadata": {
    "name": "order-new-search",
    "displayName": "Order Search",
    "module": "order",
    "paths": {
      "component": "packages/order-search/src/app/features/order",
      "table": "packages/order-search/src/app/features/order",
      "jsonFile": "packages/order-shared/assets/buc-app-order",
      "translationFile": "packages/order-shared/assets/buc-app-order"
    },
    "options": {
      "sharedLib": "order-shared",
      "routing": true,
      "prefix": "buc"
    }
  },
  "oms-api": {
    "endpoints": {
      "search": {
        "apiName": "getOrderList",
        "method": "POST"
      }
    },
    "requestMapping": {
      "pageNumber": "PageNumber",
      "pageSize": "PageSize"
    },
    "responseMapping": {
      "data": "Output.OrderList.Order",
      "totalCount": "Output.OrderList.TotalNumberOfRecords"
    },
    "requestDefaults": {
      "Order": {
        "DocumentType": "0001"
      }
    }
  },
  "search": {
    "fileName": "search_fields.json",
    "route": "/order-search/order/order-new-search",
    "breadcrumb": {
      "label": "Order Search"
    },
    "saveSearch": {
      "enabled": false
    },
    "customizeSearchCriteria": {
      "preferenceName": "order-new-search"
    },
    "searchFieldsJson": {
      "groups": {
        "paths": {
          "default": "Status",
          "searchBy": [
            {
              "content": "order-new-search.schematics.search.LABEL_STATUS",
              "value": "Status",
              "selected": true,
              "oob": true,
              "override": {
                "show": ["sampleStatusField"]
              }
            },
            {
              "content": "order-new-search.schematics.search.LABEL_ITEM",
              "value": "Item",
              "selected": false,
              "oob": true,
              "override": {
                "show": ["sampleItemField"]
              }
            }
          ]
        }
      },
      "fields": [
        {
          "id": "sampleGenField",
          "locked": true,
          "internalConfig": {
            "id": "sampleGenField",
            "title": "order-new-search.schematics.search.LABEL_GENERAL_FIELD_SAMPLE",
            "type": "dropdownQuery"
          }
        },
        {
          "id": "searchBy",
          "locked": true,
          "placementOnly": true
        },
        {
          "id": "sampleItemField",
          "render": {
            "hide": [{"searchBy": "status"}],
            "show": [{"searchBy": "item"}]
          },
          "internalConfig": {
            "id": "sampleItemField",
            "title": "order-new-search.schematics.search.LABEL_NON_GENERAL_ITEM_SAMPLE",
            "type": "dropdownQuery"
          }
        },
        {
          "id": "sampleStatusField",
          "render": {
            "hide": [{"searchBy": "item"}],
            "show": [{"searchBy": "status"}]
          },
          "internalConfig": {
            "id": "sampleStatusField",
            "title": "order-new-search.schematics.search.LABEL_NON_GENERAL_STATUS_SAMPLE",
            "type": "dropdownQuery"
          }
        }
      ]
    }
  },
  "search-results": {
    "route": "/order-search/order/order-new-search-result",
    "breadcrumb": {
      "label": "Order Search Results"
    },
    "saveSearch": {
      "enabled": true
    },
    "pagination": {
      "type": "server-side",
      "defaultPageSize": 10
    },
    "refresh": {
      "enabled": false
    },
    "tableConfigJson": {
      "name": "order-new-table",
      "headers": [
        {
          "id": "orderNo",
          "name": "Order Number",
          "sortKey": "OrderNo",
          "dataBinding": "OrderNo"
        }
      ]
    }
  }
}

Metadados

nome: (Obrigatório) O nome base dos componentes gerados. Use este valor para nomear o painel de pesquisa, os resultados e os artefatos relacionados. Por exemplo, order-new-search.
displayName: (Obrigatório) O nome legível exibido nos registros e nos diagnósticos. Use este valor para tornar a saída do log mais fácil de entender.
módulo: (Opcional) O módulo Angular no qual os componentes estão registrados. Se você omitir esse valor, o esquema gera os componentes sem registrá-los em um módulo.
paths.component: (Obrigatório) O caminho onde o painel de pesquisa e os componentes de resultados são criados. Indique um caminho válido no projeto onde esses componentes devem estar localizados.
paths.table: (Obrigatório) O caminho onde o componente de tabela é criado. Use este caminho para armazenar a implementação da tabela gerada.
paths.jsonFile: (Obrigatório) O caminho onde os arquivos JSON de configuração estão armazenados. O esquema salva arquivos como search_fields.json e buc-table-config.json neste local.
paths.translationFile: (Obrigatório) O caminho para os arquivos de tradução. Use este caminho para atualizar ou criar arquivos de localização, como en.json.
options.sharedLib: (Obrigatório) O nome da biblioteca compartilhada. Este valor identifica a biblioteca compartilhada que contém lógica e recursos reutilizáveis.
options.routing: (Opcional) Ativar ou desativar o roteamento para os componentes gerados. O valor padrão é true. Defina este valor como false para ignorar a configuração de roteamento.
options.prefix: (Opcional) O seletor HTML a ser usado para os componentes gerados. O valor padrão é buc.

Parâmetros da API OMS

endpoints.search.apiName: (Obrigatório) O nome do método da API usado para solicitações de pesquisa. Por exemplo, getOrderList.
endpoints.search.method: (Opcional) O método ` HTTP ` para a solicitação da API. O valor padrão é POST.
requestMapping.pageNumber: (Opcional) O nome do parâmetro da API para o número da página. O valor padrão é PageNumber.
requestMapping.pageSize: (Opcional) O nome do parâmetro da API para o tamanho da página. O valor padrão é PageSize.
requestDefaults: (Opcional) Valores padrão incluídos em todas as solicitações de API. Use este objeto para passar parâmetros estáticos junto com cada solicitação.
responseMapping.data: (Opcional) O caminho JSON para a matriz de dados na resposta da API. O valor padrão é data.
responseMapping.totalCount: (Opcional) O caminho JSON para a contagem total de registros na resposta da API. O valor padrão é totalCount.

Parâmetros de Procura

fileName: (Opcional) O nome do arquivo para a configuração dos campos de pesquisa. O valor padrão é search_fields.json.
rota: (Opcional) O caminho do painel de pesquisa. Se você omitir esse valor, a rota será gerada automaticamente.
breadcrumb.label: (Opcional) O rótulo usado na navegação por trilha de navegação. Se você omitir esse valor, o rótulo será gerado automaticamente.
saveSearch.enabled: (Opcional) Ativar ou desativar a funcionalidade de salvar pesquisas. O valor padrão é true.
customizeSearchCriteria.preferenceName: (Opcional) A chave de preferências usada para armazenar as configurações do usuário. O valor padrão é o valor de metadata.name.
searchFieldsJson: (Opcional) O objeto de configuração do campo de pesquisa. O esquema utiliza dados de exemplo caso você não forneça um valor.; Observação: Na fields seção, é necessário atualizar as chaves de tradução dos títulos no arquivo de tradução. Use groups para permitir a configuração por meio de customizeSearchCriteria. Você pode definir um grupo para incluir todos os campos de uso geral.

parâmetros dos resultados da pesquisa

rota: (Opcional) O caminho da rota para a página de resultados da pesquisa. Se você omitir esse valor, a rota será gerada automaticamente.
breadcrumb.label: (Opcional) O rótulo usado na navegação por trilha de navegação. Se você omitir esse valor, o rótulo será gerado automaticamente.
saveSearch.enabled: (Opcional) Ativar ou desativar a opção de salvar a pesquisa na visualização de resultados. O valor padrão é true.
pagination.type: (Opcional) O modo de paginação utilizado para os resultados. O valor padrão é server-side. Os valores suportados incluem client-side e server-side.
pagination.defaultPageSize: (Opcional) O número padrão de registros exibidos por página. O valor padrão é 25.
pagination.strategy: (Opcional) A estratégia de paginação utilizada para carregar dados adicionais. O valor padrão é NEXTPAGE.
refresh.enabled: (Opcional) Ativar ou desativar a ação de atualização. O valor padrão é true.
fileName: (Opcional) O nome do arquivo para a configuração da tabela. O valor padrão é buc-table-config.json.
tableConfigJson: (Opcional) A configuração das colunas da tabela. O esquema utiliza dados de exemplo caso você não forneça um valor.

Recursos avançados

Use esses recursos avançados para ampliar sua experiência de pesquisa e dar suporte a cenários mais complexos. Essas opções ajudam a lidar com grandes conjuntos de dados, melhoram a usabilidade e evitam conflitos de configuração.

Estratégia de paginação NEXTPAGE

Caso de uso

Use essa estratégia quando precisar carregar a próxima página usando o último registro da página anterior como referência.

Configuração

{
  "search-results": {
    "pagination": {
      "type": "server-side"
    }
  }
}

Como isso funciona

Na primeira página, não é enviado nenhum registro anterior.
Para as páginas seguintes, a chave do último registro é enviada como PreviousPage.
O componente de tabela rastreia o último registro de cada página por meio de um mapa interno.

Integração da função “Salvar pesquisa”

Ative a opção “Salvar pesquisa” para permitir que os usuários armazenem e reutilizem critérios de pesquisa.

Comportamento

Quando saveSearch.enabled é definido como true, o esquema gera componentes com suporte integrado para salvar pesquisas.

Características geradas

Opção para salvar a pesquisa no painel de pesquisa.
Possibilidade de carregar pesquisas salvas.

Nomes de arquivos personalizados

Use nomes de arquivo personalizados ao gerenciar várias configurações de pesquisa no mesmo diretório.

Configuração

{
  "search": {
    "fileName": "order-advanced-search-fields.json"
  },
  "search-results": {
    "fileName": "order-advanced-table-config.json"
  }
}

Resultado

Utiliza nomes de arquivo personalizados em vez dos nomes padrão.
Ajuda a evitar conflitos entre várias configurações de pesquisa no mesmo local.