--- title: "Estender o customizer de temas WordPress em 5 passos" description: "Estender o customizer de temas WordPress é adicionar opções próprias ao painel de personalização nativo, usando a Customize API em vez de plugins." url: https://full.services/estender-o-customizer-de-temas-wordpress/ date: 2026-06-28 author: "Clayton Margiotti" --- # Estender o customizer de temas WordPress em 5 passos **Estender o customizer de temas WordPress** significa registrar painéis, seções, configurações e controles próprios no hook customize_register. Segundo o [WordPress Theme Handbook](https://developer.wordpress.org/themes/customize-api/) (2026), a Customize API expõe quatro objetos para live-preview de qualquer mudança. O transport postMessage atualiza a prévia em milissegundos, sem recarregar a página. Comece pelo objeto WP_Customize_Manager e valide cada controle antes de salvar. Estender o customizer de temas WordPress é adicionar opções próprias ao painel de personalização nativo, usando a Customize API em vez de plugins genéricos. O processo gira em torno do hook customize_register e do objeto WP_Customize_Manager, que recebe seus painéis, seções, configurações e controles. A vantagem é dar ao cliente um editor visual com prévia ao vivo, sem expô-lo a código. Neste guia técnico você vai registrar um controle do zero, escolher entre transport refresh e postMessage e sanitizar cada valor antes de gravar. Para uma visão geral do tema antes de mexer no código, consulte os [conteúdos de temas WordPress da FULL](https://full.services/temas-wordpress/). --- ## Primeiros passos: O que é o customizer e quando estendê-lo O customizer do WordPress é o framework de personalização ao vivo que roda em `/wp-admin/customize.php` e existe no core desde a versão 3.4 (2012). Ele organiza opções em quatro objetos: painéis, seções, configurações e controles. Estender o customizer faz sentido quando seu tema precisa de opções que o editor de blocos ainda não cobre, como uma cor de marca global ou um texto de rodapé editável pelo cliente. A escolha entre estender o customizer ou usar o editor de blocos (FSE) depende do tema. Temas clássicos como Astra dependem do customizer; temas de bloco migram parte das opções para `theme.json`. A tabela abaixo resume os quatro objetos da Customize API.
Objetos da Customize API: função e método de registro
Objeto Função Método no WP_Customize_Manager
PanelAgrupa várias seções relacionadasadd_panel()
SectionContêiner de UI para controlesadd_section()
SettingGuarda, valida e faz live-preview do valoradd_setting()
ControlCampo visível (cor, texto, imagem) ligado a um settingadd_control()

Legenda: uma seção própria com controle de cor registrada via customize_register, com prévia ao vivo à direita.

