Compartir a través de


Inicio rápido: administrar citas (HTML)

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

Mediante el espacio de nombres Windows.ApplicationModel.Appointments, puedes crear y administrar citas en la aplicación de calendario de un usuario. Aquí te mostraremos cómo crear una cita, agregarla a la aplicación de calendario, reemplazarla en dicha aplicación y quitarla de ella. También te enseñaremos cómo mostrar un intervalo de tiempo para una aplicación de calendario y crear un objeto de repetición de citas. La administración de citas se admite a partir de Windows 8.1.

Aquí hacemos referencia a la muestra de API de citas. Este ejemplo muestra el modo en que se administran las citas mediante la API del espacio de nombres Windows.ApplicationModel.Appointments desde aplicaciones Windows en tiempo de ejecución.

Requisitos previos

  • Te recomendamos que estés familiarizado con Microsoft Visual Studio y sus plantillas asociadas.
  • Te recomendamos que estés familiarizado con el desarrollo con JavaScript.

Crear una cita y aplicarle datos

Crea un objeto Windows.ApplicationModel.Appointments.Appointment y asígnale una variable. Después, aplica a la Appointment las propiedades de cita suministradas por un usuario mediante la interfaz de usuario.

    function createAppointment() {
        var isAppointmentValid = true;
        var appointment = new Windows.ApplicationModel.Appointments.Appointment();

        // StartTime
        var startTime = document.querySelector('#startDatePicker').winControl.current;
        var time = document.querySelector('#startTimePicker').winControl.current;
        startTime.setMinutes(time.getMinutes());
        startTime.setHours(time.getHours());
        appointment.startTime = startTime;

        // Subject
        appointment.subject = document.querySelector('#subjectInput').value;

        if (appointment.subject.length > 255) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The subject cannot be greater than 255 characters.";
        }

        // Location
        appointment.location = document.querySelector('#locationInput').value;;

        if (appointment.location.length > 32768) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The location cannot be greater than 32,768 characters.";
        }

        // Details
        appointment.details = document.querySelector('#detailsInput').value;

        if (appointment.details.length > 1073741823) {
            isAppointmentValid = false;
            document.querySelector('#result').innerText = "The details cannot be greater than 1,073,741,823 characters.";
        }

        // Duration
        if (document.querySelector('#durationSelect').selectedIndex === 0) {
            // 30 minute duration is selected
            appointment.duration = (30 * 60 * 1000);
        } else {
            // 1 hour duration is selected
            appointment.duration = (60 * 60 * 1000);
        }

        // All Day
        appointment.allDay = (document.querySelector('#allDayCheckBox').checked);

        // Reminder
        if (document.querySelector('#reminderCheckBox').checked) {
            switch (document.querySelector('#reminderSelect').selectedIndex) {
                case 0:
                    appointment.reminder = (15 * 60 * 1000);
                    break;
                case 1:
                    appointment.reminder = (60 * 60 * 1000);
                    break;
                case 2:
                    appointment.reminder = (24 * 60 * 60 * 1000);
                    break;
            }
        }

        //Busy Status
        switch (document.querySelector('#busyStatusSelect').selectedIndex) {
            case 0:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.busy;
                break;
            case 1:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.tentative;
                break;
            case 2:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.free;
                break;
            case 3:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.outOfOffice;
                break;
            case 4:
                appointment.busyStatus = Windows.ApplicationModel.Appointments.AppointmentBusyStatus.workingElsewhere;
                break;
        }

        // Sensitivity
        switch (document.querySelector('#sensitivitySelect').selectedIndex) {
            case 0:
                appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.public;
                break;
            case 1:
                appointment.sensitivity = Windows.ApplicationModel.Appointments.AppointmentSensitivity.private;
                break;
        }

        // Uri
        var uriValue = document.querySelector('#uriInput').value;
        if (uriValue.length > 0) {
            try {
                appointment.uri = new Windows.Foundation.Uri(uriValue);
            }
            catch (e) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The Uri provided is invalid.";
            }
        }

        // Organizer
        // Note: Organizer can only be set if there are no invitees added to this appointment.
        if (document.querySelector('#organizerRadioButton').checked) {
            var organizer = new Windows.ApplicationModel.Appointments.AppointmentOrganizer();

            // Organizer Display Name
            organizer.displayName = document.querySelector('#organizerDisplayNameInput').value;

            if (organizer.displayName.length > 256) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The organizer display name cannot be greater than 256 characters.";
            } else {
                // Organizer Address (e.g. Email Address)
                organizer.address = document.querySelector('#organizerAddressInput').value;

                if (organizer.address.length > 321) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The organizer address cannot be greater than 321 characters.";
                } else if (organizer.address.length === 0) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The organizer address must be greater than 0 characters.";
                } else {
                    appointment.organizer = organizer;
                }
            }
        }

        // Invitees
        // Note: If the size of the Invitees list is not zero, then an Organizer cannot be set.
        if (document.querySelector('#inviteeRadioButton').checked) {
            var invitee = new Windows.ApplicationModel.Appointments.AppointmentInvitee();

            // Invitee Display Name
            invitee.displayName = document.querySelector('#inviteeDisplayNameInput').value;

            if (invitee.displayName.length > 256) {
                isAppointmentValid = false;
                document.querySelector('#result').innerText = "The invitee display name cannot be greater than 256 characters.";
            } else {
                // Invitee Address (e.g. Email Address)
                invitee.address = document.querySelector('#inviteAddressInput').value;

                if (invitee.address.length > 321) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The invitee address cannot be greater than 321 characters.";
                } else if (invitee.address.length === 0) {
                    isAppointmentValid = false;
                    document.querySelector('#result').innerText = "The invitee address must be greater than 0 characters.";
                } else {
                    // Invitee Role
                    switch (document.querySelector('#inviteeRoleSelect').selectedIndex) {
                        case 0:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.requiredAttendee;
                            break;
                        case 1:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.optionalAttendee;
                            break;
                        case 2:
                            invitee.role = Windows.ApplicationModel.Appointments.AppointmentParticipantRole.resource;
                            break;
                    }

                    // Invitee Response
                    switch (document.querySelector('#inviteeResponseSelect').selectedIndex) {
                        case 0:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.none;
                            break;
                        case 1:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.tentative;
                            break;
                        case 2:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.accepted;
                            break;
                        case 3:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.declined;
                            break;
                        case 4:
                            invitee.response = Windows.ApplicationModel.Appointments.AppointmentParticipantResponse.unknown;
                            break;
                    }

                    appointment.invitees.append(invitee);
                }
            }
        }

        if (isAppointmentValid) {
            document.querySelector('#result').innerText = "The appointment was created successfully and is valid.";
        }
    }

