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

Artículo
09/06/2024

En este artículo, le guiará por el proceso de actualización de un complemento de panel de tareas para incluir una experiencia de primera ejecución con el patrón de marcador de valor. Cuando el usuario ejecuta el complemento, el complemento determina si se va a mostrar o no la experiencia de primera ejecución comprobando el almacenamiento local para obtener una marca.

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.

Sugerencia

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

Requisitos previos

Seleccione el inicio rápido de Yo Office para la aplicación de Office que desea usar.
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
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.

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>

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.

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);
}

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

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ó.
Compruebe que el panel de tareas incluye la lista de características.
Cierre el panel de tareas y vuelva a abrirlo. Compruebe que el panel de tareas ya no muestra la lista de características.

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). Para obtener más información sobre las opciones de configuración disponibles, consulte Persist add-in state and settings (Conservar el estado y la configuración del complemento). Para más información sobre las opciones de autenticación disponibles, consulte Información general sobre la autenticación y la autorización.

Si va a hacer que el complemento esté disponible en el marketplace de AppSource, tendrá que 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

Tutorial de la experiencia de primera ejecución completada: el resultado de completar este tutorial con Excel.

Compartir a través de