Zum Hauptinhalt springen
Última modificação: 8 de outubro de 2025
Você pode criar uma página de configurações baseadas em React para seu aplicativo na versão mais recente (2025.2) da plataforma para desenvolvedores, a qual os usuários que instalam seu aplicativo podem acessar e personalizar para suas contas. Este guia mostra como criar um componente de configurações, usando React, que substitui a experiência anterior de configurações. Se você implantar seu novo componente de configurações, os usuários que instalarem seu aplicativo no futuro verão imediatamente sua nova extensão de configurações em vez da página de configurações criada anteriormente. Antes de começar, siga o guia de início rápido para criar seu primeiro aplicativo na versão mais recente da plataforma para desenvolvedores.
Observação:Se você criou uma página de configurações para seu aplicativo, precisará refatorar suas configurações usando o novo recurso de extensões de interface. É recomendado que você anote todos os elementos da interface na versão de produção atual do seu aplicativo antes de começar a configurar seu novo componente de configurações na versão mais recente da plataforma para desenvolvedores. Depois de passar para o novo componente de configurações do seu aplicativo, você perderá o acesso à interface de configuração WYSIWYG que usava anteriormente.

​
Criar e configurar arquivos de componentes de configurações

Primeiro, em seu diretório /app, crie um diretório /settings/ e adicione os três arquivos a seguir nele: 
├──src
│   ├── app/
│   │   └── settings/
│   │     └── Settings.tsx
│   │     └── settings-hsmeta.json
│   │     └── package.json
└──
Edite esses três arquivos para incluir o código básico nos snippets abaixo.

​
Settings.tsx

import React from 'react';
import { EmptyState, Text } from '@hubspot/ui-extensions';
import { hubspot } from '@hubspot/ui-extensions';

hubspot.extend <
  'settings' >
  (({ context }) => {
    return <Settings context={context} />;
  });

const Settings = ({ context }) => {
  // TODO: Update this JSX code to include the components that fit your settings page.
  return (
    <EmptyState title="Nothing here yet!" layout="vertical">
      <Text>
        Contact '{context.extension.appName}' for upcoming development plans.
      </Text>
    </EmptyState>
  );
};

​
settings-hsmeta.json

{
  "uid": "settings_extension",
  "type": "settings",
  "config": {
    "entrypoint": "/app/settings/Settings.tsx"
  }
}

​
package.json

{
  "name": "hubspot-settings-extension",
  "version": "0.1.0",
  "license": "MIT",
  "dependencies": {
    "@hubspot/ui-extensions": "latest",
    "react": "^18.2.0"
  },
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

​
Carregar e instalar o componente de configurações

Para carregar o componente de configurações no projeto:
  • Em seu diretório app/, execute hs project install-deps para criar um arquivo package-lock.json, que acelerará a compilação da extensão de configurações carregada, bem como garantirá que todas as dependências em seus ambientes de desenvolvimento local e de produção correspondam.
  • Em seguida, execute hs project upload. Acesse a página de detalhes do seu projeto de desenvolvedor, navegando até Desenvolvimento > Projetos e, em seguida, clique no botão nome do seu projeto.
  • Seu componente de configurações agora deve estar listado na página de detalhes.
Componente de configurações carregado na página de detalhes do projeto

​
Exibir a página de configurações na sua conta de teste de desenvolvedor

  • Para verificar se o componente de configurações está funcionando corretamente, navegue até uma conta de teste de desenvolvedor onde você instalou seu aplicativo, clique no ícone do Marketplace e clique em Aplicativos conectados.
Acesse os aplicativos conectados na conta de teste de desenvolvedor
  • Clique no nome do seu aplicativo, o que deverá levá-lo para a página de configurações do aplicativo.
Estado vazio para componente de configurações básicas na conta de teste
Agora, você pode continuar criando seu componente de configurações como faria com um cartão de aplicativo. Todas as limitações existentes em relação à criação de extensões de interface também se aplicam à criação de uma página de configurações.
  • Use hubspot.fetch para aproveitar seu backend para salvar e recuperar configurações. Saiba mais sobre como usar essa abordagem na documentação antiga.
  • Verifique a documentação de referência sobre componentes padrão para saber como usar os componentes do React ao criar sua extensão, ou use o componente no Kit de design do Figma.
  • Use o comando hs project dev para criar iterativamente sua página de configurações e visualizar suas alterações localmente.

​
Melhores práticas do componente

As seções abaixo descrevem várias práticas recomendadas para ter em mente à medida que você desenvolve a experiência de configurações para seu aplicativo.

​
Organizar conteúdo

Se você tiver conteúdo suficiente em sua extensão de configurações para garantir a necessidade de separar e organizar todos os dados de configurações do usuário, considere o uso dos componentes Painel, Modal, Acordeão e Guias. Considere como você deseja apresentar e organizar suas configurações e os dados correspondentes que devem ser buscados para cada componente.

​
Guias

Se você estiver usando guias, utilize a variante default. A extensão de configurações já está contida em uma guia de variante incluída, e uma segunda camada de guias incluídas entrará em conflito visual com o design.
Exemplo de guias aninhadas na página de configurações
O seguinte snippet descreve como estruturar as guias. 
<Tabs>

<Tab title="First Tab">
<Text>Here is the content of the first tab.</Text>
</Tab>
<Tab title="Second Tab">
<Text>This is where the content of the second tab goes.</Text>
</Tab>

</Tabs>
⌘I