Compartir a través de

Creación de un complemento de Office con una experiencia básica de primera ejecución

La implementación de una experiencia de primera ejecución ayuda a incorporar usuarios y resalta el valor del complemento. Este tutorial le guía a través de la adición de una experiencia de primera ejecución sencilla a su complemento de Office mediante el almacenamiento local para realizar un seguimiento de si el usuario ha iniciado previamente el complemento.

Nota:

La experiencia de primera ejecución es un patrón recomendado para complementos de Office. Ayuda a los usuarios a comprender las características del complemento y aumenta la interacción.

Lo que aprenderás

  • Cómo agregar una interfaz de usuario de primera ejecución al complemento.
  • Cómo usar el almacenamiento local del explorador para conservar el estado del usuario.
  • Cómo actualizar los archivos HTML, JavaScript y CSS del complemento para admitir la experiencia de primera ejecución.

Información general

Cuando un usuario abra el complemento por primera vez, mostrará un mensaje de bienvenida y una lista de características clave. En los inicios posteriores, el complemento omitirá la bienvenida y mostrará la interfaz de usuario principal. Para ello, compruebe si hay una marca en el almacenamiento local y actualice la interfaz de usuario en consecuencia.

En este tutorial se proporcionan instrucciones y capturas de pantalla de Excel, pero puede usar un patrón similar para implementar una experiencia de primera ejecución en otras aplicaciones de Office donde se admiten complementos web de Office.

Pasos

Siga estos pasos para implementar la experiencia de primera ejecución:

  1. Actualizar el código HTML: agregue un contenedor para la experiencia de primera ejecución.
  2. Actualizar JavaScript: compruebe el almacenamiento local y muestre la interfaz de usuario de primera ejecución si es necesario.
  3. Actualizar css: asegúrese de que la nueva interfaz de usuario tiene un estilo coherente.
  4. Probar el complemento: compruebe que la experiencia de primera ejecución funciona según lo esperado.

Comencemos

Sugerencia

Si desea una versión completa de este tutorial, visite el repositorio de ejemplos de complementos de Office en GitHub.

Requisitos previos

  1. Seleccione el inicio rápido de Yo Office para la aplicación de Office que desea usar.

  2. Siga las instrucciones del inicio rápido seleccionado. Una vez completada la sección "Pruébelo", vuelva aquí para continuar.

Implementación de la experiencia de primera ejecución

Actualización del archivo HTML

Tenga claro el área de la interfaz de usuario que formará parte de la experiencia de primera ejecución. En este tutorial, creará un <div> elemento con el id nombre "first-run-experience" que representa lo que los usuarios ven solo la primera vez que ejecutan el complemento.

  1. Abra el taskpane.html. Reemplace el <main> elemento por el marcado siguiente y guarde el archivo. Algunas notas sobre este marcado:

    • La "primera experiencia de ejecución" <div> se inserta en el <main> elemento . Rodea la lista de características de complementos de Office. De forma predeterminada, esto <div> no se muestra.
    • El primer <p> elemento proporciona al usuario instrucciones para usar el complemento.
    <main id="app-body" class="ms-welcome__main" style="display: none;">
    <div id="first-run-experience" style="display: none;">
        <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
        <ul class="ms-List ms-welcome__features">
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
                <span class="ms-font-m">Achieve more with Office integration</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Unlock ms-font-xl"></i>
                <span class="ms-font-m">Unlock features and functionality</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Design ms-font-xl"></i>
                <span class="ms-font-m">Create and visualize like a pro</span>
            </li>
        </ul>
    </div>
    <p class="ms-font-l">Select any range of cells in the worksheet, then click <b>Run</b>.</p>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
    <p><label id="item-subject"></label></p>    
</main>

  2. Si seleccionó una aplicación de Office además de Excel, actualice el primer <p> elemento con instrucciones más adecuadas.

Actualización del archivo JavaScript

Actualice el archivo JavaScript para mostrar la experiencia de primera ejecución si es la primera vez que el usuario ejecuta el complemento.

  1. Abra el archivo CustomStrings.js. Reemplace la Office.onReady instrucción por el código siguiente y, a continuación, guarde el archivo. Algunas notas sobre este código:

    • Comprueba el almacenamiento local en busca de una clave denominada "showedFRE". Si la clave no existe, muestre la experiencia de primera ejecución.
    • Agrega una nueva función denominada showFirstRunExperience que muestra la "primera experiencia de ejecución" <div> agregada al CÓDIGO HTML. Esta función también agrega el elemento "showedFRE" al almacenamiento local.
    Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";

    // showedFRE is created and set to "true" when you call showFirstRunExperience().
    if (!localStorage.getItem("showedFRE")) {
      showFirstRunExperience();
    }

    document.getElementById("run").onclick = run;
  }
});

async function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", true);
}

  2. Si seleccionó una aplicación de Office además de Excel, actualice la condición de la primera if instrucción para comprobar si ha elegido Office.HostType.

Actualización del archivo CSS

Actualice el archivo CSS para asegurarse de que la interfaz de usuario del complemento tenga el estilo adecuado, dada la adición de la "primera experiencia de ejecución" <div>.

  • Abra el archivo taskpane.css . Reemplace la línea .ms-welcome__main { por el código siguiente y, a continuación, guarde el archivo.

    .ms-welcome__main, .ms-welcome__main > div {

Pruébelo

  1. Asegúrese de que el servidor web se está ejecutando y que el complemento se ha cargado de forma local y, a continuación, abra el panel de tareas. Para obtener más información, consulte las instrucciones del inicio rápido que usó.

  2. Compruebe que el panel de tareas incluye la lista de características.

    Interfaz de usuario del panel de tareas del complemento en la primera ejecución.

  3. Cierre el panel de tareas y vuelva a abrirlo. Compruebe que el panel de tareas ya no muestra la lista de características.

    La interfaz de usuario del panel de tareas del complemento en la segunda ejecución.

Pasos siguientes

Enhorabuena, ha creado correctamente un complemento de panel de tareas de Office con una experiencia de primera ejecución.

Preparar la producción

Con este tutorial, implementó una experiencia básica de primera ejecución. Para que la experiencia de primera ejecución esté lista para los usuarios, debe tener en cuenta lo siguiente:

  • Actualice las características enumeradas en el marcador de valor para que coincidan con lo que realmente hace el complemento.
  • Implemente un patrón diferente (por ejemplo, placemat de vídeo o carrusel) que muestre mejor las ventajas del complemento.
  • Use una opción más segura y sólida para realizar el seguimiento del estado de primera ejecución. Por ejemplo, use la creación de particiones de almacenamiento si está disponible o implemente una solución de autenticación de inicio de sesión único (SSO).

Si va a hacer que el complemento esté disponible en Microsoft Marketplace, debe tener una experiencia de primera ejecución sólida y útil. Para obtener más información, consulte Best practices for developing Office Add-ins.

Ejemplos de código

Vea también

  • Last updated on