Skip to content
🛠 Kohandatud välja lisamine WordPressi seadetesse: add_settings_field
WordPressVeebiarendus
6 min1,153 sõna

🛠 Kohandatud välja lisamine WordPressi seadetesse: add_settings_field

Standard WordPressi seaded katavad enamiku igapäevaseid toiminguid. Kuid varem või hiljem on vaja välja, mida administraatoris ei eksisteeri: ettevõtte telefoninumber üldiste seadete jaotises, teenuse API-võti, litsentsinumbri väli või jaluse tekst.

Teema- ja pluginarendajad lahendavad selle Settings API abil, mis on WordPressi funktsioonide komplekt oma jaotiste ja väljade registreerimiseks standardsetel seadete lehtedel. Peamine neist on add_settings_field(): see lisab kohandatud välja määratud jaotisse ja lehele.

Selle õpetuse lõpuks on sul töötav kood, mis kuvab administraatoris tekstivälja, salvestab väärtuse andmebaasi ja näitab seda saidil. Ei mingeid kolmanda osapoole pluginaid, ainult sisseehitatud API.

💡 Kiire ülevaade:

  • Valmista keskkond ette: loo alamteema või paigalda Code Snippets plugin, et su kood ei kustuks peateema uuendamisel.
  • Registreeri seade: kutsu register_setting() admin_init konksul, vastasel juhul WordPress välja andmeid ei salvesta.
  • Lisa jaotis ja väli: kasuta add_settings_section() uue ploki jaoks ja add_settings_field() sisendvälja jaoks selle sees.
  • Väljasta väärtus: kasuta get_option() mallis ükskõik kus, et kuvada salvestatud andmeid saidil.

Mis on add_settings_field ja kus seda kasutatakse

Funktsioon add_settings_field() ilmus WordPress 2.7.0-s ja on sellest ajast peale jäänud peamiseks tööriistaks seadete lehtede laiendamisel. Vastavalt WordPressi dokumentatsioonile lisab see uue välja olemasolevasse jaotisse ühel administraatori lehtedest.

Mida see praktikas tähendab. Sa saad kuvada lisavälja igal standardsel lehel: Üldine (general), Kirjutamine (writing), Lugemine (reading), Arutelu (discussion) või Meedia (media). Ja kui sa lõid oma seadete lehe add_options_page() kaudu, läheb väli ka sinna.

Tüüpilised stsenaariumid:

  • „Kontakttelefoni" väli üldiste seadete jaotises, et haldur ei peaks numbri uuendamiseks koodi puutuma.
  • API-võtme väli sinu pluginile, kus kasutaja sisestab võtme administraatoris, selle asemel et redigeerida wp-config.php.
  • Väljade grupp kohandatud jaotise jaoks (telefon, e-post, aadress), kasutades add_settings_section() pluss mitut add_settings_field() väljakutset.

Märkus: add_settings_field() väljastab ainult välja HTML-i. Tegeliku salvestamise eest hoolitseb register_setting(); ilma selleta ignoreerib WordPress sisestatud andmeid.

Add_settings_field süntaks ja parameetrid

Funktsiooni signatuur, neli kohustuslikku ja kaks valikulist parameetrit:

1add_settings_field(
2    string $id,
3    string $title,
4    callable $callback,
5    string $page,
6    string $section = 'default',
7    array $args = array()
8);

Vaatame iga parameetrit lähemalt.

$id, unikaalne välja identifikaator. Sellest väärtusest saab HTML id atribuut <input> sildil, mille sa callback-funktsioonis väljastad. Kasuta prefiksit, et vältida konflikte, näiteks myplugin_phone_number.

$title, välja silt, mida kuvatakse administraatoris sisendist vasakul. Kirjuta see selgelt: „Kontakttelefon", „Teenuse API-võti".

$callback, sinu funktsiooni nimi, mis väljastab välja HTML-i (input, textarea, select). See on koht, kus sa kirjutad echo. Funktsioon peab olema eelnevalt deklareeritud; anna see edasi stringina: 'my_field_callback'.

$page, seadete lehe tunnus (slug). Standardsed väärtused: general, reading, writing, discussion ja media. Kui lõid kohandatud lehe, kasuta selle tunnust. Määrab, kus väli kuvatakse.