Agregar una cita al calendario del usuario

Crea un objeto Windows.ApplicationModel.Appointments.Appointment y asígnale una variable. Después, llama al método AppointmentManager.ShowAddAppointmentAsync(Appointment, Rect, Placement) para mostrar la interfaz de usuario para agregar citas del proveedor de citas predeterminado para permitir que el usuario agregue una cita. Si el usuario hizo clic en Agregar, la muestra imprime el identificador de citas que ShowAddAppointmentAsync devolvió.

    function addAppointment(e) {
        // Create an Appointment that should be added the user's appointments provider app.
        var appointment = new Windows.ApplicationModel.Appointments.Appointment();

        // Get the selection rect of the button pressed to add this appointment
        var boundingRect = e.srcElement.getBoundingClientRect();
        var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

        // ShowAddAppointmentAsync returns an appointment id if the appointment given was added to the user's calendar.
        // This value should be stored in app data and roamed so that the appointment can be replaced or removed in the future.
        // An empty string return value indicates that the user canceled the operation before the appointment was added.
        Windows.ApplicationModel.Appointments.AppointmentManager.showAddAppointmentAsync(appointment, selectionRect, Windows.UI.Popups.Placement.default)
            .done(function (appointmentId) {
                if (appointmentId) {
                    document.querySelector('#result').innerText = "Appointment Id: " + appointmentId;
                } else {
                    document.querySelector('#result').innerText = "Appointment not added";
                }
            });
    }

Reemplazar una cita en el calendario del usuario

