diff --git a/.github/workflows/markdown-lint-fix.yml b/.github/workflows/markdown-lint-fix.yml index a4c61716934478..61b8eb91770af8 100644 --- a/.github/workflows/markdown-lint-fix.yml +++ b/.github/workflows/markdown-lint-fix.yml @@ -60,6 +60,7 @@ jobs: - name: Lint Markdown files run: | yarn markdownlint-cli2 --fix "**/${{ matrix.lang }}/**/*.md" + node ./scripts/check-url-locale.js --fix "files/${{ matrix.lang }}" yarn prettier -w "**/${{ matrix.lang }}/**/*.md" cd ${{ github.workspace }}/mdn/content && yarn fix:fm --config-file ${{ github.workspace }}/front-matter-config.json "${{ github.workspace }}/files/${{ matrix.lang }}" diff --git a/.github/workflows/pr-check-lint_content.yml b/.github/workflows/pr-check-lint_content.yml index 58efde6c04bc8e..643cfd81a9afd6 100644 --- a/.github/workflows/pr-check-lint_content.yml +++ b/.github/workflows/pr-check-lint_content.yml @@ -114,6 +114,9 @@ jobs: echo "${EOF}" >> $GITHUB_ENV echo "FM_LINT_FAILED=${FM_LINT_FAILED}" >> $GITHUB_ENV + echo "Running url locale checker" + node ./scripts/check-url-locale.js --fix ${files_to_lint} + echo "Running Prettier" yarn prettier -w ${files_to_lint} diff --git a/.lintstagedrc.json b/.lintstagedrc.json index 5b4d530600839f..7dcd408346bf8d 100644 --- a/.lintstagedrc.json +++ b/.lintstagedrc.json @@ -1,4 +1,8 @@ { "!*.md": "prettier --ignore-unknown --write", - "*.md": ["markdownlint-cli2 --fix", "prettier --write"] + "*.md": [ + "markdownlint-cli2 --fix", + "node ./scripts/check-url-locale.js --fix", + "prettier --write" + ] } diff --git a/docs/zh-cn/translation-guide.md b/docs/zh-cn/translation-guide.md index 41c4b7d1d6caa2..0bcdb886bde7a2 100644 --- a/docs/zh-cn/translation-guide.md +++ b/docs/zh-cn/translation-guide.md @@ -12,27 +12,29 @@ ```yaml --- -title: Fetch API -slug: Web/API/Fetch_API -page-type: web-api-overview -browser-compat: api.fetch +title: atob() global function +short-title: atob() +slug: Web/API/atob +page-type: web-api-global-function +browser-compat: api.atob --- ``` 其中： - `title` 为文档的大标题 +- `short-title` 为显示在侧边栏和面包屑中的短标题 - `slug` 为与网页 URL 相关的元数据（URL path 部分的规则为：`//docs/`） - `page-type` 为页面的类型，将被用于站点管理和自动化数据处理 -- `browser-compat` 为[**浏览器兼容性表**][]对应的宏所使用的元数据。 +- `browser-compat` 为[**浏览器兼容性表**][]对应的宏所使用的元数据 -在简体中文文档翻译中，请适当翻译 `title` 元数据，以方便他人根据标题检索内容，`slug` 元数据则应与翻译对应的英文文档保持不变。对于 `page-type`、`browser-compat` 以及部分文档中使用的 `spec-urls` 元数据，它们被用于站点管理和自动化数据处理，而 yari 平台会自动将这些元数据由英文文档合并到本地化文档中。若没有特殊的需要，请将这些元数据从简体中文文档中移除。 +在简体中文文档翻译中，请适当翻译 `title` 元数据，以方便他人根据标题检索内容，`slug` 元数据则应与翻译对应的英文文档保持不变。对于 `page-type`、`browser-compat` 以及部分文档中使用的 `spec-urls` 元数据，它们被用于站点管理和自动化数据处理，而 yari 平台会自动将这些元数据由英文文档合并到本地化文档中。若没有特殊的需要，请将这些元数据从简体中文文档中移除。对于 `short-title`，如果简体中文文档采用的短标题与英文文档相同，则无需添加（仅在使用与英文文档*不同*的短标题时添加该元数据）。 最终在简体中文文档中呈现的元数据如下所示： ```yaml -title: Fetch API -slug: Web/API/Fetch_API +title: atob() 全局函数 +slug: Web/API/atob ``` ## 翻译标题和 ID diff --git a/files/es/web/css/hyphens/index.md b/files/es/web/css/hyphens/index.md index 8c609bcf1d9003..c7410317009db1 100644 --- a/files/es/web/css/hyphens/index.md +++ b/files/es/web/css/hyphens/index.md @@ -57,14 +57,18 @@ Este ejemplo usa tres clases, una por cada posible configuración de la propieda ```html ``` diff --git a/files/es/web/tutorials/index.md b/files/es/web/tutorials/index.md index a57231a1d5de5f..df97ae07f55a51 100644 --- a/files/es/web/tutorials/index.md +++ b/files/es/web/tutorials/index.md @@ -1,154 +1,145 @@ --- title: Tutoriales slug: Web/Tutorials +l10n: + sourceCommit: 07f0cf4375aaa02e1071d8bd0e8518db7609b7a9 --- -Los enlaces de esta página llevan a una gran variedad de tutoriales y material de formación. Tanto si estás en tus comienzos, aprendiendo lo básico, como si eres un veterano en desarrollo web, aquí puedes encontrar recursos que te ayuden a lograr mejores prácticas. +Los enlaces en esta página conducen a una variedad de tutoriales y materiales de capacitación. Ya sea que esté comenzando, aprendiendo los conceptos básicos o sea un experto en desarrollo web, aquí puede encontrar recursos útiles para las mejores prácticas. -Estos recursos son creados por empresas innovadoras y desarrolladores web que han adoptado los estándares abiertos y las mejores prácticas para el desarrollo web proporcionando o permitiendo traducciones mediante licencias de contenido abierto como Creative Commons. +Estos recursos son creados por empresas y desarrolladores web con visión de futuro que han adoptado estándares abiertos y mejores prácticas para el desarrollo web y que proporcionan o permiten traducciones, a través de una licencia de contenido abierto como Creative Commons. -## Para principiantes completos de la web +## Para principiantes en la Web -- [Comenzando con la web](/es/docs/Learn/Getting_started_with_the_web) - - : _Comenzando con la web_ es una serie introductoria que te presenta los aspectos prácticos del desarrollo web. Podrás configurar las herramientas que necesites para construir una página web sencilla y publicar tu propio código. +- [Primeros pasos en la Web](/es/docs/Learn/Getting_started_with_the_web) + - : _Primeros pasos en la Web_ es una serie concisa que te presenta los aspectos prácticos del desarrollo web. Configurarás las herramientas que necesitas para construir una sencilla página web y publicar tu propio código. -## Tutoriales de HTML +## Tutoriales HTML ### Nivel introductorio -- [Introducción a HTML](http://docs.webplatform.org/wiki/guides/the_basics_of_html) (WebPlatform.org) - - : Este módulo establece el escenario, haciendo que te sea común el uso de conceptos importantes y sintaxis, buscando cómo aplicar el HTML al texto, cómo crear hiperenlaces y cómo utilizar el HTML para estructurar una página web. -- [Estructura básica de una página web](http://reference.sitepoint.com/html/page-structure) (SitePoint) - - : Aprende cómo los elementos HTML encajan juntos con un enfoque más amplio. -- [Elementos fundamentales de HTML según MDN](http://reference.sitepoint.com/html/elements) (SitePoint) - - : Es una referencia exhaustiva de los elementos HTML y cómo son soportados por los distintos navegadores. -- [Tutorial de HTML para principiantes](http://htmldog.com/guides/htmlbeginner/) (HTML Dog) - - : Tutorial y ejercicios sobre los fundamentos. -- [Retos HTML](http://wikiversity.org/wiki/Web_Design/HTML_Challenges) (Wikiversity) - - : Acepta los retos para mejorar tus conocimientos sobre HTML (por ejemplo, "¿Debería usar un elemento \

o un elemento \?") y marca las respuestas correctas. -- [Manual de referencia MDN de elementos HTML](/es/docs/HTML/Element) - - : Una amplia referencia de elementos HTML, así como la forma en que Firefox y otros navegadores los soportan. +- [Introducción a HTML](/es/docs/Learn/HTML/Introduction_to_HTML) + - : Este módulo prepara el escenario, acostumbrándolo a conceptos y sintaxis importantes, analizando la aplicación de HTML al texto, cómo crear hipervínculos y cómo usar HTML para estructurar una página web. +- [Referencia de Elementos HTML](/es/docs/Web/HTML/Element) + - : Una referencia completa sobre elementos HTML y cómo los implementan los diferentes navegadores. +- [Crear una página web sencilla con HTML](https://www.theblogstarter.com/html-for-beginners/) + - : Una guía HTML para principiantes que incluye explicaciones de etiquetas comunes, incluidas las etiquetas HTML. También incluye una guía paso a paso para crear una página web básica con ejemplos de código. +- [Desafíos HTML](https://wikiversity.org/wiki/Web_Design/HTML_Challenges) + - : Utilice estos desafíos para perfeccionar sus habilidades HTML (por ejemplo, "¿Debería usar un elemento \