$section (valikuline), selle jaotise tunnus, kuhu väli kuulub. Vaikimisi 'default', mis on lehe kõige ülemine jaotis. Kui lõid oma jaotise add_settings_section() kaudu, määra selle ID siin.

$args (valikuline), massiiv lisaseadetest. Toetatud võtmed on label_for (HTML for atribuudi väärtus <label> sildil) ja class (CSS klass välja ümbrisel).

Kõik parameetrid ja nende käitumine on kirjeldatud ametlikus Settings API juhendis WordPress.org-is.

Praktiline näide: tekstivälja lisamine üldistesse seadetesse

Paneme kõik kokku. Eesmärk: kuvada „Kontakttelefoni" tekstiväli lehel Seaded → Üldine, salvestada sisestatud väärtus ja tuua see get_option() abil.

Kood läheb alamteema functions.php faili või Code Snippets plugina kaudu. Teine variant on turvalisem: koodijupp ei kustu teema uuendamisel.

1// Callback to output the section description
2function my_custom_section_callback() {
3    echo 'Contact information for the organization. Phone number is displayed in the site footer.';
4}
5 
6// Callback to output the input field
7function my_phone_field_callback() {
8    $value = get_option( 'my_contact_phone', '' );
9    echo '<input 
10        name="my_contact_phone" 
11        type="text" 
12        id="my_contact_phone" 
13        value="' . esc_attr( $value ) . '" 
14        class="regular-text" 
15        placeholder="+1 (555) 123-4567" 
16    />';
17}
18 
19// Register the section and field
20function my_register_settings() {
21    // Register the setting — without this, data will not be saved
22    register_setting( 'general', 'my_contact_phone' );
23 
24    // Add a section to the General settings page
25    add_settings_section(
26        'my_contact_section',            // Section ID
27        'Contact Information',            // Section title
28        'my_custom_section_callback',    // Callback for description
29        'general'                         // Page slug
30    );
31 
32    // Add a field to the section
33    add_settings_field(
34        'my_contact_phone',              // Field ID
35        'Contact Phone',                  // Field label
36        'my_phone_field_callback',       // Callback to render the field
37        'general',                        // Page slug
38        'my_contact_section'             // Section ID
39    );
40}
41add_action( 'admin_init', 'my_register_settings' );

Mis siin rida-realt toimub. register_setting() ütleb WordPressile: salvesta my_contact_phone välja väärtus sättena wp_options tabelisse, kui lehel general vajutatakse „Salvesta muudatused".

add_settings_section() loob uue ploki pealkirjaga „Organisatsiooni kontaktid" üldiste seadete lehel. Callback my_custom_section_callback() väljastab kirjelduse teksti jaotise väljade kohal.

add_settings_field() paigutab meie välja sellesse jaotisse ja seob selle callbackiga my_phone_field_callback(), mis renderdab <input type="text">. Funktsioon get_option() sisestab salvestatud väärtuse value atribuuti ja esc_attr() väldib väljundi.

Kogu kood on haagitud admin_init külge, mis käivitub administraatori laadimisel ja tagab, et jaotis ja väli on seadete lehe renderdamise ajaks juba registreeritud.

Pärast koodi lisamist ava wp-admin/options-general.php ja sa näed tulemust:

Sisesta number, klõpsa Salvesta muudatused ja väärtus kirjutatakse andmebaasi. Telefoninumbri kuvamiseks saidil kasuta get_option() ükskõik kus mallis:

1$phone = get_option( 'my_contact_phone', '' );
2if ( $phone ) {
3    echo '<a href="tel:' . esc_attr( $phone ) . '">' . esc_html( $phone ) . '</a>';
4}

Kuhu kood panna ja kuidas testida

Kolm paigutusvarianti, halvimast parimani.

Peateema (functions.php). Ära tee seda. Kui teema uueneb, kirjutatakse fail üle ja sinu kohandus kaob.

*Alamteema (alamteema functions.php).* Toimiv variant konkreetse saidiga seotud muudatuste jaoks. Kood säilib peateema uuendamisel.

Code Snippets plugin. Parim valik testimiseks ja pikaajaliseks hoolduseks. Sa saad koodijupi ühe klõpsuga lubada/keelata, ilma failisüsteemi puutumata. Lisaks saad isolatsiooni: kui koodijupp põhjustab fataalse vea, deaktiveerib WordPress selle automaatselt ja sait ei lähe maha.