Crea un objeto Windows.ApplicationModel.Appointments.Appointment y asígnale una variable. Después, llama al método AppointmentManager.ShowReplaceAppointmentAsync apropiado para mostrar la interfaz de usuario de reemplazo de citas del proveedor de citas predeterminado para permitir que el usuario reemplace una cita. El usuario también brinda el identificador de citas que quiere reemplazar. Este identificador se devolvió desde AppointmentManager.ShowAddAppointmentAsync. Si el usuario hizo clic en Reemplazar, la muestra imprime que actualizó ese identificador de citas.

    function replaceAppointment(e) {
        // The appointment id argument for ReplaceAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
        var appointmentIdOfAppointmentToReplace = document.querySelector('#appointmentIdInput').value;

        if (!appointmentIdOfAppointmentToReplace) {
            document.querySelector('#result').innerText = "The appointment id cannot be empty";
        } else {
            // The Appointment argument for ReplaceAppointmentAsync should contain all of the Appointment's properties including those that may have changed.
            var appointment = new Windows.ApplicationModel.Appointments.Appointment();

            // Get the selection rect of the button pressed to replace this appointment
            var boundingRect = e.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            // ReplaceAppointmentAsync returns an updated appointment id when the appointment was successfully replaced.
            // The updated id may or may not be the same as the original one retrieved from AddAppointmentAsync.
            // An optional instance start time can be provided to indicate that a specific instance on that date should be replaced
            // in the case of a recurring appointment.
            // If the appointment id returned is an empty string, that indicates that the appointment was not replaced.
            if (document.querySelector('#instanceStartDateCheckBox').checked) {
                // Replace a specific instance starting on the date provided.
                var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;

                Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
                     appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
                    .done(function (updatedAppointmentId) {
                        if (updatedAppointmentId) {
                            document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
                        } else {
                            document.querySelector('#result').innerText = "Appointment not replaced";
                        }
                    });
            } else {
                // Replace an appointment that occurs only once or in the case of a recurring appointment, replace the entire series.
                Windows.ApplicationModel.Appointments.AppointmentManager.showReplaceAppointmentAsync(
                     appointmentIdOfAppointmentToReplace, appointment, selectionRect, Windows.UI.Popups.Placement.default)
                    .done(function (updatedAppointmentId) {
                        if (updatedAppointmentId) {
                            document.querySelector('#result').innerText = "Updated Appointment Id: " + updatedAppointmentId;
                        } else {
                            document.querySelector('#result').innerText = "Appointment not replaced";
                        }
                    });
            }
        }
    }

Quitar una cita del calendario del usuario

Llama al método AppointmentManager.ShowRemoveAppointmentAsync apropiado para mostrar la interfaz de usuario de eliminación de citas del proveedor de citas predeterminado para permitir que el usuario quite una cita. El usuario también proporciona el identificador de citas que quiere quitar. Este identificador se devolvió desde AppointmentManager.ShowAddAppointmentAsync. Si el usuario hizo clic en Eliminar, la muestra imprime que quitó la cita especificada por ese identificador de citas.

    function removeAppointment(e) {
        // The appointment id argument for ShowRemoveAppointmentAsync is typically retrieved from AddAppointmentAsync and stored in app data.
        var appointmentId = document.querySelector('#appointmentIdInput').value;

        // The appointment id cannot be empty.
        if (!appointmentId) {
            document.querySelector('#result').innerText = "The appointment id cannot be empty";
        } else {
            // Get the selection rect of the button pressed to remove this appointment
            var boundingRect = e.srcElement.getBoundingClientRect();
            var selectionRect = { x: boundingRect.left, y: boundingRect.top, width: boundingRect.width, height: boundingRect.height };

            // ShowRemoveAppointmentAsync returns a boolean indicating whether or not the appointment related to the appointment id given was removed.
            // An optional instance start time can be provided to indicate that a specific instance on that date should be removed
            // in the case of a recurring appointment.
            if (document.querySelector('#instanceStartDateCheckBox').checked) {
                // Remove a specific instance starting on the date provided.
                var instanceStartDate = document.querySelector('#startTimeDatePicker').winControl.current;

                Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
                     appointmentId, selectionRect, Windows.UI.Popups.Placement.default, instanceStartDate)
                    .done(function (removed) {
                        if (removed) {
                            document.querySelector('#result').innerText = "Appointment removed";
                        } else {
                            document.querySelector('#result').innerText = "Appointment not removed";
                        }
                    });
            } else {
                // Remove an appointment that occurs only once or in the case of a recurring appointment, remove the entire series.
                Windows.ApplicationModel.Appointments.AppointmentManager.showRemoveAppointmentAsync(
                 appointmentId, selectionRect, Windows.UI.Popups.Placement.default)
                .done(function (removed) {
                    if (removed) {
                        document.querySelector('#result').innerText = "Appointment removed";
                    } else {
                        document.querySelector('#result').innerText = "Appointment not removed";
                    }
                });
            }
        }
    }