--- ## Passo a passo: Como estender o customizer de temas WordPress Registrar opções no customizer leva cerca de 20 minutos para um controle simples e segue sempre a mesma sequência: engatar no hook, criar a hierarquia (painel e seção), declarar a configuração com sanitização e ligar um controle a ela. Os 5 passos abaixo cobrem o ciclo completo, do hook ao front-end. Todo o código para estender o customizer de temas WordPress vai no arquivo functions.php do tema ou, idealmente, num [child theme](https://full.services/glossario/child-theme/) para sobreviver a atualizações. Cada passo abaixo é um H3 sob este único H2 HowTo, como manda a estrutura de um tutorial que ensina a estender o customizer de temas WordPress do começo ao fim. ### Passo 1: Engate no hook customize_register O ponto de entrada é o hook `customize_register`, que entrega o objeto `$wp_customize` (uma instância de WP_Customize_Manager). Adicione a ação no [functions.php](https://full.services/glossario/functions-php/): `add_action( 'customize_register', 'meutema_customize_register' );`. Dentro da função, todos os métodos `add_panel()`, `add_section()`, `add_setting()` e `add_control()` ficam disponíveis. Esse é o único lugar correto para registrar opções, porque o WordPress dispara esse hook só quando o customizer está sendo construído. É daqui que parte todo o trabalho de estender o customizer de temas WordPress. ### Passo 2: Crie o painel e a seção Com o `$wp_customize` em mãos, declare a hierarquia visual. Use `$wp_customize->add_section( 'meutema_cores', array( 'title' => 'Cores da marca', 'priority' => 30 ) );` para criar a seção. Se você tem muitas seções, agrupe-as antes com `add_panel()`. A propriedade `priority` controla a ordem de exibição: valores menores sobem na lista. Seções sem nenhum controle associado não aparecem no painel, então registre o controle do Passo 4 antes de testar. ### Passo 3: Registre a configuração com sanitização Cada opção precisa de um setting, e todo setting exige um `sanitize_callback`. Declare assim: `$wp_customize->add_setting( 'meutema_cor_primaria', array( 'default' => '#0073aa', 'sanitize_callback' => 'sanitize_hex_color', 'transport' => 'postMessage' ) );`. O campo `default` define o valor inicial; o `sanitize_callback` limpa a entrada antes de gravar no banco. Pular a sanitização abre brecha de segurança, um dos erros que mais aparecem nos tickets de tema que chegam ao suporte da FULL. ### Passo 4: Ligue um controle ao setting O controle é o campo visível que o cliente manipula. Ligue-o ao setting do Passo 3: `$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'meutema_cor_primaria', array( 'label' => 'Cor primária', 'section' => 'meutema_cores' ) ) );`. O WordPress traz controles prontos para cor, imagem, upload e texto. Para campos mais ricos, a biblioteca [Kirki e outros plugins de personalização](https://full.services/melhores-plugins-de-personalizacao-para-wordpress/) estendem a API com toggles, sliders e seletores de tipografia sem reescrever a classe base. ### Passo 5: Aplique o valor no front-end Recuperar o valor salvo no tema leva uma linha: `echo esc_attr( get_theme_mod( 'meutema_cor_primaria', '#0073aa' ) );`. Use sempre uma função de escape (`esc_attr`, `esc_html`, `esc_url`) conforme o contexto. Para que a prévia atualize ao vivo com transport postMessage, enfileire um arquivo JavaScript que escute a mudança do setting e injete o novo valor no DOM via `wp.customize`. Sem esse JS, o postMessage não tem efeito visível e o controle parece quebrado. Com esse passo, você fecha o ciclo de estender o customizer de temas WordPress: do registro à exibição no site. --- ## Transport refresh ou postMessage: Como decidir A propriedade `transport` define como a prévia reage à mudança e aceita só 2 valores: `refresh` (padrão) recarrega a página inteira em cada ajuste, em torno de 300 a 800 ms por reload, enquanto `postMessage` atualiza apenas o elemento alvo via JavaScript, em poucos milissegundos. A diferença de experiência é grande: um seletor de cor com refresh pisca a tela a cada clique; com postMessage, a cor muda instantaneamente. O custo do postMessage é o trabalho extra de escrever o JavaScript de live-preview, então ele não vale a pena para toda opção. Para valores raramente alterados, como um número de telefone no rodapé, o `refresh` resolve sem código adicional. Para cores, fontes e espaçamentos que o cliente fica testando, o postMessage vale o esforço. A regra prática que aplicamos na FULL é simples: se a opção muda a aparência visual e o cliente vai iterar, use postMessage; se é texto pontual, mantenha refresh. Escolher o transport certo é metade do trabalho de estender o customizer de temas WordPress com boa experiência de uso. --- ## Selective refresh: O meio-termo que poucos usam O selective refresh é um terceiro caminho entre `refresh` e `postMessage`, introduzido no WordPress 4.5 (2016), e resolve a maior parte dos casos com uma fração do código. Em vez de escrever JavaScript completo, você registra um "partial" que rerenderiza só um pedaço da página no servidor. O resultado é quase tão rápido quanto o postMessage, mas sem manter lógica de renderização duplicada em PHP e JS. O registro usa `$wp_customize->selective_refresh->add_partial()` com dois argumentos centrais: `selector`, que aponta o elemento no DOM (por exemplo `'.site-description'`), e `render_callback`, a função PHP que devolve o novo HTML. Quando o setting muda, o WordPress chama o callback no servidor e troca só aquele trecho. Temas como Astra e o próprio Twenty Twenty usam selective refresh para títulos e widgets. É o caminho que mais economiza manutenção a longo prazo ao estender o customizer de temas WordPress, porque a verdade da renderização continua num lugar só: o PHP. --- ## Erros comuns ao estender o customizer de temas WordPress Quase metade dos problemas de customizer que chegam ao suporte da FULL nasce de 3 deslizes técnicos, não de bugs do WordPress. O primeiro é registrar o setting sem `sanitize_callback`: o valor entra cru no banco e o WordPress 5.x passou a barrar isso silenciosamente, deixando o campo "sem efeito". O segundo erro é editar o functions.php do tema-pai diretamente: na próxima atualização, todo o código some, porque o tema-pai é sobrescrito por inteiro. Por isso o child theme não é luxo, é requisito. O terceiro erro recorrente é confundir `get_theme_mod()` com `get_option()`. O customizer grava valores via theme_mods, atrelados ao tema ativo; ao trocar de tema, as opções somem. A correção é deliberada: para dados que devem sobreviver à troca de tema, use a Options API com `get_option()`; para aparência ligada ao tema, mantenha `get_theme_mod()`. Antes de publicar qualquer alteração, vale também [verificar alterações suspeitas no tema](https://full.services/como-verificar-alteracoes-suspeitas-no-tema-wordpress/) para descartar código injetado. --- ## Acelere com a plataforma FULL Estender o customizer de temas WordPress à mão dá controle total, mas exige manter PHP, JavaScript e sanitização em dia em cada site. No plano PRO da FULL, por R$849 (cerca de R$85 por site no bundle de 10), você ativa em um clique os plugins que cobrem essa camada, incluindo Astra PRO e bibliotecas de personalização, e ganha o suporte de quem vê esse tipo de ticket todo dia. Em vez de reescrever a Customize API e estender o customizer de temas WordPress em cada projeto, a gente entrega o ambiente pronto, com os temas e addons já licenciados e atualizados. Para uma agência que mantém dezenas de sites, o tempo economizado em cada configuração de tema costuma pagar o plano sozinho. Conheça os [planos da FULL](https://full.services/planos) e compare com o custo de configurar tudo manualmente, site a site. --- ## Perguntas frequentes sobre estender o customizer
Como adicionar uma seção nova ao customizer do WordPress?

