Ações no grupo
Declara o que o serviço pode fazer num grupo do okmigo — responder, sugerir publicação, enquete. Quem modera ativa e escolhe as capacidades; o okmigo confere e executa. O serviço nunca vê o grupo: recebe só uma referência opaca.
grupo← voltar para o guia de integração
Comece pelo catálogo Python: ele é a forma recomendada de escrever um aplicativo inteiro. A referência JSON vem depois e mostra a fronteira que o SDK gera, o crivo aceita e os renderizadores Web e Flutter reconstruem.
Três regras fecham o contrato. Campo
desconhecido some; capacidade desconhecida no servidor recusa a tela inteira;
cliente antigo ignora o que ainda não sabe desenhar. Ação nunca aponta URL:
ela nomeia uma operação, exceto okmigoAutorizar, que é a saída
controlada para o site do serviço.
Importe sempre de okmigo_cartao. Primitivas e
composições ficam no mesmo lugar e compilam para o contrato fechado.
Os grupos abaixo cobrem a árvore do aplicativo e os componentes de
tela. Enums aparecem ao lado do componente que configuram. Funções de
validação — validar, expandir,
relatorio e materializar_manifesto — são
ferramentas do ciclo de desenvolvimento, não componentes visuais.
Declara o que o serviço pode fazer num grupo do okmigo — responder, sugerir publicação, enquete. Quem modera ativa e escolhe as capacidades; o okmigo confere e executa. O serviço nunca vê o grupo: recebe só uma referência opaca.
grupoDeclara o aplicativo inteiro, suas rotas, o tema, as operações que alimentam cada tela e quais campos carregam documento.
AplicativoSuperficieTelaFonteConsultaDaFonteTemaNavegacaoDocumentoDeclaradoTelaResponsivaOrganiza conteúdo sem declarar pixels, CSS ou comportamento específico de plataforma.
TextoPapelDoTextoPainelSecaoAreaColunaFaixaFatoFatosEspacoAlinhamentoLarguraDaAreaAlturaDaSecaoTomDaSecaoCria fichas, métricas, estados vazios, etiquetas e indicadores de andamento.
FichaMetricaGradeDeMetricasEstadoVazioComAlternativaEtiquetaStatusTomDaEtiquetaProgressoBarraDeValorColeta dados com tipos e formatos conhecidos pelos renderizadores Web e Flutter.
FormularioFormularioContextualCampoTextoCampoNumeroCampoOcultoCampoDataCampoHoraCampoMesCampoMoedaCampoDocumentoCampoTelefoneCampoUrlCampoEtiquetasCampoComUnidadeCampoFormatadoFormatoDoCampoCobre seleção simples ou múltipla, autocomplete remoto, condições, quantidade e liga/desliga.
OpcaoEscolhaFormaDaEscolhaBuscaEscolhaMultiplaFormaDaEscolhaMultiplaEscolhaCondicionalRegraAoAlterarSeletorDeQuantidadeAlternanciaConsulta ou grava somente por operações declaradas; menus e confirmações não abrem uma saída lateral.
AcaoAcoesTipoDeAcaoEnfaseDaAcaoCartaoClicavelMenuDeAcoesConfirmacaoAlternarAlvoDeVisibilidadeEnviarEAvancarTroca conteúdo que já veio no cartão, sem rede e sem executar código do serviço.
AbaAbasFiltroSegmentadoExpansivelDialogoRegistra destinos internos, organiza muitas telas, busca em todo o app, adapta lista/detalhe e declara somente o estado de UI que pode ser restaurado.
RotaDestinoDaRotaParametroDaRotaTipoDeParametroDaRotaCabecalhoDaTelaNavegacaoAgrupadaGrupoDeNavegacaoIndicadorDeNavegacaoEstadoDoIndicadorMestreDetalheFluxoEtapaDoFluxoBuscaDoAplicativoTipoDeResultadoDaBuscaEstadoRestauravelPersistenciaDoEstadoHistoricoDeNavegacaoExpande dados com limites fechados e apresenta conteúdo denso com degradação previsível.
RepetirCondicaoTabelaTabelaFlexivelLinhaDeTabelaCelulaDeTabelaPaginacaoMostra mídia acessível, recebe e entrega arquivos, copia valores e controla autorizações.
ImagemAlturaDaImagemGaleriaDeImagensArquivoFormatoDeArquivoDocumentoCopiarConviteDoGrupoCronometroAutorizarMostra número com contexto: ranking com o critério à vista, tendência com rótulo, comparação lado a lado sem nota final, agenda por data e o estado de um dado que pode estar velho.
RankingItemDeRankingMinigraficoComparadorItemComparadoCriterioComparadoAgendaItemDaAgendaEstadoDoCompromissoCabecalhoDeDetalheEstadoDoDadoEstadoDaInformacaoRepresenta datas, eventos, gestos de agenda e etapas de um processo.
CalendarioVistaDoCalendarioEventoTipoDeEventoNavegacaoDoCalendarioAoTocarODiaAcaoDoEventoGestoDoEventoLinhaDoTempoEtapaDaLinhaDoTempoEstadoDaEtapaDeclara significado dos dados; os clientes escolhem cor, escala e adaptação por plataforma.
GraficoFormaDoGraficoSeriePontoTomDoGraficoCartoesFinanceirosCartaoFinanceiroListaFinanceiraLancamentoFinanceiroDistribuicaoItemDeDistribuicaoTomFinanceiroSemanticaFinanceiraTipa capacidades do produto e ajuda a migrar manifestos antigos sem tornar o adaptador a fonte final.
OperacaoParametrizadaConviteMarcaSolicitadaContatoAceitoCatalogoPublicoMarcaHorarioTelaResumidaPainelResumidoItemResumidoAplicativoDoContratoDeclara um agente que entende o domínio do produto, com competências, ferramentas de leitura da conversa, instruções curtas e orçamento. Valida as quatro respostas: respondido, precisa_esclarecer, acao_proposta e indisponivel.
AgenteDeDominioOrcamentoExemploAgenteInvalidovalidar_respostaRespostaDeAgenteInvalidaDeclara o que o app é dono, de quem recebe e para quem entrega pelo okmigo, o vocabulário e as falas de quem usa — o que o broker lê para mandar o pedido ao app DONO. O crivo avisa o que falta no cadastro e confere os dois lados das relações.
PapelRelacaoExemploDeRoteamentoPapelInvalidoavisos_do_cadastropares_que_nao_batemExpande dados fictícios, executa o crivo, explica perdas e materializa o manifesto para registro.
ConfigContratoDoSdkInvalidovalidarexpandirrelatoriocascamanifesto_conferematerializar_manifestoRegra de autoria: uma tela nova usa somente
objetos exportados por okmigo_cartao. Dicionário cru fica
restrito ao adaptador temporário AplicativoDoContrato. Se uma
intenção ainda não existir, ela entra primeiro no SDK, crivo, Web, Flutter,
acessibilidade, fallbacks e testes.
Os exemplos usam a API pública atual e podem ser copiados para o módulo de autoria do seu produto.
from okmigo_cartao import Acao, CampoTexto, Formulario, Tela
PERFIL = Tela(
"Perfil",
(
Formulario(
"Dados básicos",
campos=(
CampoTexto(
"nome_perfil", "nome", "Nome", obrigatorio=True
),
),
acoes=(Acao.escrever("Salvar", "salvar_perfil"),),
),
),
)
PERFIL.conferir(escrituras={"salvar_perfil"})
from okmigo_cartao import (
Acao, CartaoClicavel, Confirmacao, MenuDeAcoes, Texto
)
ativo = CartaoClicavel(
(Texto("SANB11", negrito=True), Texto("R$ 28,10")),
Acao.consultar("Abrir SANB11", "detalhar_ativo"),
menu=MenuDeAcoes((
Acao.escrever(
"Remover dos favoritos",
"remover_favorito",
icone="lixeira",
confirmacao=Confirmacao(
"Remover favorito?",
"Você poderá adicioná-lo novamente depois.",
"Remover",
),
),
)),
)
from okmigo_cartao import (
Acao, BuscaDoAplicativo, CabecalhoDaTela, ConsultaDaFonte, Fonte,
ParametroDaRota, Rota, TipoDeResultadoDaBusca,
)
cabecalho = CabecalhoDaTela(
"Cliente",
"Detalhe seguro, sem URL livre",
acao_principal=Acao.navegar(
"Abrir cliente", "cliente", parametros={"id": "cli-42"}
),
)
# Dentro de Aplicativo(...)
rotas = (Rota("cliente", "detalhe", (ParametroDaRota("id"),)),)
# Na superfície "detalhe": a fonte pede o parâmetro da rota pelo marcador.
fonte = Fonte(ConsultaDaFonte("detalhar_cliente", pedido={"cliente": "{rota.id}"}))
busca = BuscaDoAplicativo(
"buscar_tudo",
(TipoDeResultadoDaBusca("cliente", "Cliente", "cliente", "clientes"),),
placeholder="Buscar cliente ou pedido",
)
from okmigo_cartao import (
Calendario, DestinoDaRota, Evento, NavegacaoDoCalendario,
VistaDoCalendario,
)
agenda = Calendario(
eventos=(Evento("{inicio}", "{titulo}", id="{id}"),),
vista=VistaDoCalendario.MES,
vistas=(
VistaDoCalendario.DIA,
VistaDoCalendario.SEMANA,
VistaDoCalendario.MES,
VistaDoCalendario.AGENDA,
),
de="{periodo_de}",
ate="{periodo_ate}",
hora_inicial=8,
hora_final=20,
ao_navegar_periodo=NavegacaoDoCalendario(
DestinoDaRota("agenda_periodo", {}),
parametro="periodo",
),
)
Para ver navegação real entre superfícies, dados fictícios, claro, escuro, desktop e celular, siga o exemplo de aplicativo completo ou abra o catálogo que acompanha o pacote:
python -m okmigo_cartao preview exemplos/sdk_catalogo.py:APLICATIVO
Use esta parte para entender a fronteira, criar um
renderer ou investigar a saída de compilar(); para autoria
nova, prefira os componentes Python acima.
AdaptiveCardA raiz de uma tela declarativa. Sem ela, o crivo recusa o cartão.
typeversionbodyokmigoTemaokmigoNavegacaoCuidados: Use okmigoTema/okmigoNavegacao só quando a natureza da experiência pedir. Temas aceitos: financeiro-violeta, jornada-ativa, mercado-editorial e operacao-direta. O cliente escolhe a aparência; tema desconhecido é ignorado. O resto do topo também é ignorado.
TextBlockTexto, título, legenda e frase de apoio.
textsizeweightisSubtlewraphorizontalAlignmentfallbackCuidados: Cor não passa. Se precisar de estado, use texto ou tom na caixa que carrega o texto.
ContainerAgrupa blocos, cria painéis, tiles, etapas e áreas tocáveis.
itemsstyleidisVisibleminHeightselectActionokmigoGradeokmigoSobrepostofallbackCuidados: selectAction só alterna visibilidade. okmigoGrade aceita true, larga, compacta ou etiquetas.
ColumnSetColunas simples dentro de uma mesma linha visual.
columnsColumn.itemsColumn.widthColumn.styleColumn.minHeightfallbackCuidados: Use auto só para conteúdo de tamanho conhecido; texto imprevisível deve ser stretch.
TableGrade tabular quando as colunas precisam alinhar entre linhas.
columnsrowsTableRowTableCellfirstRowAsHeadershowGridLinesfallbackCuidados: Teto de 16 colunas por 200 linhas. Cabeçalho sem dado derruba a tabela, então declare fallback.
FactSetPares curtos de rótulo e valor.
facts.titlefacts.valuefallbackCuidados: Fato sem título some; sem fatos, o bloco inteiro some.
ImageImagem servida pelo domínio do OkMigo.
urlheightaltTextfallbackCuidados: URL de terceiro é recusada. Use /img/... ou URL absoluta nossa; sem imagem válida vira marcador.
Input.TextCampo de texto que viaja no submit da própria caixa.
idcampolabelvalueplaceholderisMultilineisRequiredmaxLengthokmigoSomenteLeituraCuidados: id é estado do cliente; campo é o nome enviado ao serviço. Número aqui pode ser interpretado errado.
Input.NumberCampo numérico com teclado e validação de número.
idcampolabelvalueplaceholderisRequiredminmaxokmigoSomenteLeituraCuidados: Use para peso, preço, quantidade e qualquer valor que precise continuar número.
Input.ChoiceSetEscolha única por lista, fichas tocáveis ou busca filtrada.
idcampolabelchoicesvaluestyleisRequiredokmigoEstritookmigoQuemOperaokmigoNotaokmigoIconeCuidados: filtered sozinho é livre; filtered + okmigoEstrito só aceita opção da lista. okmigoQuemOpera é preenchido pelo OkMigo.
ActionSetConjunto de botões que alternam visibilidade ou enviam formulário.
actionsokmigoRodapefallbackCuidados: Botões sem ação válida somem. Rodapé prende o CTA ao pé da tela enquanto a caixa dele estiver visível.
Action.ToggleVisibilityMostra e esconde blocos que já estão no cartão.
titletargetElementselementIdisVisibleCuidados: Não toca rede, não grava e não navega. É a base de abas, etapas e voltar dentro do cartão.
Action.SubmitEnvia os campos da própria caixa para uma operação do serviço.
titledata.operacaostylemodeokmigoAposEnviarCuidados: A operação precisa estar no contrato de escrita. okmigoAposEnviar só aceita ToggleVisibility explícito.
Action.ExecuteConsulta uma operação de leitura com os campos da própria caixa e recebe outra ficha.
titledata.operacaostylemodeCuidados: A operação precisa estar no contrato de leitura; a ficha retornada atravessa o mesmo crivo.
okmigoArquivoEntrada de arquivo, porque Adaptive Cards não tem Input.File.
idcampolabelaceitamaxBytesisRequiredCuidados: aceita usa palavras: pdf, imagem, xml, planilha, texto. Palavra desconhecida some.
okmigoDocumentoArquivo do serviço para a pessoa ver ou baixar.
titulonometipotamanholer.operacaoler.pedidoCuidados: A operação de ler precisa ser leitura declarada. PDF e imagem abrem na própria tela.
okmigoCopiarBotão para copiar um valor: Pix, código de barras, protocolo.
rotulovalorCuidados: Sem valor, some. Não chama serviço e não sai do app.
okmigoConviteDoGrupoConvidar para o grupo do okmigo que nasceu de uma coisa do serviço (a turma do GrupoIn).
rotulorefCuidados: O ref é o mesmo de okmigo_grupos_nascem. O okmigo gera o link ao toque, só para quem pode convidar; o serviço nunca vê o link nem o grupo.
okmigoGraficoGráfico de barras ou linha para poucas séries.
formatituloseries.rotuloseries.corpontos.rotulopontos.valoresCuidados: Cores são semânticas: positivo, negativo, neutro, atencao, principal, suave. Não existe pizza.
okmigoCalendarioCalendário declarativo com eventos e gestos locais.
vistavistasdeatehoraInicialhoraFinaleventosaoTocarODiaacoesDoEventoaoNavegarPeriodoCuidados: Um toque abre formulário ou mostra bloco; não escreve sozinho. Evento sem id desenha, mas não aceita ação. `aoNavegarPeriodo` pede outro período por uma rota declarada (NavegacaoDoCalendario); cliente que não a conhece mostra só o período recebido.
okmigoAutorizarA única ida permitida para um endereço do serviço, normalmente OAuth ou autorização.
urlrotulomotivoCuidados: URL precisa ser https, sem credencial embutida, sem IP/porta e nunca domínio do OkMigo.
okmigoCronometroContagem regressiva dentro do cartão.
rotulosegundosCuidados: Faixa de 1 a 3600 segundos. Não começa sozinho; a pessoa inicia.
okmigoProgressoBarra de progresso do tipo feito de total.
feitoderotulotomCuidados: Recebe números, nunca porcentagem pronta. de inválido some; feito fora da faixa é prensado.
okmigoCabecalhoDaTelaTopo consistente de tela ou detalhe, com voltar, favorito, ação principal e menu.
titulosubtitulovariantevoltaracaoPrincipalfavoritardesfavoritarmenuCuidados: Navegação só usa rota registrada; favorito só usa escrita declarada. O renderer decide a adaptação.
okmigoMestreDetalheLista e detalhe lado a lado quando cabe, ou uma etapa por vez no celular.
idlistadetalhevazioselecionadoCuidados: Lista e detalhe passam integralmente pelo crivo e contam no teto de nós.
okmigoFluxoFluxo de 2 a 12 etapas com progresso, retomada e cancelamento explícito.
idetapasatualtokenDeRetomadapersistircancelarCuidados: O cliente apresenta a etapa; avançar e persistir continuam sendo operações declaradas.
okmigoCartaoBancarioCartão financeiro com fatura, limite e lançamentos.
cartoestitulonumerofaturalimiteprogresso_feitoprogresso_delancamentosCuidados: Use só no tema financeiro-violeta. Está público para transparência, mas não é bloco genérico.
okmigoDistribuicaoDistribuição financeira por categoria ou fatia.
tituloitens.rotuloitens.valoritens.textoitens.tomCuidados: Bloco específico do Financeiro. Itens sem rótulo ou valor somem.
okmigoListaFinanceiraLista de lançamentos financeiros com busca e filtros.
buscafiltrositens.iditens.grupoitens.tipoitens.tituloitens.valoritens.semanticaCuidados: Bloco específico do Financeiro. semantica fora de positivo/negativo/neutro cai em neutro.