Sobre a ação “Executar JavaScript na Página Web” no Atalhos
Quase todas as páginas web são criadas com JavaScript, uma linguagem de programação que cria efeitos dinâmicos em navegadores web, incluindo animações, menus interativos, reprodução de vídeo, dentre outros. Em geral, o JavaScript não fica visível quando você navega por uma página web. No entanto, ao criar um atalho que contém a ação “Executar JavaScript na Página Web” e executá-lo no app Safari, você pode controlar o JavaScript de uma página web.
Os atalhos que executam seu JavaScript personalizado em uma página da Web têm muitos usos. Por exemplo, você pode criar atalhos que recuperam dados específicos de uma página web e incorporar esses dados a uma tarefa, como extrair horários de aula e adicioná-los ao app Calendário ou exportar os dados de participantes de um grupo do Facebook e adicioná-los a uma planilha.
Você também pode criar atalhos que permitem modificar uma página web, como alterar a fonte do texto ou modificar a velocidade de reprodução de um vídeo.
Para obter informações sobre como usar atalhos que executam JavaScript em uma página web, consulte Use a ação “Executar JavaScript na Página Web” no Atalhos.
Sobre a recuperação de dados de página web
A ação “Executar JavaScript na Página Web” permite recuperar dados de uma página web, selecionando todos os elementos que correspondem a determinados critérios e percorrendo esses elementos para executar uma tarefa com os dados (ou para inspecionar os elementos).
Por exemplo, para criar uma lista de todos os elementos de imagem em uma página web, use:
var elements = document.querySelectorAll("img");
Em outro exemplo, para recuperar todos os elementos com a classe “post,” use:
var elements = document.querySelectorAll(".post");
Depois que um NodeList é criado, você pode percorrer os elementos (para filtrá-los ainda mais ou adicioná-los a uma estrutura de dados) usando algo como:
var elements = ...;for (let element of elements) { // ...}Para obter mais informações sobre como consultar resultados de páginas web, consulte https://developer.mozilla.org/Selectors e https://developer.mozilla.org/SelectorAll.
Entrada da ação “Executar JavaScript na Página Web”
A entrada da ação “Executar JavaScript na Página Web” deve ser uma página web ativa do Safari, o que significa que você deve executar o atalho a partir da Extensão de Ação do Atalhos na folha de compartilhamento (especificamente no Safari, SFSafariViewController ou ASWebAuthenticationSession).
Quando um atalho é executado a partir da folha de compartilhamento, a entrada do app Safari é passada para a primeira ação do seu atalho.
Embora a entrada para a ação “Executar JavaScript na Página Web” precise ser uma página web Safari, você pode usar Variáveis Mágicas para inserir dados adicionais na ação. Por exemplo, o atalho a seguir contém uma ação “Executar JavaScript na Página Web” que modifica um vídeo em uma página web. A taxa de reprodução do vídeo é controlada pela variável Velocidade.
Dica: O atalho Change Video Speed está disponível na Galeria.
Se a ação “Executar JavaScript na Página Web” não for a primeira ação do atalho, uma mensagem de erro será exibida quando o atalho for executado.
Para corrigir isso, você pode adicionar uma ação Obter Variável e definir o parâmetro para a página web do Safari para passar o conteúdo para a ação “Executar JavaScript na Página Web”.
Para obter informações sobre como executar atalhos no Safari, consulte Configure e execute atalhos a partir de outro app.
Saída da ação “Executar JavaScript na Página Web”
Para retornar dados, você deve chamar o controlador de conclusão no JavaScript, como completion(result) Como o JavaScript é geralmente usado com padrões assíncronos, a chamada é, intencionalmente, não síncrona. Desta maneira, você pode finalizar a ação de maneira assíncrona. Por exemplo, o seguinte é válido:
window.setTimeout(function() { completion(true);}, 1000);A saída da ação “Executar JavaScript na Página Web” é qualquer tipo de dado JSON válido, incluindo:
String
Número
Booleano (verdadeiro ou falso)
Matriz (contendo qualquer outro tipo JSON válido)
Dicionário (contendo qualquer outro tipo JSON válido)
nuloindefinido
Para obter mais informações sobre JSON, consulte Sobre o uso de JSON no Atalhos.
Nos bastidores, o Atalhos codifica e decodifica automaticamente o valor retornado para a comunicação entre o JavaScript e o app Atalhos. Isso significa que você não precisa chamar JSON.stringify(result) antes de chamar o controlador de conclusão.
Como o valor de retorno é JSON, alguns valores de retorno não funcionam bem. Por exemplo, uma função ou Nó não terá uma representação codificada JSON útil. Nesse caso, é recomendável criar uma Matriz/Dicionário que contenha os valores compatíveis JSON que você precisa.
Para obter mais informações sobre Nós, consulte https://developer.mozilla.org/Node; para obter mais informações sobre funções, consulte https://developer.mozilla.org/Functions.
Nota: como um objeto em JavaScript é apenas um dicionário, os objetos básicos também são convertidos em JSON.
Dica: se quiser que a ação “Executar JavaScript na Página Web” não retorne nenhum dado, chame completion() sem nenhum argumento na função (porque undefined é uma saída válida). Isso é o mesmo que chamar completion(undefined).
Tempo limite para a ação “Executar JavaScript na Página Web”
Como todas as extensões JavaScript no Safari, a ação “Executar JavaScript na Página Web” está sujeita a um limite de tempo e deve ser concluída o mais rápido possível. O JavaScript que usa funções síncronas pode não ser concluído no prazo, incluindo:
window.alert()window.prompt()window.confirm()Tempos limite que duram vários segundos, por exemplo:
window.setTimeout(function() { completion(); }, 5000);
Se o JavaScript exceder o tempo limite, o atalho não será concluído e a mensagem de erro JavaScript será exibida quando o atalho for executado.
Sintaxe e Tratamento de Erros de Tempo de Execução
Você pode usar qualquer sintaxe compatível com o Safari para escrever JavaScript na ação “Executar JavaScript na Página Web”. O iOS 12 é compatível com sintaxe de JavaScript ECMA 6, incluindo loops for of e let.
No app Atalhos, a ação “Executar JavaScript na Página Web” ajuda você a identificar erros através de uma verificação de sintaxe básica antes de executar o atalho a partir da extensão do Safari.
Conforme você insere o script no campo de texto, o destaque da sintaxe ajuda a garantir a validade do JavaScript. Por exemplo, se você esquecer de incluir aspas no final de uma string, todo o texto após a string será destacado.
Se a sintaxe do script for válida, mas apresentar um erro de tempo de execução, a ação “Executar JavaScript na Página Web” capturará e exibirá as exceções. Por exemplo, se o script referenciar uma variável ou função que não existe (como shortcuts.completion()), um erro é exibido no tempo de execução.
Privacidade e Segurança
Quando você permite que um atalho execute JavaScript em uma página web, esse atalho pode acessar todas as informações dela, incluindo dados potencialmente confidenciais. O app Atalhos toma algumas medidas para garantir que você execute atalhos JavaScript de forma segura e privada.
Quando você executa um atalho que contém a ação “Executar JavaScript na Página Web”, um aviso é exibido informando que o atalho está prestes a interagir com a página web. Isso significa que o atalho pode acessar dados potencialmente confidenciais da página web, como senhas, números de telefone ou informações de cartão de crédito.
Depois de tocar em Permitir, o atalho é executado na página web especificada. Se você executar o mesmo atalho na mesma página web novamente, o Atalhos não exibirá mais o aviso. Essa permissão persiste em uma base por atalho, por página web.
Depois de permitir que o atalho acesse uma página web, o Atalhos toma uma medida extra para protegê-lo ainda mais de scripts potencialmente mal-intencionados ao transferir periodicamente as definições atualizadas de malware. Antes de interagir com uma página web, o Atalhos analisa o JavaScript e consulta as definições de malware. Com base nessa avaliação, o Atalhos é instruído a dar acesso ao script, negar acesso ao script ou exibir um aviso adicional antes de permitir que o atalho seja executado.
Nota: essa avaliação é realizada no seu dispositivo — o conteúdo do JavaScript (no campo de texto da ação “Executar JavaScript na Página Web”) não é enviado para um servidor externo para análise.
Se o atalho não puder ser executado, é exibida uma mensagem de erro com a explicação.
Importante: nunca execute um atalho que contenha JavaScript em que você não confia.