Você adiciona uma seção chamando `$wp_customize->add_section()` dentro de uma função engatada no hook customize_register. Passe um ID único e um array com `title` e `priority`. A seção só aparece no painel depois que pelo menos um controle é associado a ela via add_control. Sem controle, o WordPress oculta a seção vazia automaticamente.

É possível estender o customizer sem editar o functions.php do tema-pai?

Sim, e é o caminho recomendado para estender o customizer de temas WordPress com segurança. Crie um child theme e coloque toda a lógica de customize_register no functions.php do tema-filho. Assim, atualizações do tema-pai não apagam seu código. Como alternativa, um plugin próprio também registra opções no customizer, já que o hook customize_register funciona de qualquer contexto carregado pelo WordPress.

Por que minha configuração do customizer não atualiza a prévia ao vivo?

Na maioria dos casos, o setting está com `transport` definido como postMessage, mas falta o JavaScript que escuta a mudança e atualiza o DOM. O postMessage não recarrega a página, então sem o `wp.customize` no front-end nada muda visualmente. A correção rápida é trocar para transport refresh ou registrar um selective refresh partial com selector e render_callback.

Qual a diferença entre get_theme_mod e get_option no customizer?

O `get_theme_mod()` lê valores atrelados ao tema ativo, gravados via theme_mods; ao trocar de tema, esses dados não acompanham. O `get_option()` lê da Options API, persistente independentemente do tema. Use theme_mod para aparência ligada ao tema e option para dados que devem sobreviver à troca de tema, como uma chave de API.

