Conoce PaperKit

Conoce PaperKit

Descubre cómo incorporar PaperKit en tus apps de iOS, iPadOS, macOS y visionOS. Hablaremos sobre cómo integrar dibujos de PencilKit en funcionalidades de marcado como formas e imágenes, y cómo personalizar la interfaz de usuario. Conoce las prácticas recomendadas sobre la compatibilidad del futuro y descubre opciones de personalización para crear experiencias de marcado únicas en tus apps.

Capítulos
- 0:00 - Introducción
- 1:36 - Conoce PaperKit
- 3:35 - Primeros pasos con PaperKit
- 8:37 - Personalización del conjunto de funcionalidades
Recursos
- PaperKit
- - Video HD
  - Video SD
Videos relacionados

WWDC24
- Squeeze the most out of Apple Pencil
WWDC20
- What's new in PencilKit
- What's new in SwiftUI
Hola, soy Andreea, ingeniera del equipo de Pencil & Paper y estoy encantada de presentarles PaperKit. PaperKit es la estructura que potencia la experiencia de marcado única de Apple en todo el sistema. Se utiliza en apps como Notas, Diario, Capturas de pantalla y QuickLook.
Es la forma más sencilla de obtener un marcado enriquecido en cualquier app. PaperKit proporciona un lienzo en el que puedes dibujar y agregar elementos de marcado, como formas, imágenes, cuadros de texto y más. La compatibilidad con elementos de dibujo y marcado es lo que hace de PaperKit una incorporación sorprendente a cualquier app para una experiencia de marcado integral.
Como novedad en macOS Tahoe, PaperKit ofrece la misma experiencia de marcado enriquecida, por lo que dibujar y marcar elementos en cualquier app de macOS funciona muy bien, al igual que la nueva app Diario que se muestra aquí.
Primero, hablaré sobre las características clave de PaperKit y explicaré los componentes principales que hay detrás de él.
A continuación, te mostraré cómo integrar el marcado de PaperKit a tu app en unos pocos pasos.
Por último, explicaré cómo personalizar la experiencia de marcado de PaperKit para que se adapte mejor a los requisitos de tu app.
Comenzaré destacando las características disponibles con una demostración. Creé una app para realizar un seguimiento de todas mis recetas y usar el marcado para actualizarlas a medida que hago cambios. Ya escribí una receta de mis galletas favoritas tradicionales rumanas que hago desde que tenía 7 años y las califiqué con formas de estrella. Para completar la receta, agregaré una imagen de las galletas. Puedo simplemente abrir la app Archivos y arrastrar una imagen a mi receta.
¡Lo reposicionaré para asegurarme de que se vea bien!
También destacaré las nueces molidas, ya que son el ingrediente clave.
Ahora que vimos qué puede hacer PaperKit, analizaré los componentes principales. El primero es el controlador de marcado llamado PaperMarkupViewController, que crea y muestra de forma interactiva el marcado y el dibujo de PaperKit.
El segundo es el contenedor del modelo de datos, llamado PaperMarkup. Se encarga de guardar y cargar el marcado de PaperKit y los datos de dibujo de PencilKit y se encarga de renderizar el marcado.
El tercero es un nuevo menú de inserción que permite realizar anotaciones con elementos de marcado en el lienzo. En iOS, iPadOS y visionOS 26, se llama MarkupEditViewController.
En macOS, una alternativa es la nueva barra de herramientas, MarkupToolbarViewController, completa con herramientas de dibujo y botones para anotar.
Comenzar a utilizar PaperKit en tu app es fácil. Comenzaré repasando cómo lo integré en mi app de recetas en iOS y, luego, cubriré los pasos para macOS.
Comencé subclasificando UIViewController. Dentro del método viewDidLoad, inicialicé un contenedor de modelo de datos de marcado y lo configuré para que coincidiera con los límites de la vista, para garantizar un diseño y un contexto de representación adecuados. Luego, creé un controlador de marcado configurado con el conjunto completo de las últimas funciones proporcionadas por PaperKit.
Lo agregué a la jerarquía de vistas utilizando el proceso de incrustación del controlador de vista estándar.
Para crear un selector de herramientas, inicialicé PencilKit y registré el controlador de marcado como observador, lo que le permitió responder dinámicamente a los cambios en el estado del selector de herramientas.
Para mostrar el selector de herramientas en mi app, lo asigné a la propiedad activeToolPicker en el estado de respuesta de PencilKit. Esta es una nueva API disponible en UIResponder que controla la visibilidad del selector de herramientas para el respondedor actual. Al configurar la propiedad toolPickerVisibility, puedo mantener el selector de herramientas activo mientras administro explícitamente su visibilidad en pantalla. Esto permite que el selector de herramientas permanezca oculto, pero completamente funcional, que responda a interacciones, como gestos de doble toque y presión, y permite que cualquier app sea compatible con la experiencia del miniselector de herramientas. Para obtener más información sobre cómo configurar el selector, consulta Presentamos PencilKit de la WWDC19 y Aprovecha al máximo el Apple Pencil de la WWDC24. Luego de configurar el selector de herramientas, configuré elemento accesorio como un botón. Al tocarlo, se activará una función para presentar el menú de inserción.
Dentro del método, inicialicé el controlador de inserción usando las mismas características que el controlador de marcado.
Luego configuré el delegado del controlador en el controlador de vista de marcado, hice que se muestre como un elemento emergente y lo anclé al elemento del botón de la barra que agregué al selector para una ubicación adecuada.
Finalmente, presenté el controlador del menú de inserción de forma modal.
Hacer que las cosas funcionen en macOS es igual de sencillo.
La configuración del modelo de marcado y del controlador de marcado son esencialmente lo mismo.
Solo que en macOS se puede crear una barra de herramientas para presentar la IU de inserción. Configura el delegado de la barra de herramientas en el controlador y agrégalo a la jerarquía de vista con el proceso NSViewController.
Una vez completa la configuración básica, es importante detenerse a considerar algunos factores que son esenciales al perfeccionar la experiencia de la app.
PaperKit se puede integrar perfectamente en un entorno SwiftUI. Los componentes se encapsulan dentro de un UIViewControllerRepresentable que luego se incorpora directamente al cuerpo de una vista SwiftUI. Esto permite que los componentes basados en UIKit se usen en un diseño SwiftUI, preservando la compatibilidad entre ambas estructuras. Para obtener más información sobre cómo integrar los controladores de vista en un entorno SwiftUI, consulta Novedades de SwiftUI de la WWDC20.
El controlador de marcado incluye un delegado que permite el manejo personalizado de las devoluciones de llamadas. Por ejemplo, puedo implementar el método delegado de cambio de marcado para guardar automáticamente cualquier modificación en el modelo de marcado. Además, el controlador de marcado se ajusta a Observable, lo que proporciona una alternativa al uso de un delegado para administrar el estado y las actualizaciones.
Al cargar datos desde el disco, es siempre esencial verificar la versión del contenido para garantizar compatibilidad con versiones posteriores. Hay dos enfoques comunes para gestionar las discrepancias de versiones: presentar una alerta para informar sobre la necesidad de actualizar o mostrar una miniatura del marcado renderizada previamente.
PaperKit proporciona herramientas para que la compatibilidad futura sea extremadamente sencilla. Primero, crea una CGContext para representar la miniatura.
Luego, genera una imagen en miniatura del modelo utilizando la función de dibujo del modelo de marcado y, finalmente, guárdala junto con el marcado.
Se considera que mostrar esta miniatura en caso de no coincidir la versión es la mejor práctica y es lo que utilizan las apps como Notas.
Ahora que expliqué cómo empezar a usar PaperKit tanto para iOS como para macOS, analizaré cómo puedes personalizar tu app para ofrecer la experiencia de marcado que imaginas. El conjunto de todas las funcionalidades de marcado disponibles en PaperKit se denomina FeatureSet. Define las capacidades y herramientas expuestas tanto a los controladores de marcado como de inserción.
FeatureSet.latest te ofrece el conjunto completo de funciones de marcado compatibles con PaperKit. Es un excelente punto de partida, ya que garantiza mantenerse actualizado con las nuevas funciones agregadas a la estructura.
Para personalizar tu experiencia de marcado, puedes utilizar las funciones eliminar e insertar. Esto te brinda control total sobre qué herramientas e interacciones están disponibles en tu app.
Puedes habilitar la compatibilidad con HDR configurando colorMaximumLinearExposure en el conjunto de características en un número mayor que 1. Para el marcado SDR, usa 1. Establece esta propiedad en el selector de herramientas también para tintas HDR. Para mi app, 4 me dio el efecto HDR que estaba buscando.
El valor que configures para colorMaximumLinearExposure ajustará el tono hasta el margen HDR compatible con la pantalla del dispositivo. O simplemente usa el valor admitido por la pantalla, que puedes obtener de UIScreen o NSScreen.
Al utilizar el último conjunto de funciones y habilitar HDR en su app, obtendrás todas las nuevas funciones y experiencias. Por ejemplo, una nueva herramienta para caligrafía, llamada herramienta Reed, introducida en PencilKit, que se ve muy bien en HDR.
Una vez que el conjunto de características esté configurado, asigna el conjunto de características personalizado tanto al controlador de marcado como al de inserción para garantizar la coherencia en todas las funciones de marcado e inserción de la app.
Otra propiedad personalizable es contentView del controlador de marcado, que se puede configurar en cualquier UIView. Por ejemplo, puedo usar la plantilla como un elemento fijo en mi app. Todo el marcado y el dibujo se representarán encima. Al personalizar FeatureSet, configurar la vista de fondo y aplicar los pasos de refinamiento delineados anteriormente, tu app puede ofrecer la misma experiencia de marcado en todo el sistema, diseñada de manera sólida y creativa.
¿Qué sigue? Adopta la potente experiencia de marcado de Apple, personaliza tu FeatureSet con tu selección de herramientas y tintas, configura tu fondo de contenido y agrega compatibilidad con HDR al marcado.
Ya sea que crees una herramienta de notas liviana o prepares un lienzo creativo, PaperKit te brinda los ingredientes para crear la experiencia perfecta. No puedo esperar a ver lo que preparas con PaperKit.
¡Gracias por acompañarnos!

