Conheça o PaperKit

Conheça o PaperKit

Descubra como incluir o PaperKit em seus apps para iOS, iPadOS, macOS e visionOS. Abordaremos como integrar perfeitamente os recursos de desenho e marcação do PencilKit, como formas e imagens, e como personalizar a interface de usuário. Conheça as melhores práticas para garantir compatibilidade futura e descubra opções avançadas de personalização para criar experiências de marcação verdadeiramente únicas em seus apps.

Capítulos
- 0:00 - Introdução
- 1:36 - Conhecer o PaperKit
- 3:35 - Começar a usar o PaperKit
- 8:37 - Personalizar o conjunto de recursos
Recursos
- PaperKit
- - Vídeo HD
  - Vídeo SD
Vídeos relacionados

WWDC24
- Squeeze the most out of Apple Pencil
WWDC20
- What's new in PencilKit
- What's new in SwiftUI
Olá! Sou Andreea, engineer da equipe Pencil & Paper, e tenho o prazer de apresentar o PaperKit. O PaperKit é o framework que possibilita a experiência de marcação da Apple em todo o sistema. É usado em recursos como Notas, Capturas de Tela, Visualização Rápida e Diário.
É a maneira mais fácil de fazer marcações eficientes em qualquer app. Com o PaperKit, você tem uma tela onde pode desenhar e adicionar vários elementos de marcação, incluindo formas, imagens, caixas de texto e outros. A compatibilidade com elementos de desenho e marcação é o que torna o PaperKit um complemento incrível para uma experiência completa.
Novidade no macOS Tahoe, ele oferece a mesma experiência. Assim, os elementos de desenho e marcação funcionam bem em qualquer app para macOS, como o novo app Diário mostrado aqui.
Primeiro, vou falar sobre os recursos do PaperKit e explicar os componentes por trás dele.
Depois, vou mostrar como integrar a marcação do PaperKit ao seu app em algumas etapas.
Para finalizar, vou explicar como personalizar a experiência do PaperKit para atender aos requisitos do seu app.
Vou começar destacando os recursos disponíveis com uma demonstração. Criei um app para registrar minhas receitas e usar a marcação para atualizá-las. Já escrevi a receita dos meus cookies romenos favoritos que faço desde os 7 anos e os avaliei com algumas formas de estrelas. Para concluir, vou adicionar uma imagem dos cookies. Vou abrir o app Arquivos e arrastar uma imagem para minha receita.
Vou reposicioná-la para garantir que fique boa.
Também vou destacar as nozes moídas, que são o ingrediente principal.
Agora que mostrei o que o PaperKit pode fazer, vou detalhar seus três componentes principais. O primeiro é o controlador de marcação chamado PaperMarkupViewController, que cria e exibe a marcação e os desenhos do PaperKit.
O segundo é o contêiner do modelo de dados, chamado PaperMarkup. Ele executa o salvamento e o carregamento da marcação do PaperKit e dos dados de desenho do PencilKit, além da renderização.
O terceiro é um menu de inserção que permite anotações com elementos de marcação na tela. No iOS, iPadOS e visionOS 26, ele é chamado de MarkupEditViewController.
No macOS, uma opção é a barra de ferramentas chamada MarkupToolbarViewController, completa com ferramentas de desenho e botões de anotação.
Começar a usar o PaperKit no seu app é fácil. Vou começar mostrando como o integrei ao meu app de receitas no iOS e abordando as etapas para o macOS.
Comecei subclassificando UIViewController. No método viewDidLoad, inicializei um contêiner de modelo de dados de marcação, configurando-o para corresponder aos limites da visualização e garantir o layout e o contexto de renderização corretos. Depois, criei um controlador de marcação configurado com os recursos mais recentes fornecidos pelo PaperKit.
Adicionei-o à hierarquia de view pelo processo de incorporação do controlador view padrão.
Para criar um seletor de ferramentas, inicializei um seletor do PencilKit e registrei o controlador de marcação como observador, para responder às alterações no estado do seletor.
Para exibir o seletor no meu app, eu o atribuí à propriedade activeToolPicker no estado do respondedor do PencilKit. Essa é uma nova API disponível no UIResponder que controla a visibilidade do seletor do respondedor atual. Ao configurar a propriedade toolPickerVisibility, posso manter o seletor ativo enquanto gerencio a visibilidade dele na tela. Com isso, o seletor permanece oculto, mas funcional, respondendo a interações, como gestos de tocar duas vezes e apertar, e permitindo que os apps ofereçam suporte ao minisseletor de ferramentas. Para saber configurar o seletor, confira as sessões "Introdução do PencilKit", da WWDC19, e "Aproveitar ao máximo o Apple Pencil", da WWDC24. Depois de configurar o seletor de ferramentas, configurei o item acessório como botão. Ao ser tocado, ele vai acionar uma função para apresentar o menu de inserção.
Dentro do método, inicializei o controlador de inserção usando os mesmos recursos do controlador de marcação.
Depois, defini o delegado do controlador como o controlador de visualização de marcação, exibido como popover, e ancorei o popover ao botão de barra adicionado ao seletor para adequar a posição.
Por fim, apresentei o controlador do menu de inserção de forma modal.
Fazer essa configuração no macOS também é simples.
A configuração do modelo de marcação e do controlador de marcação é praticamente igual.
A diferença no macOS é que você pode criar uma barra de ferramentas para apresentar a interface de inserção. A partir daí, defina o delegado da barra de ferramentas como o controlador de marcação e adicione-o à hierarquia de exibição usando o processo NSViewController padrão.
Ao concluir a configuração básica, vale a pena considerar alguns fatores essenciais para refinar a experiência do app.
O PaperKit pode ser integrado a um ambiente da SwiftUI. Os componentes são encapsulados em um UIViewControllerRepresentable, que é incorporado ao corpo de uma visualização da SwiftUI. Com isso, os componentes baseados no UIKit podem ser usados em um layout da SwiftUI, preservando a compatibilidade entre os frameworks. Para saber como integrar controladores de visualização em um ambiente da SwiftUI, confira a sessão "Novidades da SwiftUI", da WWDC20.
O controlador de marcação inclui um delegado que permite a execução personalizada de callbacks. Por exemplo, posso implementar o método de delegado de alteração de marcação para salvar modificações no modelo de marcação. Além disso, o controlador de marcação também serve como observável, sendo uma alternativa ao uso de delegado para gerenciar estados e atualizações.
Ao carregar dados do disco, é essencial verificar a compatibilidade de encaminhamento na versão do conteúdo. Há duas abordagens comuns para lidar com incompatibilidades de versão: apresentar um alerta sobre a necessidade de upgrade ou mostrar uma miniatura pré-renderizada da marcação.
O PaperKit oferece ferramentas para facilitar a compatibilidade de encaminhamento. Primeiro, crie um CGContext para renderizar a miniatura.
Depois, gere uma imagem em miniatura do modelo usando a função de desenho do modelo de marcação. Por último, salve-a com a marcação.
Exibir essa miniatura no caso de uma incompatibilidade de versão é a prática recomendada e o que apps como o Notas estão usando.
Agora que já mostrei como começar a usar o PaperKit para iOS e macOS, vou mostrar como você pode personalizar seu app para oferecer a experiência de marcação que tem em mente. O conjunto de funcionalidades de marcação disponíveis no PaperKit é chamado de FeatureSet. Ele define os recursos e ferramentas expostos aos controladores de marcação e inserção.
FeatureSet.latest fornece o conjunto completo de recursos de marcação aceitos pelo PaperKit. É um ótimo ponto de partida, pois garante recursos adicionados ao framework sempre atualizados.
Para personalizar a experiência de marcação, você pode usar as funções de remover e inserir. Isso dá controle total sobre quais ferramentas e interações estão disponíveis no seu app.
Defina a propriedade colorMaximumLinearExposure no conjunto de recursos como um número maior que 1 para ativar o suporte para HDR. Para SDR, use 1. Defina essa propriedade no seletor de ferramentas também para tintas HDR. No meu app, "4" deu o efeito HDR que eu queria.
O valor definido para colorMaximumLinearExposure vai mapear os tons para o espaço de HDR compatível com a tela do seu dispositivo. Também dá para usar o valor de compatibilidade da tela, copiando de UIScreen ou NSScreen.
Usando os recursos mais recentes e ativando o HDR no seu app, você terá todas as novas funcionalidades e experiências. Por exemplo, uma nova ferramenta de caligrafia, chamada Cálamo, lançada no PencilKit, que fica ótima em HDR.
Depois que o conjunto de recursos estiver configurado de acordo com seus requisitos, atribua-o ao controlador de marcação e ao controlador de inserção para garantir a consistência das funcionalidades de marcação e inserção do app.
Outra propriedade personalizável é contentView, do controlador de marcação, que pode ser definido como qualquer UIView. Por exemplo, posso usar o modelo como cenário de teste no meu app. Todas as marcações e desenhos serão renderizados em cima dele. Ao personalizar o FeatureSet, configurar a visualização em segundo plano e aplicar as etapas de refinamento anteriores, seu app pode oferecer a mesma experiência poderosa de marcação em todo o sistema, adaptada de forma robusta e criativa.
E agora, quais são os próximos passos? Adote a experiência de marcação da Apple, personalize seu FeatureSet com suas próprias ferramentas e tintas, defina seu próprio plano de fundo de conteúdo e adicione suporte para HDR à sua marcação.
Seja para desenvolver uma ferramenta de notas simples ou uma tela para atividades criativas, o PaperKit oferece os ingredientes certos para uma experiência perfeita. Mal posso esperar para ver o que você vai criar com o PaperKit.
Agradeço sua participação.