o un elemento \?"), enfocándose en un marcado significativo. ### Nivel intermedio -- [Incrustamiento y multimedia](/es/docs/Learn/HTML/Multimedia_and_embedding) - - : Este módulo explora cómo usar HTML para incluir multimedia en tus páginas web, incluyendo las diferentes formas en las que pueden incluirse imágenes, y cómo incrustar video, audio o incluso otras páginas web completas. +- [Multimedia e inserción](/es/docs/Learn/HTML/Multimedia_and_embedding) + - : Este módulo explora cómo usar HTML para incluir multimedia en sus páginas web, incluidas las diferentes formas en que se pueden incluir imágenes y cómo incrustar video, audio e incluso otras páginas web completas. - [Tablas HTML](/es/docs/Learn/HTML/Tables) - - : Representar datos tabulares en una forma comprensible puede ser un desafío, {{glossary("Accessibility", "accessible")}}. Este módulo cubre el marcado de una tabla básica, junto con características más complejas, como la implementación de epígrafes y resúmenes. + - : Representar datos tabulares en una página web de una manera {{glossary("Accessibility", "accesible")}} y comprensible puede ser un desafío. Este módulo cubre el marcado básico de tablas, junto con funciones más complejas, como la implementación de subtítulos y resúmenes. ### Nivel avanzado -- [Consejos para crear páginas HTML que carguen rápidamente](/es/docs/Tips_for_Authoring_Fast-loading_HTML_Pages) - - : Optimiza las páginas web para que sean adaptables a los visitantes, reduciendo la carga de tu servidor web y de tu conexión a Internet. -- [Sumérgete en HTML5](http://diveintohtml5.info/) (Mark Pilgrim) - - : Aprende de una selección de características de HTML5, la versión más reciente de las especificaciones HTML. -- [Tutoriales de HTML5](http://www.html5rocks.com/tutorials/) (HTML5 Rocks) - - : Haz una visita guiada por código que usa las características de HTML5. -- [Semántica en HTML5](http://www.alistapart.com/articles/semanticsinhtml5/) (alistapart.com) - - : Aprende marcas con significado, extensibles y compatibles con versiones tanto anteriores como posteriores. -- [Tutorial sobre Canvas](/es/docs/Canvas_tutorial) - - : Aprende cómo dibujar gráficos usando líneas de script y el elemento c*anvas*. -- [HTML5 Doctor](http://html5doctor.com/) - - : Artículos sobre cómo usar HTML5 ahora mismo. -- [La alegría del audio en HTML5](http://www.elated.com/articles/html5-audio/) (Elated) - - : Aprende a utilizar el elemento audio en HTML para incluir sonidos en tus páginas web de forma sencilla. Hay montones de códigos de ejemplos incluidos en este tutorial. +- [Formularios en HTML](/es/docs/Learn/Forms) + - : Los formularios son una parte muy importante de la Web: brindan gran parte de la funcionalidad que necesita para interactuar con sitios web, por ejemplo, registrarse e iniciar sesión, enviar comentarios, comprar productos y más. Este módulo lo ayuda a comenzar a crear las partes del lado del cliente de los formularios. +- [Consejos para la creación de páginas HTML de carga rápida](/es/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages) + - : Optimice las páginas web para proporcionar un sitio más receptivo para los visitantes y reducir la carga en su servidor web y conexión a Internet. ## Tutoriales CSS ### Nivel introductorio -- [Lo básico en CSS](/es/docs/CSS/Getting_Started) - - : Este tutorial te introduce en las hojas de estilo (_Cascading Style Sheets_ o _CSS_). Además, te guiará a través de las características básicas de CCS con ejemplos prácticos que podrás probar por ti mismo en tu propio computador. -- [Introducción a CSS](/es/docs/Learn/CSS/Introduction_to_CSS) - - : Este módulo profundiza en el funcionamiento de CSS, incluidos selectores y propiedades, redacción de reglas CSS, aplicación de CSS a HTML, cómo especificar longitud, color y otras unidades en CSS; cascada y herencia; conceptos básicos de caja y depuración de CSS. -- [Estilizando cajas](/es/docs/Learn/CSS/Styling_boxes) - - : A continuación analizamos las cajas de diseño, uno de los pasos fundamentales para diseñar una página web. En este módulo recapitulamos el modelo de caja y luego observamos los diseños de caja de control estableciendo relleno, bordes y márgenes, estableciendo colores de fondo personalizados, imágenes y otras características, y características extravagantes como sombras y filtros en cajas. -- [Hojas externas de CSS](http://en.wikiversity.org/wiki/Web_Design/External_CSS) (Wikiversity) - - : Aquí aprenderás cómo usar CSS en el HTML desde una hoja de estilo externa (en inglés). -- [Texto con estilo](/es/docs/Learn/CSS/Styling_text) - - : En esta sección repasaremos los fundamentos del estilo de texto, que incluyen la configuración de fuente, negrita e itálicas, el espaciado de líneas y letras, sombras paralelas y otras características de texto. Completaremos el módulo observando la aplicación de fuentes personalizadas en tú página y el diseño de listas y enlaces. +- [CSS básico](/es/docs/Learn/Getting_started_with_the_web/CSS_basics) + - : CSS (Hojas de Estilo en Cascada) es el código que usas para dar estilo a tu página web. CSS Básico te lleva a través de lo que tú necesitas para empezar. Contestará a preguntas del tipo: ¿Cómo hago mi texto rojo o negro? ¿Cómo hago que mi contenido se muestre en tal y tal lugar de la pantalla? ¿Cómo decoro mi página web con imágenes de fondo y colores? +- [Primeros pasos en CSS](/es/docs/Learn/CSS/First_steps) + - : CSS (Cascading Style Sheets - en español Hojas de Estilo en Cascadas) es usado para darle estilo y diseño a las páginas Web — por ejemplo, para cambiar la fuente de letra, color, tamaño y el espaciado de tu contenido; dividir en múltiples columnas, o agregar animaciones y otras propiedades decorativas. Este modulo provee un inicio suave para tu ruta de aprendizaje hacia el dominio de CSS con su funcionamiento básico, como luce su sintaxis, y cómo puedes comenzar a utilizarlo y añadir estilo a HTML. +- [Bloques de construcción CSS](/es/docs/Learn/CSS/Building_blocks) + + - : Este módulo retoma donde [Primeros pasos en CSS](/es/docs/Learn/CSS/First_steps) finalizó — ahora que estás familiarizado con el lenguaje y su sintaxis, y que tienes algo de experiencia en su uso, es hora de bucear un poco más profundo. Este módulo se centra en el estilo en cascada de css y en el concepto de herencia, también veremos todos los tipos de selectores, unidades, tamaños, estilos de fondo, bordes, debugging y mucho más. + + El objetivo aqui es proveerte de herramientas para que puedas escribir código CSS competentemente y ayudarte a entender lo escencial de la teoría antes de centrarnos en disciplinas más específicas como [text styling](/es/docs/Learn/CSS/Styling_text) y [CSS layout](/es/docs/Learn/CSS/CSS_layout). + +- [Selectores CSS](/es/docs/Learn/CSS/Building_blocks/Selectors) + + - : Apunte a elementos HTML, incluso según el estado del elemento, con CSS. + +- [Especificidad](/es/docs/Web/CSS/Specificity) + + - : Comprender el algoritmo del navegador para determinar qué declaraciones CSS se aplican a un elemento cuando hay declaraciones compitiendo, con un [cuestionario de especificidad](https://estelle.github.io/CSS/selectors/exercises/specificity.html) + +- [Cascada y herencia](/es/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance) + + - : El objetivo de este artículo es desarrollar la comprensión de algunos de los conceptos fundamentales de CSS (cascada, especificidad y herencia) que controlan cómo se aplica el CSS al HTML y cómo se resuelven los conflictos. + +- [Estilo de texto](/es/docs/Learn/CSS/Styling_text) + - : Aquí analizamos los fundamentos del estilo del texto, incluida la configuración de fuente, negrita y cursiva, espaciado entre líneas y letras, sombras paralelas y otras características del texto. Completamos el módulo analizando la aplicación de fuentes personalizadas a su página y el estilo de listas y enlaces. - [Preguntas frecuentes sobre CSS](/es/docs/Learn/CSS/Howto/CSS_FAQ) - - : Preguntas y respuestas frecuentes para principiantes. - -### Nivel Intermedio - -- [Referencia CSS](/es/docs/CSS/CSS_Reference) - - : Referencia completa para CCS con ayuda detallada por Firefox y otros navegadores. -- [Desafíos CSS](http://en.wikiversity.org/wiki/Web_Design/CSS_challenges)(Wikiversity) - - : Reta tus habilidades en CCS, con lo que podrás descubrir aquello que necesita mejorar. -- [Conceptos intermedios CSS](http://www.html.net/tutorials/css/) (HTML.net) - - : Agrupación, pseudo-clases y mucho más. -- [Posicionamiento 101 CSS](http://www.alistapart.com/articles/css-positioning-101/)(alistapart.com) - - : Usando posicionamiento con estándares complacientes y tablas de libre disposición. -- [Mejora progresivamente con CSS](http://www.alistapart.com/articles/progressiveenhancementwithcss/) (alistapart.com) - - : Intégrate mejorando progresivamente tus páginas web con CCS. -- [Cuadrícula fluida](http://www.alistapart.com/articles/fluidgrids/) (alistapart.com) - - : Diseño layouts que redimensiona fluidamente con la ventana del navegador, mientras sigue utilizando una cuadrícula tipográfica. + - : Preguntas y respuestas comunes para principiantes. + +### Nivel intermedio + +- [Diseño CSS](/es/docs/Learn/CSS/CSS_layout) + - : Llegados a este punto, hemos examinado los fundamentos básicos de CSS: cómo dar estilo al texto y cómo manipular las cajas que incluyen tu contenido. Llegó el momento de explorar cómo colocar tus cajas en el lugar que elijas con respecto a la ventana principal y el resto de cajas. Hemos cubierto ya los prerrequisitos necesarios, así que vamos a sumergirnos en la maquetación CSS, fijándonos en diferentes configuraciones de visualización, métodos de maquetación tradicionales que implican floats y posicionamiento, así como a nuevas herramientas de maquetación en voga, como flexbox. +- [Referencia CSS](/es/docs/Web/CSS/Reference) + - : Referencia completa a CSS, con detalles sobre el soporte de Firefox y otros navegadores. +- [Rejillas fluidas](https://alistapart.com/article/fluidgrids/) + - : Diseñe diseños que cambien de tamaño con fluidez con la ventana del navegador, sin dejar de utilizar una cuadrícula tipográfica. +- [Desafíos CSS](https://en.wikiversity.org/wiki/Web_Design/CSS_challenges) + - : Pon a prueba tus habilidades de CSS y descubre dónde necesitas más práctica. ### Nivel avanzado -- [CSS3 en menos de 5 minutos](http://addyosmani.com/blog/css3-screencast/) (Addy Osmani) - - : Una rápida introducción a algunas de las características fundamentales introducidas en CSS3. -- [Usando las Transformaciones CSS](/es/docs/CSS/Using_CSS_transforms) - - : Aplica rotación, inclinando escalando y traduce usando CCS. -- [Transiciones CSS](/es/docs/CSS/Transiciones_de_CSS) - - : CSS transiciones, parte del proyecto de la especificación CSS3, proporciona un modo para animar los cambios en las propiedades CSS, en lugar de que los cambios surtan efecto al instante. -- [Entendiendo las Transiciones CSS3](http://www.alistapart.com/articles/understanding-css3-transitions/) (alistapart.com) - - : Comienza usando CSS3 por transiciones eligiendo cuidadosamente las situaciones para utilizarlos. -- [Guia rápida para implementar Web Fonts con @font-face](http://www.html5rocks.com/tutorials/webfonts/quick/) (HTML5 Rocks) - - : La función @font-face de CSS3 te permite utilizar tipografías personalizadas en la web de una forma accesible, manipulable y adaptable. -- [Usando Media Queries](/es/docs/CSS/Media_queries) - - : Como realizar páginas web multiscreen con el uso de CSS y su propiedad @media. -- [Modelo de cajas con Flexbox](/es/docs/Web/Guide/CSS/Cajas_flexibles) - - : Permite distribuir el contenido de la web de forma sencilla y adaptable. +- [Uso de CSS transforms](/es/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) + - : Aplique rotación, inclinación, escala y traducción usando CSS. +- [Transiciones de CSS](/es/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) + - : Las transiciones CSS proporcionan una forma de animar los cambios en las propiedades CSS, en lugar de que los cambios surtan efecto instantáneamente. +- [Tutorial Canvas](/es/docs/Web/API/Canvas_API/Tutorial) + - : Aprenda a dibujar gráficos mediante secuencias de comandos utilizando el elemento lienzo (_canvas_). ## Tutoriales de JavaScript ### Nivel introductorio -- [Codecademy](http://www.codecademy.com/) (Codecademy) - - : Codecademy es la forma más fácil de aprender a programar en JavaScript. Es interactivo, divertido y puedes compartir o hacer código con tus amigos. -- [Comenzar con JavaScript](/es/docs/JavaScript/Getting_Started) - - : ¿Qué es JavaScript y cómo puede ayudarte en el desarrollo web? -- [Programar – Los fundamentos](http://docs.webplatform.org/wiki/concepts/programming/programming_basics) (WebPlatform.org) - - : Fundamentos de programación. Los artículos te indican lo que puedes hacer con JavaScript, las mejores prácticas para utilizarlo y mucho más. -- [Las mejores prácticas en JavaScript](http://dev.opera.com/articles/view/javascript-best-practices/)[](http://docs.webplatform.org/wiki/tutorials/javascript_best_practices)(WebPlatform.org) - - : Aprende algunas de las más evidentes (y no tan evidentes) mejores prácticas cuando escribes en JavaScript. +- [Primeros pasos con JavaScript](/es/docs/Learn/JavaScript/First_steps) + - : En nuestro primer módulo de JavaScript, primero respondemos algunas preguntas fundamentales como "¿qué es JavaScript?", "¿cómo se ve?" y "¿qué puede hacer?", antes de pasar avanzar en la guía por tu primera experiencia práctica de escribir JavaScript. Después de eso, explicaremos en detalle algunos bloques de construcción clave, tal como variables, cadenas, números y arreglos. +- [Elementos básicos de JavaScript](/es/docs/Learn/JavaScript/Building_blocks) + - : En este módulo, continuamos nuestra cobertura de todas las características clave de JavaScript, tornando nuestra atención a tipos de código comúnmente encontrados tales como enunciados condicionales, bucles (loops), funciones, y eventos. Ya has visto estas cosas en este curso, pero solo de pasada aquí lo hablaremos mas explícitamente. +- [Fundamentos de JavaScript](/es/docs/Learn/Getting_started_with_the_web/JavaScript_basics) + - : ¿Qué es JavaScript y cómo puede ayudarte? +- [Codecademy](https://www.codecademy.com/) + - : Codecademy es una manera fácil de aprender a codificar JavaScript. Es interactivo y puedes hacerlo con tus amigos. +- [freeCodeCamp](https://www.freecodecamp.org/learn) + - : freeCodeCamp enseña una variedad de lenguajes y _frameworks_ para el desarrollo web. También cuenta con un [foro](https://forum.freecodecamp.org/), una [estación de radio por Internet](https://coderadio.freecodecamp.org) y un [blog](https://www.freecodecamp.org/news). ### Nivel intermedio -- [Una reintroducción a JavaScript](/es/docs/A_re-introduction_to_JavaScript) - - : Resumen del lenguaje de programación JavaScript enfocado a desarrolladores de nivel intermedio. -- [JavaScript fluído](http://eloquentjavascript.net/contents.html) - - : Una guía completa para metodologías JavaScript intermedias y avanzadas. -- [Fundamentos de patrones de diseño en JavaScript](http://www.addyosmani.com/resources/essentialjsdesignpatterns/book/) (Addy Osmani) - - : Una introducción a las bases del diseño de patrones en JavaScript. -- [El lenguaje de programación JavaScript](http://www.yuiblog.com/blog/2007/01/24/video-crockford-tjpl/) (YUI Blog) - - : Douglas Crockford explora el lenguaje tal y como es hoy en día y cómo llegó a ser así. -- [Introducción a JavaScript Orientado a Objetos](/es/docs/Introducci%C3%B3n_a_JavaScript_orientado_a_objetos?redirectlocale=en-US&redirectslug=JavaScript%2FIntroduction_to_Object-Oriented_JavaScript) - - : Aprende sobre el modelo de objetos en JavaScript. +- [Introducción a los objetos JavaScript](/es/docs/Learn/JavaScript/Objects) + - : En JavaScript, la mayoría de las cosas son objetos, desde características del núcleo de JavaScript como arrays hasta el explorador APIs construído sobre JavaScript. Incluso puedes crear tus propios objetos para encapsular funciones y variables relacionadas dentro de paquetes eficientes que actúan como prácticos contenedores de datos. La naturaleza de JavaScript basada-en-objetos es importante de entender, si quieres avanzar con tu conocimiento del lenguaje, y por ello hemos hecho este módulo para ayudarte. Aquí enseñamos teoría de objetos y sintaxis en detalle, y luego veremos como crear tus propios objetos. +- [API web del lado del cliente](/es/docs/Learn/JavaScript/Client-side_web_APIs) + - : Cuando se escribe JavaScript para sitios web o aplicaciones del lado del cliente, no pasará mucho tiempo antes de que comience a usar APIs ("Application Programming Interfaces"). Estas son interfaces para manipular diferentes aspectos del navegador y el sistema operativo sobre el cuál se esta ejecutando, o incluso datos de otros sitios web o servicios. En este módulo, vamos a aprender que son las APIs y cómo utilizar algunas de las API más comunes que encuentran al momento de desarrollar. +- [JavaScript elocuente](https://eloquentjavascript.net/) + - : Una guía completa de metodologías JavaScript intermedias y avanzadas. +- [Hablando JavaScript](https://exploringjs.com/es5/) + - : Para programadores que quieran aprender JavaScript de forma rápida y adecuada, y para programadores de JavaScript que quieran profundizar sus habilidades y/o buscar temas específicos. +- [Patrones de diseño esenciales de JavaScript](https://addyosmani.com/resources/essentialjsdesignpatterns/book/) + - : Una introducción a los patrones de diseño esenciales de JavaScript. +- [JavaScript.info: el tutorial de JavaScript moderno](https://javascript.info/) + - : Parte 1: El lenguaje Parte 2: Trabajar con navegadores. ### Nivel avanzado -- [Aprender JavaScript avanzado](http://ejohn.org/apps/learn/) (John Resig) - - : La guía de John Resig para JavaScript avanzado. -- [Introducción a DOM en JavaScript](http://www.elated.com/articles/javascript-dom-intro/) (Elated) - - : ¿Qué es el Modelo de Objeto de Documento (_Document Object Model_) y para qué es útil? Este artículo te dará una buena introducción a esta característica de JavaScript. -- [Una API inconveniente: la teoría de DOM](http://yuiblog.com/blog/2006/10/20/video-crockford-domtheory/) (YUI Blog) - - : Douglas Crockford explica el Modelo de Objeto de Documento (_Document Object Model_). -- [JavaScript avanzado](http://yuiblog.com/blog/2006/11/27/video-crockford-advjs/) (YUI Blog) - - : Douglas Crockford estudia con detenimiento los patrones de código con los que los programadores de JavaScript pueden elegir al escribir sus aplicaciones. -- [JavaScript Garden](http://bonsaiden.github.com/JavaScript-Garden/) - - : Documentación sobre las partes más extravagantes de JavaScript. -- [¿Qué framework de JavaScript?](http://www.maestrosdelweb.com/editorial/comparacion-frameworks-javascript/) (Maestrosdelweb) - - : Consejos para escoger un framework de JavaScript. -- [Carga de JavaScript sin bloqueos](http://yuiblog.com/blog/2008/07/22/non-blocking-scripts/) (YUI Blog) - - : Consejos para mejorar el rendimiento de bajada de páginas que contienen JavaScript. -- [Guía de JavaScript](/es/docs/JavaScript/Guide) - - : Una guía de JavaScript completa y actualizada frecuentemente para todos los niveles de aprendizaje, desde principiante hasta avanzado. +- [Guía de JavaScript](/es/docs/Web/JavaScript/Guide) + - : Una guía completa y actualizada periódicamente de JavaScript para todos los niveles de aprendizaje, desde principiante hasta avanzado. +- [No conoces JS](https://github.com/getify/You-Dont-Know-JS) + - : Una serie de libros que profundizan en los mecanismos centrales del lenguaje JavaScript. +- [Jardín de JavaScript](https://github.com/BonsaiDen/JavaScript-Garden) + - : Documentación de las partes más extravagantes de JavaScript. +- [Explorando ES6](https://exploringjs.com/es6/) + - : Información confiable y detallada sobre ECMAScript 2015. +- [Patrones de JavaScript](https://shichuan.github.io/javascript-patterns/) + - : Una colección de patrones y antipatrones de JavaScript que cubre patrones de funciones, patrones de jQuery, patrones de complementos de jQuery, patrones de diseño, patrones generales, patrones literales y constructores, patrones de creación de objetos, patrones de reutilización de código, DOM. +- [Cómo funcionan los navegadores](https://www.html5rocks.com/en/tutorials/internals/howbrowserswork/) + - : Un artículo de investigación detallado que describe diferentes navegadores modernos, sus motores, representación de páginas, etc. +- [Vídeos de JavaScript](https://github.com/bolshchikov/js-must-watch) + - : Una colección de vídeos de JavaScript para ver. ### Desarrollo de extensiones -**[Extensiones web](/es/Add-ons/WebExtensions)** - -Extensiones Web es un sistema de navegación cruzada para desarrollar complementos del buscador. El sistema es en gran medida compatible con la [API (Interfaz de Programación de Aplicaciones)](https://developer.chrome.com/extensions)respaldada por Google Chrome y Opera. En la mayoría de los casos, las extensiones escritas para estos buscadores pueden funcionar en Firefox o Microsoft Edge con [solo algunos cambios](/es/Add-ons/WebExtensions/Porting_a_Google_Chrome_extension). La API es compatible también con el [multiprocesador de Firefox](/es/Firefox/Multiprocess_Firefox). +- [Extensiones del navegador](/es/docs/Mozilla/Add-ons/WebExtensions) + - : WebExtensions es un sistema multi-navegador para desarrollar complementos de navegador. En gran medida, el sistema es compatible con la [API de extensiones](https://developer.chrome.com/docs/extensions/reference/) compatible con Google Chrome y Opera. Las extensiones escritas para estos navegadores se ejecutarán en la mayoría de los casos en Firefox o [Microsoft Edge](https://docs.microsoft.com/archive/microsoft-edge/legacy/developer/) con [solo algunos cambios](https://extensionworkshop.com/documentation/develop/porting-a-google-chrome-extension/). La API también es totalmente compatible con [multiproceso Firefox](https://wiki.mozilla.org/Firefox/multiprocess). diff --git a/files/es/webassembly/reference/numeric/and/index.md b/files/es/webassembly/reference/numeric/and/index.md new file mode 100644 index 00000000000000..a30567789950ca --- /dev/null +++ b/files/es/webassembly/reference/numeric/and/index.md @@ -0,0 +1,29 @@ +--- +title: AND +slug: WebAssembly/Reference/Numeric/AND +--- + +{{WebAssemblySidebar}} + +Las instrucciones **`and`** son usadas para realizar operaciones bit a bit de tipo AND, similares al operador **`&`** en otros lenguajes. + +{{EmbedInteractiveExample("pages/wat/and.html", "tabbed-taller")}} + +## Sintáxis + +```wasm +;; Cargar dos números en la tabla +i32.const 5 ;; 00000101 +i32.const 3 ;; 00000011 + +;; ejecutar AND bit a bit +i32.and + +;; El nuevo elemento será 1 +(00000001) +``` + +| Instrucción | Código binario de operación | +| ----------- | --------------------------- | +| `i32.and` | `0x71` | +| `i64.and` | `0x83` | diff --git a/files/fr/learn/css/building_blocks/selectors/pseudo-classes_and_pseudo-elements/index.md b/files/fr/learn/css/building_blocks/selectors/pseudo-classes_and_pseudo-elements/index.md index fcb88096f77259..99e9fa41243346 100644 --- a/files/fr/learn/css/building_blocks/selectors/pseudo-classes_and_pseudo-elements/index.md +++ b/files/fr/learn/css/building_blocks/selectors/pseudo-classes_and_pseudo-elements/index.md @@ -35,7 +35,7 @@ Voyons maintenant les sélecteurs de **pseudo-classes** et de **pseudo-élément -## Qu'est ce qu'une pseudo-classe ? +## Qu'est-ce qu'une pseudo-classe ? Une pseudo-classe est un sélecteur ciblant des éléments dans un état spécifique, par ex. le premier élément d'un type, ou un élément survolé par le pointeur de la souris. Leur comportement correspond à celui d'une classe, mais qui ne s'appliquerait que partiellement. On gagne ainsi en flexibilité, en éliminant du code inutile. Le résultat est plus facile à maintenir. @@ -70,7 +70,7 @@ Certaines pseudo-classes ne s'appliquent que lorsque l'utilisateur interagit ave {{EmbedGHLiveSample("css-examples/learn/selectors/hover.html", '100%', 500)}} -## Qu'est ce qu'un pseudo-élément ? +## Qu'est-ce qu'un pseudo-élément ? Les pseudo-éléments se comportent de manière similaire, même s'ils se comportent comme si vous aviez ajouté un tout nouvel élément HTML dans le balisage, au lieu d'appliquer une classe à des éléments existants. Les pseudo-éléments commencent avec un double deux-points `::`. @@ -127,7 +127,7 @@ L'utilisation des pseudo-éléments `::before` et `::after` avec la propriété Dans cet article, nous avons présenté les pseudo-classes et les pseudo-éléments CSS, qui sont des types particuliers de sélecteurs. -Les pseudo-classes vous permettent de cibler un élément lorsqu'il se trouve dans un état particulier, comme si vous aviez ajouté une classe pour cet état au DOM. Les pseudo-éléments agissent comme si vous aviez ajouté un nouvel élément au DOM, et vous permettent de le styliser. Les pseudo-éléments `::before` et `::after` vous permettent d'insérer du contenu dans le document à l'aide de CSS. +Les pseudo-classes vous permettent de cibler un élément lorsqu'il se trouve dans un état particulier, comme si vous aviez ajouté une classe pour cet état au DOM. Les pseudo-éléments agissent comme si vous aviez ajouté un nouvel élément au DOM, et vous permettent de le styliser. Les pseudo-éléments `::before` et `::after` vous permettent d'insérer du contenu dans le document en utilisant le CSS. Dans le prochain article, nous aborderons [les combinateurs](/fr/docs/Learn/CSS/Building_blocks/Selectors/Combinators). diff --git a/files/fr/learn/css/building_blocks/values_and_units/index.md b/files/fr/learn/css/building_blocks/values_and_units/index.md index 3279f3f90c57f8..0ac808699e1f3b 100644 --- a/files/fr/learn/css/building_blocks/values_and_units/index.md +++ b/files/fr/learn/css/building_blocks/values_and_units/index.md @@ -179,7 +179,7 @@ Dans la plupart des exemples de cette section d'apprentissage ou à d'autres end ### Valeurs RGB hexadécimales -Les autres valeurs de couleur que vous rencontrerez assez souvent sont celles représentées avec des codes hexadécimaux. Chaque valeur hexadécimale se compose d'un croisillon (#) suivi de six chiffres hexadécimaux dont chacun peut prendre une valeur parmi 16 : de 0 à f (la lettre utilisée pour représentée 15) (les chiffres hexadécimaux sont : `0123456789abcdef`). Dans ces six chiffres, chaque paire de chiffre représente la valeur pour l'un des canaux de couleurs (rouge, vert et bleu) et permet d'indiquer l'une des 256 valeurs disponibles. +Les autres valeurs de couleur que vous rencontrerez assez souvent sont celles représentées avec des codes hexadécimaux. Chaque valeur hexadécimale se compose d'un croisillon (#) suivi de six chiffres hexadécimaux dont chacun peut prendre une valeur parmi 16 : de 0 à f (la lettre utilisée pour représenter 15) (les chiffres hexadécimaux sont : `0123456789abcdef`). Dans ces six chiffres, chaque paire de chiffre représente la valeur pour l'un des canaux de couleurs (rouge, vert et bleu) et permet d'indiquer l'une des 256 valeurs disponibles. Ces valeurs sont un peu plus complexes et moins faciles à comprendre, mais elles permettent d'exprimer beaucoup plus de couleurs que les mots-clés. Vous pouvez utiliser les valeurs hexadécimales pour représenter n'importe quelle couleur dans votre palette. @@ -255,7 +255,7 @@ Dans les différents exemples qui précèdent, on a vu des endroits où les mots {{EmbedGHLiveSample("css-examples/learn/values-units/strings-idents.html", '100%', 550)}} -## Functions +## Fonctions Les dernières valeurs que nous verrons ici sont les fonctions. En programmation, une fonction est une section de code réutilisable qui peut être exécutée plusieurs fois afin de réaliser une tâche de façon répétitive avec le minimum effort de la part du développeur ou de l'ordinateur. Les fonctions sont généralement associées à des langages comme JavaScript, Python ou C++ mais elles existent en CSS également pour être utilisées comme valeurs de propriétés. En fait, nous avons déjà vu des fonctions dans la section à propos des couleurs : `rgb()`, `hsl()`, etc. La valeur utilisée pour récupérer une image à partir d'un fichier, `url()` est également une fonction. diff --git a/files/fr/web/api/fetch_api/using_fetch/index.md b/files/fr/web/api/fetch_api/using_fetch/index.md index 29130b7515c2f2..9179c175b4f7c0 100644 --- a/files/fr/web/api/fetch_api/using_fetch/index.md +++ b/files/fr/web/api/fetch_api/using_fetch/index.md @@ -1,288 +1,500 @@ --- -title: Utiliser Fetch +title: Utiliser l'API Fetch slug: Web/API/Fetch_API/Using_Fetch +l10n: + sourceCommit: 251eb2f8a9132e73e647b9b7ae987ea6e2b45edc --- {{DefaultAPISidebar("Fetch API")}} -L'[API Fetch](/fr/docs/Web/API/Fetch_API) fournit une interface JavaScript pour l'accès et la manipulation des parties du pipeline HTTP, comme les requêtes et les réponses. Cela fournit aussi une méthode globale {{domxref("GlobalFetch.fetch","fetch()")}} qui procure un moyen facile et logique de récupérer des ressources à travers le réseau de manière asynchrone. +[L'API Fetch](/fr/docs/Web/API/Fetch_API) (en anglais, le verbe fetch signifie récupérer) fournit une interface JavaScript pour accéder et manipuler certaines parties du [protocole](/fr/docs/Glossary/Protocol), comme les requêtes et les réponses. Elle fournit également une méthode globale [`fetch()`](/fr/docs/Web/API/fetch) qui permet un accès pratique aux ressources récupérées de façon asynchrone sur le réseau. -Ce genre de fonctionnalité était auparavant réalisé avec {{domxref("XMLHttpRequest")}}. Fetch fournit une meilleure alternative qui peut être utilisée facilement par d'autres technologies comme {{domxref("ServiceWorker_API", "Service Workers")}}. Fetch fournit aussi un endroit unique et logique pour la définition d'autres concepts liés à HTTP comme CORS et les extensions d'HTTP. +À la différence de [`XMLHttpRequest`](/fr/docs/Web/API/XMLHttpRequest) qui fonctionne à l'aide de fonctions de rappel (callbacks), l'API Fetch utilise les promesses et fournit une meilleure alternative, qui peut être utilisée dans [les service workers](/fr/docs/Web/API/Service_Worker_API). L'API Fetch intègre également des concepts HTTP avancés tels que [le CORS](/fr/docs/Web/HTTP/CORS) et d'autres extensions de HTTP. -## Détection de la fonctionnalité - -Le support de l'API Fetch peut être détecté en vérifiant l'existence de {{domxref("Headers")}}, {{domxref("Request")}}, {{domxref("Response")}} ou {{domxref("GlobalFetch.fetch","fetch()")}} sur la portée de {{domxref("Window")}} ou de {{domxref("Worker")}}. Par exemple, vous pouvez faire cela dans votre script : +Une requête de récupération ressemblera à ceci : ```js -if (window.fetch) { - // exécuter ma requête fetch ici -} else { - // Faire quelque chose avec XMLHttpRequest? +async function afficherFilms() { + const reponse = await fetch("http://example.com/films.json"); + const films = await reponse.json(); + console.log(films); } ``` -## Créer une requête `fetch` +Dans cet exemple, nous récupérons un fichier JSON sur le Web, puis on analyse son contenu afin de pouvoir afficher les données dans la console. Dans sa forme la plus simple, `fetch()` utilise un argument qui correspond au chemin de la ressource à récupérer. Cet appel ne renvoie pas directement une réponse avec un corps en JSON, mais une promesse qui est résolue en un objet [`Response`](/fr/docs/Web/API/Response). + +L'objet [`Response`](/fr/docs/Web/API/Response) ne contient pas directement le corps de la réponse en JSON mais fournit une représentation de l'ensemble de la réponse HTTP. Aussi, pour extraire le corps en JSON de l'objet [`Response`](/fr/docs/Web/API/Response), on utilise la méthode [`json()`](/fr/docs/Web/API/Response/json), qui renvoie une deuxième promesse dont la résolution fournit le résultat de l'analyse du corps de la réponse au format JSON. + +> **Note :** Voir la section [corps](#corps) pour d'autres méthodes permettant d'extraire d'autres types de contenu du corps de la réponse. + +Les requêtes de récupération sont contrôlées par la directive `connect-src` de [la politique de sécurité du contenu (Content Security Policy ou CSP)](/fr/docs/Web/HTTP/Headers/Content-Security-Policy) plutôt que par la directive de la ressource qu'elles récupèrent. -Une requête `fetch` basique est vraiment simple à initier. Jetez un coup d'œil au code suivant : +## Fournir des options à la requête + +La méthode `fetch()` permet l'utilisation optionnelle d'un deuxième paramètre, un objet `init` pour contrôler différents paramètres. + +Voir [la page sur la méthode `fetch()`](/fr/docs/Web/API/fetch) pour plus de détails et l'exhaustivité des options disponibles. ```js -const myImage = document.querySelector("img"); - -fetch("flowers.jpg") - .then(function (response) { - return response.blob(); - }) - .then(function (myBlob) { - const objectURL = URL.createObjectURL(myBlob); - myImage.src = objectURL; +// Exemple d'implémentation pour une requête POST +async function postData(url = "", donnees = {}) { + // Les options par défaut sont indiquées par * + const response = await fetch(url, { + method: "POST", // *GET, POST, PUT, DELETE, etc. + mode: "cors", // no-cors, *cors, same-origin + cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached + credentials: "same-origin", // include, *same-origin, omit + headers: { + "Content-Type": "application/json", + // 'Content-Type': 'application/x-www-form-urlencoded', + }, + redirect: "follow", // manual, *follow, error + referrerPolicy: "no-referrer", // no-referrer, *no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url + body: JSON.stringify(donnees), // le type utilisé pour le corps doit correspondre à l'en-tête "Content-Type" }); + return response.json(); // transforme la réponse JSON reçue en objet JavaScript natif +} + +postData("https://example.com/solution", { solution: 42 }).then((donnees) => { + console.log(donnees); // Les données JSON analysées par l'appel `donnees.json()` +}); ``` -Ici nous récupérons une image à travers le réseau et l'insérons dans un élément {{htmlelement("img")}}. L'utilisation la plus simple de `fetch()` prend un argument — le chemin de la ressource que nous souhaitons récupérer — et retourne une promesse (promise) contenant, en réponse, un objet (de type {{domxref("Response")}}). +On notera que `mode: "no-cors"` ne permet qu'un ensemble limité d'en-têtes dans la requête : + +- `Accept` +- `Accept-Language` +- `Content-Language` +- `Content-Type` avec une valeur `application/x-www-form-urlencoded`, `multipart/form-data`, ou `text/plain` -Bien sûr, il s'agit seulement d'une réponse HTTP, pas exactement de l'image. Pour extraire le contenu de l'image de la réponse, nous utilisons la méthode {{domxref("Body.blob","blob()")}} (définie sur le mixin {{domxref("Body")}}, qui est implémenté autant par les objets {{domxref("Request")}} que par les objets {{domxref("Response")}}). +## Interrompre une requête -> **Note :** Le mixin Body a aussi des méthodes similaires pour extraire d'autres types contenu ; pour plus d'informations regardez la section [Corps](#corps). +Pour interrompre une opération `fetch()` en cours, on pourra utiliser les interfaces [`AbortController`](/fr/docs/Web/API/AbortController) et [`AbortSignal`](/fr/docs/Web/API/AbortSignal). -Un objet `objectURL` est ensuite créé à partir du {{domxref("Blob")}} extrait, puis est inseré dans {{domxref("img")}}. +```js +const controleur = new AbortController(); +const signal = controleur.signal; +const url = "video.mp4"; + +const btnTelechargement = document.querySelector("#telechargement"); +const btnInterruption = document.querySelector("#interrompre"); + +btnTelechargement.addEventListener("click", async () => { + try { + const reponse = await fetch(url, { signal }); + console.log("Téléchargement terminé", reponse); + } catch (error) { + console.error(`Erreur lors du téléchargement : ${error.message}`); + } +}); -Les requêtes Fetch sont controllées par la directive `connect-src` du [Content Security Policy](/fr/docs/Security/CSP/CSP_policy_directives) plutôt que par la directive de la ressource dont il s'agit de la récupération. +btnInterruption.addEventListener("click", () => { + controleur.abort(); + console.log("Téléchargement interrompu"); +}); +``` -### Fournir des options à la requête +## Envoyer une requête contenant les informations d'authentification -La méthode `fetch()` accepte un second paramètre optionnel, un objet `init` qui vous permet de contrôler un certain nombre de réglages : +Pour que les navigateurs envoient une requête avec les informations d'authentification, tant pour les requêtes sur la même origine qu'entre origines différentes, on ajoutera `credentials: 'include'` à l'objet `init` passé à la méthode `fetch()`. ```js -var myHeaders = new Headers(); +fetch("https://example.com", { + credentials: "include", +}); +``` -var myInit = { - method: "GET", - headers: myHeaders, - mode: "cors", - cache: "default", -}; - -fetch("flowers.jpg", myInit) - .then(function (response) { - return response.blob(); - }) - .then(function (myBlob) { - var objectURL = URL.createObjectURL(myBlob); - myImage.src = objectURL; - }); +> **Note :** On ne pourra pas utiliser `Access-Control-Allow-Origin: *` pour les requêtes avec `credentials: 'include'`. Pour ces cas-là, il faut fournir l'origine exacte. Même si une extension de débridage du CORS est utilisée, la requête échouera. + +> **Note :** Les navigateurs ne devraient pas envoyer d'informations d'authentification dans les _requêtes préparatoires_ (preflight requests), quelle que soit la valeur de cette option. Pour plus d'informations, voir [la section de la page CORS sur les requêtes avec informations d'authentification](/fr/docs/Web/HTTP/CORS#requêtes_avec_informations_dauthentification). + +Si on souhaite uniquement envoyer les informations d'authentification lorsque l'URL de la requête se situe sur la même origine que le script appelant, on utilisera `credentials: 'same-origin'`. + +```js +// Le script qui appelle se situe sur l'origine 'https://example.com' + +fetch("https://example.com", { + credentials: "same-origin", +}); +``` + +Pour s'assurer que les navigateurs n'envoient aucune information d'authentification dans la requête, on utilisera `credentials: 'omit'`. + +```js +fetch("https://example.com", { + credentials: "omit", +}); +``` + +## Téléverser des données JSON + +On peut utiliser [`fetch()`](/fr/docs/Web/API/fetch) pour envoyer des données au format JSON à un serveur avec une requête POST. + +```js +async function postJSON(donnees) { + try { + const reponse = await fetch("https://example.com/profile", { + method: "POST", // ou 'PUT' + headers: { + "Content-Type": "application/json", + }, + body: JSON.stringify(donnees), + }); + + const resultat = await reponse.json(); + console.log("Réussite :", resultat); + } catch (erreur) { + console.error("Erreur :", erreur); + } +} + +const donnees = { login: "Jean Biche" }; +postJSON(donnees); +``` + +## Téléverser un fichier + +Les fichiers peuvent être envoyés à l'aide d'un élément HTML [``](/fr/docs/Web/HTML/Element/input/file), de [`FormData`](/fr/docs/Web/API/FormData/FormData), et de [`fetch()`](/fr/docs/Web/API/fetch). + +```js +async function upload(donneesFormulaires) { + try { + const reponse = await fetch("https://example.com/profile/avatar", { + method: "PUT", + body: donneesFormulaires, + }); + const resultat = await reponse.json(); + console.log("Réussite :", resultat); + } catch (erreur) { + console.error("Erreur :", erreur); + } +} + +const donneesFormulaires = new FormData(); +const champFichier = document.querySelector('input[type="file"]'); + +donneesFormulaires.append("username", "abc123"); +donneesFormulaires.append("avatar", champFichier.files[0]); + +upload(donneesFormulaires); ``` -Reportez-vous à {{domxref("GlobalFetch.fetch","fetch()")}} pour la liste complète des options disponibles, et plus de détails. +## Téléverser plusieurs fichiers + +On peut envoyer plusieurs fichiers en utilisant un élément HTML [``](/fr/docs/Web/HTML/Element/input/file), [`FormData`](/fr/docs/Web/API/FormData/FormData), et [`fetch()`](/fr/docs/Web/API/fetch). + +```js +async function uploadMultiple(donneesFormulaires) { + try { + const reponse = await fetch("https://example.com/posts", { + method: "POST", + body: donneesFormulaires, + }); + const resultat = await reponse.json(); + console.log("Réussite :", resultat); + } catch (erreur) { + console.error("Erreur :", erreur); + } +} + +const photos = document.querySelector('input[type="file"][multiple]'); +const donneesFormulaires = new FormData(); + +donneesFormulaires.append("title", "Mes vacances"); -### Vérifier que la récupération a réussi +for (const [i, photo] of Array.from(photos.files).entries()) { + donneesFormulaires.append(`photos_${i}`, photo); +} -Une promesse {{domxref("GlobalFetch.fetch","fetch()")}} va retourner une {{jsxref("TypeError")}} quand un problème réseau s'est produit. Cependant, il peut aussi s'agir d'un problème de permission ou quelque chose de similaire — un code HTTP 404 ne constitue pas une erreur réseau, par exemple. Un bon test de la réussite de `fetch()` devrait inclure la vérification que la promesse soit résolue, puis vérifier que la propriété {{domxref("Response.ok")}} ait la valeur _true_. Le code devrait ressembler à ce qui suit: +uploadMultiple(donneesFormulaires); +``` + +## Traiter un fichier texte ligne à ligne + +Les fragments reçus dans une réponse ne sont pas segmentés proprement à chaque fin de ligne. Il s'agit d'objets binaires [`Uint8Array`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), pas de chaînes de caractères. Si on récupère un fichier texte et qu'on souhaite le traiter ligne à ligne, il faut gérer cette représentation. Dans l'exemple qui suit, on illustre une façon de procéder en créant un itérateur sur les lignes (pour garder l'exemple simple, on considère que le texte est encodé en UTF-8 et on ne gère pas les erreurs de récupération). ```js -fetch("flowers.jpg") - .then(function (response) { - if (response.ok) { - response.blob().then(function (myBlob) { - var objectURL = URL.createObjectURL(myBlob); - myImage.src = objectURL; - }); - } else { - console.log("Mauvaise réponse du réseau"); +async function* makeTextFileLineIterator(fileURL) { + const utf8Decoder = new TextDecoder("utf-8"); + const response = await fetch(fileURL); + const reader = response.body.getReader(); + let { value: chunk, done: readerDone } = await reader.read(); + chunk = chunk ? utf8Decoder.decode(chunk) : ""; + + const newline = /\r?\n/gm; + let startIndex = 0; + let result; + + while (true) { + const result = newline.exec(chunk); + if (!result) { + if (readerDone) break; + const remainder = chunk.substr(startIndex); + ({ value: chunk, done: readerDone } = await reader.read()); + chunk = remainder + (chunk ? utf8Decoder.decode(chunk) : ""); + startIndex = newline.lastIndex = 0; + continue; } - }) - .catch(function (error) { - console.log( - "Il y a eu un problème avec l'opération fetch : " + error.message, - ); - }); + yield chunk.substring(startIndex, result.index); + startIndex = newline.lastIndex; + } + + if (startIndex < chunk.length) { + // Last line didn't end in a newline char + yield chunk.substr(startIndex); + } +} + +async function run() { + for await (const line of makeTextFileLineIterator(urlOfFile)) { + processLine(line); + } +} + +run(); ``` -### Fournir votre propre objet requête +## Vérifier la réussite de l'opération -Plutôt que de transmettre le chemin de la ressource que vous souhaitez récupérer avec l'appel `fetch()`, vous pouvez créer un objet de requête en utilisant le constructeur {{domxref("Request.Request","Request()")}}, et le transmettre à la méthode `fetch()` en tant qu'argument : +Une promesse [`fetch()`](/fr/docs/Web/API/fetch) échouera avec une exception [`TypeError`](/fr/docs/Web/JavaScript/Reference/Global_Objects/TypeError) s'il y a une erreur réseau ou que la politique CORS est incorrectement configurée côté serveur. En revanche, une réponse 404 qui indiquerait un problème de permission ou autre ne déclencherait pas une telle erreur. Aussi, pour bien vérifier que l'opération `fetch()` est réussie, il faudra vérifier que la promesse est tenue, mais aussi vérifier que la propriété [`Response.ok`](/fr/docs/Web/API/Response/ok) vaut `true`. Le code correspondant ressemblerait à : ```js -var myHeaders = new Headers(); +async function fetchImage() { + try { + const response = await fetch("flowers.jpg"); + if (!response.ok) { + throw new Error("La réponse n'est pas OK"); + } + const myBlob = await response.blob(); + monImage.src = URL.createObjectURL(myBlob); + } catch (error) { + console.error("Un problème est survenu lors de la récupération :", error); + } +} +``` + +## Fournir un objet `Request` sur mesure + +Plutôt que de passer le chemin de la ressource à l'appel `fetch()`, on peut créer un objet représentant une requête à l'aide du constructeur [`Request()`](/fr/docs/Web/API/Request/Request) et passer cet objet comme argument à la méthode `fetch()` : -var myInit = { +```js +async function fetchImage(request) { + try { + const response = await fetch(request); + if (!response.ok) { + throw new Error("La réponse n'est pas OK"); + } + const monBlob = await response.blob(); + monImage.src = URL.createObjectURL(monBlob); + } catch (error) { + console.error("Erreur :", error); + } +} + +const mesEntetes = new Headers(); + +const maRequete = new Request("flowers.jpg", { method: "GET", - headers: myHeaders, + headers: mesEntetes, mode: "cors", cache: "default", -}; - -var myRequest = new Request("flowers.jpg", myInit); +}); -fetch(myRequest, myInit) - .then(function (response) { - return response.blob(); - }) - .then(function (myBlob) { - var objectURL = URL.createObjectURL(myBlob); - myImage.src = objectURL; - }); +fetchImage(maRequete); ``` -`Request()` accepte exactement les mêmes paramètres que la méthode `fetch()`. Vous pouvez même lui transmettre un objet Request existant pour en créer une copie : +`Request()` accepte les mêmes paramètres que la méthode `fetch()`. On peut même lui passer un objet représentant une requête existante pour en créer une copie : ```js -var anotherRequest = new Request(myRequest, myInit); +const uneAutreRequete = new Request(maRequete, monInit); ``` -C'est très pratique, si le corps de la requête et de la réponse ne sont utilisés qu'une fois seulement. Cette manière de faire une copie permet de ré-utiliser la requête/réponse, en changeant juste les options du `init` si nécessaire. +Ce mécanisme de duplication est plutôt utile, car les corps des requêtes et des réponses ne peuvent être utilisés qu'une seule fois. En construisant une telle copie, on peut à nouveau utiliser la requête ou la réponse tout en adaptant les options `init` si besoin. Attention, la copie doit être effectuée avant que le corps ait été lu. -> **Note :** Il y a aussi une méthode {{domxref("Request.clone","clone()")}} qui crée une copie. Cette sémantique est légèrement différente de l'autre méthode de copie—la première va échouer si l'ancien corps de la requête a déjà été lu (même pour copier une réponse), alors qu'elle fonctionnera avec `clone()`. +> **Note :** Il existe également la méthode [`clone()`](/fr/docs/Web/API/Request/clone) pour créer une copie. Ces deux méthodes de copie échoueront si le corps de la requête ou de la réponse originale a déjà été lu. En revanche, lire le corps d'une réponse ou d'une requête clonée ne modifiera pas l'état de lecture de l'original. -## En-têtes (headers) +## En-têtes -L'interface {{domxref("Headers")}} vous permet de créer vos propres objets d'en-têtes via le constructeur {{domxref("Headers.Headers","Headers()")}}. Un objet en-tête est un simple ensemble de plusieurs clé-valeurs : +L'interface [`Headers`](/fr/docs/Web/API/Headers) permet de créer ses propres objets représentant des en-têtes HTTP à l'aide du constructeur [`Headers()`](/fr/docs/Web/API/Headers/Headers). Un objet d'en-têtes est un tableau de correspondance entre des noms et des valeurs : ```js -var content = "Hello World"; -var myHeaders = new Headers(); -myHeaders.append("Content-Type", "text/plain"); -myHeaders.append("Content-Length", content.length.toString()); -myHeaders.append("X-Custom-Header", "ProcessThisImmediately"); +const contenu = "Coucou le monde"; +const mesEntetes = new Headers(); +mesEntetes.append("Content-Type", "text/plain"); +mesEntetes.append("Content-Length", contenu.length.toString()); +mesEntetes.append("X-Custom-Header", "ATraiterImmediatement"); ``` -On peut atteindre le même résultat en transmettant un tableau de tableaux ou un objet littéral au constructeur : +On pourra obtenir le même résultat en passant un tableau de tableaux ou un littéral objet au constructeur : ```js -myHeaders = new Headers({ +const mesEntetes = new Headers({ "Content-Type": "text/plain", - "Content-Length": content.length.toString(), - "X-Custom-Header": "ProcessThisImmediately", + "Content-Length": contenu.length.toString(), + "X-Custom-Header": "ATraiterImmediatement", }); ``` -Le contenu peut être interrogé et récupéré : +Le contenu de ces en-têtes peut être consulté et modifié : ```js -console.log(myHeaders.has("Content-Type")); // true -console.log(myHeaders.has("Set-Cookie")); // false -myHeaders.set("Content-Type", "text/html"); -myHeaders.append("X-Custom-Header", "AnotherValue"); +console.log(mesEntetes.has("Content-Type")); // true +console.log(mesEntetes.has("Set-Cookie")); // false +mesEntetes.set("Content-Type", "text/html"); +mesEntetes.append("X-Custom-Header", "UneAutreValeur"); -console.log(myHeaders.get("Content-Length")); // 11 -console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"] +console.log(mesEntetes.get("Content-Length")); // 11 +console.log(mesEntetes.get("X-Custom-Header")); // ['ATraiterImmediatement', 'UneAutreValeur'] -myHeaders.delete("X-Custom-Header"); -console.log(myHeaders.getAll("X-Custom-Header")); // [ ] +mesEntetes.delete("X-Custom-Header"); +console.log(mesEntetes.get("X-Custom-Header")); // null ``` -Certaines de ces opérations sont seulement utiles dans {{domxref("ServiceWorker_API","ServiceWorkers")}}, mais elles fournissent une bien meilleur API pour la manipulation des en-têtes. +Certaines de ces opérations ne sont utiles qu'avec les [service workers](/fr/docs/Web/API/Service_Worker_API), néanmoins, elles fournissent une API plus pratique pour manipuler les en-têtes. -Toutes les méthodes d'en-tête provoquent une erreur `TypeError` si un nom d'en-tête utilisé n'est pas un nom d'en-tête HTTP valide. Les opérations de mutation vont provoquer une erreur `TypeError` si il y a une protection immutable (voir ci-dessous). Sinon elles échoueront en silence. Par exemple : +Toutes les méthodes de `Headers` lèvent une exception `TypeError` si le nom d'en-tête utilisé n'est pas valide en HTTP. Les opérations de modification déclencheront une exception `TypeError` s'il y a une garde d'immuabilité ([voir ci-après](#garde)). Sinon, elles échouent de façon silencieuse : ```js -var myResponse = Response.error(); +const maReponse = Response.error(); try { - myResponse.headers.set("Origin", "http://mybank.com"); + maReponse.headers.set("Origin", "http://mabanque.com"); } catch (e) { - console.log("Ne peut pas prétendre être une banque!"); + console.log("On ne se fait pas passer pour une banque !"); } ``` -Un bon cas d'utilisation des en-têtes est de vérifier que le type de contenu récupéré est correct avant de poursuivre le traitement. Par exemple : +Un bon usage des en-têtes consiste à vérifier si le type de contenu est correct avant d'aller plus loin dans le traitement. Par exemple : ```js -fetch(myRequest).then(function (response) { - var contentType = response.headers.get("content-type"); - if (contentType && contentType.indexOf("application/json") !== -1) { - return response.json().then(function (json) { - // traitement du JSON - }); - } else { - console.log("Oops, nous n'avons pas du JSON!"); +async function fetchJSON(requete) { + try { + const reponse = await fetch(requete); + const typeContenu = reponse.headers.get("content-type"); + if (!typeContenu || !typeContenu.includes("application/json")) { + throw new TypeError("Ah, nous n'avons pas eu de JSON !"); + } + const donneesJSON = await reponse.json(); + // on continue le traitement des données + } catch (erreur) { + console.error("Erreur :", erreur); } -}); +} ``` -### Protection (guard) +### Garde -Puisque les en-têtes peuvent être envoyés dans les requêtes et reçus dans les réponses, et qu'elles ont diverses limitations concernant les informations qui peuvent et doivent être mutables, les objets en-tête ont une propriété guard. Celle-ci n'est pas exposée au Web, mais elle définit quelle opération de mutation est autorisée sur l'objet en-tête. +Les en-têtes sont envoyés avec les requêtes et reçus avec les réponses. Plusieurs règles indiquent les informations qui peuvent ou non être modifiées et pour traduire cela, les objets des en-têtes ont une propriété interne `guard`. Cette dernière n'est pas exposée sur le Web, mais a un impact sur les opérations de modification qui sont permises. -Les valeurs possibles de la propriété guard sont : +Les valeurs pour `guard` sont : -- `none` : défaut. -- `request` : guard pour l'en-tête obtenu d'une requête ({{domxref("Request.headers")}}). -- `request-no-cors` : guard pour l'en-tête obtenu d'une requête créée avec {{domxref("Request.mode")}} `no-cors`. -- `response` : guard pour l'en-tête obtenu d'une réponse ({{domxref("Response.headers")}}). -- `immutable` : majoritairement utilisé pour les service workers ; retourne un objet en-tête en lecture seule. +- `none` + - : La valeur par défaut. +- `request` + - : Une garde pour l'objet d'en-têtes obtenus avec une requête ([`Request.headers`](/fr/docs/Web/API/Request/headers)). +- `request-no-cors` + - : Une garde pour l'objet d'en-têtes obtenus avec une requête créée avec [`Request.mode`](/fr/docs/Web/API/Request/mode) `no-cors`. +- `response` + - : Une garde pour l'objet d'en-têtes obtenus avec une réponse ([`Response.headers`](/fr/docs/Web/API/Response/headers)). +- `immutable` + - : Une garde qui indique que l'objet d'en-têtes est en lecture seule. Elle est principalement utilisée pour les service workers. -> **Note :** Vous ne pouvez pas ajouter ou définir sur une requête protegée un en-tête `Content-Length`. De manière similaire, ajouter `Set-Cookie` dans l'en-tête de réponse n'est pas autorisé, les service workers n'étant pas autorisés à gérer des cookies via des réponses synthétisées. +> **Note :** Il n'est pas possible d'ajouter ou de modifier l'en-tête `Content-Length` d'un objet d'en-têtes de réponse avec une garde. De même, on ne pourra pas insérer d'en-tête `Set-Cookie` pour une réponse : les service workers ne sont pas autorisés à écrire des cookies dans des réponses de synthèse. -## Réponses +## Objets `Response` -Comme vous l'avez vu ci-dessus, des instances de {{domxref("Response")}} sont retournées quand la promesse de `fetch()` est résolue. +Nous l'avons vu ci-avant, ce sont des instances de [`Response`](/fr/docs/Web/API/Response) qui sont renvoyées lors de la résolution des promesses fournies par `fetch()`. -Elles peuvent aussi être programmées dans le code via JavaScript, mais c'est seulement utile concernant les [service workers](/fr/docs/Web/API/Service_Worker_API), quand vous retournez, pour une requête reçue, une réponse personnalisée en utilisant la méthode {{domxref("FetchEvent.respondWith","respondWith()")}} : +Les propriétés les plus fréquemment utilisées pour ces objets `Response` sont : -```js -var myBody = new Blob(); +- [`Response.status`](/fr/docs/Web/API/Response/status) + - : Un entier contenant le code de statut HTTP de la réponse (la valeur par défaut est 200). +- [`Response.statusText`](/fr/docs/Web/API/Response/statusText) + - : Une chaîne de caractères qui contient le message du code de statut HTTP (la valeur par défaut est la chaîne vide `""`). On notera que HTTP/2 [ne prend pas en charge](https://fetch.spec.whatwg.org/#concept-response-status-message) les messages de statut. +- [`Response.ok`](/fr/docs/Web/API/Response/ok) + - : Nous avons vu cette propriété plus tôt dans cet article : il s'agit d'un raccourci pour vérifier que le statut appartient à l'intervalle 200-299. Cette propriété est une valeur booléenne. -addEventListener('fetch', function(event) { - event.respondWith(new Response(myBody, { - headers: { "Content-Type" : "text/plain" } - }); -)}); -``` +On peut également créer des réponses artificiellement en JavaScript. Cela n'est généralement utile qu'au sein des [service workers](/fr/docs/Web/API/Service_Worker_API), lorsqu'on fournit une réponse sur mesure à une requête reçue en utilisant la méthode [`respondWith()`](/fr/docs/Web/API/FetchEvent/respondWith) : -Le constructeur {{domxref("Response.Response","Response()")}} prend deux arguments optionnels : le corps de la réponse, et un objet d'options (similaire à l'objet que {{domxref("Request.Request","Request()")}} accepte). +```js +const monCorps = new Blob(); + +addEventListener("fetch", (event) => { + // Un ServiceWorker qui intercepte une requête de récupération + event.respondWith( + new Response(monCorps, { + headers: { "Content-Type": "text/plain" }, + }), + ); +}); +``` -Les propriétés de réponse les plus communes que vous allez utiliser sont : +Le constructeur [`Response()`](/fr/docs/Web/API/Response/Response) prend deux arguments optionnels : -- {{domxref("Response.status")}} — un entier (valeur par défaut 200) contenant le code de statut de la réponse. -- {{domxref("Response.statusText")}} — une chaine de caractères (valeur par défaut "OK"), qui correspond au message du statut HTTP. -- {{domxref("Response.ok")}} — vu précedemment, c'est un raccourci pour vérifier que le code de statut et bien compris entre 200 et 299 inclus. Retourne un {{domxref("Boolean")}}. +- Un corps pour la réponse +- Un objet d'initialisation des paramètres, semblable à celui qu'on fournit au constructeur [`Request()`](/fr/docs/Web/API/Request/Request). -> **Note :** La méthode statique {{domxref("Response.error","error()")}} retourne simplement une réponse d'erreur. De manière similaire, {{domxref("Response.redirect","redirect()")}} retourne une réponse de redirection vers une URL spécifique. Elles sont aussi pertinentes pour les Service Workers. +> **Note :** La méthode statique [`error()`](/fr/docs/Web/API/Response/error_static) renvoie une réponse d'erreur. De même, [`redirect()`](/fr/docs/Web/API/Response/redirect_static) renvoie une réponse résultant en une redirection vers l'URL indiquée. Ces méthodes sont uniquement pertinentes dans le cadre des service workers. ## Corps -Autant une requête qu'une réponse peut contenir un corps avec des données. Un corps est une instance de n'importe lequel des types suivants : +Les requêtes et les réponses peuvent avoir un corps, contenant des données. Un corps pourra être une instance d'un des types suivants : -- {{domxref("ArrayBuffer")}} -- {{domxref("ArrayBufferView")}} (Uint8Array et ses proches) -- {{domxref("Blob")}}/Fichier -- chaine de caractères -- {{domxref("URLSearchParams")}} -- {{domxref("FormData")}} +- [`ArrayBuffer`](/fr/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) +- [`TypedArray`](/fr/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) (`Uint8Array`, etc.) +- [`DataView`](/fr/docs/Web/JavaScript/Reference/Global_Objects/DataView) +- [`Blob`](/fr/docs/Web/API/Blob) +- [`File`](/fr/docs/Web/API/File) +- [`String`](/fr/docs/Web/JavaScript/Reference/Global_Objects/String) ou une chaîne de caractères littérale +- [`URLSearchParams`](/fr/docs/Web/API/URLSearchParams) +- [`FormData`](/fr/docs/Web/API/FormData) -Le mixin {{domxref("Body")}} définit les méthodes suivantes pour extraire le corps (implémenté autant par la {{domxref("Request")}} que par la {{domxref("Response")}}). Elles retournent toutes une promesse qui sera éventuellement résolue avec le contenu actuel. +Les interfaces [`Request`](/fr/docs/Web/API/Request) et [`Response`](/fr/docs/Web/API/Response) partagent les méthodes suivantes pour extraire les données du corps. Toutes ces méthodes renvoient une promesse qui pourra être résolue avec le contenu effectif. -- {{domxref("Body.arrayBuffer","arrayBuffer()")}} -- {{domxref("Body.blob","blob()")}} -- {{domxref("Body.json","json()")}} -- {{domxref("Body.text","text()")}} -- {{domxref("Body.formData","formData()")}} +- [`Request.arrayBuffer()`](/fr/docs/Web/API/Request/arrayBuffer) / [`Response.arrayBuffer()`](/fr/docs/Web/API/Response/arrayBuffer) +- [`Request.blob()`](/fr/docs/Web/API/Request/blob) / [`Response.blob()`](/fr/docs/Web/API/Response/blob) +- [`Request.formData()`](/fr/docs/Web/API/Request/formData) / [`Response.formData()`](/fr/docs/Web/API/Response/formData) +- [`Request.json()`](/fr/docs/Web/API/Request/json) / [`Response.json()`](/fr/docs/Web/API/Response/json) +- [`Request.text()`](/fr/docs/Web/API/Request/text) / [`Response.text()`](/fr/docs/Web/API/Response/text) -Ceci rend l'usage de données non textuelles plus facile qu'avec XHR. +> **Note :** Ces méthodes permettent de travailler plus facilement avec du contenu non-textuel (par rapport à ce que permettait `XMLHttpRequest`). -Le corps des requêtes peut être défini en passant les paramètres du corps : +On peut fournir des corps aux requêtes en utilisant le deuxième paramètre et sa propriété `form` : ```js -var form = new FormData(document.getElementById("login-form")); +const form = new FormData(document.getElementById("login-form")); fetch("/login", { method: "POST", body: form, }); ``` -Les requêtes et réponses (et par extension la fonction `fetch()`), vont tenter de déterminer le type de contenu. Une requête va automatiquement définir un en-tête `Content-Type` si rien n'est défini dans le dictionnaire \[NDLT : configuration d'initialisation]. +Tant la requête que la réponse, ou la fonction `fetch()` essaieront de déterminer intelligemment le type de contenu. Une requête définira automatiquement un en-tête `Content-Type` si aucun n'a été fourni avec le paramètre [`options`](/fr/docs/Web/API/fetch#options). + +## Détection de la fonctionnalité -## Spécifications +La prise en charge de l'API Fetch peut être détectée en vérifiant la présence de [`Headers`](/fr/docs/Web/API/Headers), [`Request`](/fr/docs/Web/API/Request), [`Response`](/fr/docs/Web/API/Response) ou [`fetch()`](/fr/docs/Web/API/fetch) au sein des portées [`Window`](/fr/docs/Web/API/Window) ou [`Worker`](/fr/docs/Web/API/Worker). Par exemple : + +```js +if (window.fetch) { + // On exécute la requête avec Fetch ici +} else { + // On tente autre chose avec XMLHttpRequest ? +} +``` -{{Specifications}} +## Différences avec `jQuery.ajax()` -## Compatibilité des navigateurs +La spécification de `fetch()` diffère de `jQuery.ajax()` : -{{Compat}} +- La promesse renvoyée par `fetch()` ne lèvera pas d'exception en cas d'erreurs HTTP, même si le statut de la réponse HTTP est 404 ou 500. Dès que le serveur répond avec les en-têtes, la promesse sera bien résolue (la propriété [`Response.ok`](/fr/docs/Web/API/Response/ok) étant fixée à `false` si le statut de la réponse est en dehors de l'intervalle [200, 299]). La promesse sera uniquement rompue s'il y a une erreur réseau ou tout autre évènement qui a empêché sa complétion. +- À moins que `fetch()` ne soit appelé avec l'option [`credentials`](/fr/docs/Web/API/fetch#credentials) valant `include`, `fetch()` : + - N'enverra pas de cookies pour les requêtes vers d'autres origines + - N'écrira pas de cookies provenant de réponses d'autres origines ## Voir aussi -- [API ServiceWorker](/fr/docs/Web/API/ServiceWorker_API) -- [HTTP access control (CORS)](/fr/docs/Web/HTTP/Access_control_CORS) +- [L'API Service Worker](/fr/docs/Web/API/Service_Worker_API) +- [La politique HTTP d'accès aux ressources entre origines (CORS)](/fr/docs/Web/HTTP/CORS) - [HTTP](/fr/docs/Web/HTTP) -- [Polyfill pour Fetch](https://github.com/github/fetch) -- [Exemples de Fetch sur Github](https://github.com/mdn/fetch-examples/) +- [Une prothèse d'émulation (polyfill) pour `fetch()`](https://github.com/JakeChampion/fetch) +- [D'autres exemples (en anglais) sur d'utilisation de Fetch sur GitHub](https://github.com/mdn/dom-examples/tree/main/fetch) diff --git a/files/fr/web/css/gradient/repeating-linear-gradient/index.md b/files/fr/web/css/gradient/repeating-linear-gradient/index.md index 6e17dd6989940e..b4fedcf2b3499a 100644 --- a/files/fr/web/css/gradient/repeating-linear-gradient/index.md +++ b/files/fr/web/css/gradient/repeating-linear-gradient/index.md @@ -1,6 +1,8 @@ --- title: repeating-linear-gradient() slug: Web/CSS/gradient/repeating-linear-gradient +l10n: + sourceCommit: 581b0f5068b7417e525abfe5c230e35cceca04df --- {{CSSRef}} @@ -13,7 +15,7 @@ La longueur du dégradé répété est la distance entre le premier et le dernie Comme les autres dégradés, un dégradé linéaire répété [n'a pas de dimensions intrinsèques](/fr/docs/Web/CSS/image#description), c'est-à-dire qu'il n'a pas de taille ou de proportions préférées. Sa taille réelle correspondra à la taille de l'élément auquel il est appliqué. -Comme pour les autres dégradés, un dégradé linéaire répété n'est pas une couleur (type [``](/fr/docs/Web/CSS/color_value)) CSS mais un type particulier d'image (type [``](/fr/docs/Web/CSS/image). À ce titre, `repeating-linear-gradient()` ne fonctionnera pas pour [`background-color`](/fr/docs/Web/CSS/background-color) et les autres propriétés qui utilisent le type de données [``](/fr/docs/Web/CSS/color_value). +Comme pour les autres dégradés, un dégradé linéaire répété n'est pas une couleur (type [``](/fr/docs/Web/CSS/color_value)) CSS mais un type particulier d'image (type [``](/fr/docs/Web/CSS/image)). À ce titre, `repeating-linear-gradient()` ne fonctionnera pas pour [`background-color`](/fr/docs/Web/CSS/background-color) et les autres propriétés qui utilisent le type de données [``](/fr/docs/Web/CSS/color_value). ## Syntaxe @@ -28,7 +30,9 @@ repeating-linear-gradient(45deg, blue, red 33.3%); repeating-linear-gradient(to left top, blue, red 20px); /* Un dégradé répétitif allant du bas vers le haut, - débutant bleu, étant vert après 40% et finissant rouge */ + débutant bleu, étant vert après 40% et finissant rouge. + Ce dégradé ne se répète pas car le dernier arrêt de couleur + est par défaut à 100%. */ repeating-linear-gradient(0deg, blue, green 40%, red); /* Un dégradé répété cinq fois, progressant de gauche à @@ -50,9 +54,9 @@ repeating-linear-gradient(to right, red 0%, green 10%, red 20%); - `` - : Un arrêt de couleur décrit par une valeur [``](/fr/docs/Web/CSS/color_value), suivie d'une ou deux positions optionnelles (une position étant donnée par un pourcentage (type [``](/fr/docs/Web/CSS/percentage)) ou une longueur (type [``](/fr/docs/Web/CSS/length)) le long de l'axe du dégradé). Un pourcentage à `0%`, ou une longueur à `0` représente le début du dégradé. La valeur `100%` correspond à 100% de la taille de l'image, indiquant que le dégradé ne se répètera pas. - `` - - : L'indication de couleur est une indication pour l'interpolation des couleurs le long du dégradé et entre deux points d'arrêt de couleur. La longueur définit l'emplacement où la transition entre les deux couleurs est appliquée à moitié. Si cette valeur est absente, le niveau intermédiaire de la transition se situera à équidistance des deux points d'arrêt de couleur. + - : L'indication de couleur est une indication pour l'interpolation des couleurs le long du dégradé et entre deux points d'arrêt de couleur. La longueur définit à quel point, entre deux arrêts de couleur, la couleur du dégradé doit atteindre le point médian de la transition de couleur. Si cette valeur est absente, le niveau intermédiaire de la transition se situera à équidistance des deux points d'arrêt de couleur. -> **Note :** Le rendu des arrêts de couleurs des dégradés CSS suit les mêmes règles que les [arrêts de couleur pour les dégradés SVG](/fr/docs/Web/SVG/Tutorial/Gradients). +> **Note :** Le rendu des arrêts de couleurs des dégradés CSS suit les mêmes règles que [les arrêts de couleur pour les dégradés SVG](/fr/docs/Web/SVG/Tutorial/Gradients). ### Syntaxe formelle @@ -113,7 +117,7 @@ body { Le dernier arrêt de couleur étant situé à 10% et le dégradé étant vertical, chaque dégradé unitaire occupe 10% de la hauteur totale, ce qui permet d'avoir 10 barres horizontales. -> **Note :** Voir [la page Utiliser les dégradés CSS](/fr/docs/Web/CSS/CSS_Images/Using_CSS_gradients) pour plus d'exemples. +> **Note :** Voir [la page Utiliser les dégradés CSS](/fr/docs/Web/CSS/CSS_images/Using_CSS_gradients) pour plus d'exemples. ## Spécifications @@ -125,7 +129,7 @@ Le dernier arrêt de couleur étant situé à 10% et le dégradé étant vertica ## Voir aussi -- [Utiliser les dégradés CSS](/fr/docs/Web/CSS/CSS_Images/Using_CSS_gradients) +- [Utiliser les dégradés CSS](/fr/docs/Web/CSS/CSS_images/Using_CSS_gradients) - Les autres fonctions de dégradés : - [`conic-gradient()`](/fr/docs/Web/CSS/gradient/conic-gradient) - [`linear-gradient()`](/fr/docs/Web/CSS/gradient/linear-gradient) diff --git a/files/fr/web/progressive_web_apps/tutorials/index.md b/files/fr/web/progressive_web_apps/tutorials/index.md new file mode 100644 index 00000000000000..d690b96f787a70 --- /dev/null +++ b/files/fr/web/progressive_web_apps/tutorials/index.md @@ -0,0 +1,18 @@ +--- +title: Tutoriels +slug: Web/Progressive_web_apps/Tutorials +l10n: + sourceCommit: 8d202854ade7328f827da2951bc714455f78674f +--- + +{{PWASidebar}} + +Cette page répertorie les tutoriels permettant d'apprendre à développer des applications web progressives (abbrégé PWA en anglais pour « Progressive Web Apps »). Les tutoriels décrivent les étapes de la création d'une application, du début à la fin, en expliquant comment les différentes fonctionnalités de l'application sont mises en œuvre. + +- [Créer votre première PWA](/fr/docs/Web/Progressive_web_apps/Tutorials/CycleTracker) + + - : Ce tutoriel pour débutantes et débutants présente la création d'une application web pour le suivi des cycles menstruels. Les leçons comprennent un passage en revue du HTML, du CSS et du JavaScript nécessaires pour créer une application web entièrement fonctionnelle, la mise en place d'un environnement de test et des explications complètes guidant dans la mise à niveau de l'application web en une application web progressive ; y compris le développement et l'inspection d'un manifeste, l'ajout d'un service workers et l'utilisation de service workers pour supprimer les caches périmés. + +- [Introduction aux PWA](/fr/docs/Web/Progressive_web_apps/Tutorials/js13kGames) + + - : Ce tutoriel de niveau intermédiaire présente la création d'une PWA qui répertorie les informations sur les jeux soumis dans la catégorie A-Frame du concours [js13kGames 2017](https://2017.js13kgames.com/). Ce tutoriel comprend toutes les bases de la création d'une PWA, avec des fonctionnalités supplémentaires, y compris les notifications, l'usage de push et les performances de l'application. diff --git a/files/fr/webassembly/javascript_interface/index.md b/files/fr/webassembly/javascript_interface/index.md index 74de65994d661c..30636377dac9a4 100644 --- a/files/fr/webassembly/javascript_interface/index.md +++ b/files/fr/webassembly/javascript_interface/index.md @@ -22,7 +22,7 @@ L'objet `WebAssembly` est notamment utilisé pour : - {{jsxref("WebAssembly.instantiate()")}} - : La méthode qu'on utilisera la plupart du temps pour compiler et instancier du code WebAssembly, elle renvoie une promesse qui est résolue en une `Instance` ou en une `Instance` et un `Module`. - {{jsxref("WebAssembly.instantiateStreaming()")}} - - : Cette méthode peremet de compiler et d'instancier un module WebAssembly à partir d'un flux source (_streamed source_). Elle renvoie à la fois un objet `Module` et sa première `Instance`. + - : Cette méthode permet de compiler et d'instancier un module WebAssembly à partir d'un flux source (_streamed source_). Elle renvoie à la fois un objet `Module` et sa première `Instance`. - {{jsxref("WebAssembly.compile()")}} - : Cette méthode permet de compiler un {{jsxref("WebAssembly.Module")}} à partir de _bytecode_ WebAssembly, l'instanciation doit alors être effectuée dans une autre étape. - {{jsxref("WebAssembly.compileStreaming()")}} diff --git a/files/ja/learn/javascript/first_steps/strings/index.md b/files/ja/learn/javascript/first_steps/strings/index.md index c0ebf081b422d6..11e395ddefb278 100644 --- a/files/ja/learn/javascript/first_steps/strings/index.md +++ b/files/ja/learn/javascript/first_steps/strings/index.md @@ -191,7 +191,7 @@ console.log(`${name}${number}`); // "フロント 242" 文字列に変換したいがそれ以外は変更しない数値変数、または数値に変換したいがそれ以外は変更しない文字列変数がある場合、以下の 2 つの構文を使用することができます。 -- {{jsxref("Number/Number", "Number()")}} 関数トは渡されたものすべてを数値に変換します。次の例を実行してみましょう。 +- {{jsxref("Number/Number", "Number()")}} 関数は渡されたものすべてを数値に変換します。次の例を実行してみましょう。 ```js const myString = "123"; diff --git a/files/ja/web/api/audiocontext/audiocontext/index.md b/files/ja/web/api/audiocontext/audiocontext/index.md index 3c2f1da9c8fdc3..0d8e9b2a3e12bc 100644 --- a/files/ja/web/api/audiocontext/audiocontext/index.md +++ b/files/ja/web/api/audiocontext/audiocontext/index.md @@ -1,26 +1,90 @@ --- -title: AudioContext() +title: "AudioContext: AudioContext() コンストラクター" +short-title: AudioContext() slug: Web/API/AudioContext/AudioContext +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- -{{APIRef("Web Audio API")}}{{SeeCompatTable}} +{{APIRef("Web Audio API")}} -**`AudioContext()`** コンストラクタは新しい {{domxref("AudioContext")}} オブジェクトを作成します。このオブジェクトはオーディオモジュールが相互に接続された音声処理のグラフを表現しています。このグラフ中で用いられるオーディオモジュールは {{domxref("AudioNode")}} として表現されます。 +**`AudioContext()`** コンストラクターは新しい {{domxref("AudioContext")}} オブジェクトを生成します。このオブジェクトは音声モジュールが相互に接続された音声処理のグラフを表現しています。このグラフ中で用いられる音声モジュールは {{domxref("AudioNode")}} として表現されます。 -## 記法 +## 構文 -``` -var audioContext = new AudioContext(options) +```js-nolint +new AudioContext() +new AudioContext(options) ``` ### 引数 -なし。 +- `options` {{optional_inline}} + - : コンテキストを設定するために使用するオブジェクト。利用できるプロパティは以下のとおりです。 + - `latencyHint` {{optional_inline}} + - : コンテキストを使用する再生の種類。定義済みの文字列（`"balanced"`、`"interactive"`、`"playback"`）、またはコンテキストの推奨する最大レイテンシーを秒単位で示す倍精度浮動小数点数値です。 + ユーザーエージェントは、このリクエストに応じても応じなくても構いません。 + コンテキストを作成した後、 {{domxref("AudioContext.baseLatency")}} の値を調べて真のレイテンシーを決定します。 + - `"balanced"`: ブラウザーはレイテンシー値を選択する際、音声出力のレイテンシーと消費電力のバランスをとります。 + - `"interactive"` （既定値）: 音声は、ユーザー操作に反応したり、動画やゲームのアクションなどの視覚的な合図に合わせる必要があるなど、インタラクティブな要素に関与します。 + ブラウザーは音声にグリッチを発生させない使用可能な最低のレイテンシーを選択します。これは消費電力の増加を要求される可能性があります。 + - `"playback"`: ブラウザーは、レイテンシーを犠牲にして消費電力を最小限に抑え、再生時間を最大化するレイテンシーを選択します。 + 音楽再生など、操作を必要としない再生に有益な機能です。 + - `sampleRate` {{optional_inline}} + - : 新しいコンテキストに使用するサンプリングレートを示します。この値は、新しいコンテキストを構成するサンプリングレートを示す浮動小数点数で、 1 秒あたりのサンプル数でなければなりません。 + また、 {{domxref("AudioBuffer.sampleRate")}} で対応している値でなければなりません。 + 値は通常 8,000Hz から 96,000Hz の間で、既定値は出力機器によって異なりますが、サンプリングレート 44,100Hz が最も一般的です。 + もし `sampleRate` プロパティがオプションに含まれていなかったり、音声コンテキストを作成するときにオプションが指定されていなかったりした場合 は、新しいコンテキストの出力機器が推奨するサンプリングレートが既定で使用されます。 + - `sinkId` {{optional_inline}} {{Experimental_Inline}} + - : `AudioContext` に使用するオーディオ出力機器のシンク ID を指定します。これは以下の値のうちの一つを取ります。 + - シンク ID を表す文字列です。これは例えば、 {{domxref("MediaDevices.enumerateDevices()")}} が返す {{domxref("MediaDeviceInfo")}} オブジェクトの `deviceId` プロパティから取得したものです。 + - シンク ID を表す文字列です。シンク ID を表す文字列です。 + +### 返値 + +新しい {{domxref("AudioContext")}} インスタンスです。 + +### 例外 + +- `NotSupportedError` {{domxref("DOMException")}} + - : 指定した `sampleRate` がコンテキストで対応していない場合に発生します。 + +## 使用上の注意 + +仕様書では、ユーザーエージェントが対応すべき音声コンテキストの数や、レイテンシの最小・最大要件（もしあれば）などについてあまり詳しく説明していないため、これらの詳細はブラウザーによって異なる可能性があります。重要であれば、必ず値を調べてください。 + +特に、仕様書では同時に開くための音声コンテキストの最大数や最小数を示していないため、これはブラウザーの実装に任せられています。 + +### Google Chrome + +#### Chrome におけるタブごとの音声コンテキストの制約 -## 仕様 +バージョン 66 以前の Google Chrome では、 1 つのタブにつき最大 6 つの音声コンテキストにしか対応していませんでした。 + +#### Chrome での標準外の例外 + +`latencyHint` プロパティの値が有効でない場合、Chrome は "The provided value '...' is not a valid enum value of type AudioContextLatencyCategory" というメッセージと共に {{jsxref("TypeError")}} 例外を発生します。 + +## 例 + +この例では、インタラクティブ音声用の新しい {{domxref("AudioContext")}} を作成し（遅延を最適化）、サンプルレートを 44.1kHz、音声出力を固有のものにします。 + +```js +const audioCtx = new AudioContext({ + latencyHint: "interactive", + sampleRate: 44100, + sinkId: "bb04fea9a8318c96de0bd...", // truncated for brevity +}); +``` + +## 仕様書 {{Specifications}} ## ブラウザー互換性 -{{Compat("api.AudioContext.AudioContext")}} +{{Compat}} + +## 関連情報 + +- {{domxref("OfflineAudioContext.OfflineAudioContext()", "new OfflineAudioContext()")}} コンストラクター diff --git a/files/ja/web/api/audiocontext/baselatency/index.md b/files/ja/web/api/audiocontext/baselatency/index.md index 1b4e03502fc2a4..7651c1ff1bcfd1 100644 --- a/files/ja/web/api/audiocontext/baselatency/index.md +++ b/files/ja/web/api/audiocontext/baselatency/index.md @@ -1,13 +1,14 @@ --- -title: AudioContext.baseLatency +title: "AudioContext: baseLatency プロパティ" +short-title: baseLatency slug: Web/API/AudioContext/baseLatency l10n: - sourceCommit: bca8d1ab2bc4f5a1ef6b39c454b0229539178e98 + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{APIRef("Web Audio API")}} -{{domxref("AudioContext")}} インターフェイスの読み取り専用プロパティ **`baseLatency`** は、{{domxref("AudioDestinationNode")}} すなわち音声グラフの終端から音声バッファーをホストシステムで再生の準備ができている音声サブシステムに渡すときに発生する処理の遅延の秒数を表す `double` の値を返します。 +**`baseLatency`** は {{domxref("AudioContext")}} インターフェイスの読み取り専用プロパティで、{{domxref("AudioDestinationNode")}} すなわち音声グラフの終端から音声バッファーをホストシステムで再生の準備ができている音声サブシステムに渡すときに発生する処理の遅延の秒数を表す `double` の値を返します。 > **メモ:** {{domxref("AudioContext.AudioContext()", "コンテキストの生成時", "", "true")}}に `latencyHint` オプションを用いることで特定の遅延を要求することができます。しかし、ブラウザーはこのオプションを無視する可能性があります。 @@ -37,5 +38,5 @@ console.log(audioCtx2.baseLatency); // 0.15 ## 関連情報 -- [Web Audio API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) - [ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/close/index.md b/files/ja/web/api/audiocontext/close/index.md index 95d24b75c1ea23..01ea5cc3eac1a0 100644 --- a/files/ja/web/api/audiocontext/close/index.md +++ b/files/ja/web/api/audiocontext/close/index.md @@ -1,35 +1,38 @@ --- -title: AudioContext.close() +title: "AudioContext: close() メソッド" +short-title: close() slug: Web/API/AudioContext/close +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -{{ domxref("AudioContext") }}インターフェースの`close()`メソッドは、オーディオコンテキストを閉じて使っていたシステムのオーディオリソースを全て解放します。 +`close()` は {{ domxref("AudioContext") }} インターフェイスのメソッドで、音声コンテキストを閉じて使っていたシステムの音声リソースを全て解放します。 -閉じたコンテキストは新しいノードを生成できませんが、音声データのデコードやバッファの生成などは可能です。 - -この関数は、他の参照も同様に解放されない限り、AudioContext が生成したオブジェクトは自動的には解放しません。しかし、これはオーディオリソースを強制的に解放します。よって、オーディオコンテキストの更なる生成と使用はできなくなり、オーディオコンテキストの時間の流れは止まり、音声データの処理は停止します。 -全ての AudioContext-creation-blocking リソースが解放されたとき、返された{{jsxref("Promise")}}が完了します。このメソッドは{{domxref("OfflineAudioContext")}}で呼ばれたとき`INVALID_STATE_ERR`例外が発生します。 +この関数は、他の参照も同様に解放されない限り、 `AudioContext` が生成したオブジェクトは自動的には解放しません。しかし、これは音声リソースを強制的に解放します。よって、音声コンテキストの更なる生成と使用はできなくなり、音声コンテキストの時間の流れは止まり、音声データの処理は停止します。 `AudioContext` の生成をブロックするリソースがすべて解放されたとき、返された {{jsxref("Promise")}} が解決します。このメソッドは {{domxref("OfflineAudioContext")}} で呼ばれたとき `INVALID_STATE_ERR` 例外が発生します。 ## 構文 -```js -var audioCtx = new AudioContext(); -audioCtx.close().then(function() { ... }); +```js-nolint +close() ``` -### 戻り値 +### 引数 + +なし。 + +### 返値 -void で完了する{{jsxref("Promise")}}。 +{{jsxref('undefined')}} で解決する {{jsxref("Promise")}} です。 ## 例 -次のスニペットは[AudioContext states デモ](https://github.com/mdn/audiocontext-states/settings)([すぐ実行](http://mdn.github.io/audiocontext-states/))から取ったものです。stop ボタンをクリックすると、`close()`が呼ばれます。プロミスに成功すると、リセットされ最初の状態に戻ります。 +次のスニペットは [AudioContext states デモ](https://github.com/mdn/webaudio-examples/blob/master/audiocontext-states/index.html)（[すぐ実行](https://mdn.github.io/webaudio-examples/audiocontext-states/)）から取ったものです。stop ボタンをクリックすると、 `close()` が呼び出されます。プロミスに成功すると、リセットされ最初の状態に戻ります。 ```js -stopBtn.onclick = function () { - audioCtx.close().then(function () { +stopBtn.onclick = () => { + audioCtx.close().then(() => { startBtn.removeAttribute("disabled"); susresBtn.setAttribute("disabled", "disabled"); stopBtn.setAttribute("disabled", "disabled"); @@ -37,15 +40,15 @@ stopBtn.onclick = function () { }; ``` -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザ互換性 +## ブラウザーの互換性 -{{Compat("api.AudioContext.close")}} +{{Compat}} -## 参考 +## 関連情報 -- [Using the Web Audio API](/ja/docs/Web_Audio_API/Using_Web_Audio_API) -- [Web Audio API](/ja/docs/Web/API/Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/createmediaelementsource/index.md b/files/ja/web/api/audiocontext/createmediaelementsource/index.md index 36d198878b3fac..c056083b6ea5f8 100644 --- a/files/ja/web/api/audiocontext/createmediaelementsource/index.md +++ b/files/ja/web/api/audiocontext/createmediaelementsource/index.md @@ -1,88 +1,80 @@ --- -title: AudioContext.createMediaElementSource() +title: "AudioContext: createMediaElementSource() メソッド" +short-title: createMediaElementSource() slug: Web/API/AudioContext/createMediaElementSource +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -{{ domxref("AudioContext") }}インターフェースの createMediaElementSource()メソッドは、新しく{{ domxref("MediaElementAudioSourceNode") }} オブジェクトを作成するために使用されます。HTML 内に存在する{{htmlelement("audio")}} または {{htmlelement("video")}} を指定すると、そのオーディオを再生し、操作することができます。 +`createMediaElementSource()` は {{ domxref("AudioContext") }} インターフェイスのメソッドで、新しい {{ domxref("MediaElementAudioSourceNode") }} オブジェクトを作成するために使用されます。 HTML 内に存在する{{htmlelement("audio")}} または {{htmlelement("video")}} を指定すると、その音声を再生し、操作することができます。 -media element audio source nodes についての詳細は、 {{ domxref("MediaElementAudioSourceNode") }} を参照して下さい。 +メディア要素の音声ソースノードについての詳細は、 {{ domxref("MediaElementAudioSourceNode") }} を参照して下さい。 ## 構文 -```js -var audioCtx = new AudioContext(); -var source = audioCtx.createMediaElementSource(myMediaElement); +```js-nolint +createMediaElementSource(myMediaElement) ``` ### 引数 - `myMediaElement` - - : プロセッシング・グラフで操作するための {{ domxref("HTMLMediaElement") }} オブジェクトです。 + - : 音声処理グラフに与えて操作したい {{domxref("HTMLMediaElement")}} オブジェクトです。 -### 戻り値 +### 返値 -{{domxref("MediaElementAudioSourceNode")}} +{{domxref("MediaElementAudioSourceNode")}} です。 ## 例 -以下の例では、createMediaElementSource()を使用して {{ htmlelement("audio") }} から音源を作成します。 再生される音源は {{ domxref("GainNode") }} を介し {{ domxref("AudioDestinationNode") }} に渡されます。マウスポインタが動くと updatePage()関数が呼ばれ、マウスポインタの Y 座標の値をウィンドウの高さで割った比率を元に現在のゲインを計算します。また、マウスポインタを上下に動かすことで、再生している音楽の音量を上げ下げできます。 +以下の例では、 `createMediaElementSource()` を使用して {{htmlelement("audio") }} から音源を作成します。再生される音源は {{ domxref("GainNode") }} を介し {{ domxref("AudioDestinationNode") }} に渡されます。マウスポインターが動くと `updatePage()` 関数が呼ばれ、マウスポインターの Y 座標の値をウィンドウの高さで割った比率を元に現在のゲインを計算します。また、マウスポインターを上下に動かすことで、再生している音楽の音量を上げ下げできます。 -> **メモ:** [この例のデモ](http://mdn.github.io/media-source-buffer/)と、[ソース](https://github.com/mdn/media-source-buffer)を見ることができます。 +> **メモ:** [ライブで実行する例](https://mdn.github.io/webaudio-examples/media-source-buffer/)と、[ソース](https://github.com/mdn/media-source-buffer)を見ることができます。 ```js -var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); -var myAudio = document.querySelector("audio"); -var pre = document.querySelector("pre"); -var myScript = document.querySelector("script"); - -pre.innerHTML = myScript.innerHTML; +const audioCtx = new AudioContext(); +const myAudio = document.querySelector("audio"); // MediaElementAudioSourceNodeを作成 // HTMLMediaElementをそこへ接続 -var source = audioCtx.createMediaElementSource(myAudio); +const source = audioCtx.createMediaElementSource(myAudio); -// gain nodeを作成 -var gainNode = audioCtx.createGain(); +// ゲインノードを作成 +const gainNode = audioCtx.createGain(); -// マウスポインタのY座標と +// マウスポインターの Y 座標と // 画面の高さを保持するための変数を作成 -var CurY; -var HEIGHT = window.innerHeight; +let curY; +const HEIGHT = window.innerHeight; // マウスが動いたら新しいY座標を取得し、 // ゲインの値を設定する document.onmousemove = updatePage; function updatePage(e) { - CurY = window.Event - ? e.pageY - : event.clientY + - (document.documentElement.scrollTop - ? document.documentElement.scrollTop - : document.body.scrollTop); - - gainNode.gain.value = CurY / HEIGHT; + curY = e.pageY; + gainNode.gain.value = curY / HEIGHT; } -// AudioBufferSourceNodeをgainNodeへ接続 -// gainNodeをdestinationへ接続 +// AudioBufferSourceNode を gainNode へ接続 +// gainNode を destination へ接続 // これで音楽の再生と、マウスカーソルで音量を調節できるようになる source.connect(gainNode); gainNode.connect(audioCtx.destination); ``` -> **メモ:** createMediaElementSource()を呼んだ結果として {{ domxref("HTMLMediaElement") }} から再生される音声は AudioContext のプロセッシング・グラフへ再度ルーティングされます。従って、*createMediaElementSource()を呼んだ後も*音声の再生/一時停止は media element API 及びプレーヤーの再生/一時停止ボタンから操作できます。 +> **メモ:** `createMediaElementSource()`を呼び出した結果、 {{domxref("HTMLMediaElement")}} からの音声再生は AudioContext の処理グラフに再ルーティングされます。そのため、メディアの再生/一時停止は、メディア要素 API とプレーヤコントロールを通して行うことができます。 -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザの互換性 +## ブラウザーの互換性 -{{Compat("api.AudioContext.createMediaElementSource")}} +{{Compat}} ## 関連情報 -- [Web Audio API の利用](/ja/docs/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/createmediastreamdestination/index.md b/files/ja/web/api/audiocontext/createmediastreamdestination/index.md index 684899fbfe0a01..36684ae6217d0d 100644 --- a/files/ja/web/api/audiocontext/createmediastreamdestination/index.md +++ b/files/ja/web/api/audiocontext/createmediastreamdestination/index.md @@ -1,11 +1,14 @@ --- -title: AudioContext.createMediaStreamDestination() +title: "AudioContext: createMediaStreamDestination() メソッド" +short-title: createMediaStreamDestination() slug: Web/API/AudioContext/createMediaStreamDestination +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc --- {{ APIRef("Web Audio API") }} -{{ domxref("AudioContext") }} インターフェイスの `createMediaStreamDestination()` メソッドは、[WebRTC](/ja/docs/WebRTC) {{domxref("MediaStream")}} と関連付けられた {{domxref("MediaStreamAudioDestinationNode")}} オブジェクトを生成します。この MediaStream はローカルファイルに格納されたり他のコンピュータに送信されたりする音声ストリームを表します。 +`createMediaStreamDestination()` は {{ domxref("AudioContext") }} インターフェイスのメソッドで、 [WebRTC](/ja/docs/Web/API/WebRTC_API) の {{domxref("MediaStream")}} と関連付けられた {{domxref("MediaStreamAudioDestinationNode")}} オブジェクトを生成します。この MediaStream はローカルファイルに格納されたり他のコンピューターに送信されたりする音声ストリームを表します。 {{domxref("MediaStream")}} はノードが生成されたときに作成され、{{domxref("MediaStreamAudioDestinationNode")}}の `stream` プロパティを通じてアクセスすることができます。このストリームは {{domxref("navigator.getUserMedia") }} で得られた `MediaStream` と同じような使い方ができます。例えば、`RTCPeerConnection` インターフェイスの `addStream()` メソッドでリモートの端末に送ることができます。 @@ -13,27 +16,31 @@ slug: Web/API/AudioContext/createMediaStreamDestination ## 構文 -```js -var audioCtx = new AudioContext(); -var destination = audioCtx.createMediaStreamDestination(); +```js-nolint +createMediaStreamDestination() ``` -### 戻り値 +### 引数 -{{domxref("MediaStreamAudioDestinationNode")}} +なし。 + +### 返値 + +{{domxref("MediaStreamAudioDestinationNode")}} です。 ## 例 -次の簡単な例では、{{domxref("MediaStreamAudioDestinationNode")}}と{{ domxref("OscillatorNode") }}と{{ domxref("MediaRecorder") }} (そのため現時点では、このサンプルは Firefox と Chrome でしか動作しません) を作成します。`MediaRecorder` は `MediaStreamDestinationNode` からの情報を記録するように設定されています。 +次の簡単な例では、{{domxref("MediaStreamAudioDestinationNode")}} と {{ domxref("OscillatorNode") }} と {{ domxref("MediaRecorder") }} (そのため現時点では、このサンプルは Firefox と Chrome でしか動作しません) を作成します。`MediaRecorder` は `MediaStreamDestinationNode` からの情報を記録するように設定されています。 -ボタンをクリックするとオシレーター(振動子)が開始し、`MediaRecorder` も開始します。再びボタンを押して止めると、オシレーターと `MediaRecorder` の両方が停止します。`MediaRecorder` が停止すると `dataavailable` イベントが発火され、イベントデータが `chunks`配列にプッシュされます。その後、`stop` イベントが発火すると、新しい `blob` が opus タイプで作られます—そこには `chunks`配列のデータが書き込まれていて、その blob の URL を指す新しいウィンドウ(タブ)が開きます。 +ボタンをクリックするとオシレーター（振動子）が開始し、`MediaRecorder` も開始します。再びボタンを押して止めると、オシレーターと `MediaRecorder` の両方が停止します。`MediaRecorder` が停止すると `dataavailable` イベントが発火され、イベントデータが `chunks`配列にプッシュされます。その後、`stop` イベントが発火すると、新しい `blob` が opus タイプで作られます—そこには `chunks`配列のデータが書き込まれていて、その blob の URL を指す新しいウィンドウ（タブ）が開きます。 そこで opus ファイルの再生と保存ができます。 ```html - + + createMediaStreamDestination() demo @@ -43,20 +50,20 @@ var destination = audioCtx.createMediaStreamDestination(); @@ -82,14 +89,14 @@ var destination = audioCtx.createMediaStreamDestination(); > **メモ:** Github で[実際に動作する例を閲覧](https://mdn.github.io/webaudio-examples/create-media-stream-destination/index.html)したり、[ソースコードを読む](https://github.com/mdn/webaudio-examples/blob/master/create-media-stream-destination/index.html)ことができます。 -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザー互換性 +## ブラウザーの互換性 -{{Compat("api.AudioContext.createMediaStreamDestination")}} +{{Compat}} -## 参考 +## 関連情報 -- [Using the Web Audio API](/ja/docs/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/createmediastreamsource/index.md b/files/ja/web/api/audiocontext/createmediastreamsource/index.md index b844ac11f2a5a1..de05de10aa853f 100644 --- a/files/ja/web/api/audiocontext/createmediastreamsource/index.md +++ b/files/ja/web/api/audiocontext/createmediastreamsource/index.md @@ -1,91 +1,74 @@ --- -title: AudioContext.createMediaStreamSource() +title: "AudioContext: createMediaStreamSource() メソッド" +short-title: createMediaStreamSource() slug: Web/API/AudioContext/createMediaStreamSource +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -インターフェースの`createMediaStreamSource()`メソッドは、指定のメディアストリームから(言い換えると{{ domxref("navigator.getUserMedia") }}インスタンスから){{ domxref("MediaStreamAudioSourceNode") }}オブジェクトを生成します。ここからの音声は再生や編集ができます。 +`createMediaStreamSource()` は {{ domxref("AudioContext") }} インターフェイスのメソッドで、指定のメディアストリームから（言い換えると {{ domxref("navigator.getUserMedia") }} インスタンスから） {{ domxref("MediaStreamAudioSourceNode") }} オブジェクトを生成します。ここからの音声は再生や編集ができます。 -メディアストリームオーディオソースノードの詳細は{{ domxref("MediaStreamAudioSourceNode") }}のページを参照してください。 +メディアストリームの音声ソースノードの詳細は{{ domxref("MediaStreamAudioSourceNode") }}のページを参照してください。 ## 構文 -```js -var audioCtx = new AudioContext(); -var source = audioCtx.createMediaStreamSource(stream); +```js-nolint +createMediaStreamSource(stream) ``` ### 引数 -- stream - - : 操作のためにオーディオグラフに加えたい{{domxref("MediaStream")}}オブジェクト。 +- `stream` + - : 操作のために音声グラフに加えたい {{domxref("MediaStream")}} オブジェクト。 -### 戻り値 +### 返値 -{{domxref("MediaStreamAudioSourceNode")}} +指定したソースストリームから取得したメディアを持つ音声ノードを表す新しい {{domxref("MediaStreamAudioSourceNode")}} オブジェクトです。 ## 例 -この例では、メディア(音声+映像)ストリームを{{ domxref("navigator.getUserMedia") }}から獲得し、それを{{ htmlelement("video") }}要素に渡し、映像は再生しますが音声は再生しないようにします。音声は{{ domxref("MediaStreamAudioSourceNode") }}に渡します。次に、音声をローパスフィルタ{{ domxref("BiquadFilterNode") }}(低音を強めるように働きます)に渡し、そして{{domxref("AudioDestinationNode") }}に渡します。 +この例では、メディア（音声＋映像）ストリームを {{ domxref("navigator.getUserMedia") }} から獲得し、それを {{ htmlelement("video") }} 要素に渡し、映像は再生しますが音声は再生しないようにします。音声は {{ domxref("MediaStreamAudioSourceNode") }} に渡します。次に、音声をローパスフィルター {{ domxref("BiquadFilterNode") }} （低音を強めるように働きます）に渡し、そして {{domxref("AudioDestinationNode") }} に渡します。 -{{ htmlelement("video") }}要素の下のスライダーはローパスフィルタの増幅量を操作します—スライダーで値を大きくすると、より低音が強くなります! +{{ htmlelement("video") }} 要素の下のスライダーはローパスフィルターの増幅量を操作します—スライダーで値を大きくすると、より低音が強くなります。 > **メモ:** [この例の実行](http://mdn.github.io/stream-source-buffer/)と[ソースの閲覧](https://github.com/mdn/stream-source-buffer)もできます。 ```js -// プレフィックスが必要な場合を考慮して、getUserMediaはブラウザのバージョンごとに分ける - -navigator.getUserMedia = - navigator.getUserMedia || - navigator.webkitGetUserMedia || - navigator.mozGetUserMedia || - navigator.msGetUserMedia; - -// 他の変数を定義する - -var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); -var myAudio = document.querySelector("audio"); -var pre = document.querySelector("pre"); -var video = document.querySelector("video"); -var myScript = document.querySelector("script"); -var range = document.querySelector("input"); - -// マウスポインタのY座標と、画面の高さを格納する変数を定義する -var CurY; -var HEIGHT = window.innerHeight; +const pre = document.querySelector("pre"); +const video = document.querySelector("video"); +const myScript = document.querySelector("script"); +const range = document.querySelector("input"); // getUserMediaのブロック - ストリームを得る // MediaStreamAudioSourceNodeに渡す // 映像はvideo要素に出力する -if (navigator.getUserMedia) { +if (navigator.mediaDevices) { console.log("getUserMedia supported."); - navigator.getUserMedia( - // 制約: このアプリで音声と映像を有効にする - { - audio: true, - video: true, - }, - - // 成功時のコールバック - function (stream) { - video.src = (window.URL && window.URL.createObjectURL(stream)) || stream; - video.onloadedmetadata = function (e) { + navigator.mediaDevices + .getUserMedia({ audio: true, video: true }) + .then((stream) => { + video.srcObject = stream; + video.onloadedmetadata = (e) => { video.play(); - video.muted = "true"; + video.muted = true; }; - // MediaStreamAudioSourceNodeを生成し、それにHTMLMediaElementを渡す - var source = audioCtx.createMediaStreamSource(stream); + // MediaStreamAudioSourceNode を生成し、 + // それに HTMLMediaElement を渡す + const audioCtx = new AudioContext(); + const source = audioCtx.createMediaStreamSource(stream); // 二次フィルターを生成する - var biquadFilter = audioCtx.createBiquadFilter(); + const biquadFilter = audioCtx.createBiquadFilter(); biquadFilter.type = "lowshelf"; biquadFilter.frequency.value = 1000; biquadFilter.gain.value = range.value; - // AudioBufferSourceNodeをgainNodeに、そしてgainNodeをdestinationに接続する + // AudioBufferSourceNode を gainNode に、 + // そして gainNode を destination に接続する // これでマウスを動かすことで音楽のボリュームを調整することができる source.connect(biquadFilter); biquadFilter.connect(audioCtx.destination); @@ -93,35 +76,32 @@ if (navigator.getUserMedia) { // マウスが動いたとき新しい座標を得る // そして増幅量を更新する - range.oninput = function () { + range.oninput = () => { biquadFilter.gain.value = range.value; }; - }, - - // エラー時のフィードバック - function (err) { - console.log("The following gUM error occured: " + err); - }, - ); + }) + .catch((err) => { + console.log(`The following gUM error occurred: ${err}`); + }); } else { console.log("getUserMedia not supported on your browser!"); } -// pre要素にスクリプトを書き出す +// pre 要素にスクリプトを書き出す pre.innerHTML = myScript.innerHTML; ``` -> **メモ:** `createMediaStreamSource()`の呼び出しによるメディアストリームの音声は、再び`AudioContext`の処理グラフに入ります。よって、ストリームの再生/停止は、まだメディア API とプレイヤーの操作で行えます。 +> **メモ:** `createMediaStreamSource()` を呼び出した結果、メディアストリームからの音声再生は {{domxref("AudioContext")}} の処理グラフに再ルーティングされます。そのため、ストリームの再生/一時停止は、メディア要素 API とプレーヤーコントロールを通して行うことができます。 -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザ互換性 +## ブラウザーの互換性 -{{Compat("api.AudioContext.createMediaStreamSource")}} +{{Compat}} -## 参考 +## 関連情報 -- [Using the Web Audio API](/ja/docs/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/createmediastreamtracksource/index.md b/files/ja/web/api/audiocontext/createmediastreamtracksource/index.md index 43507e715d5b33..5f171368ab08e5 100644 --- a/files/ja/web/api/audiocontext/createmediastreamtracksource/index.md +++ b/files/ja/web/api/audiocontext/createmediastreamtracksource/index.md @@ -1,15 +1,16 @@ --- -title: AudioContext.createMediaStreamTrackSource() +title: "AudioContext: createMediaStreamTrackSource() メソッド" +short-title: createMediaStreamTrackSource() slug: Web/API/AudioContext/createMediaStreamTrackSource l10n: - sourceCommit: 98155013dee7d8b58a5df61b8195fa4b8196625b + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -{{domxref("AudioContext")}} インターフェイスの **`createMediaStreamTrackSource()`** メソッドは、指定の {{domxref("MediaStreamTrack")}} からデータを受け取る音源を表す {{domxref("MediaStreamTrackAudioSourceNode")}} を作成して返します。 +**`createMediaStreamTrackSource()`** は {{ domxref("AudioContext") }} インターフェイスのメソッドで、指定された {{domxref("MediaStreamTrack")}} からデータを受け取る音源を表す {{domxref("MediaStreamTrackAudioSourceNode")}} を作成して返します。 -このメソッドは、指定の {{domxref("MediaStream")}} の中の {{domxref("MediaStreamTrack.id", "id")}} が辞書順 (アルファベット順) で最初である音声トラックからデータを受け取る {{domxref("MediaStreamAudioSourceNode")}} を作成する {{domxref("AudioContext.createMediaStreamSource", "createMediaStreamSource()")}} とは異なります。 +このメソッドが {{domxref("AudioContext.createMediaStreamSource", "createMediaStreamSource()")}} と異なる点は、指定された {{domxref("MediaStream")}} の中の {{domxref("MediaStreamTrack.id", "id")}} が辞書順（アルファベット順）で最初の音声トラックからデータを受け取る {{domxref("MediaStreamAudioSourceNode")}} を作成する点です。 ## 構文 @@ -30,7 +31,7 @@ createMediaStreamTrackSource(track) この例では、ユーザーのマイクへのアクセスを要求するために {{domxref("MediaDevices.getUserMedia", "getUserMedia()")}} を使います。アクセスができるようになると、音声コンテキストを作成し、`getUserMedia()` が返したストリームの最初の音声トラックから音声を取得する {{domxref("MediaStreamTrackAudioSourceNode")}} を `createMediaStreamTrackSource()` により作成します。 -そして、{{domxref("BaseAudioContext/createBiquadFilter", "createBiquadFilter()")}} により {{domxref("BiquadFilterNode")}} を作成し、音源から流れてくる音声にローシェルフフィルターを適用するように意図通り設定します。すると、マイクからの出力が新しい双 2 次フィルターに流れ、フィルターの出力が音声コンテキストの{{domxref("BaseAudioContext/destination", "出力先")}}に順に流れるようになります。 +そして、{{domxref("BaseAudioContext/createBiquadFilter", "createBiquadFilter()")}} により {{domxref("BiquadFilterNode")}} を作成し、音源から流れてくる音声にローシェルフフィルターを適用するように意図通り設定します。すると、マイクからの出力が新しいバイクワッドフィルターに流れ、フィルターの出力が音声コンテキストの出力先 ({{domxref("BaseAudioContext/destination", "destination")}}) に順に流れるようになります。 ```js navigator.mediaDevices @@ -69,6 +70,6 @@ navigator.mediaDevices ## 関連情報 -- Web Audio API -- [Web Audio API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- ウェブオーディオ API +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) - {{domxref("MediaStreamTrackAudioSourceNode")}} diff --git a/files/ja/web/api/audiocontext/getoutputtimestamp/index.md b/files/ja/web/api/audiocontext/getoutputtimestamp/index.md index 4471a81b4e1c22..b50d661fbd57ee 100644 --- a/files/ja/web/api/audiocontext/getoutputtimestamp/index.md +++ b/files/ja/web/api/audiocontext/getoutputtimestamp/index.md @@ -1,17 +1,18 @@ --- -title: AudioContext.getOutputTimestamp() +title: "AudioContext: getOutputTimestamp() メソッド" +short-title: getOutputTimestamp() slug: Web/API/AudioContext/getOutputTimestamp l10n: - sourceCommit: 31d64df1a8632a2a539e5b16451c6efd7e002d68 + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{APIRef("Web Audio API")}} -{{domxref("AudioContext")}} インターフェイスの **`getOutputTimestamp()`** メソッドは、現在の音声コンテキストに関係する 2 個の音声タイムスタンプが格納された新しい `AudioTimestamp` オブジェクトを返します。 +**`getOutputTimestamp()`** は {{domxref("AudioContext")}} インターフェイスのメソッドで、現在の音声コンテキストに関係する 2 つの音声タイムスタンプが格納された新しい `AudioTimestamp` オブジェクトを返します。 -2 個の値とは、以下のものです。 +2 つの値とは、以下のものです。 -- `AudioTimestamp.contextTime`: コンテキストの {{domxref("BaseAudioContext/currentTime", "AudioContext.currentTime")}} で用いられるのと同じ単位と始点の、現在音声出力デバイスで出力されているサンプルフレームの時刻 (すなわち、出力音声ストリームの位置) です。 +- `AudioTimestamp.contextTime`: コンテキストの {{domxref("BaseAudioContext/currentTime", "AudioContext.currentTime")}} で用いられるのと同じ単位と始点の、現在音声出力デバイスで出力されているサンプルフレームの時刻（すなわち、出力音声ストリームの位置）です。 基本的には、これは音声コンテキストが最初に作られてからの時間です。 - `AudioTimestamp.performanceTime`: {{domxref("performance.now()")}} で用いられるのと同じ単位と始点の、`contextTime` の値に対応するサンプルフレームが音声出力デバイスで出力される時刻の推定値です。これは、音声コンテキストを含む文章が最初に描画されてからの時間です。 diff --git a/files/ja/web/api/audiocontext/index.md b/files/ja/web/api/audiocontext/index.md index e66331f186b74f..3935cf826d63f9 100644 --- a/files/ja/web/api/audiocontext/index.md +++ b/files/ja/web/api/audiocontext/index.md @@ -1,59 +1,57 @@ --- title: AudioContext slug: Web/API/AudioContext +l10n: + sourceCommit: bca8d1ab2bc4f5a1ef6b39c454b0229539178e98 --- {{APIRef("Web Audio API")}} -`AudioContext` インターフェイスは{{domxref("AudioNode")}}によって表現され、一緒にリンクした音声モジュールから作った音声処理グラフを表します。音声コンテキストはコンテキストを含むノードの作成と音声処理もしくはデコードの実行の両方を制御します。コンテキスト内部で全てのことが起こるので、何かをする前に `AudioContext` を作る必要があります。 +`AudioContext` インターフェイスは {{domxref("AudioNode")}} によって表現され、互いにリンクする音声モジュールから作られた音声処理グラフを表します。 + +音声コンテキストは、それが格納するノードの作成と、音声処理（デコード）の実行の両方を制御します。何らかの処理を行う前に `AudioContext` を作成する必要があります。毎回新しいものを初期化するのではなく、 1 つの AudioContext を作成し、それを再利用することを推奨します。また、 1 つの `AudioContext` を複数の異なるオーディオソースに使用し、同時にパイプラインを使用しても問題ありません。 {{InheritanceDiagram}} -## Constructor +## コンストラクター - {{domxref("AudioContext.AudioContext", "AudioContext()")}} - : `AudioContext` オブジェクトを新しく作成し、返します。 -## プロパティ +## インスタンスプロパティ -_親インターフェイス{{domxref("BaseAudioContext")}}からプロパティを継承します。_ +_親インターフェイスである {{domxref("BaseAudioContext")}} から継承したプロパティもあります。_ -- {{domxref("AudioContext.baseLatency")}} {{readonlyinline}} {{experimental_inline}} - - : {{domxref("AudioDestinationNode")}}から音声サブシステムまでの音声を渡す{{domxref("AudioContext")}}によって起きる処理レイテンシーの秒数を返します。 -- {{domxref("AudioContext.outputLatency")}} {{readonlyinline}} {{experimental_inline}} - - : 現在の音声コンテキストの出力レイテンシーの見積もりを返します。 +- {{domxref("AudioContext.baseLatency")}} {{ReadOnlyInline}} + - : {{domxref("AudioContext")}} が {{domxref("AudioDestinationNode")}} から音声サブシステムに音声を渡す際に発生する処理遅延の秒数を返します。 +- {{domxref("AudioContext.outputLatency")}} {{ReadOnlyInline}} + - : 現在の音声コンテキストの出力レイテンシーの見積を返します。 - {{domxref("AudioContext.sinkId")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : 現在の出力音声デバイスの sink ID を返します。 + - : 現在の出力音声機器のシンク ID を返します。 -## メソッド +## インスタンスメソッド -親インターフェイス{{domxref("BaseAudioContext")}} からメソッドを継承します。 +_親インターフェイスである {{domxref("BaseAudioContext")}} から継承したメソッドもあります。_ - {{domxref("AudioContext.close()")}} - : 任意のシステム音声リソースをリリースするために、音声コンテキストを閉じます。 - {{domxref("AudioContext.createMediaElementSource()")}} - - : {{domxref("HTMLMediaElement")}}と関連付けられた{{domxref("MediaElementAudioSourceNode")}}を生成します。これは{{HTMLElement("video")}}要素もしくは{{HTMLElement("audio")}}要素からの再生や操作をするために使うことができます。 + - : {{domxref("HTMLMediaElement")}} と関連付けられた {{domxref("MediaElementAudioSourceNode")}} を生成します。これは {{HTMLElement("video")}} 要素もしくは {{HTMLElement("audio")}} 要素からの再生や操作をするために使うことができます。 - {{domxref("AudioContext.createMediaStreamSource()")}} - - : ローカルのコンピューターのマイクもしくは他のソースから来る音声ストリームを表現している{{domxref("MediaStream")}}と関連付けられた{{domxref("MediaStreamAudioSourceNode")}}を生成します。 + - : ローカルのコンピューターのマイクもしくは他のソースから来る音声ストリームを表現している {{domxref("MediaStream")}} と関連付けられた {{domxref("MediaStreamAudioSourceNode")}} を生成します。 - {{domxref("AudioContext.createMediaStreamDestination()")}} - - : ローカルファイルに保存されたものかその他のコンピューターに送信された音声ストリームを表している{{domxref("MediaStream")}}と関連付けられた{{domxref("MediaStreamAudioDestinationNode")}}を生成します + - : ローカルファイルに保存されたものかその他のコンピューターに送信された音声ストリームを表す {{domxref("MediaStream")}} と関連付けられた {{domxref("MediaStreamAudioDestinationNode")}} を生成します。 - {{domxref("AudioContext.createMediaStreamTrackSource()")}} - - : メディアストリームトラックを表している{{domxref("MediaStream")}}と関連づけられた{{domxref("MediaStreamTrackAudioSourceNode")}}を生成します。 + - : メディアストリームトラックを表す {{domxref("MediaStream")}} と関連づけられた {{domxref("MediaStreamTrackAudioSourceNode")}} を生成します。 - {{domxref("AudioContext.getOutputTimestamp()")}} - - : 二つの関連づけられたコンテキストの音声ストリームの位置の値を含んでいる `AudioTimestamp` オブジェクトを新しく返します。 + - : 2 つの関連づけられたコンテキストの音声ストリームの位置の値を含む新しい `AudioTimestamp` オブジェクトを返します。 +- {{domxref("AudioContext.resume()")}} + - : 前回中断/一時停止した音声コンテキストの時間の進行を再開します。 - {{domxref("AudioContext.setSinkId()")}} {{Experimental_Inline}} - - : この `AudioContext` 用の出力音声デバイスを設定します。 + - : この `AudioContext` 用の出力音声機器を設定します。 - {{domxref("AudioContext.suspend()")}} - : 一時的に音声ハードウェアアクセスを停止し、プロセスの CPU/バッテリー使用を減らすために、音声コンテキストの時間の進行を中断します。 -### 非推奨メソッド - -- {{domxref("AudioContext.resume()")}} - - - : あらかじめ中断させられた音声コンテキストの時間の進行を返します。 - - 注意: `resume()` メソッドはまだ利用することができます。このメソッドは{{domxref("BaseAudioContext")}}インターフェイス({{domxref("BaseAudioContext.resume()")}}を見てください)上で現在定義されています。したがって、{{domxref("AudioContext")}}インターフェイスと{{domxref("OfflineAudioContext")}}インターフェイスの両方でアクセスすることができます。 - ## イベント - {{domxref("AudioContext/sinkchange_event", "sinkchange")}} {{Experimental_Inline}} @@ -61,21 +59,14 @@ _親インターフェイス{{domxref("BaseAudioContext")}}からプロパティ ## 例 -基本的な音声コンテキストの作成方法: - -```js -var audioCtx = new AudioContext(); -``` - -クロスブラウザー対応版: +基本的な音声コンテキストの作成方法です。 ```js -var AudioContext = window.AudioContext || window.webkitAudioContext; -var audioCtx = new AudioContext(); +const audioCtx = new AudioContext(); -var oscillatorNode = audioCtx.createOscillator(); -var gainNode = audioCtx.createGain(); -var finish = audioCtx.destination; +const oscillatorNode = audioCtx.createOscillator(); +const gainNode = audioCtx.createGain(); +const finish = audioCtx.destination; // etc. ``` @@ -85,9 +76,9 @@ var finish = audioCtx.destination; ## ブラウザーの互換性 -{{Compat("api.AudioContext")}} +{{Compat}} ## 参考 -- [Web Audio API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) - {{domxref("OfflineAudioContext")}} diff --git a/files/ja/web/api/audiocontext/outputlatency/index.md b/files/ja/web/api/audiocontext/outputlatency/index.md index f5e5495706cae4..c33dad56e4b87d 100644 --- a/files/ja/web/api/audiocontext/outputlatency/index.md +++ b/files/ja/web/api/audiocontext/outputlatency/index.md @@ -1,13 +1,14 @@ --- -title: AudioContext.outputLatency +title: "AudioContext: outputLatency プロパティ" +short-title: outputLatency slug: Web/API/AudioContext/outputLatency l10n: - sourceCommit: bca8d1ab2bc4f5a1ef6b39c454b0229539178e98 + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{APIRef("Web Audio API")}} -the {{domxref("AudioContext")}} の読み取り専用プロパティ **`outputLatency`** は、現在の音声コンテキストにおける出力遅延の見積もりを提供します。 +**`outputLatency`** は {{domxref("AudioContext")}} の読み取り専用プロパティで、現在の音声コンテキストにおける出力遅延の見積を提供します。 この値は、ブラウザーが音声バッファーを再生のために音声グラフからホストシステムの音声サブシステムに渡してから、バッファー内の最初のサンプルが実際に音声出力デバイスで処理されるまでの秒数です。 @@ -15,7 +16,7 @@ the {{domxref("AudioContext")}} の読み取り専用プロパティ **`outputLa ## 値 -出力遅延の秒数を表す `double` の値です。 +出力遅延の秒数を表す double 値です。 ## 例 @@ -34,5 +35,5 @@ console.log(audioCtx.outputLatency); ## 関連情報 -- [Web Audio API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) - [ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/resume/index.md b/files/ja/web/api/audiocontext/resume/index.md index cfccf28ffa939a..0440abca1460ce 100644 --- a/files/ja/web/api/audiocontext/resume/index.md +++ b/files/ja/web/api/audiocontext/resume/index.md @@ -1,55 +1,58 @@ --- -title: AudioContext.resume() +title: "AudioContext: resume() メソッド" +short-title: resume() slug: Web/API/AudioContext/resume +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -{{ domxref("AudioContext") }}インターフェースの`resume()`メソッドは、一時停止されたオーディオコンテキストの時間の流れを再開します。 +**`resume()`** は {{ domxref("AudioContext") }} インターフェイスのメソッドで、一時停止された音声コンテキストの時間の流れを再開します。 -{{domxref("OfflineAudioContext")}}でこのメソッドを呼ぶと`INVALID_STATE_ERR`例外が発生します。 +{{domxref("OfflineAudioContext")}} でこのメソッドを呼び出すと、 `INVALID_STATE_ERR` 例外が発生します。 ## 構文 -```js -Promise<> baseAudioContext.resume(); +```js-nolint +resume() ``` ### 引数 -なし +なし。 -### 戻り値 +### 返値 -void で完了する{{jsxref("Promise")}}。コンテキストが既に閉じている場合、プロミスは失敗します。 +コンテキストが再開されたときに解決する {{jsxref("Promise")}} です。このプロミスは、コンテキストが既に閉じている場合は拒否されます。 ## 例 -次のスニペットは[AudioContext states デモ](https://github.com/mdn/audiocontext-states/settings)([すぐ実行](http://mdn.github.io/audiocontext-states/))から取ったものです。suspend/resume ボタンをクリックすると、{{domxref("AudioContext.state")}}を問い合わせます—もし`running`ならば、{{domxref("AudioContext.suspend()", "suspend()")}}が呼ばれます。`suspended`ならば、`resume()`が呼ばれます。両方ともプロミスに成功するとボタンのラベルが適したものに更新されます。 +次のスニペットは [AudioContext states のデモ](https://github.com/mdn/webaudio-examples/tree/master/audiocontext-states)（[ライブ実行](https://mdn.github.io/webaudio-examples/audiocontext-states/)）から取ったものです。suspend/resume ボタンをクリックすると、{{domxref("BaseAudioContext.state")}} を問い合わせます。もし `running` ならば、 {{domxref("AudioContext.suspend()", "suspend()")}} が呼び出されます。 `suspended` ならば、 `resume()` が呼ばれます。両方ともプロミスが解決すると、ボタンのラベルが適切なものに更新されます。 ```js -susresBtn.onclick = function () { +susresBtn.onclick = () => { if (audioCtx.state === "running") { - audioCtx.suspend().then(function () { + audioCtx.suspend().then(() => { susresBtn.textContent = "Resume context"; }); } else if (audioCtx.state === "suspended") { - audioCtx.resume().then(function () { + audioCtx.resume().then(() => { susresBtn.textContent = "Suspend context"; }); } }; ``` -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザ互換性 +## ブラウザーの互換性 {{Compat}} -## 参考 +## 関連情報 -- [Using the Web Audio API](/ja/docs/Web_Audio_API/Using_Web_Audio_API) -- [Web Audio API](/ja/docs/Web/API/Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) diff --git a/files/ja/web/api/audiocontext/setsinkid/index.md b/files/ja/web/api/audiocontext/setsinkid/index.md index 5dfd1b1b871b43..8f7ae3453f0fb4 100644 --- a/files/ja/web/api/audiocontext/setsinkid/index.md +++ b/files/ja/web/api/audiocontext/setsinkid/index.md @@ -1,17 +1,18 @@ --- -title: AudioContext.setSinkId() +title: "AudioContext: setSinkId() メソッド" +short-title: setSinkId() slug: Web/API/AudioContext/setSinkId l10n: - sourceCommit: bca8d1ab2bc4f5a1ef6b39c454b0229539178e98 + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{APIRef("Web Audio API")}}{{SeeCompatTable}} -{{domxref("AudioContext")}} インターフェイスの **`setSinkId()`** メソッドは、`AudioContext` の出力音声デバイスを設定します。sink ID が明示的に設定されていない場合は、デフォルトのシステム音声出力デバイスが使われます。 +**`setSinkId()`** は {{domxref("AudioContext")}} インターフェイスのメソッドで、`AudioContext` の音声出力機器を設定します。sink ID が明示的に設定されていない場合は、既定のシステム音声出力機器が使われます。 -音声デバイスをデフォルトでないデバイスに設定するには、開発者は音声デバイスにアクセスする許可を得る必要があります。必要な場合、{{domxref("MediaDevices.getUserMedia()")}} を呼ぶことによりユーザーに必要な許可を求めるプロンプトを表示することができます。 +音声機器を既定でない機器に設定するには、開発者は音声機器にアクセスする許可を得る必要があります。必要な場合、{{domxref("MediaDevices.getUserMedia()")}} を呼ぶことによりユーザーに必要な許可を求めるプロンプトを表示することができます。 -さらに、この機能は [`speaker-selection`](/ja/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [Permissions Policy](/ja/docs/Web/HTTP/Permissions_Policy) によりブロックされる場合があります。 +さらに、この機能は [`speaker-selection`](/ja/docs/Web/HTTP/Headers/Permissions-Policy/speaker-selection) [権限ポリシー](/ja/docs/Web/HTTP/Permissions_Policy) によりブロックされる場合があります。 ## 構文 @@ -22,34 +23,34 @@ setSinkId(sinkId) ### 引数 - `sinkId` - - : 出力音声デバイスとして設定するデバイスの sink ID です。以下の型のいずれかです。 - - String - - : sink ID を表す文字列です。たとえば、{{domxref("MediaDevices.enumerateDevices()")}} が返す {{domxref("MediaDeviceInfo")}} オブジェクトの `deviceId` プロパティで取得できます。 + - : 出力音声機器として設定する機器のシンク ID です。以下の型のいずれかです。 + - 文字列 + - : シンク ID を表す文字列です。たとえば、{{domxref("MediaDevices.enumerateDevices()")}} が返す {{domxref("MediaDeviceInfo")}} オブジェクトの `deviceId` プロパティで取得できます。 - `AudioSinkOptions` - - : sink ID の異なるオプションを表すオブジェクトです。現在、これは 1 個のプロパティ `type` を取り、その値は `none` です。この値を設定すると、音声を音声出力デバイスで再生せずに処理させることができます。これは、処理と並行して再生する必要がないときにエネルギーの消費を最小化するのに有用なオプションです。 + - : シンク ID の様々なオプションを表すオブジェクトです。現在、これは 1 個のプロパティ `type` を取り、その値は `none` です。この値を設定すると、音声を音声出力機器で再生せずに処理させることができます。これは、処理と並行して再生する必要がないときにエネルギーの消費を最小化するのに有用なオプションです。 ### 返値 -値 `undefined` で解決する {{jsxref("Promise")}} を返します。 +`undefined` の値で解決する {{jsxref("Promise")}} を返します。 -sink ID を既存の値 (すなわち、{{domxref("AudioContext.sinkId")}} が返す値) に設定しようとすると、エラーは投げられませんが、処理がすぐに停止します。 +シンク ID を既存の値（すなわち、{{domxref("AudioContext.sinkId")}} が返す値）に設定しようとすると、エラーは発生しませんが、処理がすぐに停止します。 ### 例外 - `InvalidAccessError` {{domxref("DOMException")}} - - : 選択された音声出力デバイスへのアクセスに失敗したとき投げられます。 + - : 選択された音声出力機器へのアクセスに失敗したとき発生します。 - `NotAllowedError` {{domxref("DOMException")}} - - : ブラウザーに音声デバイスにアクセスする許可がないとき投げられます。 + - : ブラウザーに音声機器にアクセスする許可がないとき発生します。 - `NotFoundError` {{domxref("DOMException")}} - - : 渡された `sinkId` がシステムで検出されたどの音声デバイスにも一致しないとき投げられます。 + - : 渡された `sinkId` がシステムで検出されたどの音声機器にも一致しないとき発生します。 ## 例 [SetSinkId test example](https://set-sink-id.glitch.me/) ([ソースコード](https://glitch.com/edit/#!/set-sink-id)を見る) では、{{domxref("AudioBufferSourceNode")}} により 3 秒間のホワイトノイズを生成し、{{domxref("GainNode")}} に通して少し音量を下げる音声グラフを作成します。 -さらに、音声出力デバイスをその場で変えることができるドロップダウンメニューを用意します。そのために、 +さらに、音声出力機器をその場で変えることができるドロップダウンメニューを用意します。そのために、 -1. ドロップダウンメニューに配置するボタンを用意します。まず、{{domxref("MediaDevices.getUserMedia()")}} を呼び、デバイスを列挙するために必要な許可を得るためのプロンプトを開きます。次に、{{domxref("MediaDevices.enumerateDevices()")}} を用いてすべての利用可能なデバイスを取得します。ループにより、各デバイスを {{htmlelement("select")}} 要素の選択肢として利用可能にします。さらに、音声をどの出力でも再生したくないときのために選択肢「None」を作成します。 +1. ドロップダウンメニューに配置するボタンを用意します。まず、{{domxref("MediaDevices.getUserMedia()")}} を呼び、機器を列挙するために必要な許可を得るためのプロンプトを開きます。次に、{{domxref("MediaDevices.enumerateDevices()")}} を用いてすべての利用可能な機器を取得します。ループにより、各機器を {{htmlelement("select")}} 要素の選択肢として利用可能にします。さらに、音声をどの出力でも再生したくないときのために選択肢「None」を作成します。 ```js mediaDeviceBtn.addEventListener('click', async () => { @@ -80,7 +81,7 @@ sink ID を既存の値 (すなわち、{{domxref("AudioContext.sinkId")}} が //... ``` -2. {{htmlelement("select")}} 要素に {{domxref("HTMLElement/change_event", "change")}} イベントリスナーを追加し、新しい値が選択された時に sink ID を変更して音声出力デバイスを変更できるようにします。ドロップダウンで「None」が選択された場合は `{ type : 'none' }` オブジェクトを引数として `setSinkId()` を呼ぶことにより音声デバイスが選択されていない状態にし、それ以外の場合は `` 要素の `value` 属性に格納された音声機器 ID を引数として呼びます。 ```js // ... @@ -96,7 +97,7 @@ sink ID を既存の値 (すなわち、{{domxref("AudioContext.sinkId")}} が }); ``` -出力デバイスの変更は音声の再生中にも、再生前にも、再生と再生の間にもできます。 +出力機器の変更は音声の再生中にも、再生前にも、再生と再生の間にもできます。 ## 仕様書 diff --git a/files/ja/web/api/audiocontext/sinkid/index.md b/files/ja/web/api/audiocontext/sinkid/index.md index b25191788ab704..7ee927419d0e4d 100644 --- a/files/ja/web/api/audiocontext/sinkid/index.md +++ b/files/ja/web/api/audiocontext/sinkid/index.md @@ -1,34 +1,35 @@ --- -title: AudioContext.sinkId +title: "AudioContext: sinkId プロパティ" +short-title: sinkId slug: Web/API/AudioContext/sinkId l10n: - sourceCommit: bca8d1ab2bc4f5a1ef6b39c454b0229539178e98 + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{APIRef("Web Audio API")}}{{SeeCompatTable}} -{{domxref("AudioContext")}} インターフェイスの読み取り専用プロパティ **`sinkId`** は、現在の出力音声デバイスの sink ID を返します。 +**`sinkId`** は {{domxref("AudioContext")}} インターフェイスの読み取り専用プロパティで、現在の音声出力機器のシンク ID を返します。 ## 値 -このプロパティは、どのように sink ID が設定されているかにより、以下の値のいずれかを返します。 +このプロパティは、どのようにシンク ID が設定されているかにより、以下の値のいずれかを返します。 - 空文字列 - - : sink ID が明示的に設定されていない場合、デフォルトのシステム音声出力デバイスが用いられ、`sinkId` は空文字列を返します。 + - : シンク ID が明示的に設定されていない場合、デフォルトのシステム音声出力機器が用いられ、`sinkId` は空文字列を返します。 - 文字列 - - : sink ID が ({{domxref("AudioContext.setSinkId", "setSinkId()")}} を用いるか、{{domxref("AudioContext.AudioContext", "AudioContext()")}} コンストラクターのオプション `sinkId` を用いて) 文字列として設定されている場合、`sinkId` は同じ文字列を返します。 + - : シンク ID が（{{domxref("AudioContext.setSinkId", "setSinkId()")}} を用いるか、{{domxref("AudioContext.AudioContext", "AudioContext()")}} コンストラクターのオプション `sinkId` を用いて）文字列として設定されている場合、`sinkId` は同じ文字列を返します。 - {{domxref("AudioSinkInfo")}} オブジェクト - - : sink ID が ({{domxref("AudioContext.setSinkId", "setSinkId()")}} を用いるか、{{domxref("AudioContext.AudioContext", "AudioContext()")}} コンストラクターのオプション `sinkId` を用いて) オプションオブジェクトとして設定されている場合、`sinkId` は最初のオプションオブジェクトで設定された値と同じ値を持つ {{domxref("AudioSinkInfo")}} オブジェクトを返します。 + - : シンク ID が（{{domxref("AudioContext.setSinkId", "setSinkId()")}} を用いるか、{{domxref("AudioContext.AudioContext", "AudioContext()")}} コンストラクターのオプション `sinkId` を用いて）オプションオブジェクトとして設定されている場合、`sinkId` は最初のオプションオブジェクトで設定された値と同じ値を持つ {{domxref("AudioSinkInfo")}} オブジェクトを返します。 ## 例 -[SetSinkId test example](https://set-sink-id.glitch.me/) では、{{domxref("AudioBufferSourceNode")}} により 3 秒間のホワイトノイズを生成し、{{domxref("GainNode")}} を通して少し音量を下げる音声グラフを作成します。さらに、ユーザーが音声出力デバイスを変えることができるドロップダウンメニューを提供します。 +[SetSinkId test example](https://set-sink-id.glitch.me/) では、{{domxref("AudioBufferSourceNode")}} により 3 秒間のホワイトノイズを生成し、{{domxref("GainNode")}} を通して少し音量を下げる音声グラフを作成します。さらに、ユーザーが音声出力機器を変えることができるドロップダウンメニューを提供します。 -Play ボタンがクリックされると、音声グラフを組み立て、再生を開始し、`sinkId` の値に基づいて現在のデバイスの情報を記録します。これは以下のような動作になります。 +Play ボタンがクリックされると、音声グラフを組み立て、再生を開始し、`sinkId` の値に基づいて現在の機器の情報を記録します。これは以下のような動作になります。 -- 空文字列は、まだデフォルトのデバイスが使われていることを表します。 -- 値がオブジェクトである場合は、`type: 'none'` が格納されたオプションオブジェクトを設定しているため、音声はどのデバイスでも再生されません。 -- それ以外の場合は、値は sink ID の文字列のはずなので、記録します。 +- 空文字列は、まだ既定の機器が使われていることを表します。 +- 値がオブジェクトである場合は、`type: 'none'` が格納されたオプションオブジェクトを設定しているため、音声はどの機器でも再生されません。 +- それ以外の場合は、値はシンク ID の文字列のはずなので、記録します。 ```js playBtn.addEventListener("click", () => { @@ -39,14 +40,14 @@ playBtn.addEventListener("click", () => { source.start(); if (audioCtx.sinkId === "") { - console.log("音声はデフォルトのデバイスで再生されています"); + console.log("音声は既定の機器で再生されています"); } else if ( typeof audioCtx.sinkId === "object" && audioCtx.sinkId.type === "none" ) { - console.log("音声はどのデバイスでも再生されていません"); + console.log("音声はどの機器でも再生されていません"); } else { - console.log(`音声はデバイス ${audioCtx.sinkId} で再生されています`); + console.log(`音声は機器 ${audioCtx.sinkId} で再生されています`); } }); ``` diff --git a/files/ja/web/api/audiocontext/suspend/index.md b/files/ja/web/api/audiocontext/suspend/index.md index b21d062c37dc52..90c896db0cb07f 100644 --- a/files/ja/web/api/audiocontext/suspend/index.md +++ b/files/ja/web/api/audiocontext/suspend/index.md @@ -1,52 +1,58 @@ --- -title: AudioContext.suspend() +title: "AudioContext: suspend() メソッド" +short-title: suspend() slug: Web/API/AudioContext/suspend +l10n: + sourceCommit: 135b8311a5e3d12789e8421845be3ce026ef72b8 --- {{ APIRef("Web Audio API") }} -`suspend()`メソッドは、オーディオコンテキストの時間の流れを一時停止します。音声ハードウェアへのアクセスを一時的に停止し、処理に必要だった CPU/バッテリーの使用を減らすことが出来ます。これは、アプリケーションがしばらくの間オーディオを扱わない間に、音声ハードウェアに電源を供給しないようにしたいときに便利です。 +`suspend()` は {{ domxref("AudioContext") }} インターフェイスのメソッドで、音声コンテキストの時間の流れを一時停止します。音声ハードウェアへのアクセスを一時的に停止し、処理に必要だった CPU/バッテリーの使用を減らすことが出来ます。これは、アプリケーションがしばらくの間音声を扱わない間に、音声ハードウェアに電源を供給しないようにしたいときに便利です。 -{{domxref("OfflineAudioContext")}}でこのメソッドを呼ぶと`INVALID_STATE_ERR`例外が発生します。 +{{domxref("OfflineAudioContext")}} でこのメソッドを呼び出すと、 `INVALID_STATE_ERR` 例外が発生します。 ## 構文 -```js -var audioCtx = new AudioContext(); -audioCtx.suspend().then(function() { ... }); +```js-nolint +suspend() ``` -### 戻り値 +### 引数 + +なし。 + +### 返値 -void で完了する{{jsxref("Promise")}}。コンテキストが既に閉じている場合、プロミスは失敗します。 +{{jsxref("Promise")}} であり、これは {{jsxref('undefined')}} で解決します。コンテキストが既に閉じている場合、プロミスは失敗します。 ## 例 -次のスニペットは[AudioContext states デモ](https://github.com/mdn/audiocontext-states/settings)([すぐ実行](http://mdn.github.io/audiocontext-states/))から取ったものです。suspend/resume ボタンをクリックすると、{{domxref("AudioContext.state")}}を問い合わせます—もし`running`ならば、`suspend()`が呼ばれます。`suspended`ならば、{{domxref("resume")}}が呼ばれます。両方ともプロミスに成功するとボタンのラベルが適したものに更新されます。 +次のスニペットは [AudioContext states デモ](https://github.com/mdn/webaudio-examples/blob/master/audiocontext-states/index.html)（[ライブ実行](https://mdn.github.io/webaudio-examples/audiocontext-states/)）から取ったものです。suspend/resume ボタンをクリックすると、 {{domxref("BaseAudioContext/state", "AudioContext.state")}} を問い合わせます。もし `running` ならば、 `suspend()` が呼び出されます。 `suspended` ならば、 {{domxref("AudioContext/resume", "resume()")}} が呼び出されます。両方ともプロミスに成功するとボタンのラベルが適したものに更新されます。 ```js -susresBtn.onclick = function () { +susresBtn.onclick = () => { if (audioCtx.state === "running") { - audioCtx.suspend().then(function () { + audioCtx.suspend().then(() => { susresBtn.textContent = "Resume context"; }); } else if (audioCtx.state === "suspended") { - audioCtx.resume().then(function () { + audioCtx.resume().then(() => { susresBtn.textContent = "Suspend context"; }); } }; ``` -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザ互換性 +## ブラウザーの互換性 -{{Compat("api.AudioContext.suspend")}} +{{Compat}} -## 参考 +## 関連情報 -- [Using the Web Audio API](/ja/docs/Web_Audio_API/Using_Web_Audio_API) -- [Web Audio API](/ja/docs/Web/API/Web_Audio_API) +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) diff --git a/files/ja/web/api/document/startviewtransition/index.md b/files/ja/web/api/document/startviewtransition/index.md new file mode 100644 index 00000000000000..0b80c3830a1817 --- /dev/null +++ b/files/ja/web/api/document/startviewtransition/index.md @@ -0,0 +1,73 @@ +--- +title: "Document: startViewTransition() メソッド" +short-title: startViewTransition() +slug: Web/API/Document/startViewTransition +l10n: + sourceCommit: 7b3ccaec4a93584da12939587ea746acaabe30bc +--- + +{{APIRef("Document")}}{{SeeCompatTable}} + +**`startViewTransition()`** は{{domxref("View Transitions API", "ビュートランジション API", "", "nocode")}} のメソッドで、新しいビュートランジションを始め、それを表す {{domxref("ViewTransition")}} オブジェクトを返します。 + +`startViewTransition()`を呼び出すと、[ビュートランジションのプロセス](/ja/docs/Web/API/View_Transitions_API#ビュートランジションのプロセス)で説明されている一連の手順が続きます。 + +## 構文 + +```js-nolint +startViewTransition(callback) +``` + +### 引数 + +- `callback` + - : 通常、ビュートランジションプロセス中に DOM を更新するために呼び出されるコールバック関数で、プロミス ({{jsxref("Promise")}}) を返します。コールバックは、 API が現在のページのスクリーンショットを導いたら呼び出されます。コールバックが返すプロミスが履行されると、次のフレームでビュートランジションが始まります。コールバックが返すプロミスが拒否された場合、トランジションは放棄されます。 + +### 返値 + +{{domxref("ViewTransition")}} のオブジェクトインスタンスです。 + +## 例 + +### 基本的な使用方法 + +[基本的なビュートランジションのデモ](https://mdn.github.io/dom-examples/view-transitions/)では、 `updateView()` 関数はビュートランジション API に対応しているブラウザーと対応していないブラウザーの両方に対応しています。対応しているブラウザーで、返値を気にせずにビュートランジションのプロセスを設定するには `startViewTransition()` を呼び出します。 + +```js +function updateView(event) { + // Handle the difference in whether the event is fired on the or the + let targetIdentifier; + if (event.target.firstChild === null) { + targetIdentifier = event.target; + } else { + targetIdentifier = event.target.firstChild; + } + + const displayNewImage = () => { + const mainSrc = `${targetIdentifier.src.split("_th.jpg")[0]}.jpg`; + galleryImg.src = mainSrc; + galleryCaption.textContent = targetIdentifier.alt; + }; + + // Fallback for browsers that don't support View Transitions: + if (!document.startViewTransition) { + displayNewImage(); + return; + } + + // With View Transitions: + const transition = document.startViewTransition(() => displayNewImage()); +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/element/index.md b/files/ja/web/api/element/index.md index d6a4fe080ef7bd..321a7be5dd9701 100644 --- a/files/ja/web/api/element/index.md +++ b/files/ja/web/api/element/index.md @@ -2,7 +2,7 @@ title: Element slug: Web/API/Element l10n: - sourceCommit: 930683b0618a36a5bb497cfaedced2f4de767889 + sourceCommit: 56c76424a5edb45f6716ac4ee48861dac8e7ae38 --- {{APIRef("DOM")}} @@ -291,15 +291,11 @@ _`Element` は親である {{DOMxRef("Node")}}、およびその親である {{D - {{domxref("HTMLDialogElement/cancel_event", "cancel")}} - : ユーザーがブラウザーに、現在開いているモーダルダイアログを閉じたいと指示したときに {{HTMLElement("dialog")}} に発行されます。ブラウザーがこのイベントを発行させる可能性があるのは、例えばユーザーが Esc キーを押してモーダルダイアログを閉じた時です。 - {{domxref("Element/contentvisibilityautostatechange_event", "contentvisibilityautostatechange")}} {{Experimental_Inline}} - - : {{cssxref("content-visibility", "content-visibility: auto")}} が設定されている要素が[ユーザーに関連する](/ja/docs/Web/CSS/CSS_Containment#relevant_to_the_user)、[コンテンツのスキップ](/ja/docs/Web/CSS/CSS_Containment#skips_its_contents)を開始または終了するときに、その要素を対象に発行されます。 -- {{domxref("Element/error_event", "error")}} - - : リソースの読み込みに失敗したか、利用できなかった場合に発行されます。例えば、スクリプトに実行エラーがあった場合や、画像が見つからなかった場合、無効であった場合などです。 + - : {{cssxref("content-visibility", "content-visibility: auto")}} が設定されている要素が[ユーザーに関連する](/ja/docs/Web/CSS/CSS_containment#relevant_to_the_user)、[コンテンツのスキップ](/ja/docs/Web/CSS/CSS_containment#skips_its_contents)を開始または終了するときに、その要素を対象に発行されます。 - {{domxref("Element/scroll_event", "scroll")}} - : 文書のビューまたは要素がスクロールしたときに発行されます。 - {{domxref("Element/securitypolicyviolation_event","securitypolicyviolation")}} - : [コンテンツセキュリティポリシー](/ja/docs/Web/HTTP/CSP)に違反したときに発生します。 -- {{domxref("Element/select_event", "select")}} - - : いくらかのテキストが選択されたときに発行されます。 - {{domxref("Element/wheel_event","wheel")}} - : ユーザーがポインティングデバイス（普通はマウス）のホイールボタンを回転させたときに発行されます。 diff --git a/files/ja/web/api/gpuadapter/features/index.md b/files/ja/web/api/gpuadapter/features/index.md new file mode 100644 index 00000000000000..bf456a0433b4fd --- /dev/null +++ b/files/ja/web/api/gpuadapter/features/index.md @@ -0,0 +1,62 @@ +--- +title: "GPUAdapter: features プロパティ" +slug: Web/API/GPUAdapter/features +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapter")}} インターフェイスの読み取り専用プロパティ **`features`** は、アダプターが対応している追加の機能を表現する {{domxref("GPUSupportedFeatures")}} オブジェクトを返します。 + +仮想のハードウェアで対応している機能であっても、対応するすべてのブラウザーの WebGPU ですべての機能が使用できるわけではないことに注意するべきです。これは、たとえば以下の場合など、仮想のシステム、ブラウザー、アダプターの制約によるものである可能性があります。 + +- 仮想のシステムがあるブラウザーと互換性がある方法で機能を利用可能にする保証ができないかもしれません。 +- ブラウザーのベンダーが機能への対応を実装するセキュアな方法をまだ見つけられていないか、単に実装まで手が回っていないかもしれません。 + +WebGPU アプリケーションで特定の追加機能の恩恵を受けたい場合は、徹底的にテストすることが推奨されます。 + +## 値 + +{{domxref("GPUSupportedFeatures")}} オブジェクトのインスタンスです。これは [Set 風](/ja/docs/Web/JavaScript/Reference/Global_Objects/Set)オブジェクトです。 + +## 例 + +以下のコードでは、{{domxref("GPUAdapter")}} で `texture-compression-astc` 機能が利用可能かをチェックします。利用可能であれば、それを配列 `requiredFeatures` にプッシュし、{{domxref("GPUAdapter.requestDevice()")}} でこの機能を要件としてデバイスを要求します。 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const requiredFeatures = []; + + if (adapter.features.has("texture-compression-astc")) { + requiredFeatures.push("texture-compression-astc"); + } + + const device = await adapter.requestDevice({ + requiredFeatures, + }); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapter/index.md b/files/ja/web/api/gpuadapter/index.md new file mode 100644 index 00000000000000..a3e3649031d5d4 --- /dev/null +++ b/files/ja/web/api/gpuadapter/index.md @@ -0,0 +1,61 @@ +--- +title: GPUAdapter +slug: Web/API/GPUAdapter +l10n: + sourceCommit: ee9993f6186ca6673b96d226e63132b3e317813f +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("WebGPU API", "WebGPU API", "", "nocode")}} の **`GPUAdapter`** インターフェイスは、GPU アダプターを表します。これを用いて {{domxref("GPUDevice")}}、アダプターの情報、機能、制限を要求できます。 + +`GPUAdapter` オブジェクトは {{domxref("GPU.requestAdapter()")}} メソッドを用いて要求できます。 + +{{InheritanceDiagram}} + +## インスタンスプロパティ + +- {{domxref("GPUAdapter.features", "features")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターが対応している追加の機能を表現する {{domxref("GPUSupportedFeatures")}} オブジェクトです。 +- {{domxref("GPUAdapter.isFallbackAdapter", "isFallbackAdapter")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : 論理値です。アダプターが[フォールバックアダプター](/ja/docs/Web/API/GPU/requestAdapter#フォールバックアダプター)である場合は `true` を返し、そうでない場合は `false` を返します。 +- {{domxref("GPUAdapter.limits", "limits")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターが対応している制限を表現する {{domxref("GPUSupportedLimits")}} オブジェクトです。 + +## インスタンスメソッド + +- {{domxref("GPUAdapter.requestAdapterInfo", "requestAdapterInfo()")}} {{Experimental_Inline}} + - : アダプターに関する特定用の情報が格納された {{domxref("GPUAdapterInfo")}} オブジェクトで解決する {{jsxref("Promise")}} を返します。 +- {{domxref("GPUAdapter.requestDevice", "requestDevice()")}} {{Experimental_Inline}} + - : GPU とのやりとり用の第一インターフェイスである {{domxref("GPUDevice")}} オブジェクトで解決する {{jsxref("Promise")}} を返します。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const device = await adapter.requestDevice(); + + //... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapter/isfallbackadapter/index.md b/files/ja/web/api/gpuadapter/isfallbackadapter/index.md new file mode 100644 index 00000000000000..8e7be8c7805d06 --- /dev/null +++ b/files/ja/web/api/gpuadapter/isfallbackadapter/index.md @@ -0,0 +1,46 @@ +--- +title: "GPUAdapter: isFallbackAdapter プロパティ" +slug: Web/API/GPUAdapter/isFallbackAdapter +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapter")}} インターフェイスの読み取り専用プロパティ **`isFallbackAdapter`** は、アダプターが[フォールバックアダプター](/ja/docs/Web/API/GPU/requestAdapter#フォールバックアダプター)である場合は `true` を返し、そうでない場合は `false` を返します。 + +## 値 + +論理値です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error('WebGPU に対応していません。'); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error('WebGPU アダプターを要求できませんでした。'); + } + + const fallback = adapter.isFallbackAdapter; + console.log(fallback); + + // ... + +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapter/limits/index.md b/files/ja/web/api/gpuadapter/limits/index.md new file mode 100644 index 00000000000000..bac79ea8dffa8a --- /dev/null +++ b/files/ja/web/api/gpuadapter/limits/index.md @@ -0,0 +1,61 @@ +--- +title: "GPUAdapter: limits プロパティ" +slug: Web/API/GPUAdapter/limits +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapter")}} インターフェイスの読み取り専用プロパティ **`limits`** は、アダプターが対応している制限を表現する {{domxref("GPUSupportedLimits")}} オブジェクトを返します。 + +ドライブバイフィンガープリンティングで利用できる一意な情報を減らすため、ブラウザーは各 GPU の正確な制限を報告するのではなく、それぞれの制限で異なる段階ごとの値を報告する可能性が高いです。たとえば、ある制限の段階は 2048、8192、32768 である可能性があります。GPU の実際の制限が 16384 である場合は、このブラウザーは 8192 として報告します。 + +異なるブラウザーは異なる扱いをする可能性があり、段階の値は時間の経過で変わる可能性があるため、正確な制限の値を予想するのは難しいです。徹底的にテストすることが推奨されます。 + +## 値 + +{{domxref("GPUSupportedLimits")}} オブジェクトのインスタンスです。 + +## 例 + +以下のコードでは、`GPUAdapter.limits` の `maxBindGroups` の値を問い合わせ、6 以上であるかをチェックします。理論上のサンプルアプリケーションは理想的には 6 個のバインドグループを必要とするので、返された値が 6 以上の場合は `requiredLimits` オブジェクトに最大値 6 を追加適用し、{{domxref("GPUAdapter.requestDevice()")}} を用いてこの制限の要件を満たすデバイスを要求します。 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const requiredLimits = {}; + + // アプリケーションは理想的には 6 個のバインドグループを必要とするので、 + // アプリケーションが必要とする分の要求を試みる + if (adapter.limits.maxBindGroups >= 6) { + requiredLimits.maxBindGroups = 6; + } + + const device = await adapter.requestDevice({ + requiredLimits, + }); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapter/requestadapterinfo/index.md b/files/ja/web/api/gpuadapter/requestadapterinfo/index.md new file mode 100644 index 00000000000000..ee6764ef7b9f60 --- /dev/null +++ b/files/ja/web/api/gpuadapter/requestadapterinfo/index.md @@ -0,0 +1,61 @@ +--- +title: "GPUAdapter: requestAdapterInfo() メソッド" +slug: Web/API/GPUAdapter/requestAdapterInfo +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapter")}} インターフェイスの **`requestAdapterInfo()`** メソッドは、アダプターに関する特定用の情報が格納された {{domxref("GPUAdapterInfo")}} オブジェクトで解決する {{jsxref("Promise")}} を返します。 + +このメソッドの背景の意図は、開発者がユーザーの GPU の特定の詳細を要求し、GPU に固有のバグの回避策を先手を取って適用したり、異なる GPU のアーキテクチャにより合う異なるコードパスを提供したりできるようにすることです。このような情報を提供すると、フィンガープリンティングに利用でき、セキュリティリスクが発生します。そのため、共有される情報は最小限にとどめられ、異なるブラウザーのベンダー間で情報の種類と粒度を共通化するでしょう。 + +> **メモ:** 仕様書には `requestAdapterInfo()` 用の引数として、上記のセキュリティリスクを低減することを意図した `unmaskHints` が存在します。これに対応すれば、開発者は本当に知る必要がある値を指定することができるようになり、ユーザーはメソッドが呼び出されたとき情報を共有してよいかを尋ねる許可プロンプトを提示されるようになるでしょう。許可プロンプトで守られる場合、メソッドのフィンガープリンティングの対象としての有用度は下がるので、ブラウザーのベンダーはより有用な情報を共有するようになるでしょう。 + +## 構文 + +```js-nolint +requestAdapterInfo() +``` + +### 引数 + +なし + +### 返値 + +{{domxref("GPUAdapterInfo")}} オブジェクトのインスタンスで解決する {{jsxref("Promise")}} です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.vendor); + console.log(adapterInfo.architecture); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapter/requestdevice/index.md b/files/ja/web/api/gpuadapter/requestdevice/index.md new file mode 100644 index 00000000000000..9cfc7b6b9a0003 --- /dev/null +++ b/files/ja/web/api/gpuadapter/requestdevice/index.md @@ -0,0 +1,123 @@ +--- +title: "GPUAdapter: requestDevice() メソッド" +slug: Web/API/GPUAdapter/requestDevice +l10n: + sourceCommit: bc35e70e543bc32e4e1eb0436b18f11e17fb470c +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapter")}} インターフェイスの **`requestDevice()`** メソッドは、GPU とのやりとり用の第一インターフェイスである {{domxref("GPUDevice")}} オブジェクトで解決する {{jsxref("Promise")}} を返します。 + +## 構文 + +```js-nolint +requestDevice() +requestDevice(descriptor) +``` + +### 引数 + +- `descriptor` {{optional_inline}} + - : 以下のプロパティを持つオブジェクトです。 + - `defaultQueue` {{optional_inline}} + - : デバイスのデフォルトの ({{domxref("GPUDevice.queue")}} が返す) {{domxref("GPUQueue")}} の情報を提供するオブジェクトです。このオブジェクトは 1 個のプロパティ `label` を持ち、{{domxref("GPUQueue.label", "label")}} の値を指定したデフォルトキューを提供します。値が指定されない場合のデフォルト値は空のオブジェクトであり、デフォルトキューのラベルは空文字列になります。 + - `label` {{optional_inline}} + - : {{domxref("GPUDevice")}} の特定に用いることができるラベルを表す文字列です。たとえば、コンソールでの警告や {{domxref("GPUError")}} のメッセージで使用できます。 + - `requiredFeatures` {{optional_inline}} + - : 返される {{domxref("GPUDevice")}} が対応することを要求する追加機能を表す文字列の配列です。`GPUAdapter` がこれらの機能を提供できない場合は、`requestDevice()` の呼び出しは失敗します。とりうる機能の完全なリストは、{{domxref("GPUSupportedFeatures")}} を参照してください。値が指定されない場合のデフォルトは空の配列です。 + - `requiredLimits` {{optional_inline}} + - : 返される {{domxref("GPUDevice")}} が対応することを要求する制限を表すプロパティが格納されたオブジェクトです。`GPUAdapter` がこれらの制限を提供できない場合は、`requestDevice()` の呼び出しは失敗します。それぞれのキーは {{domxref("GPUSupportedLimits")}} のメンバーである名前でなければなりません。値が指定されない場合のデフォルトは空のオブジェクトです。 + +> **メモ:** 下層のハードウェアが対応している場合でも、すべての機能と制限が対応しているすべてのブラウザーの WebGPU で利用可能なわけではありません。詳しくは、{{domxref("GPUAdapter.features", "features")}} および {{domxref("GPUAdapter.limits", "limits")}} のページを参照してください。 + +### 返値 + +{{domxref("GPUDevice")}} オブジェクトのインスタンスで解決する {{jsxref("Promise")}} です。 + +重複して呼び出した場合、すなわち `requestDevice()` が既に呼び出されている {{domxref("GPUAdapter")}} で `requestDevice()` を呼び出した場合、プロミスは即ロストするデバイスで解決します。そして、デバイスがどうしてロストしたのかの情報を {{domxref("GPUDevice.lost")}} から取得できます。 + +### 例外 + +- `OperationError` {{domxref("DOMException")}} + - : `requiredLimits` プロパティに含まれる制限が有効な制限でないか、値がアダプターの制限値より高いために {{domxref("GPUAdapter")}} が対応していない場合、プロミスは `OperationError` で拒否されます。 +- `TypeError` {{domxref("DOMException")}} + - : `requiredFeatures` プロパティに含まれる機能に {{domxref("GPUAdapter")}} が対応していない場合、プロミスは `TypeError` で拒否されます。 + +## 例 + +### 基本的な例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const device = await adapter.requestDevice(); + + // ... +} +``` + +### 特定の機能と制限を要求する + +以下のコードでは、 + +1. {{domxref("GPUAdapter")}} で `texture-compression-astc` 機能が利用可能かをチェックします。利用可能であれば、それを配列 `requiredFeatures` にプッシュします。 +2. `GPUAdapter.limits` の `maxBindGroups` の値を問い合わせ、6 以上であるかをチェックします。理論上のサンプルアプリケーションは理想的には 6 個のバインドグループを必要とするので、返された値が 6 以上の場合は `requiredLimits` オブジェクトに最大値 6 を追加適用します。 +3. これらの機能および制限の要件に `defaultQueue` ラベルを追加し、デバイスを要求します。 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const requiredFeatures = []; + + if (adapter.features.has("texture-compression-astc")) { + requiredFeatures.push("texture-compression-astc"); + } + + const requiredLimits = {}; + + // アプリケーションは理想的には 6 個のバインドグループを必要とするので、 + // アプリケーションが必要とする分の要求を試みる + if (adapter.limits.maxBindGroups >= 6) { + requiredLimits.maxBindGroups = 6; + } + + const device = await adapter.requestDevice({ + defaultQueue: { + label: "myqueue", + }, + requiredFeatures, + requiredLimits, + }); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapterinfo/architecture/index.md b/files/ja/web/api/gpuadapterinfo/architecture/index.md new file mode 100644 index 00000000000000..b43c9fa3ab082e --- /dev/null +++ b/files/ja/web/api/gpuadapterinfo/architecture/index.md @@ -0,0 +1,46 @@ +--- +title: "GPUAdapterInfo: architecture プロパティ" +slug: Web/API/GPUAdapterInfo/architecture +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapterInfo")}} インターフェイスの読み取り専用プロパティ **`architecture`** は、アダプターが属している GPU のファミリーまたはクラスの名前を返します。取得できない場合は空文字列を返します。 + +## 値 + +文字列です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.architecture); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapterinfo/description/index.md b/files/ja/web/api/gpuadapterinfo/description/index.md new file mode 100644 index 00000000000000..32aca6931d7731 --- /dev/null +++ b/files/ja/web/api/gpuadapterinfo/description/index.md @@ -0,0 +1,46 @@ +--- +title: "GPUAdapterInfo: description プロパティ" +slug: Web/API/GPUAdapterInfo/description +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapterInfo")}} インターフェイスの読み取り専用プロパティ **`description`** は、アダプターを表現する人間に読める文字列を返します。取得できない場合は空文字列を返します。 + +## 値 + +文字列です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.description); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapterinfo/device/index.md b/files/ja/web/api/gpuadapterinfo/device/index.md new file mode 100644 index 00000000000000..eddfc34a6a239a --- /dev/null +++ b/files/ja/web/api/gpuadapterinfo/device/index.md @@ -0,0 +1,46 @@ +--- +title: "GPUAdapterInfo: device プロパティ" +slug: Web/API/GPUAdapterInfo/device +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapterInfo")}} インターフェイスの読み取り専用プロパティ **`device`** は、アダプターのベンダー固有の識別子を返します。取得できない場合は空文字列を返します。 + +## 値 + +文字列です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.device); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapterinfo/index.md b/files/ja/web/api/gpuadapterinfo/index.md new file mode 100644 index 00000000000000..13964af678d768 --- /dev/null +++ b/files/ja/web/api/gpuadapterinfo/index.md @@ -0,0 +1,58 @@ +--- +title: GPUAdapterInfo +slug: Web/API/GPUAdapterInfo +l10n: + sourceCommit: ee9993f6186ca6673b96d226e63132b3e317813f +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("WebGPU API", "WebGPU API", "", "nocode")}} の **`GPUAdapterInfo`** インターフェイスには、{{domxref("GPUAdapter")}} に関する特定用の情報が格納されています。 + +`GPUAdapterInfo` オブジェクトのインスタンスは、{{domxref("GPUAdapter.requestAdapterInfo()")}} メソッドを用いて要求できます。 + +{{InheritanceDiagram}} + +## インスタンスプロパティ + +- {{domxref("GPUAdapterInfo.architecture", "architecture")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターが属している GPU のファミリーまたはクラスの名前です。取得できない場合は空文字列を返します。 +- {{domxref("GPUAdapterInfo.description", "description")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターを表現する人間に読める文字列です。取得できない場合は空文字列を返します。 +- {{domxref("GPUAdapterInfo.device", "device")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターのベンダー固有の識別子です。取得できない場合は空文字列を返します。 +- {{domxref("GPUAdapterInfo.vendor", "vendor")}} {{Experimental_Inline}} {{ReadOnlyInline}} + - : アダプターのベンダーの名前です。取得できない場合は空文字列を返します。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.architecture); + console.log(adapterInfo.vendor); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/gpuadapterinfo/vendor/index.md b/files/ja/web/api/gpuadapterinfo/vendor/index.md new file mode 100644 index 00000000000000..b4d9c7b8c8a76d --- /dev/null +++ b/files/ja/web/api/gpuadapterinfo/vendor/index.md @@ -0,0 +1,46 @@ +--- +title: "GPUAdapterInfo: vendor プロパティ" +slug: Web/API/GPUAdapterInfo/vendor +l10n: + sourceCommit: b6984118ac9482e683a654edfefa4b426ca3c7ca +--- + +{{APIRef("WebGPU API")}}{{SeeCompatTable}} + +{{domxref("GPUAdapterInfo")}} インターフェイスの読み取り専用プロパティ **`vendor`** は、アダプターのベンダーの名前を返します。取得できない場合は空文字列を返します。 + +## 値 + +文字列です。 + +## 例 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const adapterInfo = await adapter.requestAdapterInfo(); + console.log(adapterInfo.vendor); + + // ... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU API](/ja/docs/Web/API/WebGPU_API) diff --git a/files/ja/web/api/sharedworker/index.md b/files/ja/web/api/sharedworker/index.md index a2bcdaf8896e85..484e75e1f7a238 100644 --- a/files/ja/web/api/sharedworker/index.md +++ b/files/ja/web/api/sharedworker/index.md @@ -9,7 +9,7 @@ l10n: **`SharedWorker`** インターフェイスは、ウィンドウ、iframe、ワーカーなど複数の閲覧コンテキストからアクセスできる、特定の種類のワーカーを表します。これらは専用ワーカーとは異なるインターフェイスを実装しており、異なるグローバルコンテキストである {{domxref("SharedWorkerGlobalScope")}} を持ちます。 -> **メモ:** SharedWorkerが複数の閲覧コンテキストからアクセスできる場合、それらの閲覧コンテキストはすべて、まったく同じ元（同じプロトコル、ホスト、ポート）を共有している必要があります。 +> **メモ:** SharedWorkerが複数の閲覧コンテキストからアクセスできる場合、それらの閲覧コンテキストはすべて、まったく同じオリジン（同じプロトコル、ホスト、ポート）を共有している必要があります。 {{InheritanceDiagram}} diff --git a/files/ja/web/api/view_transitions_api/index.md b/files/ja/web/api/view_transitions_api/index.md new file mode 100644 index 00000000000000..d5183b971aa4d9 --- /dev/null +++ b/files/ja/web/api/view_transitions_api/index.md @@ -0,0 +1,307 @@ +--- +title: ビュートランジション API +slug: Web/API/View_Transitions_API +l10n: + sourceCommit: 6d4b6a0f9df94de158c373d6b08c504caafcee5f +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("View Transitions API")}} + +**ビュートランジション API** は、異なる DOM 状態間のアニメーション遷移を簡単に作成する仕組みを提供し、同時に DOM コンテンツも単一の手順で更新します。 + +## 概念と使い方 + +ビュートランジションは、ユーザーがアプリケーションの状態またはビューの間を移動する際に、ユーザーの認知的負荷を縮小し、コンテキストにとどまることを支援し、読み込み待ちの知覚時間を短縮するための有力な設計の選択肢です。 + +しかし、ウェブ上でビュートランジションを作成するのは、過去には困難なことでした。単一のページアプリ (SPA) で状態間の遷移を行うには、かなりの CSS と JavaScript を書かなければならない傾向があります。 + +- 古いコンテンツと新しいコンテンツの読み込みと位置決めを処理します。 +- 古い状態と新しい状態をアニメーション化して、トランジションを作成します。 +- 古いコンテンツを誤ってユーザーが操作して問題が発生しないようにします。 +- トランジションが完了したら、古いコンテンツを除去します。 + +また、新しいコンテンツと古いコンテンツが同時に DOM に存在することで、読み上げ位置の喪失、フォーカスの混乱、奇妙なライブ領域のアナウンス動作といったアクセシビリティの課題も生じます。さらに、文書間の（つまり、 SPA ではない通常のウェブサイトの異なるページ間の）ビュートランジションは不可能です。 + +ビュートランジション API は、要求される DOM の変更とトランジションアニメーションをより簡単に処理する方法を提供します。 + +> **メモ:** ビュートランジション API は、現在のところ文書間のビュートランジションを可能にするものではありませんが、これは将来の仕様レベルで計画されており、活発に作業されています。 + +### 基本的なビュートランジションの作成 + +例えば、ナビゲーションリンクがクリックされたり、サーバーから更新がプッシュされたりといった何らかのイベントに応答して、新しいコンテンツを取得して DOM を更新する機能を SPA に含めることができます。この[基本的なビュートランジションのデモ](https://mdn.github.io/dom-examples/view-transitions/)では、クリックされたサムネイルに基づいて新しいフルサイズの画像を表示する `displayNewImage()` 関数に単純化しました。これを `updateView()` 関数内にカプセル化し、ブラウザーの対応している場合にのみビュートランジション API を呼び出すようにしています。 + +```js +function updateView(event) { + // と のどちらにイベントが発生するかの違いを扱う + const targetIdentifier = event.target.firstChild || event.target; + + const displayNewImage = () => { + const mainSrc = `${targetIdentifier.src.split("_th.jpg")[0]}.jpg`; + galleryImg.src = mainSrc; + galleryCaption.textContent = targetIdentifier.alt; + }; + + // ビュートランジションに対応していないブラウザー用のフォールバック + if (!document.startViewTransition) { + displayNewImage(); + return; + } + + // ビュートランジションで + const transition = document.startViewTransition(() => displayNewImage()); +} +``` + +このコードだけで表示画像の切り替えを処理することができます。対応しているブラウザーでは、古い画像から新しい画像とキャプションへの変更をスムーズなクロスフェード（ビュートランジションの既定値）として表示させます。対応していないブラウザーでも動作しますが、アニメーションは表示されません。 + +`startViewTransition()` は {{domxref("ViewTransition")}} インスタンスを返しますが、このインスタンスにはいくつかのプロミスが含まれており、ビュートランジションプロセスの異なる部分に到達するためにコードを実行することができます。 + +### ビュートランジションのプロセス + +これがどのように動作するのかを見ていきましょう。 + +1. {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} が呼び出されると、 API は現在のページのスクリーンショットを撮ります。 +2. 次に `startViewTransition()` に渡したコールバック（この場合は `displayNewImage`）を呼び出し、これが DOM を変更します。 + + コールバックが正常に実行されると、 {{domxref("ViewTransition.updateCallbackDone")}} のプロミスが履行され、 DOM の更新に応答できるようになります。 + +3. API はページの新しい状態をライブ表現として取り込みます。 +4. API は以下のような構造の擬似要素ツリーを構築します。 + + ```plain + ::view-transition + └─ ::view-transition-group(root) + └─ ::view-transition-image-pair(root) + ├─ ::view-transition-old(root) + └─ ::view-transition-new(root) + ``` + + - {{cssxref("::view-transition")}} はビュートランジションオーバーレイのルートで、すべてのビュートランジションを収め、他のすべてのページコンテンツの上に配置されます。 + - {{cssxref("::view-transition-old")}} は古いページ表示のスクリーンショットで、 {{cssxref("::view-transition-new")}} は新しいページ表示のライブ表示です。どちらも {{htmlelement("img")}} や {{htmlelement("video")}} と同じように置換コンテンツとしてレンダリングされ、 {{cssxref("object-fit")}} や {{cssxref("object-position")}} のような便利なプロパティでスタイル設定できることを意味しています。 + + トランジションアニメーションが実行されるとき、 {{domxref("ViewTransition.ready")}} プロミスが履行され、例えば既定のアニメーションではなく独自の JavaScript アニメーションを実行して対応することができます。 + +5. 古いページ表示の {{cssxref("opacity")}} を 1 から 0 へアニメーションさせる一方、新しい表示の `opacity` を 0 から 1 までアニメーションします。これは既定のクロスフェードを作成するものです。 +6. トランジションアニメーションが終了状態に達すると、 {{domxref("ViewTransition.finished")}} プロミスが履行され、応答できるようになります。 + +### 要素ごとに異なるトランジション + +現時点では、 DOM 更新時に変化する異なる要素はすべて同じアニメーションを使用してトランジションします。異なる要素を既定で「ルート」アニメーションとは異なる形でアニメーションさせたい場合は、 {{cssxref("view-transition-name")}} プロパティを使用してそれらを区切ることができます。例えば、以下のようにします。 + +```css +figcaption { + view-transition-name: figure-caption; +} +``` + +{{htmlelement("figcaption")}} 要素に `figure-caption` という `view-transition-name` を指定したのは、ビュートランジションでページの他の部分と区別するためです。 + +この CSS を適用すると、擬似要素ツリーは次のようになります。 + +```plain +::view-transition +├─ ::view-transition-group(root) +│ └─ ::view-transition-image-pair(root) +│ ├─ ::view-transition-old(root) +│ └─ ::view-transition-new(root) +└─ ::view-transition-group(figure-caption) + └─ ::view-transition-image-pair(figure-caption) + ├─ ::view-transition-old(figure-caption) + └─ ::view-transition-new(figure-caption) +``` + +2 つ目の擬似要素が存在することで、 `
` だけに別個のビュートランジションスタイル設定を適用することができます。異なる新旧のページビューのキャプチャは完全に別個のものとして処理されます。 + +`view-transition-name` の値は `none` 以外であれば何らかの値を指定することができます。`none` はその要素がビュートランジションに参加しないことを意味します。 + +> **メモ:** `view-transition-name` は一意でなければなりません。 2 つのレンダリング要素が同時に同じ `view-transition-name` がある場合、 {{domxref("ViewTransition.ready")}} は拒否され、トランジションはスキップされます。 + +### アニメーションのカスタマイズ + +ビュートランジションの擬似要素には既定で [CSS アニメーション](/ja/docs/Web/CSS/CSS_animations)が適用されています（詳しくは[参照ページ](#css_の追加)を参照してください）。 + +特に、 `height`、`width`、`position`、`transform` のトランジションはスムーズなクロスフェードアニメーションを使用しません。その代わりに、height と width のトランジションでは拡大縮小するアニメーションが適用されます。一方、position と transform のトランジションは要素に滑らかな移動アニメーションを適用します。 + +既定のアニメーションは、通常の CSS を使用して自由に変更することができます。 + +例えば、そのスピードを変えるには次のようにします。 + +```css +::view-transition-old(root), +::view-transition-new(root) { + animation-duration: 0.5s; +} +``` + +もっと面白いものを見ていきましょう。 `
` のカスタムアニメーションです。 + +```css +@keyframes grow-x { + from { + transform: scaleX(0); + } + to { + transform: scaleX(1); + } +} + +@keyframes shrink-x { + from { + transform: scaleX(1); + } + to { + transform: scaleX(0); + } +} + +::view-transition-old(figure-caption), +::view-transition-new(figure-caption) { + height: auto; + right: 0; + left: auto; + transform-origin: right center; +} + +::view-transition-old(figure-caption) { + animation: 0.25s linear both shrink-x; +} + +::view-transition-new(figure-caption) { + animation: 0.25s 0.25s linear both grow-x; +} +``` + +ここでは、独自の CSS アニメーションを作成し、それを `::view-transition-old(figure-caption)` および `::view-transition-new(figure-caption)` 擬似要素に適用しています。他にも、同じ配置を維持し、既定値のスタイル設定がカスタムアニメーションの邪魔をしないようにするために、両方にスタイルを追加しています。 + +なお、上記よりもシンプルで、より良い結果をもたらす別のトランジションオプションも見つけました。最終的な `
` のビュートランジションはこのようになりました。 + +```css +figcaption { + view-transition-name: figure-caption; +} + +::view-transition-old(figure-caption), +::view-transition-new(figure-caption) { + height: 100%; +} +``` + +これは既定では `::view-transition-group` が古いビューと新しいビューの間で幅と高さを遷移させるのでうまくいきます。これはうまくいくために、両方の状態で固定された `height` を設定する必要がありました。 + +> **メモ:** [ビュートランジション API によるスムーズでシンプルなトランジション](https://developer.chrome.com/docs/web-platform/view-transitions/)には、いくつかの他のカスタマイズ例があります。 + +### JavaScript によるアニメーションの制御 + +{{domxref("Document.startViewTransition()", "document.startViewTransition()")}} メソッドは {{domxref("ViewTransition")}} オブジェクトインスタンスを返します。このオブジェクトインスタンスには、いくつかのプロミスメンバーが含まれており、トランジションの様々な状態に達したことに応答して JavaScript を実行することができます。例えば、 {{domxref("ViewTransition.ready")}} は擬似要素ツリーが作成され、アニメーションが始まろうとすると履行され、 {{domxref("ViewTransition.finished")}} はアニメーションが完了し、新しいページビューがユーザーに表示され操作できるようになると履行されます。 + +例えば、次の例では、{{domxref("Web Animations API", "ウェブアニメーション API", "", "nocode")}} によって指定されたアニメーションで、クリック時のユーザーカーソルの位置から発せられる円形の明らかになるビュー遷移を作成するために、以下の JavaScript を使用することができます。 + +```js +// 最後のクリックイベントを格納 +let lastClick; +addEventListener("click", (event) => (lastClick = event)); + +function spaNavigate(data) { + // この API に対応していないブラウザーのためのフォールバック + if (!document.startViewTransition) { + updateTheDOMSomehow(data); + return; + } + + // クリック位置を取得するか、画面の中央へフォールバックする + const x = lastClick?.clientX ?? innerWidth / 2; + const y = lastClick?.clientY ?? innerHeight / 2; + // 最も遠いコーナーまでの距離を取得 + const endRadius = Math.hypot( + Math.max(x, innerWidth - x), + Math.max(y, innerHeight - y), + ); + + // トランジションを作成 + const transition = document.startViewTransition(() => { + updateTheDOMSomehow(data); + }); + + // 擬似要素が作成されるのを待つ + transition.ready.then(() => { + // ルートの新しいビューをアニメーション + document.documentElement.animate( + { + clipPath: [ + `circle(0 at ${x}px ${y}px)`, + `circle(${endRadius}px at ${x}px ${y}px)`, + ], + }, + { + duration: 500, + easing: "ease-in", + // アニメーションさせる擬似要素を指定 + pseudoElement: "::view-transition-new(root)", + }, + ); + }); +} +``` + +このアニメーションには以下の CSS も必要です。CSS の既定のアニメーションをオフにし、新しい状態と古い状態を混合しないようにします（新しい状態はトランジションするのではなく、古い状態のすぐ上に「ワイプ」されます）。 + +```css +::view-transition-image-pair(root) { + isolation: auto; +} + +::view-transition-old(root), +::view-transition-new(root) { + animation: none; + mix-blend-mode: normal; + display: block; +} +``` + +## インターフェイス + +- {{domxref("ViewTransition")}} + - : ビュートランジションを表します。トランジションが異なる状態（アニメーションを実行する準備ができている、アニメーションが完了したなど）に達したり、トランジションを完全にスキップしたりする機能を提供します。 + +## 他のインターフェイスの拡張 + +- {{domxref("Document.startViewTransition()")}} + - : 新しいビュートランジションを開始し、それを表す {{domxref("ViewTransition")}} オブジェクトを返します。 + +## CSS の追加 + +### プロパティ + +- {{cssxref("view-transition-name")}} + - : 選択された要素に別な識別名を提供し、ルートのビュートランジションとは別のビュートランジションに参加させます。 `none` の値が指定された場合はビュートランジションに参加させません。 + +### 擬似要素 + +- {{cssxref("::view-transition")}} + - : ビュートランジションオーバーレイのルートで、すべてのビュートランジションを格納し、他のすべてのページコンテンツの上に配置されます。 +- {{cssxref("::view-transition-group", "::view-transition-group()")}} + - : 単一のビュートランジションのルートです。 +- {{cssxref("::view-transition-image-pair", "::view-transition-image-pair()")}} + - : ビュートランジションの新旧ビュー（トランジション前とトランジション後）のコンテナーです。 +- {{cssxref("::view-transition-old", "::view-transition-old()")}} + - : ビュートランジション移行前の静止スクリーンショットです。 +- {{cssxref("::view-transition-new", "::view-transition-new()")}} + - : ビュートランジション後の新しいビューのライブ表現です。 + +## 例 + +- [Basic View Transitions demo](https://mdn.github.io/dom-examples/view-transitions/): 基本的な画像ギャラリーのデモで、古い画像と新しい画像、古いキャプションと新しいキャプションの間に別個のトランジションがあります。 +- [HTTP 203 playlist](https://http203-playlist.netlify.app/): [ビュートランジション API によるスムーズでシンプルなトランジション](https://developer.chrome.com/docs/web-platform/view-transitions/)では、その多くが説明されています。異なる多くのビュートランジション機能を備えた、より洗練された動画プレーヤーのデモアプリです。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュートランジション API によるスムーズでシンプルなトランジション](https://developer.chrome.com/docs/web-platform/view-transitions/) +- [View Transitions API: Creating Smooth Page Transitions](https://stackdiary.com/view-transitions-api/) diff --git a/files/ja/web/api/viewtransition/finished/index.md b/files/ja/web/api/viewtransition/finished/index.md new file mode 100644 index 00000000000000..5cafe9e9a4130a --- /dev/null +++ b/files/ja/web/api/viewtransition/finished/index.md @@ -0,0 +1,57 @@ +--- +title: "ViewTransition: finished プロパティ" +short-title: finished +slug: Web/API/ViewTransition/finished +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc +--- + +{{APIRef("View Transitions API")}}{{SeeCompatTable}} + +**`finished`** は {{domxref("ViewTransition")}} インターフェイスの読み取り専用のプロパティで、ビュートランジションのアニメーションが完了し、新しいページビューがユーザーに表示され操作可能になると履行されるプロミス ({{jsxref("Promise")}}) です。 + +`finished` は {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} に渡されたコールバックが例外を発生するか、拒否されてページの新しい状態が作成されなかったことを示すプロミスを返した場合にのみ拒否されます。 + +トランジションのアニメーションが開始されなかったり、 {{domxref("ViewTransition.skipTransition()")}} を使用してアニメーション中にスキップされた場合でも、終了状態に到達しているため、 `finished` は履行されます。 + +## 値 + +プロミスです。 + +## 例 + +### 様々な操作に様々なトランジション + +特定のナビゲーションで、固有のトランジションが要求されることがあります。例えば、「戻る」ナビゲーションは「進む」ナビゲーションとは異なるトランジションが必要かもしれません。このようなケースを処理する最良の方法は、 `` 要素にクラス名を設定し、ビュートランジションのアニメーションを使用しながらトランジションを処理し、トランジションが完了したらクラス名を除去することです。 + +```js +async function handleTransition() { + if (isBackNavigation) { + document.documentElement.classList.add("back-transition"); + } + + const transition = document.startViewTransition(() => + updateTheDOMSomehow(data), + ); + + try { + await transition.finished; + } finally { + document.documentElement.classList.remove("back-transition"); + } +} +``` + +> **メモ:** `isBackNavigation` は組み込み機能ではありません。これは理論的な機能で、[ナビゲーション API](/ja/docs/Web/API/Navigation_API) などを使用して実装できるかもしれません。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/viewtransition/index.md b/files/ja/web/api/viewtransition/index.md new file mode 100644 index 00000000000000..f4d7fd96973c4c --- /dev/null +++ b/files/ja/web/api/viewtransition/index.md @@ -0,0 +1,106 @@ +--- +title: ViewTransition +slug: Web/API/ViewTransition +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc +--- + +{{APIRef("View Transitions API")}}{{SeeCompatTable}} + +**`ViewTransition`** は{{domxref("View Transitions API", "ビュートランジション API", "", "nocode")}} のインターフェースで、ビュートランジションを表し、トランジションが様々な状態（例えば、アニメーションを実行する準備ができている、またはアニメーションが終了した）に達したときに反応する機能、またはトランジションを完全にスキップする機能を提供します。 + +このオブジェクト型は {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} メソッドが返します。 `startViewTransition()` が呼び出されると、[ビュートランジションのプロセス](/ja/docs/Web/API/View_Transitions_API#ビュートランジションのプロセス)で説明されている一連のステップに従います。これは様々なプロミスが履行されるタイミングについても説明しています。 + +{{InheritanceDiagram}} + +## インスタンスプロパティ + +- {{domxref("ViewTransition.finished")}} {{Experimental_Inline}} + - : {{jsxref("Promise")}} で、トランジションのアニメーションが完了し、新しいページビューがユーザーに表示され操作可能になると履行されます。 +- {{domxref("ViewTransition.ready")}} {{Experimental_Inline}} + - : {{jsxref("Promise")}} で、擬似要素ツリーが作成され、トランジションのアニメーションが始まろうとすると履行されます。 +- {{domxref("ViewTransition.updateCallbackDone")}} {{Experimental_Inline}} + - : {{jsxref("Promise")}} で、 {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} のコールバックが返すプロミスが履行されたときに履行されます。 + +## インスタンスメソッド + +- {{domxref("ViewTransition.skipTransition", "skipTransition()")}} {{Experimental_Inline}} + - : ビュートランジションのアニメーション部分をスキップします。ただし、 DOM を更新する {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} コールバックの実行はスキップしません。 + +## 例 + +次の例では、 {{domxref("ViewTransition.ready")}} プロミスを使用して、クリック時のユーザーカーソルの位置から発生する独自の円形表示ビュートランジションを発生させ、 {{domxref("Web Animations API", "ウェブアニメーション API", "", "nocode")}} によってアニメーションが指定されています。 + +```js +// 最後のクリックイベントを保存 +let lastClick; +addEventListener("click", (event) => (lastClick = event)); + +function spaNavigate(data) { + // この API に対応していないブラウザーのためのフォールバック + if (!document.startViewTransition) { + updateTheDOMSomehow(data); + return; + } + + // クリック位置を取得するか、画面の中央へフォールバックする + const x = lastClick?.clientX ?? innerWidth / 2; + const y = lastClick?.clientY ?? innerHeight / 2; + // 最も遠いコーナーまでの距離を取得 + const endRadius = Math.hypot( + Math.max(x, innerWidth - x), + Math.max(y, innerHeight - y), + ); + + // トランジションを作成 + const transition = document.startViewTransition(() => { + updateTheDOMSomehow(data); + }); + + // 擬似要素が作成されるのを待つ + transition.ready.then(() => { + // ルートの新しいビューをアニメーション + document.documentElement.animate( + { + clipPath: [ + `circle(0 at ${x}px ${y}px)`, + `circle(${endRadius}px at ${x}px ${y}px)`, + ], + }, + { + duration: 500, + easing: "ease-in", + // アニメーションさせる擬似要素を指定 + pseudoElement: "::view-transition-new(root)", + }, + ); + }); +} +``` + +このアニメーションには以下の CSS も必要です。既定のアニメーションをオフにし、古いビューと新しいビューの状態が混ざり合わないようにします（新しい状態はビュートランジションの遷移ではなく、古い状態のすぐ上に「ワイプ」されます）。 + +```css +::view-transition-image-pair(root) { + isolation: auto; +} + +::view-transition-old(root), +::view-transition-new(root) { + animation: none; + mix-blend-mode: normal; + display: block; +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/viewtransition/ready/index.md b/files/ja/web/api/viewtransition/ready/index.md new file mode 100644 index 00000000000000..ff9ff1feb1d23c --- /dev/null +++ b/files/ja/web/api/viewtransition/ready/index.md @@ -0,0 +1,95 @@ +--- +title: "ViewTransition: ready プロパティ" +short-title: ready +slug: Web/API/ViewTransition/ready +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc +--- + +{{APIRef("View Transitions API")}}{{SeeCompatTable}} + +**`ready`** は {{domxref("ViewTransition")}} インターフェイスの読み取り専用プロパティで、擬似要素ツリーが作成され、ビュートランジションのアニメーションが始まるときに履行される {{jsxref("Promise")}} です。 + +`ready` はトランジションを始められない場合に拒否されます。これは、例えば {{cssxref("view-transition-name")}} が重複していたり、{{domxref("Document.startViewTransition()")}} に渡されたコールバックが拒否されたプロミスを発生させたり返したりするなど、設定ミスが原因である可能性があります。 + +## 値 + +プロミスです。 + +## 例 + +次の例では、 {{domxref("ViewTransition.ready")}} プロミスを使用して、クリック時のユーザーカーソルの位置から発生する独自の円形表示ビュートランジションを発生させ、 {{domxref("Web Animations API", "ウェブアニメーション API", "", "nocode")}} によってアニメーションが指定されています。 + +```js +// 最後のクリックイベントを保存 +let lastClick; +addEventListener("click", (event) => (lastClick = event)); + +function spaNavigate(data) { + // この API に対応していないブラウザーのためのフォールバック + if (!document.startViewTransition) { + updateTheDOMSomehow(data); + return; + } + + // クリック位置を取得するか、画面の中央へフォールバックする + const x = lastClick?.clientX ?? innerWidth / 2; + const y = lastClick?.clientY ?? innerHeight / 2; + // 最も遠いコーナーまでの距離を取得 + const endRadius = Math.hypot( + Math.max(x, innerWidth - x), + Math.max(y, innerHeight - y), + ); + + // トランジションを作成 + const transition = document.startViewTransition(() => { + updateTheDOMSomehow(data); + }); + + // 擬似要素が作成されるのを待つ + transition.ready.then(() => { + // ルートの新しいビューをアニメーション + document.documentElement.animate( + { + clipPath: [ + `circle(0 at ${x}px ${y}px)`, + `circle(${endRadius}px at ${x}px ${y}px)`, + ], + }, + { + duration: 500, + easing: "ease-in", + // アニメーションさせる擬似要素を指定 + pseudoElement: "::view-transition-new(root)", + }, + ); + }); +} +``` + +このアニメーションには以下の CSS も必要です。既定のアニメーションをオフにし、古いビューと新しいビューの状態が混ざり合わないようにします（新しい状態はビュートランジションの遷移ではなく、古い状態のすぐ上に「ワイプ」されます）。 + +```css +::view-transition-image-pair(root) { + isolation: auto; +} + +::view-transition-old(root), +::view-transition-new(root) { + animation: none; + mix-blend-mode: normal; + display: block; +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/viewtransition/skiptransition/index.md b/files/ja/web/api/viewtransition/skiptransition/index.md new file mode 100644 index 00000000000000..dc4ba2894e1f1d --- /dev/null +++ b/files/ja/web/api/viewtransition/skiptransition/index.md @@ -0,0 +1,47 @@ +--- +title: "ViewTransition: skipTransition() メソッド" +short-title: skipTransition() +slug: Web/API/ViewTransition/skipTransition +l10n: + sourceCommit: 7b3ccaec4a93584da12939587ea746acaabe30bc +--- + +{{APIRef("View Transitions API")}}{{SeeCompatTable}} + +**`skipTransition()`** は {{domxref("ViewTransition")}} インターフェイスのメソッドで、ビュートランジションのアニメーション部分をスキップしますが、 DOM を更新する {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} コールバックの実行はスキップしません。 + +## 構文 + +```js-nolint +skipTransition() +``` + +### 引数 + +なし。 + +### 返値 + +`undefined` です。 + +## 例 + +```js +// 新しいビュートランジションを開始 +const transition = document.startViewTransition(() => displayNewImage()); + +// アニメーションをスキップし、DOM を更新する +transition.skipTransition(); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/viewtransition/updatecallbackdone/index.md b/files/ja/web/api/viewtransition/updatecallbackdone/index.md new file mode 100644 index 00000000000000..3a0aca0ee3f3ca --- /dev/null +++ b/files/ja/web/api/viewtransition/updatecallbackdone/index.md @@ -0,0 +1,42 @@ +--- +title: "ViewTransition: updateCallbackDone プロパティ" +short-title: updateCallbackDone +slug: Web/API/ViewTransition/updateCallbackDone +l10n: + sourceCommit: 7b3ccaec4a93584da12939587ea746acaabe30bc +--- + +{{APIRef("View Transitions API")}}{{SeeCompatTable}} + +**`updateCallbackDone`** は {{domxref("ViewTransition")}} インターフェイスの読み取り専用のプロパティで、 {{domxref("Document.startViewTransition()", "document.startViewTransition()")}} のコールバックが返すプロミスが履行されると履行され、拒否されると拒否されるプロミス ({{jsxref("Promise")}}) です。 + +`updateCallbackDone` は、ビュートランジションのアニメーションの成否を気にせず、 DOM が更新されたかどうか、いつ更新されたかを知りたい場合に有益です。 + +## 値 + +プロミスです。 + +## 例 + +```js +// 新しいビュートランジションを開始 +const transition = document.startViewTransition(() => displayNewImage()); + +transition.updateCallbackDone.then(() => { + // 正常に更新された DOM に応答 +}); +``` + +有用な例は、 [Transitions as an enhancement](https://developer.chrome.com/docs/web-platform/view-transitions/#transitions-as-an-enhancement) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/api/webgpu_api/index.md b/files/ja/web/api/webgpu_api/index.md new file mode 100644 index 00000000000000..ab9ec264f1e878 --- /dev/null +++ b/files/ja/web/api/webgpu_api/index.md @@ -0,0 +1,606 @@ +--- +title: WebGPU API +slug: Web/API/WebGPU_API +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc +--- + +{{DefaultAPISidebar("WebGPU API")}}{{SeeCompatTable}}{{securecontext_header}} + +**WebGPU API** は、ウェブ開発者が下層のシステムの GPU (Graphics Processing Unit) を使用し、高効率の計算をしたり、ブラウザーでレンダーできる複雑な画像を描画したりすることを可能にします。 + +WebGPU は {{domxref("WebGL_API", "WebGL", "", "nocode")}} の後継で、最近の GPU とのより良い互換性を提供し、汎用 GPU 計算に対応し、操作を速くし、さらに高度な GPU の機能へのアクセスを可能にします。 + +## 概念と使用法 + +2011 年頃に最初に登場した後、{{domxref("WebGL_API", "WebGL", "", "nocode")}} がグラフィックの能力の面でウェブに革命を起こしたといえます。WebGL は [OpenGL ES 2.0](https://registry.khronos.org/OpenGL-Refpages/es2.0/) グラフィックライブラリーの JavaScript への移植であり、ウェブページがレンダリング計算をデバイスの GPU に直接渡し、超高速で処理させ、結果を {{htmlelement("canvas")}} 要素内に描画することを可能にします。 + +WebGL と WebGL シェーダーのコードを書くのに用いられる [GLSL]() 言語は複雑なので、WebGL アプリケーションをより簡単に書けるようにするためにいくつかの WebGL ライブラリーが作られました。有名な例としては [Three.js](https://threejs.org/)、[Babylon.js](https://www.babylonjs.com/)、[PlayCanvas](https://playcanvas.com/) などがあります。開発者はこれらのツールを用い、没入感のあるウェブベースの 3D ゲーム、ミュージックビデオ、訓練やモデリングのツール、VR や AR の体験、などを作ってきました。 + +しかし、WebGL には修正が必要な根本的な問題点がいくつかあります。 + +- WebGL がリリースされて以降、新世代のネイティブ GPU API が登場しました。最も人気があるのは [Microsoft の Direct3D 12](https://learn.microsoft.com/ja-jp/windows/win32/direct3d12/direct3d-12-graphics)、[Apple の Metal](https://developer.apple.com/metal/)、[The Khronos Group の Vulkan](https://www.vulkan.org/) です。これらは多くの新機能を提供します。OpenGL のアップデートはもう計画されておらず、WebGL も同様なので、これらの新機能は何も導入されません。一方、WebGPU は進歩し、新機能が追加されるでしょう。 +- WebGL は完全にグラフィックを描画し、それをキャンバスに描画するというユースケースに基づいており、汎用 GPPU (GPGPU) 計算をあまり上手く扱うことができません。GPGPU 計算は機械学習モデルをベースにするものなど、多くの異なるユースケースでどんどん重要になってきています。 +- 3D グラフィックアプリケーションは、同時にレンダリングするオブジェクトの数と新しいレンダリング機能の活用の両面で、負荷が高くなってきています。 + +WebGPU は、最近の GPU API と互換性があり、より「webby」な感じがする新しい汎用アーキテクチャを提供し、これらの問題点を解決します。グラフィックのレンダリングに対応しているとともに、GPGPU 計算にもよく対応しています。CPU 側での個別のオブジェクトの描画は劇的に軽くなり、計算ベースのパーティクルや、色効果、鮮明化、被写界深度シミュレーションなどの後処理フィルターなどの最近の GPU のレンダリング機能にも対応します。さらに、カリングやスキン付きモデルの変換などの重い計算を直接 GPU で扱うことができます。 + +## 一般モデル + +デバイスの GPU と WebGPU API を実行しているウェブブラウザーの間には、いくつかの抽象化レイヤーがあります。WebGPU の学習を開始する際、これらを理解することは有用です。 + +![デバイス上の WebGPU アーキテクチャの異なる要素の位置を示す基本の積層図](basic-webgpu-stack.png) + +- GPU がある物理デバイス。ほとんどのデバイスには GPU が 1 個だけありますが、複数あるデバイスもあります。以下の異なる GPU の種類が利用可能です。 + + - 統合 GPU: CPU と同じ基板にあり、メモリーを共有します。 + - 個別 GPU: 独自の基板にあり、CPU からは分離されています。 + - ソフトウェア「GPU」: CPU 上で実装されています。 + + > **メモ:** 上記の図では、GPU が 1 個だけあるデバイスを仮定しています。 + +- OS の一部であるネイティブ GPU API (たとえば macOS 上の Metal) は、ネイティブアプリケーションが GPU の機能を用いることができるプログラミングインターフェイスです。API 命令がドライバーを通じて GPU に送られ、結果を受け取ります。上記の図ではネイティブ API およびドライバーが 1 個だけあるデバイスを仮定していますが、システムが GPU とやり取りするための複数のネイティブ OS API やドライバーを持つことも可能です。 +- ブラウザーの WebGPU 実装は、ネイティブ GPU API ドライバーを通じた GPU とのやり取りを扱います。WebGPU のアダプターが、あなたのコード上で下層のシステムで利用可能な物理 GPU とドライバーを効率よく表します。 +- 論理デバイスは、単一のウェブアプリケーションが分離された方法で GPU の機能にアクセスできるようにする抽象化です。論理デバイスは、多重化の機能を提供する必要があります。物理デバイスの GPU は多くのアプリケーションで用いられ、並行で処理を行います。この中には多くのウェブアプリケーションが含まれる可能性があります。それぞれのウェブアプリケーションは、セキュリティおよびロジック上の理由で、隔離された状態で WebGPU にアクセスできる必要があります。 + +## デバイスへのアクセス + +論理デバイスは、{{domxref("GPUDevice")}} オブジェクトインスタンスで表され、ウェブアプリケーションが WebGPU のすべての機能にアクセスする基礎となります。デバイスへのアクセスは、以下の手順で行われます。 + +1. {{domxref("Navigator.gpu")}} プロパティ (もしくは、ワーカーから WebGPU の機能を用いる場合は {{domxref("WorkerNavigator.gpu")}}) が現在のコンテキスト用の {{domxref("GPU")}} オブジェクトを返します。 +2. {{domxref("GPU.requestAdapter", "GPU.requestAdapter()")}} メソッドを通じてアダプターにアクセスします。このメソッドは省略可能な設定オブジェクトを受け取り、たとえば高パフォーマンスのアダプターや低消費電力のアダプターを要求することができます。これが無い場合は、デバイスはデフォルトのアダプターへのアクセスを提供し、これはほとんどの目的に十分適するでしょう。 +3. {{domxref("GPUAdapter.requestDevice()")}} によりデバイスを要求できます。このメソッドは、(ディスクリプターと呼ばれる) オプションオブジェクトも受け取り、これにより論理デバイスに期待する詳細な機能や制限を指定できます。これが無い場合は、返されるデバイスは合理的な汎用のスペックを持ち、これはほとんどの用途に適します。 + +これらにいくつかの機能検出チェックを加えると、上記の手順は以下のようにして実現できます。 + +```js +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターの要求に失敗しました。"); + } + + const device = await adapter.requestDevice(); + + //... +} +``` + +## パイプラインとシェーダー: WebGPU アプリケーションの構造 + +パイプラインは、プログラムの処理を実現するために実行するプログラマブルなステージが入る論理的な構造です。現在、WebGPU では以下の 2 種類のパイプラインを扱うことができます。 + +- レンダーパイプラインはグラフィックをレンダリングします。{{htmlelement("canvas")}} 要素に描画することが多いですが、オフスクリーンでグラフィックをレンダリングすることもできます。これには以下の 2 個のメインステージがあります。 + + - バーテックスステージ: バーテックスシェーダーが GPU に渡された位置データを受け取り、回転、変換、射影などの指定の効果を適用することで 3D 空間内の頂点群の位置を決定します。そして、頂点は三角形 (レンダリングされるグラフィックの基礎となる部品) などのプリミティブに組み立てられ、GPU によって描画を行うキャンバスのどのピクセルをカバーするかを特定するためにラスタライズされます。 + + - : フラグメントステージ: バーテックスシェーダーによって生成されたプリミティブでカバーされた各ピクセルの色をフラグメントシェーダーが計算します。これらの計算には、表面の詳細を提供する (テクスチャ形式の) 画像や、仮想光源の位置や色などの入力がよく用いられます。 + +- コンピュートパイプラインは一般の計算用です。コンピュートパイプラインは 1 個の計算ステージからなります。このステージでは、コンピュートシェーダーが一般のデータを受け取り、指定の数のワークグループで並列計算を行い、結果を 1 個以上のバッファーで返します。バッファーには任意の種類のデータを置けます。 + +上記で言及されたシェーダーは、GPU で処理される命令の集合です。WebGPU のシェーダーは [WebGPU Shader Language](https://gpuweb.github.io/gpuweb/wgsl/) (WGSL) と呼ばれる Rust 風の低レベルの言語で書かれます。 + +WebGPU アプリケーションを構築するにはいくつかの異なる方法がありますが、このプロセスはおそらく以下の手順を含むでしょう。 + +1. [シェーダーモジュールの生成](#シェーダーモジュールの生成): WGSL でシェーダーコードを書き、1 個以上のシェーダーモジュールにパッケージ化します。 +2. [キャンバスコンテキストの取得と設定](#キャンバスコンテキストの取得と設定): `` 要素の `webgpu` コンテキストを取得し、GPU 論理デバイスでどのような画像をレンダリングするかの情報を設定します。この手順は、コンピュートパイプラインのみを用いる場合など、アプリケーションが画像を出力しない場合は不要です。 +3. [データを格納したリソースの生成](#バッファを生成して三角形データを書き込む): パイプラインで処理するデータは、アプリケーションからアクセスするため、GPU バッファーまたはテクスチャーに格納される必要があります。 +4. [パイプラインの生成](#レンダーパイプラインの定義と生成): 必要なデータ構造、バインディング、シェーダー、リソースの配置を含めて要求するパイプラインを詳細に記述するパイプラインディスクリプターを定義し、それに基づいてパイプラインを生成します。ここでの基本デモには 1 個のパイプラインのみがありますが、自明でないアプリケーションは通常異なる目的のための複数のパイプラインを持ちます。 +5. [計算またはレンダリングパスの実行](#レンダリングパスの実行): これはいくつかのサブ手順からなります。 + 1. 実行用に GPU に渡すコマンド一式をエンコードするコマンドエンコーダーを生成します。 + 2. 計算またはレンダリングコマンドを発行するパスエンコーダーオブジェクトを生成します。 + 3. 使用するパイプラインの指定、必要なデータの取得元となるバッファーの指定、(レンダーパイプラインの場合は) 行う描画操作の数の指定、などを行うコマンドを実行します。 + 4. コマンドリストをファイナライズし、コマンドバッファーにカプセル化します。 + 5. 論理デバイスのコマンドキューを通して、コマンドバッファーを GPU に送信します。 + +以下の節では、レンダーパイプラインの基本デモを解析し、必要なものを探索できるようにします。その後、[コンピュートパイプラインの基本](#コンピュートパイプラインの基本)の例も解析し、レンダーパイプラインとの違いに注目します。 + +## レンダーパイプラインの基本 + +[レンダリング基本デモ](https://mdn.github.io/dom-examples/webgpu-render-demo/)では、`` 要素に青一色の背景を用意し、その上に三角形を描画します。 + +### シェーダーモジュールの生成 + +ここでは以下のシェーダーコードを用います。バーテックスシェーダーステージ (`@vertex` ブロック) は、位置と色が格納されたデータのチャンクを受け取り、位置に基づいて頂点を配置し、色を補間し、これらのデータをフラグメントシェーダーステージに渡します。フラグメントシェーダーステージ (`@fragment` ブロック) は、バーテックスシェーダーステージからデータを受け取り、指定の色に基づいて頂点の色を決定します。 + +```js +const shaders = ` +struct VertexOut { + @builtin(position) position : vec4f, + @location(0) color : vec4f +} + +@vertex +fn vertex_main(@location(0) position: vec4f, + @location(1) color: vec4f) -> VertexOut +{ + var output : VertexOut; + output.position = position; + output.color = color; + return output; +} + +@fragment +fn fragment_main(fragData: VertexOut) -> @location(0) vec4f +{ + return fragData.color; +} +`; +``` + +> **メモ:** ここでのデモではシェーダーコードをテンプレートリテラルに格納していますが、WebGPU プログラムに渡すテキストとして取得しやすい場所ならどこに格納することもできます。たとえば、シェーダーを {{htmlelement("script")}} 要素の中に格納し、{{domxref("Node.textContent")}} を用いて内容を取り出す方法もよく用いられます。WGSL 用の正しい MIME タイプは `text/wgsl` です。 + +シェーダーコードを WebGPU で利用できるようにするには、シェーダーコードをディスクリプターオブジェクトのプロパティとして {{domxref("GPUDevice.createShaderModule()")}} に渡し、{{domxref("GPUShaderModule")}} の中に格納する必要があります。これは、たとえば以下のように行います。 + +```js +const shaderModule = device.createShaderModule({ + code: shaders, +}); +``` + +### キャンバスコンテキストの取得と設定 + +レンダーパイプラインでは、グラフィックのレンダリング先を指定する必要があります。ここでは、画面上の `` 要素への参照を取得し、引数 `webgpu` を {{domxref("HTMLCanvasElement.getContext()")}} に渡すことで、GPU コンテキスト ({{domxref("GPUCanvasContext")}} のインスタンス) を返してもらいます。 + +そして、レンダリング情報の取得元となる {{domxref("GPUDevice")}}、テクスチャーの形式、半透明のテクスチャーをレンダリングする際に用いるアルファモードが格納されたオプションオブジェクトを {{domxref("GPUCanvasContext.configure()")}} に渡すことで、コンテキストを設定します。 + +```js +const canvas = document.querySelector("#gpuCanvas"); +const context = canvas.getContext("webgpu"); + +context.configure({ + device: device, + format: navigator.gpu.getPreferredCanvasFormat(), + alphaMode: "premultiplied", +}); +``` + +> **メモ:** 使用するテクスチャーの形式を決めるベストプラクティスは、{{domxref("GPU.getPreferredCanvasFormat()")}} メソッドを用いることです。これは、ユーザーのデバイス用の最も効率的な形式 (`bgra8unorm` または `rgba8unorm`) を選択します。 + +### バッファを生成して三角形データを書き込む + +次に、WebGPU が利用できる形式で、WebGPU にデータを提供します。データは最初 {{jsxref("Float32Array")}} で提供され、ここには三角形の各頂点について 8 個のデータ (位置の X, Y, Z, W および色の R, G, B, A) が格納されています。 + +```js +const vertices = new Float32Array([ + 0.0, 0.6, 0, 1, 1, 0, 0, 1, -0.5, -0.6, 0, 1, 0, 1, 0, 1, 0.5, -0.6, 0, 1, 0, + 0, 1, 1, +]); +``` + +しかし、ここで問題に直面します。データを {{domxref("GPUBuffer")}} に格納する必要があります。裏側では、この種類のバッファーは GPU のコアに非常に密接に統合されたメモリーに保存され、期待される高効率の処理を可能にします。副作用として、このメモリーはブラウザーなどのホストシステム上で実行されているプロセスからはアクセスできません。 + +{{domxref("GPUBuffer")}} は {{domxref("GPUDevice.createBuffer()")}} を呼び出すことにより生成できます。すべてのデータを格納できるよう、配列 `vertices` の長さと同じサイズを指定します。さらに、バッファーを頂点バッファーとして、およびコピー先として用いることを示す `VERTEX` および `COPY_DST` 使用法フラグを指定します。 + +```js +const vertexBuffer = device.createBuffer({ + size: vertices.byteLength, // 頂点を格納するのに十分な大きさにする + usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST, +}); +``` + +[コンピュートパイプラインの例](#コンピュートパイプラインの基本)でデータを GPU から JavaScript に読み戻すために用いるようなマッピング操作を用いてデータを `GPUBuffer` に乗せることもできます。しかし、ここでは使いやすい {{domxref("GPUQueue.writeBuffer()")}} メソッドを用います。このメソッドは、書き込み先のバッファー、書き込み元のデータソース、それぞれのオフセット値、そして書き込むデータのサイズ (ここでは配列全体の長さを指定した) を引数としてとります。すると、ブラウザーは最も効率のよい方法でデータの書き込みを処理します。 + +```js +device.queue.writeBuffer(vertexBuffer, 0, vertices, 0, vertices.length); +``` + +### レンダーパイプラインの定義と生成 + +これでデータをバッファーに配置できました。準備の次のパートは、レンダリングに用いることができるパイプラインを実際に生成することです。 + +まず最初に、頂点データで必要なレイアウトを記述するオブジェクトを生成します。これは以前に配列 `vertices` およびバーテックスシェーダーステージで見たものを完全に記述します。すなわち、各頂点が位置と色のデータを持ちます。どちらも (WGSL の `vec4` 型に対応する) `float32x4` 形式でフォーマットされ、色データは各頂点で 16 バイトのオフセットから始まります。`arrayStride` はストライド、すなわち各頂点を構成するバイト数を指定し、`stepMode` はデータを頂点ごとに読み取るべきであることを指定します。 + +```js +const vertexBuffers = [ + { + attributes: [ + { + shaderLocation: 0, // 位置 + offset: 0, + format: "float32x4", + }, + { + shaderLocation: 1, // 色 + offset: 16, + format: "float32x4", + }, + ], + arrayStride: 32, + stepMode: "vertex", + }, +]; +``` + +次に、レンダーパイプラインステージの構成を指定するディスクリプターオブジェクトを生成します。両方のシェーダーステージで関係するコードがある {{domxref("GPUShaderModule")}} (`shaderModule`)、および各ステージのエントリーポイントとなる関数の名前を指定します。 + +さらに、バーテックスシェーダーステージでは頂点データに求める状態を提供する `vertexBuffers` オブジェクトを提供し、フラグメントシェーダーステージでは (以前キャンバスコンテキストの設定で指定した形式と一致する) 指定のレンダリング形式を表す色ターゲットの状態の配列を提供します。 + +さらに、`primitive` 状態も指定します。これは今回は単に描画するプリミティブの種類を表します。さらに、`layout` を `auto` に設定します。`layout` プロパティはパイプラインの実行中に用いるすべての GPU リソース (バッファーやテクスチャーなど) のレイアウト (構造、用途、種類) を定義します。より複雑なアプリケーションでは、これは {{domxref("GPUPipelineLayout")}} オブジェクトの形式になるでしょう。これは {{domxref("GPUDevice.createPipelineLayout()")}} を用いて生成でき ([コンピュートパイプラインの基本](#コンピュートパイプラインの基本)で例を見ることができます)、GPU がどうすればパイプラインを最も効率よく実行できるかを事前に決定できるようにします。しかし、ここでは値 `auto` を指定し、パイプラインにシェーダーコードで定義されたバインディングに基づいて暗黙のバインドグループレイアウトを生成させます。 + +```js +const pipelineDescriptor = { + vertex: { + module: shaderModule, + entryPoint: "vertex_main", + buffers: vertexBuffers, + }, + fragment: { + module: shaderModule, + entryPoint: "fragment_main", + targets: [ + { + format: navigator.gpu.getPreferredCanvasFormat(), + }, + ], + }, + primitive: { + topology: "triangle-list", + }, + layout: "auto", +}; +``` + +最後に、`pipelineDescriptor` オブジェクトを引数として {{domxref("GPUDevice.createRenderPipeline()")}} メソッドを呼び出すことで、これに基づいて {{domxref("GPURenderPipeline")}} を生成できます。 + +```js +const renderPipeline = device.createRenderPipeline(pipelineDescriptor); +``` + +### レンダリングパスの実行 + +これですべての準備が完了したので、レンダリングパスを実際に実行し、`` への描画を行うことができます。後で GPU に発行するコマンドをエンコードするには、{{domxref("GPUCommandEncoder")}} インスタンスを生成する必要があります。これは {{domxref("GPUDevice.createCommandEncoder()")}} を呼び出すことで生成できます。 + +```js +const commandEncoder = device.createCommandEncoder(); +``` + +次に、{{domxref("GPUCommandEncoder.beginRenderPass()")}} を呼び出して {{domxref("GPURenderPassEncoder")}} インスタンスを生成することで、レンダリングパスの実行を開始します。このメソッドはディスクリプターオブジェクトを引数にとります。このオブジェクトの唯一の必須プロパティは配列 `colorAttachments` です。ここでは、以下を指定します。 + +1. レンダリング先のテクスチャービュー: {{domxref("GPUTexture.createView", "context.getCurrentTexture().createView()")}} により `` から新しいビューを生成します。 +2. ビューをロード後任意の描画を行う前に指定の色に「クリア」すること。これにより、三角形の後ろの青い背景を生成します。 +3. 現在のレンダリングパスの値をこのカラーアタッチメント用に格納すること。 + +```js +const clearColor = { r: 0.0, g: 0.5, b: 1.0, a: 1.0 }; + +const renderPassDescriptor = { + colorAttachments: [ + { + clearValue: clearColor, + loadOp: "clear", + storeOp: "store", + view: context.getCurrentTexture().createView(), + }, + ], +}; + +const passEncoder = commandEncoder.beginRenderPass(renderPassDescriptor); +``` + +すると、三角形を描画するためにレンダリングパスエンコーダーのメソッドを呼び出すことができるようになります。 + +1. `renderPipeline` オブジェクトを引数として {{domxref("GPURenderPassEncoder.setPipeline()")}} を呼び出すことにより、レンダリングパスで使用するパイプラインを指定します。 +2. `vertexBuffer` オブジェクトを引数として {{domxref("GPURenderPassEncoder.setVertexBuffer()")}} を呼び出すことにより、レンダリング用にパイプラインに渡すデータソースにします。最初の引数は頂点バッファーを設定するスロットであり、バッファーのレイアウトを記述する配列 `vertexBuffers` の要素のインデックスの参照です。 +3. {{domxref("GPURenderPassEncoder.draw()")}} により描画を実行します。`vertexBuffer` には 3 個の頂点のデータが格納されているので、それらすべてを描画するために頂点数の値を `3` に設定します。 + +```js +passEncoder.setPipeline(renderPipeline); +passEncoder.setVertexBuffer(0, vertexBuffer); +passEncoder.draw(3); +``` + +コマンド列のエンコードを完了して GPU に発行するために、あと 3 個の手順が必要です。 + +1. {{domxref("GPURenderPassEncoder.end()")}} メソッドを呼び出し、レンダーパスコマンドリストの終わりを示します。 +2. {{domxref("GPUCommandEncoder.finish()")}} メソッドを呼び出し、発行したコマンドの列の記録を完了し、{{domxref("GPUCommandBuffer")}} オブジェクトインスタンスにカプセル化します。 +3. {{domxref("GPUCommandBuffer")}} を GPU に送るため、デバイスの ({{domxref("GPUQueue")}} インスタンスで表される) コマンドキューに送信します。デバイスのキューは {{domxref("GPUDevice.queue")}} プロパティを通じて利用可能であり、{{domxref("GPUQueue.submit()")}} を呼び出すことでキューに {{domxref("GPUCommandBuffer")}} のインスタンスの配列を追加できます。 + +これらの 3 個の手順は以下の 2 行で実現できます。 + +```js +passEncoder.end(); + +device.queue.submit([commandEncoder.finish()]); +``` + +## コンピュートパイプラインの基本 + +[計算基本デモ](https://mdn.github.io/dom-examples/webgpu-compute-demo/)では、GPU にある値を計算させ、それらを出力バッファーに書き込み、そのデータをステージングバッファーにコピーし、JavaScript からデータを読み取ってコンソールに記録できるようにステージングバッファーをマップします。 + +このアプリケーションは、レンダリング基本デモに似た構造をなぞります。以前と同様に {{domxref("GPUDevice")}} の参照を生成し、{{domxref("GPUDevice.createShaderModule()")}} の呼び出しによりシェーダーコードを {{domxref("GPUShaderModule")}} にカプセル化します。ここでの違いは、シェーダーコードに `@compute` ステージという 1 個のシェーダーステージしか無いことです。 + +```js +// グローバルのバッファサイズを定義する +const BUFFER_SIZE = 1000; + +const shader = ` +@group(0) @binding(0) +var output: array; + +@compute @workgroup_size(64) +fn main( + @builtin(global_invocation_id) + global_id : vec3u, + + @builtin(local_invocation_id) + local_id : vec3u, +) { + // バッファーの範囲外にアクセスしないようにする + if (global_id.x >= ${BUFFER_SIZE}) { + return; + } + + output[global_id.x] = + f32(global_id.x) * 1000. + f32(local_id.x); +} +`; +``` + +### データを扱うバッファの生成 + +この例では、データを扱うために 2 個の {{domxref("GPUBuffer")}} インスタンスを生成します。GPU での計算結果を高速で書き込む `output` バッファーと、`output` の内容をコピーして JavaScript から値にアクセスできるようにマップできる `stagingBuffer` です。 + +- `output` は、コピー操作のコピー元となるストレージバッファーとして指定されています。 +- `stagingBuffer` は JavaScript から読むためにマップでき、コピー操作のコピー先となるバッファーとして指定されています。 + +```js +const output = device.createBuffer({ + size: BUFFER_SIZE, + usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC, +}); + +const stagingBuffer = device.createBuffer({ + size: BUFFER_SIZE, + usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, +}); +``` + +### バインドグループレイアウトの生成 + +パイプラインの生成時、そのパイプラインで使用するバインドグループを指定します。このためには、まずこのパイプラインで用いるバッファーなどの GPU リソースの構造と目的を定義する {{domxref("GPUBindGroupLayout")}} を ({{domxref("GPUDevice.createBindGroupLayout()")}} を呼び出すことにより) 生成します。このレイアウトは、バインドグループが従うテンプレートとして用いられます。ここでは、パイプラインがバインディングスロット 0 (シェーダーコードの関連するバインディング番号 `@binding(0)` に対応します) に結びつき、パイプラインのコンピュートステージで使用でき、バッファーの目的が `storage` と定義された 1 個のメモリーバッファーにアクセスできるようにします。 + +```js +const bindGroupLayout = device.createBindGroupLayout({ + entries: [ + { + binding: 0, + visibility: GPUShaderStage.COMPUTE, + buffer: { + type: "storage", + }, + }, + ], +}); +``` + +次に、{{domxref("GPUDevice.createBindGroup()")}} を呼び出すことにより、{{domxref("GPUBindGroup")}} を生成します。このメソッドに、バインドグループのベースとなるバインドグループレイアウトを指定するディスクリプターオブジェクトと、このレイアウトで定義されたスロットにバインドする変数の詳細を渡します。ここでは、バインディング 0 を宣言し、前に定義した `output` バッファーをそれにバインドするよう指定します。 + +```js +const bindGroup = device.createBindGroup({ + layout: bindGroupLayout, + entries: [ + { + binding: 0, + resource: { + buffer: output, + }, + }, + ], +}); +``` + +> **メモ:** {{domxref("GPUComputePipeline.getBindGroupLayout()")}} メソッドを呼び出すことで、バインドグループの生成時に使用される暗黙のレイアウトを取得できます。さらに、レンダーパイプラインで利用可能なバージョンもあります。{{domxref("GPURenderPipeline.getBindGroupLayout()")}} を参照してください。 + +### コンピュートパイプラインの生成 + +上記すべてを用意したら、パイプラインディスクリプターオブジェクトを渡して {{domxref("GPUDevice.createComputePipeline()")}} を呼び出すことで、コンピュートパイプラインを生成できます。これは、レンダーパイプラインの生成と似た方法です。コンピュートシェーダーを記述し、コードを探すモジュールとエントリーポイントを指定します。さらに、パイプラインの `layout` も指定します。ここでは、{{domxref("GPUDevice.createPipelineLayout()")}} を呼び出し、前に定義した `bindGroupLayout` をベースにレイアウトを生成します。 + +```js +const computePipeline = device.createComputePipeline({ + layout: device.createPipelineLayout({ + bindGroupLayouts: [bindGroupLayout], + }), + compute: { + module: shaderModule, + entryPoint: "main", + }, +}); +``` + +ここでのレンダーパイプラインのレイアウトとの違いの一つは、何も描画を行わないので、プリミティブの種類を指定していないことです。 + +### コンピュートパスの実行 + +コンピュートパスの実行はレンダリングパスの実行と構造は似ており、別のコマンドを用います。まず、{{domxref("GPUCommandEncoder.beginComputePass()")}} によりパスエンコーダーを生成します。 + +コマンドの発行には、以前と同様に {{domxref("GPUComputePassEncoder.setPipeline()")}} を用いてパイプラインを指定します。しかし、その後は、{{domxref("GPUComputePassEncoder.setBindGroup()")}} を用いて計算に用いるデータの指定に `bindGroup` を用いることを指定し、{{domxref("GPUComputePassEncoder.dispatchWorkgroups()")}} を用いて計算の実行に用いる GPU ワークグループの数を指定します。 + +そして、{{domxref("GPURenderPassEncoder.end()")}} を用いてレンダーパスのコマンドリストの終端を示します。 + +```js +passEncoder.setPipeline(computePipeline); +passEncoder.setBindGroup(0, bindGroup); +passEncoder.dispatchWorkgroups(Math.ceil(BUFFER_SIZE / 64)); + +passEncoder.end(); +``` + +### 結果を JavaScript で読み取る + +{{domxref("GPUQueue.submit()")}} を用いてエンコードされたコマンドを実行用に GPU に送信する前に、{{domxref("GPUCommandEncoder.copyBufferToBuffer()")}} を用いて `output` バッファーの中身を `stagingBuffer` バッファーにコピーします。 + +```js +// 出力バッファーをステージングバッファーにコピーする +commandEncoder.copyBufferToBuffer( + output, + 0, // コピー元のオフセット + stagingBuffer, + 0, // コピー先のオフセット + BUFFER_SIZE, +); + +// コマンドバッファーの配列を実行用のコマンドキューに渡し、フレームを終える +device.queue.submit([commandEncoder.finish()]); +``` + +出力データが `stagingBuffer` で参照可能になったら、{{domxref("GPUBuffer.mapAsync()")}} メソッドを用いてデータを中間メモリーにマップし、{{domxref("GPUBuffer.getMappedRange()")}} を用いてマップされた範囲への参照を取得し、データを JavaScript にコピーし、コンソールに記録します。さらに、処理が完了したら `stagingBuffer` のマップを解除します。 + +```js +// JS に結果を読み戻すため、ステージングバッファーをマップする +await stagingBuffer.mapAsync( + GPUMapMode.READ, + 0, // オフセット + BUFFER_SIZE, // サイズ +); + +const copyArrayBuffer = stagingBuffer.getMappedRange(0, BUFFER_SIZE); +const data = copyArrayBuffer.slice(); +stagingBuffer.unmap(); +console.log(new Float32Array(data)); +``` + +## GPU エラーの処理 + +WebGPU の呼び出しは、GPU 処理の中で非同期で検証されます。エラーが検出された場合は、プログラムの呼び出しが GPU 側で無効とマークされます。無効になった呼び出しの返り値に依存する他の呼び出しが行われた場合は、このオブジェクトも無効とマークされ、その先も同様です。このため、WebGPU におけるエラーは「感染性」といわれます。 + +それぞれの {{domxref("GPUDevice")}} のインスタンスは、各自のエラースコープスタックを管理します。このスタックは最初は空で、特定の種類のエラーをキャプチャするため {{domxref("GPUDevice.pushErrorScope()")}} を呼び出してスタックにエラースコープをプッシュできます。 + +エラーのキャプチャが完了したら、{{domxref("GPUDevice.popErrorScope()")}} を呼び出すことでキャプチャを終了できます。これは、スタックからスコープをポップし、スコープで最初にキャプチャされたエラーを表現するオブジェクト ({{domxref("GPUInternalError")}} または {{domxref("GPUOutOfMemoryError")}} または {{domxref("GPUValidationError")}}) か、エラーがキャプチャされていない場合は `null` で解決する {{jsxref("Promise")}} を返します。 + +適する場合は、WebGPU のコードでなぜエラーが発生しているのかを理解する助けとなる有用な情報を「バリデーション」節で提供することを試みました。この節では、エラーを回避するために満たすべき基準を列挙しています。例として、[`GPUDevice.createBindGroup()` のバリデーション節](/ja/docs/Web/API/GPUDevice/createBindGroup#バリデーション)を参照してください。この情報には複雑なものもあります。仕様を繰り返すのではなく、以下の性質を持つエラーの基準のみを列挙することにしました。 + +- 明らかではないもの。たとえば、バリデーションエラーを発生させるディスクリプタープロパティの組み合わせです。正しいディスクリプターオブジェクトの構造を確実に使うよう言うのは意味がありません。これは明らかであり、あいまいです。 +- 開発者が制御できるもの。エラーの基準のいくつかは内部のみに基づき、ウェブ開発者には関係ありません。 + +explainer で、WebGPU のエラー処理についての詳細情報を得ることができます。[Object validity and destroyed-ness](https://gpuweb.github.io/gpuweb/explainer/#invalid-and-destroyed) および [Errors](https://gpuweb.github.io/gpuweb/explainer/#errors) を参照してください。[WebGPU Error Handling best practices](https://toji.dev/webgpu-best-practices/error-handling) には有用な実世界での例やアドバイスがあります。 + +> **メモ:** WebGL でエラーを処理する歴史上の方法は、エラーの情報を返す {{domxref("WebGLRenderingContext.getError", "getError()")}} メソッドを提供することです。これはエラーを同期式で返し、効率がよくないという問題があります。これを呼び出すごとに GPU との往復のやりとりを行い、これまで発行した処理がすべて完了するまで待つ必要があります。さらに、状態モデルはフラット、すなわち関係ないコードの間でエラーが漏れる可能性があります。WebGPU の作者はこれらの点を改善することにしました。 + +## インターフェイス + +### API のエントリーポイント + +- {{domxref("Navigator.gpu")}} / {{domxref("WorkerNavigator.gpu")}} + - : この API のエントリーポイントです。現在のコンテキスト用の {{domxref("GPU")}} オブジェクトを返します。 +- {{domxref("GPU")}} + - : WebGPU を用いるための出発点です。{{domxref("GPUAdapter")}} を得るのに用いることができます。 +- {{domxref("GPUAdapter")}} + - : GPU アダプターを表します。これを用いて {{domxref("GPUDevice")}}、アダプターの情報、機能、制限を要求できます。 +- {{domxref("GPUAdapterInfo")}} + - : アダプターについての特定用の情報を保持します。 + +### GPU デバイスの設定 + +- {{domxref("GPUDevice")}} + - : 論理 GPU デバイスを表します。これは WebGPU の機能の大半へのアクセスに用いるメインインターフェイスです。 +- {{domxref("GPUSupportedFeatures")}} + - : {{domxref("GPUAdapter")}} や {{domxref("GPUDevice")}} が対応している追加の機能を表す [Set 風](/ja/docs/Web/JavaScript/Reference/Global_Objects/Set)オブジェクトです。 +- {{domxref("GPUSupportedLimits")}} + - : {{domxref("GPUAdapter")}} や {{domxref("GPUDevice")}} が対応している制限を表します。 + +### 描画を行う `` の設定 + +- {{domxref("HTMLCanvasElement.getContext()")}} — `"webgpu"` `contextType` + - : `"webgpu"` `contextType` を指定して `getContext()` を呼び出すと、{{domxref("GPUCanvasContext")}} オブジェクトのインスタンスを返します。これは、{{domxref("GPUCanvasContext.configure()")}} を用いて設定できます。 +- {{domxref("GPUCanvasContext")}} + - : {{htmlelement("canvas")}} 要素の WebGPU レンダリングコンテキストを表します。 + +### パイプラインリソースの表現 + +- {{domxref("GPUBuffer")}} + - : GPU での処理で用いる生データを格納できるメモリーのブロックを表します。 +- {{domxref("GPUExternalTexture")}} + - : GPU でのレンダリング処理でテクスチャーとして用いることができる {{domxref("HTMLVideoElement")}} のスナップショットが格納されたラッパーオブジェクトです。 +- {{domxref("GPUSampler")}} + - : シェーダーがテクスチャーのリソースデータの変換やフィルターを行う方法を制御します。 +- {{domxref("GPUShaderModule")}} + - : 内部のシェーダーモジュールオブジェクトへの参照で、パイプラインにより実行用に GPU に送信できる WGSL のシェーダーコードのコンテナーです。 +- {{domxref("GPUTexture")}} + - : GPU でのレンダリング処理で使用する用の、画像などの 1 次元、2 次元、または 3 次元のデータの配列を格納するのに用いるコンテナーです。 +- {{domxref("GPUTextureView")}} + - : 特定の {{domxref("GPUTexture")}} で定義された、テクスチャーのサブリソースの部分のビューです。 + +### パイプラインの表現 + +- {{domxref("GPUBindGroup")}} + - : {{domxref("GPUBindGroupLayout")}} に基づき、`GPUBindGroup` はグループで一緒にバインドされるリソースの集合と、これらのリソースのシェーダーステージでの利用法を定義します。 +- {{domxref("GPUBindGroupLayout")}} + - : パイプラインで用いられるバッファーなどの関連する GPU リソースの構造と目的を定義し、{{domxref("GPUBindGroup")}} を生成する際のテンプレートとして用いられます。 +- {{domxref("GPUComputePipeline")}} + - : コンピュートシェーダーステージを制御し、{{domxref("GPUComputePassEncoder")}} で使用できます。 +- {{domxref("GPUPipelineLayout")}} + - : パイプラインで用いる {{domxref("GPUBindGroupLayout")}} を定義します。コマンドのエンコード時にパイプラインとともに用いる {{domxref("GPUBindGroup")}} は、互換性がある {{domxref("GPUBindGroupLayout")}} を持っている必要があります。 +- {{domxref("GPURenderPipeline")}} + - : バーテックスシェーダーステージとフラグメントシェーダーステージを制御し、{{domxref("GPURenderPassEncoder")}} や {{domxref("GPURenderBundleEncoder")}} で使用できます。 + +### コマンドのエンコードと GPU への送信 + +- {{domxref("GPUCommandBuffer")}} + - : 実行用に {{domxref("GPUQueue")}} に送信できる、記録した GPU コマンドのリストを表します。 +- {{domxref("GPUCommandEncoder")}} + - : コマンドエンコーダーを表します。GPU に発行するコマンドのエンコードに使用します。 +- {{domxref("GPUComputePassEncoder")}} + - : {{domxref("GPUComputePipeline")}} が発行し、コンピュートシェーダーステージの制御に関するコマンドをエンコードします。{{domxref("GPUCommandEncoder")}} による全体のエンコード処理の一部です。 +- {{domxref("GPUQueue")}} + - : GPU でのエンコードされたコマンドの実行を制御します。 +- {{domxref("GPURenderBundle")}} + - : 事前に記録されたコマンド群のバンドル用のコンテナーです。({{domxref("GPURenderBundleEncoder")}} を参照してください) +- {{domxref("GPURenderBundleEncoder")}} + - : コマンド群のバンドルを事前に記録するのに使用します。これらは、必要に応じて何度でも、{{domxref("GPURenderPassEncoder.executeBundles", "executeBundles()")}} メソッドにより {{domxref("GPURenderPassEncoder")}} で再利用できます。 +- {{domxref("GPURenderPassEncoder")}} + - : {{domxref("GPURenderPipeline")}} が発行し、バーテックスシェーダーステージとフラグメントシェーダーステージの制御に関するコマンドをエンコードします。{{domxref("GPUCommandEncoder")}} による全体のエンコード処理の一部です。 + +### レンダリングパスにおけるクエリーの実行 + +- {{domxref("GPUQuerySet")}} + - : オクルージョンやタイムスタンプのクエリーなど、パスにおけるクエリーの結果の記録に用います。 + +### エラーのデバッグ + +- {{domxref("GPUCompilationInfo")}} + - : {{domxref("GPUCompilationMessage")}} オブジェクトの配列です。シェーダーコードの問題の診断を助けるため、GPU シェーダーモジュールコンパイラーにより生成されます。 +- {{domxref("GPUCompilationMessage")}} + - : GPU シェーダーモジュールコンパイラーが生成した、1 個の情報、警告、もしくはエラーのメッセージを表します。 +- {{domxref("GPUDeviceLostInfo")}} + - : {{domxref("GPUDevice.lost")}} {{jsxref("Promise")}} が解決する際に返され、デバイスがロストした原因の情報を提供します。 +- {{domxref("GPUError")}} + - : {{domxref("GPUDevice.popErrorScope")}} および {{domxref("GPUDevice.uncapturederror_event", "uncapturederror")}} イベントで浮かび上がったエラー用のベースインターフェイスです。 +- {{domxref("GPUInternalError")}} + - : {{domxref("GPUDevice.popErrorScope")}} および {{domxref("GPUDevice")}} {{domxref("GPUDevice.uncapturederror_event", "uncapturederror")}} イベントで浮かび上がったエラーの型の一つです。バリデーションの要求がすべて満たされたにもかかわらずシステムまたは実装に固有の理由で処理に失敗したことを表します。 +- {{domxref("GPUOutOfMemoryError")}} + - : {{domxref("GPUDevice.popErrorScope")}} および {{domxref("GPUDevice")}} {{domxref("GPUDevice.uncapturederror_event", "uncapturederror")}} イベントで浮かび上がったエラーの型の一つです。要求された処理を完了するのに十分な空きメモリが無かったことを表します。 +- {{domxref("GPUPipelineError")}} + - : パイプラインの失敗を表現します。この値は {{domxref("GPUDevice.createComputePipelineAsync()")}} や {{domxref("GPUDevice.createRenderPipelineAsync()")}} から返された {{jsxref("Promise")}} が拒否されたとき渡されます。 +- {{domxref("GPUUncapturedErrorEvent")}} + - : {{domxref("GPUDevice")}} {{domxref("GPUDevice.uncapturederror_event", "uncapturederror")}} イベント用のイベントオブジェクトの型です。 +- {{domxref("GPUValidationError")}} + - : {{domxref("GPUDevice.popErrorScope")}} および {{domxref("GPUDevice")}} {{domxref("GPUDevice.uncapturederror_event", "uncapturederror")}} イベントで浮かび上がったエラーの型の一つです。操作が WebGPU API のバリデーションの制約を満たさなかったことを表すアプリケーションエラーを表現します。 + +## セキュリティの要件 + +この API 全体は[安全なコンテキスト](/ja/docs/Web/Security/Secure_Contexts)でのみ利用可能です。 + +## 例 + +- [計算基本デモ](https://mdn.github.io/dom-examples/webgpu-compute-demo/) +- [レンダリング基本デモ](https://mdn.github.io/dom-examples/webgpu-render-demo/) +- [WebGPU samples](https://webgpu.github.io/webgpu-samples/) + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [WebGPU best practices](https://toji.dev/webgpu-best-practices/) +- [WebGPU explainer](https://gpuweb.github.io/gpuweb/explainer) +- [WebGPU — All of the cores, none of the canvas](https://surma.dev/things/webgpu/) diff --git a/files/ja/web/api/workernavigator/globalprivacycontrol/index.md b/files/ja/web/api/workernavigator/globalprivacycontrol/index.md new file mode 100644 index 00000000000000..96e2577763d177 --- /dev/null +++ b/files/ja/web/api/workernavigator/globalprivacycontrol/index.md @@ -0,0 +1,40 @@ +--- +title: "WorkerNavigator: globalPrivacyControl プロパティ" +slug: Web/API/WorkerNavigator/globalPrivacyControl +l10n: + sourceCommit: 5ec94e56259b839211f1adc63f06c66f94865993 +--- + +{{APIRef("DOM")}}{{SeeCompatTable}} + +読み取り専用プロパティ **`WorkerNavigator.globalPrivacyControl`** は、ユーザーの現在のウェブサイト用の Global Privacy Control 設定を返します。 +この設定は、ウェブサイトやサービスがユーザーの個人情報を第三者に販売したり共有したりすることにユーザーが同意しているかを示します。 + +このプロパティの値は、{{httpheader("Sec-GPC")}} HTTP ヘッダーの値を反映します。 + +## 値 + +ユーザーが明示的にデータの販売や共有に同意 _しない_ ときは `true` です。 +ユーザーが同意しているか、希望を示していないときは `false` です。 + +## 例 + +```js +console.log(navigator.globalPrivacyControl); +// ユーザーが特にデータを共有したり販売したりされたくないと示しているとき "true"、そうでないとき "false" です。 +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{HTTPHeader("Sec-GPC")}} ヘッダー +- [globalprivacycontrol.org](https://globalprivacycontrol.org/) +- [Global Privacy Control Spec](https://privacycg.github.io/gpc-spec/) +- [Do Not Track on Wikipedia](https://en.wikipedia.org/wiki/Do_Not_Track) diff --git a/files/ja/web/api/workernavigator/gpu/index.md b/files/ja/web/api/workernavigator/gpu/index.md new file mode 100644 index 00000000000000..76cb27d804d207 --- /dev/null +++ b/files/ja/web/api/workernavigator/gpu/index.md @@ -0,0 +1,46 @@ +--- +title: "WorkerNavigator: gpu プロパティ" +slug: Web/API/WorkerNavigator/gpu +l10n: + sourceCommit: cc070123f72376faec06e36622c4fc723a75325f +--- + +{{APIRef("Web Workers API")}}{{SeeCompatTable}} + +{{domxref("WorkerNavigator")}} インターフェイスの読み取り専用プロパティ **`gpu`** は、現在のワーカーコンテキスト用の {{domxref("GPU")}} オブジェクトを返します。これは {{domxref("WebGPU_API", "WebGPU API", "", "nocode")}} のエントリーポイントです。 + +## 値 + +{{domxref("GPU")}} オブジェクトです。 + +## 例 + +```js +// ウェブワーカーの内部で実行できます +async function init() { + if (!navigator.gpu) { + throw Error("WebGPU に対応していません。"); + } + + const adapter = await navigator.gpu.requestAdapter(); + if (!adapter) { + throw Error("WebGPU アダプターを要求できませんでした。"); + } + + const device = await adapter.requestDevice(); + + //... +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("WebGPU_API", "WebGPU API", "", "nocode")}} diff --git a/files/ja/web/api/workernavigator/index.md b/files/ja/web/api/workernavigator/index.md index e1c0b17eb14df1..574f23151d6d1f 100644 --- a/files/ja/web/api/workernavigator/index.md +++ b/files/ja/web/api/workernavigator/index.md @@ -21,6 +21,10 @@ _`WorkerNavigator` インターフェイスは何もプロパティを継承し - : ブラウザー のバージョンを文字列で返します。このプロパティが正しい値を返すことに頼らないでください。 - {{DOMxRef("WorkerNavigator.connection")}} {{ReadOnlyInline}} - : 端末のネットワーク接続に関する情報を格納した {{DOMxRef("NetworkInformation")}} オブジェクトを提供します。 +- {{domxref("WorkerNavigator.globalPrivacyControl")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : ユーザーの情報の共有や販売への同意状況を表す論理値を返します。 +- {{domxref("WorkerNavigator.gpu")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : 現在のワーカーコンテキスト用の {{domxref("GPU")}} オブジェクトを返します。{{domxref("WebGPU_API", "WebGPU API", "", "nocode")}} のエントリーポイントです。 - {{DOMxRef("WorkerNavigator.hardwareConcurrency")}} {{ReadOnlyInline}} - : 利用可能な論理プロセッサーコアの数を返します。 - {{DOMxRef("WorkerNavigator.language")}} {{ReadOnlyInline}} @@ -29,6 +33,8 @@ _`WorkerNavigator` インターフェイスは何もプロパティを継承し - : ユーザーが知っている言語を、環境設定の順に文字列の配列で返します。 - {{DOMxRef("WorkerNavigator.locks")}} {{ReadOnlyInline}} - : 新しい {{DOMxRef("LockManager")}} オブジェクトをリクエストしたり、既存の {{DOMxRef('Lock')}} オブジェクトを問い合わせるためのメソッドを提供する `Lock` オブジェクトを返します。 +- {{DOMxRef("WorkerNavigator.mediaCapabilities")}} {{ReadOnlyInline}} + - : 指定の形式のデコードおよびエンコードの能力と、出力の能力に関する情報を参照可能にする {{domxref("MediaCapabilities")}} オブジェクトを返します。 - {{DOMxRef("WorkerNavigator.onLine")}} {{ReadOnlyInline}} - : ブラウザーがオンラインであるかどうかを示す論理値を返します。 - {{DOMxRef("WorkerNavigator.permissions")}} {{Experimental_Inline}} {{ReadOnlyInline}} diff --git a/files/ja/web/api/workernavigator/mediacapabilities/index.md b/files/ja/web/api/workernavigator/mediacapabilities/index.md new file mode 100644 index 00000000000000..da7e9b30252f26 --- /dev/null +++ b/files/ja/web/api/workernavigator/mediacapabilities/index.md @@ -0,0 +1,47 @@ +--- +title: "WorkerNavigator: mediaCapabilities プロパティ" +slug: Web/API/WorkerNavigator/mediaCapabilities +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc +--- + +{{APIRef("HTML DOM")}} + +読み取り専用プロパティ **`WorkerNavigator.mediaCapabilities`** は、[Media Capabilities API](/ja/docs/Web/API/Media_Capabilities_API) における定義に沿って、指定の形式のデコードやエンコードの能力、および出力の能力に関する情報へのアクセスを可能にする {{domxref("MediaCapabilities")}} オブジェクトを返します。 + +## 値 + +{{domxref("MediaCapabilities")}} オブジェクトです。 + +## 例 + +```js +navigator.mediaCapabilities + .decodingInfo({ + type: "file", + audio: { + contentType: "audio/mp3", + channels: 2, + bitrate: 132700, + samplerate: 5200, + }, + }) + .then((result) => { + console.log(`この構成に対応していま${result.supported ? "す" : "せん"}。`); + console.log(`スムーズ${result.smooth ? "" : "じゃない"}です。`); + console.log(`電力効率がよ${result.powerEfficient ? "" : "くな"}いです。`); + }); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [Media Capabilities API](/ja/docs/Web/API/Media_Capabilities_API) +- {{domxref("WorkerNavigator")}} diff --git a/files/ja/web/css/_doublecolon_view-transition-old/index.md b/files/ja/web/css/_doublecolon_view-transition-old/index.md new file mode 100644 index 00000000000000..095ece0ef0169e --- /dev/null +++ b/files/ja/web/css/_doublecolon_view-transition-old/index.md @@ -0,0 +1,109 @@ +--- +title: "::view-transition-old" +slug: Web/CSS/::view-transition-old +l10n: + sourceCommit: c9cc38c3c3c342e2e952c1acd57f55e104c5bb06 +--- + +{{CSSRef}}{{SeeCompatTable}} + +**`::view-transition-old`** は [CSS](/ja/docs/Web/CSS) の[擬似要素](/ja/docs/Web/CSS/Pseudo-elements)で、ビュートランジションの「古い」ビュー状態、すなわちトランジション前の古いビューの静的なスクリーンショットを表します。 + +ビュートランジションの間、 `::view-transition-old` は[ビュートランジションのプロセス](/ja/docs/Web/API/View_Transitions_API#ビュートランジションのプロセス)で説明されているように、関連する擬似要素ツリーに記載されます。これは {{cssxref("::view-transition-image-pair")}} の子要素でしかなく、子要素を持つことはありません。 + +これは置換要素であり、 {{cssxref("object-fit")}} や {{cssxref("object-position")}} などのプロパティで操作できます。コンテンツのサイズに等しい自然な寸法を持ちます。 + +UA スタイルシートでは以下の既定値が指定されています。 + +```css +@keyframes -ua-view-transition-fade-out { + to { + opacity: 0; + } +} + +html::view-transition-old(*) { + position: absolute; + inset-block-start: 0; + inline-size: 100%; + block-size: auto; + + animation-name: -ua-view-transition-fade-out; + animation-duration: inherit; + animation-fill-mode: inherit; +} +``` + +> **メモ:** `::view-transition-old` のアニメーションを設定するために、追加のビュートランジションスタイルシートスタイルも設定されます。これらはビュートランジション中に動的に生成されます。詳細は仕様書の [setup transition pseudo-elements](https://drafts.csswg.org/css-view-transitions-1/#setup-transition-pseudo-elements) および [update pseudo-element styles](https://drafts.csswg.org/css-view-transitions-1/#update-pseudo-element-styles) の節を参照してください。 + +## 構文 + +```css-nolint +::view-transition-old() { + /* ... */ +} +``` + +`` は以下の値のうちのいずれかです。 + +- `*` + - : 擬似要素が、すべてのビュートランジショングループに一致するようにします。 +- `root` + - : 擬似要素が、ページ全体のビュートランジションを含むためにユーザエージェントによって作成された既定の `root` ビュートランジショングループに一致するようにします。すなわち、 {{cssxref("view-transition-name")}} プロパティによって自分自身を固有のビュートランジショングループに割り当てていない要素を意味します）。 +- {{cssxref("custom-ident")}} + - : 擬似要素が、指定された {{cssxref("custom-ident")}} を {{cssxref("view-transition-name")}} プロパティを通して要素に割り当てることによって作成された固有のビュートランジショングループに一致するようにします。 + +## 例 + +```css +figcaption { + view-transition-name: figure-caption; +} + +@keyframes grow-x { + from { + transform: scaleX(0); + } + to { + transform: scaleX(1); + } +} + +@keyframes shrink-x { + from { + transform: scaleX(1); + } + to { + transform: scaleX(0); + } +} + +::view-transition-old(figure-caption), +::view-transition-new(figure-caption) { + height: auto; + right: 0; + left: auto; + transform-origin: right center; +} + +::view-transition-old(figure-caption) { + animation: 0.25s linear both shrink-x; +} + +::view-transition-new(figure-caption) { + animation: 0.25s 0.25s linear both grow-x; +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュートランジション API](/ja/docs/Web/API/View_Transitions_API) +- [ビュートランジション API によるスムーズでシンプルなトランジション](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/css/_doublecolon_view-transition/index.md b/files/ja/web/css/_doublecolon_view-transition/index.md new file mode 100644 index 00000000000000..d208c883fa4bd9 --- /dev/null +++ b/files/ja/web/css/_doublecolon_view-transition/index.md @@ -0,0 +1,52 @@ +--- +title: "::view-transition" +slug: Web/CSS/::view-transition +l10n: + sourceCommit: 1a27ade8c981c8a98c8fac9881b362e881a4d236 +--- + +{{CSSRef}}{{SeeCompatTable}} + +**`::view-transition`** は [CSS](/ja/docs/Web/CSS) の[擬似要素](/ja/docs/Web/CSS/Pseudo-elements)で、[ビュートランジション](/ja/docs/Web/API/View_Transitions_API)のオーバーレイのルートを表します。これはすべてのビュートランジションを含み、他のすべてのページコンテンツの最上位の上に位置します。 + +ビュートランジションの間、 `::view-transition` は[ビュートランジションのプロセス](/ja/docs/Web/API/View_Transitions_API#the_view_transition_process)で説明されているように、関連する擬似要素ツリーに含まれます。これはこのツリーの最上位ノードであり、 1 つ以上の {{cssxref("::view-transition-group")}} を子として持ちます。 + +`::view-transition` は UA スタイルシートでは以下の既定値が指定されています。 + +```css +html::view-transition { + position: fixed; + inset: 0; +} +``` + +すべての {{cssxref("::view-transition-group")}} 擬似要素は、ビュートランジションルートに対して相対的に配置されます。 + +## 構文 + +```css +::view-transition { + /* ... */ +} +``` + +## 例 + +```css +::view-transition { + background-color: rgba(0, 0, 0, 0.25); +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュートランジション API](/ja/docs/Web/API/View_Transitions_API) +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/css/view-transition-name/index.md b/files/ja/web/css/view-transition-name/index.md new file mode 100644 index 00000000000000..8169522d4d7977 --- /dev/null +++ b/files/ja/web/css/view-transition-name/index.md @@ -0,0 +1,57 @@ +--- +title: view-transition-name +slug: Web/CSS/view-transition-name +l10n: + sourceCommit: 1a27ade8c981c8a98c8fac9881b362e881a4d236 +--- + +{{CSSRef}}{{SeeCompatTable}} + +**`view-transition-name`** は [CSS](/ja/docs/Web/CSS) のプロパティで、選択された要素に識別名 ({{cssxref("custom-ident")}}) を与え、ルートビュートランジションとは別の[ビュートランジション](/ja/docs/Web/API/View_Transitions_API)に参加させます。 `none` の値が指定された場合はビュートランジションを行いません。 + +## 構文 + +```css +/* 値の例 */ +view-transition-name: header; +view-transition-name: figure-caption; + +/* キーワード値 */ +view-transition-name: none; +``` + +### 値 + +- {{cssxref("custom-ident")}} + - : 選択した要素を、ルートビュートランジションとは別の[ビュートランジション](/ja/docs/Web/API/View_Transitions_API)に参加させるための識別名です。識別子は一意でなければなりません。 2 つのレンダリング要素が同時に同じ `view-transition-name` を持つ場合、 {{domxref("ViewTransition.ready")}} は拒否され、トランジションはスキップされます。 +- `none` + - : 選択された要素はビュートランジションに参加しません。 + +## 公式定義 + +{{cssinfo}} + +## 形式文法 + +{{csssyntax}} + +## 例 + +```css +figcaption { + view-transition-name: figure-caption; +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュートランジション API](/ja/docs/Web/API/View_Transitions_API) +- [Smooth and simple transitions with the View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions/) diff --git a/files/ja/web/html/attributes/pattern/index.md b/files/ja/web/html/attributes/pattern/index.md index 9a4c7d4e1fe003..95a82ca4e38437 100644 --- a/files/ja/web/html/attributes/pattern/index.md +++ b/files/ja/web/html/attributes/pattern/index.md @@ -15,7 +15,7 @@ l10n: `pattern` 属性は {{HTMLElement("input/text", "text")}}, {{HTMLElement("input/tel", "tel")}}, {{HTMLElement("input/email", "email")}}, {{HTMLElement("input/url", "url")}}, {{HTMLElement("input/password", "password")}}, {{HTMLElement("input/search", "search")}} の入力型の属性です。 -`pattern` 属性は、[制約検証](/ja/docs/Web/HTML/Constraint_validation)を通過させるために、入力の {{htmlattrxref("value")}} が一致するべき正規表現です。これは有効な JavaScript の正規表現でなければならず、 {{jsxref("RegExp")}} 型で使用されたり、[正規表現ガイド](/ja/docs/Web/JavaScript/Guide/Regular_Expressions)で説明されているものと同じものです。正規表現をコンパイルする際に `'u'` フラグが指定されるので、パターンが ASCII ではなく Unicode コードポイントの並びとして扱われるようになります。パターンテキストの周りには、スラッシュを指定してはいけません。 +`pattern` 属性は、[制約検証](/ja/docs/Web/HTML/Constraint_validation)を通過させるために、入力の [`value`](/ja/docs/Web/HTML/Element/input#value) が一致するべき正規表現です。これは有効な JavaScript の正規表現でなければならず、 {{jsxref("RegExp")}} 型で使用されたり、[正規表現ガイド](/ja/docs/Web/JavaScript/Guide/Regular_Expressions)で説明されているものと同じものです。正規表現をコンパイルする際に `'u'` フラグが指定されるので、パターンが ASCII ではなく Unicode コードポイントの並びとして扱われるようになります。パターンテキストの周りには、スラッシュを指定してはいけません。 パターンが指定されていないか無効な場合、正規表現は適用されず、この属性は無視されます。 @@ -85,7 +85,7 @@ input:invalid { ### パターンの指定 -{{htmlattrxref("pattern", "input")}} 属性を使用すると、入力された値が有効とみなされるために一致しなければならない正規表現を指定することができます（正規表現を使用して入力を検証する簡単な集中講座は、[正規表現での検証](/ja/docs/Learn/Forms/Form_validation#正規表現での検証)を参照してください）。 +[`pattern`](/ja/docs/Web/HTML/Element/input#pattern) 属性を使用すると、入力された値が有効とみなされるために一致しなければならない正規表現を指定することができます（正規表現を使用して入力を検証する簡単な集中講座は、[正規表現での検証](/ja/docs/Learn/Forms/Form_validation#正規表現での検証)を参照してください）。 以下の例では、値を 4-8 文字に制限し、小文字のみを含むことを要求しています。 diff --git a/files/ja/web/html/element/details/index.md b/files/ja/web/html/element/details/index.md index 0d70f1d09d1e7b..de616284b4c38b 100644 --- a/files/ja/web/html/element/details/index.md +++ b/files/ja/web/html/element/details/index.md @@ -13,7 +13,7 @@ slug: Web/HTML/Element/details `
` ウィジェットは 2 つの状態のうち 1 つを取ります。既定の*閉じた*状態は `` を使用して指定されたラベル文字列（または `` がない場合は{{Glossary("user agent", "ユーザーエージェント")}}が定義した既定の文字列）とウィジェット自身による三角形だけを表示します。 -ユーザーがウィジェットをクリックするか、フォーカスしてスペースバーを押すと、ウィジェットは「ツイスト」して開き、中身が見えるようになります。ウィジェットの開閉を表すために、回転したりねじれたりする三角形を使用することが多いため、「ツイスティ」 (twisty) と呼ばれることもある。 +ユーザーがウィジェットをクリックするか、フォーカスしてスペースバーを押すと、ウィジェットは「ツイスト」して開き、中身が見えるようになります。ウィジェットの開閉を表すために、回転したりねじれたりする三角形を使用することが多いため、「ツイスティ」 (twisty) と呼ばれることもあります。 CSS を使用して折り畳みウィジェットのスタイルを設定することができます。また、 [`open`](open) 属性を設定したり削除したりすることによって、プログラムによってウィジェットを開いたり閉じたりすることも可能です。残念ながら、現時点では、開閉の遷移をアニメーションで表現する方法は組み込まれていません。 diff --git a/files/ja/web/http/redirections/index.md b/files/ja/web/http/redirections/index.md index 049bca1c87cbb7..334f3fcb347211 100644 --- a/files/ja/web/http/redirections/index.md +++ b/files/ja/web/http/redirections/index.md @@ -32,10 +32,10 @@ HTTP では、リダイレクトはリクエストに対して、サーバーが これらのリダイレクトは永遠に続くことを意味します。これらのリダイレクトは、元の URL はもう使用されず、新しいものに置き換えるべきであることを示しています。検索エンジンのロボット、 RSS リーダー、および他のクローラーは、リソースの元の URL を更新します。 -| コード | テキスト | メソッドの扱い | 主な使用例 | -| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| コード | テキスト | メソッドの扱い | 主な使用例 | +| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `301` | `Moved Permanently` | {{HTTPMethod("GET")}} メソッドは変更しません。 他のメソッドは {{HTTPMethod("GET")}} に変更されるかもしれません。[1] | ウェブサイトの再編。 | -| `308` | `Permanent Redirect` | メソッドや本文は変更しません。 | GET 以外のリンクや操作を含むウェブサイトの再編。 | +| `308` | `Permanent Redirect` | メソッドや本文は変更しません。 | GET 以外のリンクや操作を含むウェブサイトの再編。 | \[1] 仕様書ではメソッドの変更を意図していませんが、メソッドを変更するユーザーエージェントが存在します。 {{HTTPStatus("308")}} が定義されたのは、 `GET` 以外のメソッドを使用するときの動作のあいまいさをなくすためです。 @@ -45,11 +45,11 @@ HTTP では、リダイレクトはリクエストに対して、サーバーが 検索エンジンのロボットは、新たな一時的 URL を記録しません。一時的リダイレクトは、リソースを作成、更新、削除しているときに一時的な進捗ページを提供するためにも利用されます。 -| コード | テキスト | メソッドの扱い | 主な使用例 | -| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| コード | テキスト | メソッドの扱い | 主な使用例 | +| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `302` | `Found` | {{HTTPMethod("GET")}} メソッドは変更しません。 他のメソッドは {{HTTPMethod("GET")}} に変更されるかもしれません。[2] | ウェブページは不測の理由により、一時的に利用できない状態です。 | -| `303` | `See Other` | {{HTTPMethod("GET")}} メソッドは変更しません。 他のメソッドは `GET` に*変更します* (本文は失われます)。 | ページの再読み込みによって操作が再度実施されることを防ぐために、{{HTTPMethod("PUT")}} や {{HTTPMethod("POST")}} の後のリダイレクトで使用します。 | -| `307` | `Temporary Redirect` | メソッドと本文は変更しません。 | ウェブページは不測の理由により、一時的に使用できない状態です。検索エンジンは自身のリンクを更新しません。 `302` と比較して、サイトで `GET` 以外の操作を使用できる場合に推奨されます。 | +| `303` | `See Other` | {{HTTPMethod("GET")}} メソッドは変更しません。 他のメソッドは `GET` に*変更します* (本文は失われます)。 | ページの再読み込みによって操作が再度実施されることを防ぐために、{{HTTPMethod("PUT")}} や {{HTTPMethod("POST")}} の後のリダイレクトで使用します。 | +| `307` | `Temporary Redirect` | メソッドと本文は変更しません。 | ウェブページは不測の理由により、一時的に使用できない状態です。検索エンジンは自身のリンクを更新しません。 `302` と比較して、サイトで `GET` 以外の操作を使用できる場合に推奨されます。 | \[2] 仕様書ではメソッドの変更を意図していませんが、実際はメソッドを変更するユーザーエージェントが存在します。`GET` 以外のメソッドを使用するときの動作のあいまいさをなくすために、 {{HTTPStatus("307")}} が定義されました。 diff --git a/files/ja/web/http/status/102/index.md b/files/ja/web/http/status/102/index.md new file mode 100644 index 00000000000000..72f2e72d600987 --- /dev/null +++ b/files/ja/web/http/status/102/index.md @@ -0,0 +1,29 @@ +--- +title: 102 Processing +slug: Web/HTTP/Status/102 +l10n: + sourceCommit: 592f6ec42e54981b6573b58ec0343c9aa8cbbda8 +--- + +{{HTTPSidebar}}{{deprecated_header}} + +HTTP **`102 Processing`** 情報ステータスレスポンスコードは、リクエスト全体が受信され、サーバーがそれを処理中であることをクライアントに示します。 + +このステータスコードは、リクエストの処理に長時間かかるとサーバーが判断した場合のみ送信されます。これは、クライアントにリクエストがまだ死んでいないことを伝えます。 + +> **メモ:** このステータスコードは非推奨になっており、もう送られるべきではありません。クライアントはまだ受け入れる可能性がありますが、単純に無視します。 + +## ステータス + +```plain +102 Processing +``` + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- {{HTTPHeader("Expect")}} +- {{HTTPStatus("100")}} diff --git a/files/ja/web/http/status/207/index.md b/files/ja/web/http/status/207/index.md new file mode 100644 index 00000000000000..9d3ef748e5af26 --- /dev/null +++ b/files/ja/web/http/status/207/index.md @@ -0,0 +1,66 @@ +--- +title: 207 Multi-Status +slug: Web/HTTP/Status/207 +l10n: + sourceCommit: 592f6ec42e54981b6573b58ec0343c9aa8cbbda8 +--- + +{{HTTPSidebar}} + +> **メモ:** _リソースのコレクション_ を返す機能は {{Glossary("WebDAV")}} プロトコルの一部です。(WebDAV サーバーにアクセスしているウェブアプリケーションが受信する可能性があります) ウェブページにアクセスしているブラウザーがこのステータスコードを受け取ることは無いでしょう。 + +HTTP **`207 Multi-Status`** レスポンスコードは、レスポンスが混ざっている可能性があることを示します。 + +レスポンスボディは `multistatus` ルート要素を持つ `text/xml` または `application/xml` の HTTP エンティティです。XML ボディですべての個別のレスポンスコードが列挙されます。 + +## ステータス + +```plain +207 Multi-Status +``` + +## 例 + +```http +HTTP/1.1 207 Multi-Status +Content-Type: application/xml; charset="utf-8" +Content-Length: 1241 + + + + + http://www.example.com/Coll/ + + + Loop Demo + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf8 + + + HTTP/1.1 200 OK + + + + http://www.example.com/Coll/Bar + + + Loop Demo + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf8 + + + HTTP/1.1 208 Already Reported + + + +``` + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- [HTTP リクエストメソッド](/ja/docs/Web/HTTP/Methods) +- {{HTTPStatus("204")}} +- {{HTTPStatus("403")}} diff --git a/files/ja/web/http/status/208/index.md b/files/ja/web/http/status/208/index.md new file mode 100644 index 00000000000000..d8454b4cf8b16d --- /dev/null +++ b/files/ja/web/http/status/208/index.md @@ -0,0 +1,76 @@ +--- +title: 208 Already Reported +slug: Web/HTTP/Status/208 +l10n: + sourceCommit: 592f6ec42e54981b6573b58ec0343c9aa8cbbda8 +--- + +{{HTTPSidebar}} + +> **メモ:** いくつかのパスにリソースを _バインド_ する機能は {{Glossary("WebDAV")}} プロトコルの拡張です。(WebDAV サーバーにアクセスしているウェブアプリケーションが受信する可能性があります) ウェブページにアクセスしているブラウザーがこのステータスコードを受け取ることは無いでしょう。 + +HTTP **`208 Already Reported`** レスポンスコードは、容量を節約し、競合を防ぐため、{{HTTPStatus("207")}} (`207 Multi-Status`) レスポンスで用いられます。 +同じリソースが (たとえばコレクションの一部として) 異なるパスで複数回要求された場合、最初のもののみ {{HTTPStatus("200")}} で報告されます。 +それ以外のすべてのバインディングへのレスポンスはこの `208` ステータスコードで報告されるので、競合を起こさず、レスポンスは短く保たれます。 + +## ステータス + +```plain +208 Already Reported +``` + +## 例 + +```http +HTTP/1.1 207 Multi-Status +Content-Type: application/xml; charset="utf-8" +Content-Length: 1241 + + + + + http://www.example.com/Coll/ + + + Loop Demo + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf8 + + + HTTP/1.1 200 OK + + + + http://www.example.com/Coll/Foo + + + Bird Inventory + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf9 + + + HTTP/1.1 200 OK + + + + http://www.example.com/Coll/Bar + + + Loop Demo + + urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf8 + + + HTTP/1.1 208 Already Reported + + + +``` + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- {{HTTPStatus("200")}} diff --git a/files/ja/web/http/status/226/index.md b/files/ja/web/http/status/226/index.md new file mode 100644 index 00000000000000..fbf351c878476d --- /dev/null +++ b/files/ja/web/http/status/226/index.md @@ -0,0 +1,26 @@ +--- +title: 226 IM Used +slug: Web/HTTP/Status/226 +l10n: + sourceCommit: 592f6ec42e54981b6573b58ec0343c9aa8cbbda8 +--- + +{{HTTPSidebar}} + +> **メモ:** ブラウザーは HTTP で _デルタエンコーディング_ に対応していません。このステータスコードは特定のクライアントで用いられるカスタムされたサーバーから送り返されます。 + +デルタエンコーディングの文脈において、HTTP **`226 IM Used`** ステータスコードは受信した {{HTTPMethod("GET")}} リクエストに対する _デルタ_ を返していることを示すためにサーバーによって設定されます。 + +デルタエンコーディングでは、サーバーは {{HTTPMethod("GET")}} リクエストに対して (現在のドキュメントではなく) 指定のベースドキュメントからの (_デルタ_ と呼ばれる) 違いで応答します。クライアントは `A-IM:` HTTP ヘッダーにより使用する差分アルゴリズムを示し、`If-None-Match:` ヘッダーで取得した最新バージョンに関するヒントをサーバーに与えます。サーバーはデルタを生成し、ステータスコードが `226` で、(使用したアルゴリズムの名前を伴う) `IM:` HTTP ヘッダーおよび (デルタに紐づくベースドキュメントに対応する {{HTTPHeader("ETag")}} を伴う) `Delta-Base:` HTTP ヘッダーが含まれる HTTP レスポンスで返します。 + +IM は _instance manipulations_ を表します。これは _デルタ_ の生成アルゴリズムを記述する際に用いられる用語です。 + +## ステータス + +```plain +226 IM Used +``` + +## 仕様書 + +{{Specifications}} diff --git a/files/ja/web/javascript/closures/index.md b/files/ja/web/javascript/closures/index.md index 7cd19b99cb8f6c..abae99ec640866 100644 --- a/files/ja/web/javascript/closures/index.md +++ b/files/ja/web/javascript/closures/index.md @@ -80,7 +80,7 @@ myFunc(); このコードが動作するということは直感的に理解できないかもしれません。いくつかのプログラミング言語では、関数内部のローカル変数はその関数が実行されている間だけ存在します。一旦 `makeFunc()` の実行が完了したら、name 変数はもう必要とされなくなると考えた方が筋は通っています。ただこのコードが期待したとおりに動くという事は、これは明らかに JavaScript にはあてはまりません。 -この理由は、JavaScript の関数はクロージャとなるためです。クロージャは関数とその関数が作られた環境という 2 つのものの組み合わせです。この環境は、クロージャが作られた時点でスコープ内部にあったあらゆる変数によって構成されています。この場合、`myFunc` は `makeFunc` が実行された時に作られた `displayName` 関数のインスタンスへの参照です。`displayName` のインスタンスはレキシカル環境への参照を保持し、そこに `name` 変数が存在します。このため、`makeFunc` が実行された時に、`name` 変数が残っていて "Mozilla" が `alert` に渡されます。 +この理由は、JavaScript の関数はクロージャとなるためです。クロージャは関数とその関数が作られた環境という 2 つのものの組み合わせです。この環境は、クロージャが作られた時点でスコープ内部にあったあらゆる変数によって構成されています。この場合、`myFunc` は `makeFunc` が実行された時に作られた `displayName` 関数のインスタンスへの参照です。`displayName` のインスタンスはレキシカル環境への参照を保持し、そこに `name` 変数が存在します。このため、`makeFunc` が実行された時に、`name` 変数が残っていて "Mozilla" が `console.log` に渡されます。 ここにもう少し面白い例があります。`makeAdder` 関数です。 diff --git a/files/ko/glossary/accessible_name/index.md b/files/ko/glossary/accessible_name/index.md new file mode 100644 index 00000000000000..fb98f1d7d2d416 --- /dev/null +++ b/files/ko/glossary/accessible_name/index.md @@ -0,0 +1,31 @@ +--- +title: 접근 가능한 이름 (Accessible name) +slug: Glossary/Accessible_name +l10n: + sourceCommit: 371bd494d2580e7f4f45f1934cfe8335bd3cc80e +--- + +**접근 가능한 이름(Accessible name)**은 사용자 인터페이스 요소의 이름입니다. 이는 보조 기술 사용자에게 요소에 대한 레이블을 제공하는 HTML 요소와 연관된 텍스트입니다. + +접근 가능한 이름은 요소의 목적이나 의도를 전달합니다. 이는 사용자가 요소의 용도와 요소와 상호 작용하는 방법을 이해하는 데 도움이 됩니다. 일반적으로, 요소의 접근 가능한 이름은 페이지마다 고유해야 합니다. 이를 통해 사용자는 특정 요소를 다른 요소와 구별하고 상호 작용하려는 요소를 식별하는 데 도움이 됩니다. + +요소와 HTML 마크업에 따라, 접근 가능한 이름의 값은 보이는 (예, {{HTMLElement("figcaption")}} 내의 텍스트) 또는 보이지 않는 (예, 요소에 설정된 `aria-label` 속성) 콘텐츠 또는 둘 다의 조합에서 나타날 수 있습니다. 요소의 접근 가능한 이름이 결정되는 방식은 요소마다 다른 [접근 가능한 이름 계산](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#name_calculation)을 기반으로 합니다. + +접근 가능한 이름으로 보이는 텍스트를 사용하는 것이 가장 좋습니다. {{HTMLElement("a")}}, {{HTMLElement("td")}} 및 {{HTMLElement("button")}}을 포함한 많은 요소는 해당 콘텐츠에서 이름을 얻습니다. 예를 들어, `Bar`가 있는 경우 접근 가능한 이름은 "Bar"입니다. + +다른 요소는 연관된 요소의 콘텐츠에서 접근 가능한 이름을 얻습니다. {{HTMLElement("fieldset")}}, {{HTMLElement("table")}} 및 {{HTMLElement("figure")}}와 같은 일부 상위 요소의 경우 해당 요소에 하위 {{HTMLElement("fieldset")}}, {{HTMLElement("caption")}} 또는 {{HTMLElement("figcaption")}}는 각각 자동으로 연결됩니다. {{HTMLElement("textarea")}} 및 {{HTMLElement("input")}}와 같은 일부 다른 요소의 경우 접근 가능한 이름은 관련 요소인 {{HTMLElement("label")}} 요소에서도 알 수 있습니다. 하지만 해당 연결은 form control의 `id`와 일치하는 `