Come eseguire immediatamente il commit delle impostazioni

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Nelle app di Windows Store tutte le impostazioni vengono applicate appena l'utente ne modifica il valore. Questo modello è importante perché può mostrarti come eseguire immediatamente il commit delle impostazioni usando il riquadro a comparsa Impostazioni WinJS e i dati locali dell'applicazione.

Prerequisiti

Leggi le Linee guida per le impostazioni dell'app.

Aggiungere un riquadro a comparsa Impostazioni all'accesso alle impostazioni

Per maggiori dettagli su come aggiungere un riquadro a comparsa Impostazioni, vedi Guida introduttiva: Aggiunta di impostazioni app con la libreria Windows per JavaScript. Ma ecco un breve riepilogo.

Definisci l'HTML per il riquadro a comparsa Impostazioni:

<div aria-label="App Settings Flyout" data-win-control="WinJS.UI.SettingsFlyout" data-win-options="{settingsCommandId:'settingsExample', width:'narrow'}">
<!-- Add the background color matching you app tile color to the Settings flyout header. -->
<!-- Use add the win-ui-dark class if the background color requires a white text  -->
<!-- Add the app small logo to the Settings flyout header                         -->
    <div class="win-header win-ui-light" style="background-color: #dbf9ff;">
        <button class="win-backbutton" onclick="WinJS.UI.SettingsFlyout.show()" type="button"></button>
     <div class="win-label">Example</div>
     <img alt="smalllogo" src="/images/smalllogo.png" style="height: 30px; width: 30px; position: absolute; right: 40px;"/>
    </div>
    <div class="win-content">
    <!—Your settings contents go here -->
    </div>
</div>

Collega il riquadro a comparsa Impostazioni all'accesso alle impostazioni:

WinJS.Application.onsettings = function (e) {
    e.detail.applicationcommands = {
        "settingsExample": { title: "Example" }
    };
    WinJS.UI.SettingsFlyout.populateSettings(e);
};

Aggiungere controlli al riquadro a comparsa

In questo esempio aggiungiamo un controllo di attivazione/disattivazione e un controllo di selezione al riquadro a comparsa Impostazioni. Sono infatti i due controlli più usati per le impostazioni.

<div class="win-content">
    <div class="win-settings-section">
        <h3>Example settings section</h3>
        <p>Description: toggle and select are common settings controls</p>
        <div id="settingsToggle" data-win-control="WinJS.UI.ToggleSwitch" 
             data-win-options="{title:'Example toggle switch', 
             onchange: settingsToggleChange}"></div>
    </div>
    <div class="win-settings-section">
        <h3>Select control</h3>
        <p>Select controls let users select an item from a set of text only items.</p>
        <label>Example select control</label>
        <select id="settingsSelect" aria-label="Example select control">
            <option value="1">Value 1</option>
            <option value="2">Value 2</option>
            <option value="3">Value 3</option>
            <option value="4">Value 4</option>
        </select>
    </div>
</div>

Nota

Abbiamo aggiunto un'opzione di evento onchange all'attributo data-win-options di settingsToggle. Questo codice registra l'evento onchange per il controllo ToggleSwitch. Per maggiori dettagli, vedi Linee guida ed elenco di controllo per gli interruttori attiva/disattiva.
Le impostazioni sono incapsulate nelle classi CSS win-settings-section e usano gli elementi consigliati per ottenere uno stile allineato con le linee guida sulle impostazioni (vedi Linee guida per le impostazioni dell'app).

Inizializzare i controlli dall'archivio dei dati locali dell'app

In questo esempio usiamo l'archivio dei dati locali dell'app. Ogni volta che il riquadro a comparsa Impostazioni viene richiamato dall'utente, leggiamo i valori dei dati dell'app per verificare che i controlli dell'interfaccia utente rispecchino i valori più aggiornati.

function initSettingsControls() {
    // Initialize the toggle control using the current value of settingsToggleValue in the local state store
    var toggleControl = document.getElementById("settingsToggle").winControl;
    toggleControl.checked = (Windows.Storage.ApplicationData.current.localSettings.values["settingsToggleValue"] === "on");

    // Initialize the select control using the current value of settingsSelectValue in the locale state store
    var selectControl = document.getElementById("settingsSelect");
    var settingsSelectValue = Windows.Storage.ApplicationData.current.localSettings.values["settingsSelectValue"];
    for (var i = 0; i < selectControl.options.length; i++) {
        if (selectControl.options(i).value === settingsSelectValue) {
            selectControl.selectedIndex = i;
            break;
        }
    }

    // Add event listener for change event on select control
    selectControl.addEventListener("change", settingsSelectChange, false);
}

Nota

Verifichiamo quindi che l'inizializzazione dei controlli avvenga dopo il caricamento del DOM e l'inizializzazione dei controlli WinJS. Quando si usa un riquadro a comparsa Impostazioni definito nella propria pagina HTML, può essere necessario chiamare il metodo pageControlReady per verificare che il riquadro a comparsa sia pronto per l'uso.
Tieni presente che in questo esempio usiamo l'archivio dei dati locali dell'app. Potresti anche usare l'archivio dei dati mobili dell'applicazione per verificare che il roaming delle impostazioni venga eseguito automaticamente. Per maggiori dettagli, vedi Linee guida per il roaming dei dati dell'applicazione.

Gestire gli eventi di modifica ai controlli delle impostazioni

È qui che avviene veramente il commit immediato. Quando l'utente modifica i valori associati al controllo, scriviamo immediatamente il nuovo valore nell'archivio dei dati dell'app. Questa operazione viene eseguita nel gestore dell'evento onchange associato al controllo.

function settingsToggleChange() {
    var toggleControl = document.getElementById("settingsToggle").winControl;
    // Write new value to the local state store
    Windows.Storage.ApplicationData.current.localSettings.values["settingsToggleValue"] = (toggleControl.checked ? "on" : "off");
}

// To protect against untrusted code execution, all functions are required 
// to be marked as supported for processing before they can be used inside 
// a data-win-options attribute in HTML markup.
WinJS.Utilities.markSupportedForProcessing(settingsToggleChange);

function settingsSelectChange(changedEvent) {
    // Write new value to the local state store
    Windows.Storage.ApplicationData.current.localSettings.values["settingsSelectValue"] = changedEvent.target.options.value;
}

Riepilogo

In questa guida introduttiva hai imparato a eseguire il commit immediato degli aggiornamenti alle impostazioni.

Condividi tramite