// Adopt PaperKit in iOS

override func viewDidLoad() {
    super.viewDidLoad()
    
    let markupModel = PaperMarkup(bounds: view.bounds)
    let paperViewController = PaperMarkupViewController(markup: markupModel, supportedFeatureSet: .latest)
    view.addSubview(paperViewController.view)
    addChild(paperViewController)
    paperViewController.didMove(toParent: self)
    becomeFirstResponder()    

    let toolPicker = PKToolPicker()
    toolPicker.addObserver(paperViewController)
    
    pencilKitResponderState.activeToolPicker = toolPicker
    pencilKitResponderState.toolPickerVisibility = .visible
    
    toolPicker.accessoryItem = UIBarButtonItem(barButtonSystemItem: .add, target: self, action: #selector(plusButtonPressed(_:)))
}

@objc func plusButtonPressed(_ button: UIBarButtonItem) {
    let markupEditViewController = MarkupEditViewController(supportedFeatureSet: .latest)    
    markupEditViewController.delegate = paperViewController
    markupEditViewController.modalPresentationStyle = .popover
    markupEditViewController.popoverPresentationController?.barButtonItem = button
    present(markupEditViewController, animated: true)
}

6:11 - Adopt PaperKit in macOS

// Adopt PaperKit in macOS

override func viewDidLoad() {
    super.viewDidLoad()
    
    let markupModel = PaperMarkup(bounds: view.bounds)
    let paperViewController = PaperMarkupViewController(markup: markupModel, supportedFeatureSet: .latest)
    view.addSubview(paperViewController.view)
    addChild(paperViewController)

    // Create toolbar for macOS
    let toolbarViewController = MarkupToolbarViewController(supportedFeatureSet: .latest)
    toolbarViewController.delegate = paperViewController
    view.addSubview(toolbarViewController.view)
    
    // Set layout
    setupLayoutConstraints()
}

7:18 - Auto-save markup changes

// Auto-save markup changes
    
func paperMarkupViewControllerDidChangeMarkup(_ paperMarkupViewController: PaperMarkupViewController) {
    let markupModel = paperMarkupViewController.markup
    Task {
        // Create a data blob and save it
        let data = try await markupModel.dataRepresentation()
        try data.write(toFile: paperKitDataURL)
    }
}

8:02 - Thumbnail for forward compatibility

// Thumbnail for forward compatibility

func updateThumbnail(_ markupModel: PaperMarkup) async throws {
    // Set up CGContext to render thumbnail in
    let thumbnailSize = CGSize(width: 200, height: 200)
    let context = makeCGContext(size: thumbnailSize)
    context.setFillColor(gray: 1, alpha: 1)
    context.fill(renderer.format.bounds)            

    // Render the PaperKit markup
    await markupModel.draw(in: context, frame: CGRect(origin: .zero, size: thumbnailSize))
    
    thumbnail = context.makeImage()
}

9:02 - Customized markup FeatureSet

// Customized markup FeatureSet
    
var featureSet: FeatureSet = .latest

featureSet.remove(.text)
featureSet.insert(.stickers)

// HDR support
featureSet.colorMaximumLinearExposure = 4
toolPicker.colorMaximumLinearExposure = 4

let paperViewController = PaperMarkupViewController(supportedFeatureSet: featureSet)
let markupEditViewController = MarkupEditViewController(supportedFeatureSet: featureSet)

10:50 - Custom background on markup controller

// Custom background on markup controller

let template = UIImage(named: "MyTemplate.jpg")
let templateView = UIImageView(image: template)
paperViewController.contentView = templateView

- 0:00 - Introducción
- Con PaperKit, puedes crear experiencias de marcado enriquecidas en varias apps de iOS y macOS, incluidas Notas, Capturas de pantalla, QuickLook y la app Diario. La estructura proporciona un lienzo para dibujar y agregar formas, imágenes, campos de entrada de texto y más. PaperKit simplifica la integración de la funcionalidad de marcado en cualquier app, ofreciendo una experiencia de usuario perfecta.
- 1:36 - Conoce PaperKit
- La app de ejemplo es una herramienta de gestión de recetas que permite a las personas crear, actualizar y anotar recetas utilizando marcado. La app incluye un controlador de marcado, un contenedor de modelo de datos y un menú de inserción o barra de herramientas (según el sistema operativo) para realizar anotaciones fácilmente. La demostración muestra estas funciones agregando una imagen, resaltando los ingredientes y calificando una receta de galletas tradicionales rumanas.
- 3:35 - Primeros pasos con PaperKit
- Para integrar PaperKit en una app iOS, subclase 'UIViewController' e inicialice un contenedor y un controlador de modelo de datos de marcado. Luego, configura un selector de herramientas PencilKit y configura un controlador de menú de inserción para que se muestre como una ventana emergente cuando se activa mediante un elemento accesorio de botón. También, puedes integrar PaperKit perfectamente en un entorno SwiftUI. El controlador de marcado incluye un delegado para el manejo personalizado de devoluciones de llamadas y se ajusta a 'Observable' para la gestión del estado. Cuando cargues datos desde el disco, es fundamental verificar siempre la versión del contenido para garantizar la compatibilidad con versiones posteriores. PaperKit proporciona herramientas para generar miniaturas para la renderización previa, en caso de que no haya coincidencias de versiones.
- 8:37 - Personalización del conjunto de funcionalidades
- 'FeatureSet' de PaperKit define la funcionalidad de marcado disponible en una app. Puede comenzar con 'FeatureSet.latest' para incluir todas las funciones más recientes. Para personalizar la app, puedes eliminar o insertar herramientas e interacciones utilizando las funciones proporcionadas. Para habilitar la compatibilidad con HDR, configure la propiedad 'colorMaximumLinearExposure' en un valor mayor que 1, que asigna tonos al margen HDR admitido por el dispositivo. Al hacerlo se mejora la calidad visual del marcado, especialmente cuando se utilizan herramientas nuevas como la herramienta de caña de caligrafía introducida en PencilKit. También puede personalizar el 'contentView' del controlador de marcado para mostrar cualquier 'UIView', como una plantilla, proporcionando un fondo consistente para el marcado y el dibujo.

Capítulos

Recursos

Videos relacionados

WWDC24

WWDC20