// 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 - Introdução
- Com o PaperKit, crie experiências ricas de marcação em diversos apps para iOS e macOS, incluindo Notas, Capturas de Tela, QuickLook e o app Diário. O framework oferece uma tela para desenhar e adicionar formas, imagens, campos de texto e muito mais. O PaperKit simplifica a integração da funcionalidade de marcação em qualquer app, proporcionando uma experiência fluida.
- 1:36 - Conhecer o PaperKit
- O app de exemplo é uma ferramenta de gerenciamento de receitas que permite criar, atualizar e anotar receitas usando marcação. O app inclui um controlador de marcação, um contêiner de modelo de dados e um menu de inserção ou barra de ferramentas para facilitar as anotações. A demonstração destaca esses recursos adicionando uma imagem, destacando ingredientes e avaliando uma receita de biscoitos tradicionais.
- 3:35 - Começar a usar o PaperKit
- Para integrar o PaperKit a um app iOS, crie a subclasse 'UIViewController' e inicialize um contêiner e um controlador de modelo de dados de marcação. Configure o seletor de ferramentas do PencilKit e o controlador do menu de inserção para exibição como popover quando acionado por um botão acessório. Você também pode integrar o PaperKit em um ambiente SwiftUI. O controlador de marcação inclui um delegado para tratamento de callbacks e implementa 'Observable' para gerenciamento de estado. Ao carregar dados do disco, verifique a compatibilidade de encaminhamento na versão do conteúdo. O PaperKit fornece ferramentas para gerar miniaturas para pré-renderização, em caso de incompatibilidade de versão.
- 8:37 - Personalizar o conjunto de recursos
- O 'FeatureSet' do PaperKit define a funcionalidade de marcação disponível em um app. Comece com 'FeatureSet.latest' para incluir todos os recursos mais recentes. Para personalizar o app, remova ou insira ferramentas e interações usando as funções fornecidas. Para ativar o suporte a HDR, defina 'colorMaximumLinearExposure' com um valor maior que 1, o que será mapeado por tom para a capacidade de HDR compatível pelo dispositivo. Fazer isso melhora a qualidade visual da marcação ao usar novas ferramentas como a caneta de caligrafia tipo "reed" lançada no PencilKit. Personalize a 'contentView' do controlador de marcação para exibir qualquer 'UIView', como um modelo, oferecendo um fundo consistente para marcações e desenhos.

Capítulos

Recursos

Vídeos relacionados

WWDC24

WWDC20