O customizer ainda vale a pena com o editor de blocos e FSE?

Sim, para temas clássicos e opções globais. Temas de bloco migram cor e tipografia para o `theme.json` e o editor de site, mas o customizer continua vivo para temas clássicos como Astra e para opções que o FSE não cobre, como integrações de terceiros. Em 2026, a maioria dos sites WordPress ainda roda tema clássico, então dominar a Customize API segue sendo relevante.

--- ## Próximos passos para dominar a personalização de temas Estender o customizer de temas WordPress é menos sobre decorar a API e mais sobre seguir os 5 passos na ordem certa: engate no customize_register, crie a seção, registre o setting com sanitização e ligue um controle, em cerca de 20 minutos por opção. Escolha o transport pela frequência de uso e prefira selective refresh quando quiser velocidade sem manter código duplicado. Com esses fundamentos, estender o customizer de temas WordPress deixa de ser tentativa e erro e vira um processo repetível em qualquer projeto. Antes de avançar para temas de bloco, vale entender bem [o que acontece quando você muda seu tema](https://full.services/o-que-acontece-quando-voce-muda-seu-tema-wordpress/) e como editar o visual com segurança. Para continuar aprendendo, o [FULL Academy](https://full.services/academy/) reúne tutoriais, guias e reviews de WordPress num só lugar. --- ## Metadados Estruturados (Schema.org) ```json-ld { "@context": "https://schema.org", "@graph": [ { "@type": "TechArticle", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#article", "headline": "Estender o customizer de temas WordPress em 5 passos", "description": "Estender o customizer de temas WordPress é adicionar opções próprias ao painel de personalização nativo, usando a Customize API em vez de plugins genéricos.", "url": "https://full.services/estender-o-customizer-de-temas-wordpress/", "datePublished": "2026-06-28T09:00:00-03:00", "dateModified": "2026-06-28T09:00:00-03:00", "inLanguage": "pt-BR", "articleSection": "Temas WordPress", "keywords": [ "estender o customizer de temas wordpress", "WordPress Themes", "Web Design", "WordPress Templates" ], "author": { "@id": "https://full.services/#person-clayton" }, "publisher": { "@id": "https://full.services/#org" }, "about": [ { "@type": "Thing", "name": "WordPress Themes" }, { "@type": "Thing", "name": "Web Design" }, { "@type": "Thing", "name": "WordPress Templates" } ], "mentions": [ { "@type": "Organization", "name": "WordPress", "url": "https://wordpress.org/", "@id": "https://www.wikidata.org/wiki/Q13166", "sameAs": "https://www.wikidata.org/wiki/Q13166" } ], "mainEntityOfPage": { "@type": "WebPage", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/" }, "wordCount": 2233, "citation": [ { "@type": "CreativeWork", "name": "WordPress Developer Docs", "url": "https://developer.wordpress.org/themes/customize-api/", "publisher": { "@type": "Organization", "name": "WordPress Developer Docs" } } ] }, { "@type": "FAQPage", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq", "isPartOf": { "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#article" }, "mainEntity": [ { "@type": "Question", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq-q1", "name": "Como adicionar uma seção nova ao customizer do WordPress?", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Você adiciona uma seção chamando `$wp_customize->add_section()` dentro de uma função engatada no hook customize_register. Passe um ID único e um array com `title` e `priority`. A seção só aparece no painel depois que pelo menos um controle é associado a ela via add_control. Sem controle, o WordPress oculta a seção vazia automaticamente.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq-q2", "name": "É possível estender o customizer sem editar o functions.php do tema-pai?", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Sim, e é o caminho recomendado para estender o customizer de temas WordPress com segurança. Crie um child theme e coloque toda a lógica de customize_register no functions.php do tema-filho. Assim, atualizações do tema-pai não apagam seu código. Como alternativa, um plugin próprio também registra opções no customizer, já que o hook customize_register funciona de qualquer contexto carregado pelo WordPress.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq-q3", "name": "Por que minha configuração do customizer não atualiza a prévia ao vivo?", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Na maioria dos casos, o setting está com `transport` definido como postMessage, mas falta o JavaScript que escuta a mudança e atualiza o DOM. O postMessage não recarrega a página, então sem o `wp.customize` no front-end nada muda visualmente. A correção rápida é trocar para transport refresh ou registrar um selective refresh partial com selector e render_callback.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq-q4", "name": "Qual a diferença entre get_theme_mod e get_option no customizer?", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "O `get_theme_mod()` lê valores atrelados ao tema ativo, gravados via theme_mods; ao trocar de tema, esses dados não acompanham. O `get_option()` lê da Options API, persistente independentemente do tema. Use theme_mod para aparência ligada ao tema e option para dados que devem sobreviver à troca de tema, como uma chave de API.", "author": { "@id": "https://full.services/#org" } } }, { "@type": "Question", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#faq-q5", "name": "O customizer ainda vale a pena com o editor de blocos e FSE?", "inLanguage": "pt-BR", "acceptedAnswer": { "@type": "Answer", "text": "Sim, para temas clássicos e opções globais. Temas de bloco migram cor e tipografia para o `theme.json` e o editor de site, mas o customizer continua vivo para temas clássicos como Astra e para opções que o FSE não cobre, como integrações de terceiros. Em 2026, a maioria dos sites WordPress ainda roda tema clássico, então dominar a Customize API segue sendo relevante.", "author": { "@id": "https://full.services/#org" } } } ] }, { "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://full.services/" }, { "@type": "ListItem", "position": 2, "name": "Temas WordPress", "item": "https://full.services/temas-wordpress/" }, { "@type": "ListItem", "position": 3, "name": "Estender o customizer de temas WordPress em 5 passos", "item": "https://full.services/estender-o-customizer-de-temas-wordpress/" } ] }, { "@type": "Organization", "@id": "https://full.services/#org", "name": "FULL Services", "url": "https://full.services", "logo": { "@type": "ImageObject", "url": "https://full.services/wp-content/uploads/full-services-logo.png", "width": 200, "height": 60 }, "sameAs": [ "https://www.instagram.com/fullservicesbr", "https://www.facebook.com/fullservices.br", "https://www.linkedin.com/company/fullservicesbr/" ], "knowsAbout": [ "WordPress", "WordPress Hosting", "Web Development", "Performance Optimization", "WordPress Security", "SEO para WordPress" ], "award": [ "Gold Medal - The WP Weekly Awards 2023 (https://thewpweekly.com/awards-2023/)", "Gold Medal - The WP Weekly Awards 2024 (https://thewpweekly.com/awards-2024/)" ], "hasCredential": { "@type": "EducationalOccupationalCredential", "credentialCategory": "certification", "name": "CVE Numbering Authority (CNA)", "description": "Autoridade de numeração de vulnerabilidades (CVE) para o ecossistema WordPress, autorizada a atribuir IDs CVE. Certificação válida desde 2022-05-03, com abrangência global.", "url": "https://www.cve.org/PartnerInformation/ListofPartners/partner/FULL", "recognizedBy": { "@type": "Organization", "name": "CISA — Cybersecurity and Infrastructure Security Agency", "url": "https://www.cisa.gov/", "sameAs": "https://www.cisa.gov/" } } }, { "@type": "Person", "@id": "https://full.services/#person-clayton", "name": "Clayton Margiotti", "givenName": "Clayton", "familyName": "Margiotti", "jobTitle": "Fundador e CEO da FULL Services", "description": "Fundador e CEO da FULL Services, plataforma WordPress SaaS com 50 mil clientes e 150 mil sites conectados, e anchor do ecossistema Elevor Global. Em 2024 conduziu a FULL a se tornar a primeira e unica empresa brasileira aprovada como CVE Numbering Authority sob a CISA (DHS/EUA). Mais de 20 anos construindo empresas digitais, com 13+ reconhecimentos internacionais (Facebook, GPTW, ONU, RD Summit).", "url": "https://full.services/sobre-nos/", "image": "https://full.services/wp-content/uploads/2026/05/clayton-margiotti.jpg", "sameAs": [ "https://www.linkedin.com/in/cmargiotti/" ], "knowsAbout": [ "Artificial Intelligence", "Cybersecurity", "CVE Program", "WordPress Enterprise", "SaaS Platforms", "Digital Infrastructure", "Technology Entrepreneurship", "Company Building", "Business Leadership", "Digital Growth" ], "hasOccupation": { "@type": "Occupation", "name": "Fundador e CEO", "occupationalCategory": "11-1011.00" }, "knowsLanguage": [ { "@type": "Language", "name": "Portuguese", "alternateName": "pt-BR" }, { "@type": "Language", "name": "English", "alternateName": "en" } ], "memberOf": { "@type": "Organization", "name": "CVE Numbering Authorities", "url": "https://www.cve.org/", "sameAs": "https://www.cve.org/" }, "alumniOf": [ { "@type": "EducationalOrganization", "name": "Global Scaling Academy (Blitzscaling Program)", "url": "https://www.blitzscalingacademy.com" }, { "@type": "EducationalOrganization", "name": "Esade", "url": "https://www.esade.edu" }, { "@type": "EducationalOrganization", "name": "Business School Sao Paulo (BSP)", "url": "https://bsp.edu.br/" }, { "@type": "EducationalOrganization", "name": "Tera", "url": "https://somostera.com" }, { "@type": "EducationalOrganization", "name": "Le Wagon", "url": "https://www.lewagon.com" }, { "@type": "EducationalOrganization", "name": "FIAP", "url": "https://www.fiap.com.br" }, { "@type": "EducationalOrganization", "name": "PUCRS", "url": "https://online.pucrs.br/" } ], "award": [ "Digital Disruptor – Engaging Experiences Master (Globant, 2021)", "Maior ROI do e-commerce brasileiro – Letrissimas (Facebook, 2019)", "1º lugar – Melhores Empresas para Trabalhar no Brasil – Eleva Digital (Great Place to Work, 2018)", "Case global de educacao no Facebook – Metodo SUPERA (Facebook, 2017)", "Maquina de Geracao de Leads, Agencia do Ano (RD Summit / RD Station, 2015)", "Monthly Recurring Revenue, top performance (RD Summit / RD Station, 2015)", "Quality/Efficiency – Entrepreneurship Training (UNCTAD / PNUD-ONU, 2010)" ], "subjectOf": [ { "@type": "NewsArticle", "url": "https://www.globant.com/news/globant-reveals-inaugural-digital-disruptors-award-winners", "publisher": { "@type": "Organization", "name": "Globant" } }, { "@type": "NewsArticle", "url": "https://www.prnewswire.com/news-releases/letrissimas-com-e-destaque-do-e-commerce-brasileiro-com-maior-roi-de-2018-877517801.html", "publisher": { "@type": "Organization", "name": "PR Newswire" } }, { "@type": "NewsArticle", "url": "https://www.segs.com.br/seguros/102599-gestao-de-pessoas-garante-mais-lucro-as-empresas", "publisher": { "@type": "Organization", "name": "Segs" } }, { "@type": "NewsArticle", "url": "https://franquiaeducacional.com/negocios-inovadores-facebook-elege-supera-case-mundial-de-educacao", "publisher": { "@type": "Organization", "name": "Franquia Educacional" } }, { "@type": "NewsArticle", "url": "https://acontecendoaqui.com.br/marketing/resultados-digitais-divulga-vencedores-do-premio-agencias-de-resultados-2015-durante-o-rd", "publisher": { "@type": "Organization", "name": "Acontecendo Aqui" } } ], "worksFor": { "@type": "Organization", "@id": "https://full.services/#org" } }, { "@type": "HowTo", "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#howto", "isPartOf": { "@id": "https://full.services/estender-o-customizer-de-temas-wordpress/#article" }, "name": "Passo a passo: estender o customizer de temas wordpress", "description": "Guia passo a passo sobre estender o customizer de temas wordpress para WordPress.", "url": "https://full.services/estender-o-customizer-de-temas-wordpress/", "totalTime": "PT30M", "author": { "@type": "Organization", "@id": "https://full.services/#org" }, "step": [ { "@type": "HowToStep", "position": 1, "name": "Passo 1: Engate no hook customize_register", "text": "O ponto de entrada é o hook `customize_register`, que entrega o objeto `$wp_customize` (uma instância de WP_Customize_Manager). Adicione a ação no functions.php: `add_action( 'customize_register', 'meutema_customize_register' );`. Dentro da função, todos os métodos `add_panel()`, `add_section()`, `add_setting()` e `add_control()` ficam disponíveis. Esse é o único lugar correto para registrar opções, porque o WordPress dispara esse hook só quando o customizer está sendo construído. É daqui que parte todo o trabalho de estender o customizer de temas WordPress." }, { "@type": "HowToStep", "position": 2, "name": "Passo 2: Crie o painel e a seção", "text": "Com o `$wp_customize` em mãos, declare a hierarquia visual. Use `$wp_customize->add_section( 'meutema_cores', array( 'title' => 'Cores da marca', 'priority' => 30 ) );` para criar a seção. Se você tem muitas seções, agrupe-as antes com `add_panel()`. A propriedade `priority` controla a ordem de exibição: valores menores sobem na lista. Seções sem nenhum controle associado não aparecem no painel, então registre o controle do Passo 4 antes de testar." }, { "@type": "HowToStep", "position": 3, "name": "Passo 3: Registre a configuração com sanitização", "text": "Cada opção precisa de um setting, e todo setting exige um `sanitize_callback`. Declare assim: `$wp_customize->add_setting( 'meutema_cor_primaria', array( 'default' => '#0073aa', 'sanitize_callback' => 'sanitize_hex_color', 'transport' => 'postMessage' ) );`. O campo `default` define o valor inicial; o `sanitize_callback` limpa a entrada antes de gravar no banco. Pular a sanitização abre brecha de segurança, um dos erros que mais aparecem nos tickets de tema que chegam ao suporte da FULL." }, { "@type": "HowToStep", "position": 4, "name": "Passo 4: Ligue um controle ao setting", "text": "O controle é o campo visível que o cliente manipula. Ligue-o ao setting do Passo 3: `$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'meutema_cor_primaria', array( 'label' => 'Cor primária', 'section' => 'meutema_cores' ) ) );`. O WordPress traz controles prontos para cor, imagem, upload e texto. Para campos mais ricos, a biblioteca Kirki e outros plugins de personalização estendem a API com toggles, sliders e seletores de tipografia sem reescrever a classe base." }, { "@type": "HowToStep", "position": 5, "name": "Passo 5: Aplique o valor no front-end", "text": "Recuperar o valor salvo no tema leva uma linha: `echo esc_attr( get_theme_mod( 'meutema_cor_primaria', '#0073aa' ) );`. Use sempre uma função de escape (`esc_attr`, `esc_html`, `esc_url`) conforme o contexto. Para que a prévia atualize ao vivo com transport postMessage, enfileire um arquivo JavaScript que escute a mudança do setting e injete o novo valor no DOM via `wp.customize`. Sem esse JS, o postMessage não tem efeito visível e o controle parece quebrado. Com esse passo, você fecha o ciclo de estender o customizer de temas WordPress: do registro à exibição no site. --- A propriedade `transport` define como a prévia reage à mudança e aceita só 2 valores: `refresh` (padrão) recarrega a página inteira em cada ajuste, em torno de 300 a 800 ms por reload, enquanto `postMessage` atualiza apenas o elemento alvo via JavaScript, em poucos milissegundos. A diferença de experiência é grande: um seletor de cor com refresh pisca a tela a cada clique; com postMessage, a cor muda instantaneamente. O custo do postMessage é o trabalho extra de escrever o JavaScript de live-preview, então ele não vale a pena para toda opção. Para valores raramente alterados, como um número de telefone no" } ] } ] } ```