Mostrar un intervalo de tiempo para el proveedor de citas

Llama al método AppointmentManager.ShowTimeFrameAsync para mostrar un intervalo de tiempo específico para la interfaz de usuario principal del proveedor de citas predeterminado si el usuario hizo clic en Mostrar. La muestra imprime que el proveedor de citas predeterminado apareció en pantalla.

    // Show the appointment provider app at the current date and time with a 1 hour duration
    function showTimeFrame() {
        var dateToShow = new Date();
        Windows.ApplicationModel.Appointments.AppointmentManager.showTimeFrameAsync(dateToShow, (60 * 60 * 1000))
            .done(function () {
                document.querySelector('#result').innerText = "The default appointments provider should have appeared on screen.";
            });
    }

Crear un objeto de repetición de citas y aplicarle datos

Crea un objeto Windows.ApplicationModel.Appointments.AppointmentRecurrence y asígnale una variable. Después, aplica a AppointmentRecurrence la propiedades de repetición suministradas por un usuario mediante la interfaz de usuario.

    function createRecurrence() {
        var isRecurrenceValid = true;
        var recurrence = new Windows.ApplicationModel.Appointments.AppointmentRecurrence();

        // Unit
        switch (document.querySelector('#unitSelect').selectedIndex) {
            case 0:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.daily;
                break;
            case 1:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly;
                break;
            case 2:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthly;
                break;
            case 3:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay;
                break;
            case 4:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearly;
                break;
            case 5:
                recurrence.unit = Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay;
                break;
        }

        // Occurrences
        // Note: Occurrences and Until properties are mutually exclusive.
        if (document.querySelector('#occurrencesRadioButton').checked) {
            recurrence.occurrences = document.querySelector('#occurrencesRange').valueAsNumber;
        }

        // Until
        // Note: Until and Occurrences properties are mutually exclusive.
        if (document.querySelector('#untilRadioButton').checked) {
            recurrence.until = document.querySelector('#untilDatePicker').winControl.current;
        }

        // Interval
        recurrence.interval = document.querySelector('#intervalRange').valueAsNumber;

        // Week of the month
        switch (document.querySelector('#weekOfMonthSelect').selectedIndex) {
            case 0:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.first;
                break;
            case 1:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.second;
                break;
            case 2:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.third;
                break;
            case 3:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.fourth;
                break;
            case 4:
                recurrence.weekOfMonth = Windows.ApplicationModel.Appointments.AppointmentWeekOfMonth.last;
                break;
        }

        // Days of the Week
        // Note: For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values, at least one day must be specified.
        if (document.querySelector('#sundayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.sunday; }
        if (document.querySelector('#mondayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.monday; }
        if (document.querySelector('#tuesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.tuesday; }
        if (document.querySelector('#wednesdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.wednesday; }
        if (document.querySelector('#thursdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.thursday; }
        if (document.querySelector('#fridayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.friday; }
        if (document.querySelector('#saturdayCheckBox').checked) { recurrence.daysOfWeek |= Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.saturday; }

        if (((recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.weekly)       ||
             (recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.monthlyOnDay) ||
             (recurrence.unit === Windows.ApplicationModel.Appointments.AppointmentRecurrenceUnit.yearlyOnDay)) &&
            (recurrence.daysOfWeek === Windows.ApplicationModel.Appointments.AppointmentDaysOfWeek.none)) {
            isRecurrenceValid = false;
            document.querySelector('#result').innerText = "The recurrence specified is invalid. For Weekly, MonthlyOnDay or YearlyOnDay recurrence unit values, 
                                                           at least one day must be specified.";
        }

        // Month of the year
        recurrence.month = document.querySelector('#monthOfYearRange').valueAsNumber;

        // Day of the month
        recurrence.day = document.querySelector('#dayOfMonthRange').valueAsNumber;

        if (isRecurrenceValid)
        {
            document.querySelector('#result').innerText = "The recurrence specified was created successfully and is valid.";
        }
    }

Resumen y siguientes pasos

Con esto deberías tener nociones básicas sobre cómo administrar citas. Descarga la muestra de API de citas de la galería de códigos para ver el ejemplo completo de cómo administrar citas.

Temas relacionados

Muestra de API de citas