Testimise protseduur. Loo täielik saidi varukoopia (andmebaas + failid), see on standardne ettevaatusabinõu igaks administraatori muudatuseks. Lisa kood, kasutades valitud meetodit. Ava seadete leht ja veendu, et väli kuvatakse. Sisesta väärtus ja salvesta. Kontrolli püsivust: värskenda lehte, väli peaks olema täidetud sellega, mille sisestasid.

Kui väli ei ilmu, kontrolli, et sa ei ajasid jaotise ID segamini add_settings_field() parameetris $section. Levinud viga: jaotis luuakse ühe ID-ga, kuid väljale antakse teine.

Videoõpetus teemal

Materjali kinnistamiseks vaata WordPressi arendaja videoülevaadet Settings API-st. See näitab täistsüklit: jaotise registreerimine, välja lisamine, salvestamine ja saidil väljastamine.

⁉️🤔 Korduma kippuvad küsimused

Kas ma saan ühte jaotisse mitu välja lisada?

Jah. Kutsu add_settings_field() nii mitu korda, kui palju välju vajad. Anna parameetris $section sama jaotise ID. Iga väli saab unikaalse $id ja oma callbacki. add_settings_field() väljakutsete järjekord määrab väljade järjekorra lehel.

Kuidas lisada tekstivälja asemel select, textarea või checkbox?

Välja tüüp määratakse callback-funktsiooni sees HTML-i abil. Selecti jaoks ehita <select> koos <option> siltidega; textarea jaoks <textarea> silt; checkboxi jaoks <input type="checkbox">. Väärtus salvestatakse samamoodi register_setting() kaudu ja tuuakse get_option() abil. Erinevused on ainult HTML-is.

Kas ma pean callbackis väljundit vältima (escape)?

Jah, kindlasti. Kasuta atribuutide väärtuste (value, name, id) jaoks esc_attr() ja siltide vahel oleva teksti jaoks esc_html(). See kaitseb XSS-i eest ja tagab, et salvestatud väärtuses olevad erimärgid ei lõhu kujundust.

Kas ma saan lisada välja oma plugina lehele?

Jah. Loo leht add_options_page() või add_menu_page() kaudu, seejärel registreeri jaotised ja väljad samamoodi. Kasuta oma lehe tunnust add_settings_field() parameetris $page. Mehaanika ei erine standardsetest lehtedest.

Mis siis, kui väärtus ei salvestu pärast „Salvesta muudatused" klõpsamist?

Peaaegu kindlasti jätsid register_setting() vahele. Ilma selle funktsioonita ei tea WordPress, et väli tuleb salvestada, ja ignoreerib seda saatmisel. Kontrolli: register_setting() esimene parameeter peab ühtima lehe nimega (nt 'general') ja teine peab ühtima sinu välja name atribuudiga.

Kokkuvõte: millal on administraatori seadete laiendamine mõistlik

WordPressi Settings API on küps ja stabiilne mehhanism: add_settings_field() ei ole alates versioonist 2.7 muutunud ja on jätkuvalt asjakohane aastal 2026. Oma väljade lisamine administraatorisse on õigustatud kolmel juhul:

  • Sa arendad teemat või pluginat ja soovid anda kasutajale liidese andmete sisestamiseks, ilma koodi redigeerimata.
  • Sa vajad saidi taseme seadevälja (telefoninumber, API-võti, kataloogi ID) ja see peaks olema ligipääsetav administraatori kaudu, mitte wp-config.php kaudu.
  • Sa kohandad kliendi saiti ja soovid, et haldur saaks ise andmeid muuta, ilma arendajaga ühendust võtmata.

Kui väli on ainult sulle ja muutub kord aastas, on lihtsam väärtus koodi sisse kirjutada. Settings API särab seal, kus seadeid kasutab keegi teine peale arendaja.

Alusta lihtsalt: lisa üks tekstiväli, järgides ülaltoodud näidet. Kui oled omandanud põhivoo, registreerimine, callback, salvestamine, väljastamine, liigu edasi valikute, väljagruppide ja kohandatud seadete lehtede juurde. Ja millise väljatüübiga sina kõige sagedamini töötad? Anna meile teada kommentaarides.

Toimetus
ToimetusToimetuse meeskond→ Kõik publikatsioonid

Professionaalne kirjanike ja toimetajate meeskond, kes on spetsialiseerunud kvaliteetse sisu loomisele.