From fed9ad9d0412a8e2e544e67cb3fb41308c6f6de9 Mon Sep 17 00:00:00 2001 From: familyboat <84062528+familyboat@users.noreply.github.com> Date: Mon, 9 Sep 2024 08:55:26 +0800 Subject: [PATCH 001/489] zh-cn: update the translation of the learn/css index page (#23446) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: A1lo --- files/zh-cn/learn/css/index.md | 42 +++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/files/zh-cn/learn/css/index.md b/files/zh-cn/learn/css/index.md index 445c058f77add0..19c8fc5d7f26d7 100644 --- a/files/zh-cn/learn/css/index.md +++ b/files/zh-cn/learn/css/index.md @@ -7,44 +7,48 @@ l10n: {{LearnSidebar}} -层叠样式表——或 {{glossary("CSS")}}——是你在 {{glossary("HTML")}} 之后应该学习的第二门技术。HTML 用于定义内容的结构和语义，CSS 用于设计风格和布局。比如，你可以使用 CSS 来更改内容的字体、颜色、大小、间距，将内容分为多列，或者添加动画及其他的装饰效果。 +层叠样式表——或 {{glossary("CSS")}}——是你在学完 {{glossary("HTML")}} 之后应该学习的第一门技术。HTML 用于为你的内容定义结构和语义，CSS 用于为内容提供样式和对内容进行布局。例如，你可以使用 CSS 更改内容的字体、颜色、大小和间距，将内容分成多列，或添加动画和其它装饰特性。 -## 学习路径 +## 前提 -在尝试学习 CSS 之前，你应该了解 HTML 的基础知识。建议你先学习 [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML)模块。 +在尝试 CSS 之前，你应该学习 HTML 的基础知识。我们建议你先学习 [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML)。 -一旦你掌握了 HTML 的基础知识，我们建议你同时学习更深入的 HTML 和 CSS，在这两个主题之间来回切换学习。这是因为当你应用 CSS 时，HTML 会变得更加有趣，学习起来也更有乐趣，而不了解 HTML 就无法学习 CSS。 +一旦你理解了 HTML 的基础知识，我们就建议你同时更深入地学习 HTML 和 CSS，在这两个专题之间来回切换。这么做是因为在应用了 CSS 后，HTML 会变得更加有趣，学习起来也更有乐趣。并且不了解 HTML 的话，也无法学习 CSS。 -在开始这个主题之前，你还应该熟悉使用计算机和被动地使用网络（即，仅仅浏览和消费内容）。你应该按照[安装基础软件](/zh-CN/docs/Learn/Getting_started_with_the_web/Installing_basic_software)中详细说明的内容设置好一个基本的工作环境，并且理解如何创建和管理文件，这在[处理文件](/zh-CN/docs/Learn/Getting_started_with_the_web/Dealing_with_files)中有详细介绍——这些都是我们从零[开始学网页](/zh-CN/docs/Learn/Getting_started_with_the_web)初学者完整模块的一部分。 +在开始本专题之前，你还应该熟悉如何使用电脑，如何被动地使用 Web（例如，只是浏览和消费内容）。你应该按照[安装基础软件](/zh-CN/docs/Learn/Getting_started_with_the_web/Installing_basic_software)中的详细内容搭建基础工作环境，以及按照[处理文件](/zh-CN/docs/Learn/Getting_started_with_the_web/Dealing_with_files)中的内容理解如何创建和管理文件——两个都是 [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)纯新手模块的一部分。 -如果你对网页开发完全陌生，建议你在继续学习这个主题之前，先完成从零[开始学网页](/zh-CN/docs/Learn/Getting_started_with_the_web)的学习。不过，[CSS 基础](/zh-CN/docs/Learn/Getting_started_with_the_web/CSS_basics)文章中涵盖的大部分内容也在我们的 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)模块中有更详细的讲解。 +在开始本专题之前，还是建议你先学习 [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)，尤其当你是 Web 开发的纯新手的话。不过，[CSS 基础](/zh-CN/docs/Learn/Getting_started_with_the_web/CSS_basics)这篇文章中涉及的大部分内容在 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)模块中也有所涉及，而且更详细。 ## 模块 -本主题包含以下模块，建议按顺序阅读这些模块。你应该从第一个模块开始。 +本专题包含以下模块，建议按顺序学习这些模块。你应该从第一个模块开始。 - [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps) - - : CSS（层叠样式表）用于样式化和布局网页。例如，可以更改内容的字体、颜色、大小和间距，将内容分成多列，或添加动画和其他装饰功能。本模块将为你提供通往精通 CSS 之路的平缓起点，让你了解 CSS 的基本工作原理、语法，以及如何开始使用 CSS 为 HTML 添加样式。 -- [构建 CSS 块](/zh-CN/docs/Learn/CSS/Building_Blocks) - - : 本模块承接 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)，进行进一步的学习——既然你已经熟悉了 CSS 的语言和语法，有了一些使用 CSS 的基本经验，是时候再深入一些了。本模块涉及了层叠与继承、可用的所有种类的选择器、单位、尺寸、样式化背景和边框、调试，还有更多。这样做的目的是，在继续深入到更加具体的规则，例如[样式化文本](/zh-CN/docs/Learn/CSS/Styling_text)和 [CSS 布局](/zh-CN/docs/Learn/CSS/CSS_layout)前，为你提供一个编写合格 CSS 的工具包，帮你理解所有必要的理论。 -- [样式化文本](/zh-CN/docs/Learn/CSS/Styling_text) - - : 在覆盖了 CSS 语言的基础知识之后，下一个需要集中学习的 CSS 主题是文本样式化——这是你使用 CSS 最常做的事情之一。这里我们研究文本样式化的基本原理，包括设置字体、粗细、斜体、行距和字母间距、阴影等文本特征。我们最后还会讨论如何将自定义字体应用到页面上，以及如何样式化列表和链接。 + - : CSS（层叠样式表）用于为网页添加样式，对网页进行布局——例如，修改内容的字体、颜色、大小和间距，将内容分成多列，或添加动画和其它装饰特性。在前往掌握 CSS 基础知识（CSS 的运作方式，CSS 语法是什么样子，在 HTML 中如何使用 CSS 添加样式）的道路上，本模块是一个很好的开始。 +- [CSS 构建块](/zh-CN/docs/Learn/CSS/Building_Blocks) + + - : 本模块承接 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)——这时你已经熟悉 CSS 语言及其语法，有了基本的使用经验，是时候再深入一些。在本模块中，你会学习层叠和继承、可用的选择器类型、单位、大小、为背景和边框添加样式、调试，以及其它内容。 + + 本文的目的是，在了解诸如[为文本添加样式](/zh-CN/docs/Learn/CSS/Styling_text)和 [CSS 布局](/zh-CN/docs/Learn/CSS/CSS_layout)等特定领域的知识之前，提供一个能让你编写合格 CSS 的工具集并帮助你理解基本的理论。 + +- [为文本添加样式](/zh-CN/docs/Learn/CSS/Styling_text) + - : 在学完 CSS 语言的基础知识后，下一个集中学习的 CSS 主题是为文本添加样式——用 CSS 做的最多的事之一。本文介绍了为文本添加样式的基础知识，包括：设置字体、加粗、斜体、行间距、字间距、阴影和其它文本特性。在本模块中，还会学习的内容有：在页面中应用自定义字体、为列表和链接添加样式。 - [CSS 布局](/zh-CN/docs/Learn/CSS/CSS_layout) - - : 到目前为止，我们已经学习了 CSS 基础知识、如何设置文本样式、如何设计并操作内容所在的盒子。现在应该考虑如何把你的盒子以合适的位置放置在视口内和其他盒子旁边了。我们已经学习了在深入 CSS 布局之前需要学会的必要知识，下一步我们通过学习设置 display 属性，使用新的布局工具如弹性盒（flexbox）、CSS 网格和定位，以及你仍想知道的一些传统技术，来深入学习 CSS 布局。 + - : 看到这儿，你已经学习过 CSS 基础知识、如何为文本添加样式、如何为放置内容的盒子添加样式并操纵它。现在，是时候学习参照视口或另一个盒子时如何将盒子放置在正确的位置。必要的前置知识已经具备，此时你可以深入 CSS 布局，学习不同的显示设置、现代的布局工具（如弹性盒、CSS 网格）、定位，以及一些你可能仍想了解的传统技术。 ## 解决常见的 CSS 问题 -[使用 CSS 解决常见问题](/zh-CN/docs/Learn/CSS/Howto)解释了怎样使用 CSS 解决创建一个网页时常遇到的问题。 +[使用 CSS 解决常见问题](/zh-CN/docs/Learn/CSS/Howto)提供了用于解释如何使用 CSS 解决创建网页时常遇到的问题的内容的链接。 -从这里开始，你大致就能在 HTML 元素和它们的背景上应用颜色、改变形状尺寸和元素的位置、向元素上添加并定义边框。但是，只要你对 CSS 的基础知识有了扎实的了解，就没有做不到的事情了。学习 CSS 的最大好处之一就是，一旦你了解了 CSS 的基础知识，即使你还不知道如何操作，通常也能很好地了解哪些可以做到，哪些不可以做到！ +刚开始，你主要是为 HTML 元素及其背景应用颜色，改变元素的大小、形状和位置，为元素添加和定义边框。但这并不是你唯一能做的，只要你对 CSS 的基础知识有了坚实的理解的话。学习 CSS 最棒的事情之一就是，一旦你了解了基础，即使你还不知道如何做，通常会对能做的和不能做的有一个很好的感知。 -## “CSS 是怪异的” +## “CSS 真奇怪” -CSS 确实有些独特，它的工作方式与大多数编程语言和设计工具有些不同。为什么 CSS 会以这种方式工作呢？在下面的视频中，Miriam Suzanne 提供了一个有用的解释，说明了 CSS 为什么会这样工作，以及为什么它会这样演变： +CSS 与你接触到的大多数编程语言和设计工具的运作方式有点不同。CSS 为什么以这种方式运作？在下面的视频中，对 CSS 为什么这样运作以及 CSS 为什么演变成这样做了很好的解释： {{EmbedYouTube("aHUtMbJw8iA")}} -## 参阅 +## 参见 - [MDN 上的 CSS 文档](/zh-CN/docs/Web/CSS) - - : MDN 上 CSS 文档的主要入口，可以在这里找到 CSS 语言所有特性的详细参考文档。想要了解某个属性可以取的所有值吗？这是一个很好的去处。 + - : MDN 上 CSS 文档的主入口，在这里可以找到 CSS 语言全部特性的详细参考文档。想要了解某个属性可以取的所有值吗？这是一个很好的去处。 From 71cd8ddcb0eb7edeac8f83a6a418676bb129f3fc Mon Sep 17 00:00:00 2001 From: familyboat <84062528+familyboat@users.noreply.github.com> Date: Mon, 9 Sep 2024 11:50:46 +0800 Subject: [PATCH 002/489] zh-cn: update the translation of the home page of learn (#23483) --- files/zh-cn/learn/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/zh-cn/learn/index.md b/files/zh-cn/learn/index.md index 4a034f032cf040..64a62faebde32a 100644 --- a/files/zh-cn/learn/index.md +++ b/files/zh-cn/learn/index.md @@ -16,7 +16,7 @@ l10n: 你要是还不确定是否要深入地学习 Web 开发，仅想从体验环节开始，我们会建议你从 [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)指南开始学习。除此之外，你应该从下面的专题开始学习。 - HTML 和 CSS - - : HTML 为 Web 内容提供结构，而 CSS 为 Web 内容添加样式并对 Web 内容进行布局。在[介绍 HTML](/zh-CN/docs/Learn/HTML/Introduction_to_HTML) 和 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)中学习基本的入门知识。 + - : HTML 为 Web 内容提供结构，而 CSS 为 Web 内容添加样式并对 Web 内容进行布局。在 [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML)和 [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps)中学习基本的入门知识。 - JavaScript - : JavaScript 为网站提供交互功能。从 [JavaScript 第一步](/zh-CN/docs/Learn/JavaScript/First_steps)开始学习。 - 框架和工具 @@ -29,7 +29,7 @@ l10n: > > #### 想成为一名前端 Web 开发者吗？ > -> 你要是想成为一名前端 Web 开发者，但不确定该从哪开始学习，我们会建议使用 [MDN 合作课程](/en-US/curriculum/)作为你的学习计划。它提供一个结构化的学习路径，包含：成为一名成功的前端开发者所需的基本技巧和练习，以及推荐学习资源。 +> 你要是想成为一名前端 Web 开发者，但不确定该从哪开始学习，我们会建议使用 [MDN 课程](/en-US/curriculum/)作为你的学习计划。它提供一个结构化的学习路径，包含：成为一名成功的前端开发者所需的基本技巧和练习，以及推荐学习资源。 > > [**现在开始**](/en-US/curriculum/) From e7b8882784dcf1d8234ffe6ff4141a9d377da284 Mon Sep 17 00:00:00 2001 From: Tianyi Tao Date: Mon, 9 Sep 2024 13:28:10 +0800 Subject: [PATCH 003/489] [zh-cn]: update the translation of `global_objects/nan` (#23464) Co-authored-by: A1lo --- .../reference/global_objects/nan/index.md | 42 +++++++++++++------ 1 file changed, 29 insertions(+), 13 deletions(-) diff --git a/files/zh-cn/web/javascript/reference/global_objects/nan/index.md b/files/zh-cn/web/javascript/reference/global_objects/nan/index.md index c10489297bdbff..cb6b5128933288 100644 --- a/files/zh-cn/web/javascript/reference/global_objects/nan/index.md +++ b/files/zh-cn/web/javascript/reference/global_objects/nan/index.md @@ -1,21 +1,27 @@ --- title: NaN slug: Web/JavaScript/Reference/Global_Objects/NaN +l10n: + sourceCommit: 915c9519f3cca1c616c2f554d5ad9e1483bbb170 --- {{jsSidebar("Objects")}} 全局属性 **`NaN`** 是一个表示非数字的值。 -{{js_property_attributes(0, 0, 0)}} - {{EmbedInteractiveExample("pages/js/globalprops-nan.html")}} +## 值 + +其与 {{jsxref("Number.NaN")}} 的值相同。 + +{{js_property_attributes(0, 0, 0)}} + ## 描述 -`NaN`是*全局对象*的一个属性。换句话说，它是全局作用域中的一个变量。 +`NaN` 是*全局对象*的一个属性。换句话说，它是全局作用域中的一个变量。 -`NaN` 的初始值不是数字——与 {{jsxref("Number.NaN")}} 的值相同。在现代浏览器中，`NaN` 是一个不可配置、不可写的属性。即使不是这样，也要避免重写它。在程序中很少使用 `NaN`。 +在现代浏览器中，`NaN` 是一个不可配置、不可写的属性。即使不是这样，也要避免重写它。 有五种不同类型的操作返回 `NaN`： @@ -27,8 +33,8 @@ slug: Web/JavaScript/Reference/Global_Objects/NaN `NaN` 及其行为不是 JavaScript 发明的。它在浮点运算中的语义（包括 `NaN !== NaN`）是由 [IEEE 754](https://zh.wikipedia.org/wiki/雙精度浮點數) 指定的。`NaN` 的行为包括： -- 如果 `NaN` 涉及数学运算（但不涉及[位运算](/zh-CN/docs/Web/JavaScript/Reference/Operators#位移运算符)），结果通常也是 `NaN`。（参见下面的[反例](#默默逃离_nan)。） -- 当 `NaN` 是任何关系比较（`>`, `<`, `>=`, `<=`）的操作数之一时，结果总是 `false`。 +- 如果 `NaN` 涉及数学运算（但不涉及[位运算](/zh-CN/docs/Web/JavaScript/Reference/Operators#位移运算符)），结果通常也是 `NaN`。（参见下面的[反例](#静默逃逸的_nan_值)。） +- 当 `NaN` 是任何关系比较（`>`、`<`、`>=`、`<=`）的操作数之一时，结果总是 `false`。 - `NaN` 不等于（通过 [`==`](/zh-CN/docs/Web/JavaScript/Reference/Operators/Equality)、[`!=`](/zh-CN/docs/Web/JavaScript/Reference/Operators/Inequality)、[`===`](/zh-CN/docs/Web/JavaScript/Reference/Operators/Strict_equality) 和 [`!==`](/zh-CN/docs/Web/JavaScript/Reference/Operators/Strict_inequality)）任何其他值——包括与另一个 `NaN` 值。 `NaN` 也是 JavaScript 中的[假](/zh-CN/docs/Glossary/Falsy)值之一。 @@ -75,7 +81,7 @@ const arr = [2, 4, NaN, 12]; arr.indexOf(NaN); // -1 arr.includes(NaN); // true -// Methods accepting a properly defined predicate can always find NaN +// 接受正确定义的断言的方法总是能够找到 NaN arr.findIndex((n) => Number.isNaN(n)); // 2 ``` @@ -83,23 +89,33 @@ arr.findIndex((n) => Number.isNaN(n)); // 2 ### 明显不同的 NaN 值 -这是 `NaN` 与自身不平等的动机。可以用不同的二进制表示生成两个都是 `NaN` 的浮点数，因为在 [IEEE 754 编码](https://zh.wikipedia.org/wiki/NaN#浮点数)中，任何指数为 `0x7ff` 且尾数非零的浮点数都是 `NaN`。在 JavaScript 中，你可以使用[类型化数组](/zh-CN/docs/Web/JavaScript/Typed_arrays)来进行位操作。 +可以用不同的二进制表示生成两个都是 `NaN` 的浮点数，这是因为在 [IEEE 754 编码](https://zh.wikipedia.org/wiki/NaN#浮点数)中，任何指数为 `0x7ff` 且尾数非零的浮点数都是 `NaN`。在 JavaScript 中，你可以使用[类型化数组](/zh-CN/docs/Web/JavaScript/Typed_arrays)来进行位操作。 ```js const f2b = (x) => new Uint8Array(new Float64Array([x]).buffer); const b2f = (x) => new Float64Array(x.buffer)[0]; -// Get a byte representation of NaN +// 获取 NaN 的字节表示 const n = f2b(NaN); -// Change the first bit, which is the sign bit and doesn't matter for NaN -n[0] = 1; +const m = f2b(NaN); +// 更改符号位，对于 NaN 而言，这个比特位不重要。 +n[7] += 2 ** 7; +// n[0] += 2**7; 对于大端处理器 const nan2 = b2f(n); console.log(nan2); // NaN console.log(Object.is(nan2, NaN)); // true console.log(f2b(NaN)); // Uint8Array(8) [0, 0, 0, 0, 0, 0, 248, 127] -console.log(f2b(nan2)); // Uint8Array(8) [1, 0, 0, 0, 0, 0, 248, 127] +console.log(f2b(nan2)); // Uint8Array(8) [0, 0, 0, 0, 0, 0, 248, 255] +// 更改第一个比特位，即符号位，对于 NaN 而言，这个比特位不重要。 +m[0] = 1; +// m[7] = 1; 对于大端处理器 +const nan3 = b2f(m); +console.log(nan3); // NaN +console.log(Object.is(nan3, NaN)); // true +console.log(f2b(NaN)); // Uint8Array(8) [0, 0, 0, 0, 0, 0, 248, 127] +console.log(f2b(nan3)); // Uint8Array(8) [1, 0, 0, 0, 0, 0, 248, 127] ``` -### 默默逃离 NaN +### 静默逃逸的 NaN 值 `NaN` 通过数学运算进行传播，因此通常在计算结束时测试 `NaN` 一次就足以检测错误条件。`NaN` 被静默转义的唯一情况是使用指数为 `0` [求幂](/zh-CN/docs/Web/JavaScript/Reference/Operators/Exponentiation)时，它立即返回 `1` 而不测试基数的值。 From a75bf486fd88a3ac5be87e173e4d1dbf7c0712ad Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 9 Sep 2024 14:26:58 +0800 Subject: [PATCH 004/489] zh-CN: glossary/color_space (#20022) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: A1lo Co-authored-by: 720 <71604450+T34-active@users.noreply.github.com> Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- files/zh-cn/glossary/color_space/index.md | 95 +++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 files/zh-cn/glossary/color_space/index.md diff --git a/files/zh-cn/glossary/color_space/index.md b/files/zh-cn/glossary/color_space/index.md new file mode 100644 index 00000000000000..7780fb8c3d9022 --- /dev/null +++ b/files/zh-cn/glossary/color_space/index.md @@ -0,0 +1,95 @@ +--- +title: 色彩空间 +slug: Glossary/Color_space +l10n: + sourceCommit: 530c1f54e63834411aa38789b1ac82e3831c4dfa +--- + +{{GlossarySidebar}} + +**色彩空间**是对色彩的命名组织方式，用于基于坐标的色彩排列的基本色彩模型。色彩模型定义了色彩的组成部分（例如 [`hwb()`](/zh-CN/docs/Web/CSS/color_value/hwb) 色彩的 `h`、`w` 和 `b` 通道）与色彩空间之间的关系。多数色彩空间是表示色彩的三维或四维网格，其中各维度（轴）对应色彩空间中的一个通道。一个色彩可以在保持看起来仍然一样的情况下在多个色彩空间中表达，或者从一个色彩空间转换到另一个色彩空间。 + +色彩空间对特定范围的色彩进行分类和定义。每个色彩空间由数学模型和相关的规则集定义。每个色彩空间都有一个定义好的{{glossary("gamut", "色域")}}（它指的是它能表示的特定范围的色彩）。这些规则使得跨不同设备和软件的色彩表现一致且可重现。 + +_sRGB_ 色彩空间（标准红绿蓝）是为 Web 创建的，但我们不再局限于这个色彩空间。[CSS 色彩模块第 4 版](https://drafts.csswg.org/css-color-4)指定了几种预定义的色彩空间，而 [CSS 色彩模块第 5 版](https://drafts.csswg.org/css-color-5/)则进一步规定了用于定义自定义色彩空间的特性。 + +## 具名色彩空间 + +预定义的 [RGB 色彩空间](#rgb_色彩空间)包括 `srgb`、`srgb-linear`、`display-p3`、`a98-rgb`、`prophoto-rgb` 和 `rec2020`。预定义的 [CIELAB 色彩空间](#cielab_色彩空间)包括 `lab-d50` 和 `lab-d65`。预定义的 [XYZ 色彩空间](#xyz_色彩空间)包括 `xyz-d50` 和 `xyz-d65`（以及作为其别名的 `xyz`）。 + +色彩空间可以是[矩形或极坐标的](https://ericportis.com/posts/2024/okay-color-spaces/)。矩形色彩空间包括 `srgb`、`srgb-linear`、`display-p3`、`a98-rgb`、`prophoto-rgb`、`rec2020`、`lab`、`oklab`、`xyz-d50` 和 `xyz-d65`（或 `xyz`）。极坐标色彩空间包括 `hsl`、`hwb`、`lch` 和 `oklch`。 + +### RGB 色彩空间 + +RGB 是一种色彩模型，将色彩表示为三个基本成分（红色、绿色和蓝色色彩通道）的混合，产生各种色调。sRGB（标准 RGB）是 {{Glossary("RGB")}} 色彩的底层色彩空间。sRGB 旨在编纂个人电脑及{{glossary("world wide web", "万维网")}}成像系统的显示规范。目前，sRGB 通常是那些没有标记或没有嵌入色彩配置文件的默认色彩空间。 + +RGB 色彩空间有几种，如可以表示比 _sRGB_ 色彩空间更广泛的{{glossary("gamut", "色域")}}的 _Adobe RGB_ 色彩空间。_sRGB_ 和 _Adobe RGB_（`a98-rgb`）中的坐标是不同的。有很多种方式来描述色彩的 RGB 成分：在 {{Glossary("CSS")}} 中，色彩可以表示为十六进制表示法的单个 24 位整数（如淡蓝色 `#add8e6`），或者在 [`rgb()`](/zh-CN/docs/Web/CSS/color_value/rgb) 函数表示法中表示为 0 到 255 之间的三个独立数字（如，`rgb(46 139.5 87)`）。 + +在 sRGB 色彩空间中，CSS `` 值包括{{cssxref("hex-color", "十六进制色彩")}}、{{cssxref("named-color", "具名色彩")}}、{{cssxref("color_value/rgb", "rgb()")}}、{{cssxref("color_value/hsl", "hsl()")}}（色调、饱和度、亮度）和{{cssxref("color_value/hwb", "hwb()")}}（色调、白度、黑度）。[`color`](/zh-CN/docs/Web/CSS/color_value/color) 函数还支持 `srgb`、`srgb-linear`、`a98-rgb` 和 `prophoto-rgb` 色彩空间。 + +HSV（色调、饱和度和值）色彩空间及其同义词 HSB（色调、饱和度和亮度）在 CSS 中都用 [`hwb()`](/zh-CN/docs/Web/CSS/color_value/hwb) 表示。命名色彩只是与特定十六进制值相对应的关键字。将这些不同的色彩表示法转换为 `sRGB` 的数学方法是直观的。请注意，{{cssxref("<color>", "currentcolor", "#currentcolor_关键字")}} 可以是任何色彩，而不仅限于 `sRGB` 色彩空间。 + +`rgb` 色彩函数不是可以用于表示 _sRGB_ 色彩空间的唯一色彩函数。圆柱坐标系，如 [`HSL`](/zh-CN/docs/Web/CSS/color_value/hsl)（_色调—饱和度—亮度_）或 [`HWB`](/zh-CN/docs/Web/CSS/color_value/hwb)（_色调—白度—黑度_）色彩模型也用于在 Web 上表示 sRGB 色彩。 + +- `sRGB` 色彩空间 + - : sRGB 色彩空间（“标准 RGB”），是标准的 RGB（红、绿、蓝）色彩空间，用于显示器、打印机和 Web 中。它是使用最广泛的色彩空间，受到大多数操作系统、软件程序、显示器和打印机的支持。sRGB 以 `r`、`g` 和 `b` 为基础，色域范围为 `0` 至 `1`。它的白点为 D65。 +- `srgb-linear` 色彩空间 + - : 预定义的线性光 sRGB 色彩空间 `srgb-linear` 与 `srgb`相同，只是传输函数是没有伽玛编码的线性光。`srgb-linear` 色彩空间接受三个 `r`、`g` 和 `b` 值作为数值参数，色域范围为 `0` 至 `1`。它的白点为 D65。 +- `display-p3` 色彩空间 + - : **Display P3** 色彩空间由苹果公司定义，结合了 DCI-P3 色域、D65 白点和 sRGB 伽马曲线。它是一种典型的宽色域空间，适用于当前的宽色域显示器，能呈现出比 sRGB 色域更鲜艳的绿色和红色。`display-p3` 基于 `r`、`g` 和 `b`，伽玛值范围为 `0` 至 `1`。它的白点为 D65。 +- `a98-rgb` 色彩空间 + - : `a98-rgb` 是 Adobe® 1998 RGB 色彩空间，旨在将所有 CMYK 颜色表示为 RGB。它可实现 [CIELab 色彩空间](#cielab_色彩空间)指定的约 50% 的可见色彩，比其他 RGB 色彩空间包含更多的青绿色调。伽玛内的 `r`、`g` 和 `b` 值范围从 `0` 到 `1`。它的传输曲线是一个伽马函数，不完全地接近于 1/2.2。它的白点为 D65。 +- `prophoto-rgb` + - : `prophotoo-rgb` 色彩空间由柯达公司开发，可以表示自然界中可能出现的所有颜色和大约 90% 的 [CIElab 颜色](#cielab_色彩空间)。色域范围的 `r`、`g` 和 `b` 值范围从 `0` 至 `1`。转移曲线是一个伽马函数，值为 1/1.8，其中在黑色附近有一小段线性。它的白点为 D50，与 CIELab 使用的白点相同。 +- `rec2020` + - : `rec2020` 是超高清 4k 和 8k 电视的广播行业标准。超宽色域空间能够呈现现实世界中几乎所有可见的颜色，超出了目前大多数显示器的能力。随着显示器的不断改进，预计覆盖范围会逐渐扩大。色域内的 `r`、`g` 和 `b` 值从 `0` 至 `1`。它的白点为 D65。 + +> [!NOTE] +> CSS 规范中没有的其他圆柱形 RGB 空间，如 `HSI`（色调、饱和度和强度）、`Okhsv`、`Okhsl`、`HSLuv`、`HPLuv` 和 `Cubehelix`。 + +### CIELAB 色彩空间 + +CIELAB（或 CIELab）色彩空间，也称为 L\*a\*b*（简称 Lab*），表示人类可以看到的所有色彩范围。这个色彩空间是由国际照明委员会（CIE）定义的。它将色彩表示为三个值：L\* 表示感知亮度，a\* 和 b\* 表示人类视觉的四种独特色彩：红、绿、蓝和黄。 + +Lab 是一个矩形坐标系统，有一个中央的亮度 `L` 轴。`a` 轴上的正值是紫红色，而负值是其补色绿色。`b` 轴上的正值是黄色，负值是蓝色/紫罗兰色。不饱和的色彩具有小的 `a` 和 `b` 值，而绝对值更大的更饱和。 + +CIELAB 色彩函数包括 {{CSSXref("color_value/lab", "lab()")}}（亮度、a 轴、b 轴）和 {{CSSXref("color_value/lch", "lch()")}}（亮度、色度、色调），以及 {{CSSXref("color_value/oklab", "oklab()")}} 和 {{CSSXref("color_value/oklch", "oklch()")}}。它们的亮度值是相同的，但是 `lch()` 和 `oklch` 是一个 `C`（色度）和 `H`（色调）使用极坐标而不是轴的极坐标柱面坐标系统。 + +> [!NOTE] +> 函数 `lch()` 和 `oklch` 中的色调和亮度与 {{cssxref("color_value/hsl", "hsl()")}} 或其他 sRGB 色彩空间中同名值不同。 + +CIELab 色彩空间包括 Lab、Lch、Oklab 和 Oklch，是设备无关的色彩空间。 + +- `lab-d50` 色彩空间 + + - : 将色彩表示为 `L` 在 `0` 到 `100` 范围内，并且 `a` 和 `b` 范围在 `-125` 到 `125` 之间的色彩空间。`a` 和 `b` 轴不受这些范围值的限制，这些值是在与 `Display P3` 色彩空间相关的百分比输入和输出中使用的参考点。它的白点是 D50。 + +- `lab-d65` 色彩空间 + + - : 除使用 D65 作为白点外，与 `lab-d50` 相同。 + +- `oklab` 色彩空间 + + - : 类似于 `lab-d65`，但 `L` 的范围是 `0` 到 `1`，`a` 和 `b` 的范围是 `-0.4` 到 `0.4`。 + +### XYZ 色彩空间 + +尽管红、绿和蓝的组合在屏幕上表示色彩效果很好，但 sRGB 并不直接对应于人类感知的色彩。CIEXYZ（或 XYZ）色彩空间是由国际照明委员会（CIE）在 1931 年定义的。它是电磁可见光谱中波长分布与人类视觉中感知色彩之间的第一个定义的定量联系。 + +视力正常的人有三种对不同波长的光谱具有峰值敏感度的感光锥细胞。CIE X、Y 和 Z 参数对应于三种视锥细胞的刺激水平，原则上可以描述每一种可见光颜色。`Y` 通道代表一种颜色的亮度。`Z` 通道反映颜色中蓝色的含量（但与 RGB 中的 B 不同）。`X` 轴与 XYZ 色彩三维坐标系的 Y 轴和 Z 轴正交。 + +- `xyz` 和 `xyz-d65` 色彩空间 + + - : `xyz` 标识符是 `xyz-d65` 色彩空间的同义词。由于色彩空间不限于此范围，因而轴不限于 `0` 到 `1` 的范围；这些值只在定义输入输出的百分比时使用作为参考点。它的白点是 D65。 + +- `xyz-d50` 色彩空间 + - : 除使用 `d50` 作为白点外，与 `xyz-d65` 相同。 + +## 参见 + +- {{cssxref("@media/color-gamut", "color-gamut")}} `@media` 特性 +- [CSS 数据类型：``](/zh-CN/docs/Web/CSS/color_value) +- [sRGB 色彩空间](https://webstore.iec.ch/en/publication/6168) +- 维基百科上的 [CIELAB 色彩空间](https://zh.wikipedia.org/wiki/CIELAB色彩空间) +- 维基百科上的 [CIE 1931 色彩空间](https://zh.wikipedia.org/wiki/CIE_1931色彩空间) +- [Oklab](https://bottosson.github.io/posts/oklab/) 色彩空间 From 3d0baa0907b59b12d532b9548f8d69abb410d07e Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 9 Sep 2024 14:33:44 +0800 Subject: [PATCH 005/489] zh-CN: create Glossary/Canonical_order (#23351) Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- files/zh-cn/glossary/canonical_order/index.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 files/zh-cn/glossary/canonical_order/index.md diff --git a/files/zh-cn/glossary/canonical_order/index.md b/files/zh-cn/glossary/canonical_order/index.md new file mode 100644 index 00000000000000..3a62c23616024b --- /dev/null +++ b/files/zh-cn/glossary/canonical_order/index.md @@ -0,0 +1,28 @@ +--- +title: 规范顺序 +slug: Glossary/Canonical_order +l10n: + sourceCommit: 7a551aaa034fbada3eb99e6fc924a0313b78307f +--- + +{{GlossarySidebar}} + +CSS **规范顺序**是指需要指定（或{{Glossary("parse", "解析")}}）或作为 CSS 属性值的一部分进行{{Glossary("serialization", "序列化")}}的单独值的顺序。它由属性的正式{{Glossary("syntax", "语法")}}定义，通常指的是应该在单个简写值的一部分中指定全称值的顺序。 + +例如，{{cssxref("background")}} 简写属性值由几个 `background-*` 全称属性组成。这些全称值的规范顺序定义如下： + +1. {{cssxref("background-image")}} +2. {{cssxref("background-position")}} +3. {{cssxref("background-size")}} +4. {{cssxref("background-repeat")}} +5. {{cssxref("background-attachment")}} +6. {{cssxref("background-origin")}} +7. {{cssxref("background-clip")}} +8. {{cssxref("background-color")}} + +另外，它的语法规定如果给出了 {{cssxref("background-size")}} 的值，则这个值**必须**在 {{cssxref("background-position")}} 的值**之后**指定，并用斜杠分隔。其他值则可以以任何顺序出现。 + +## 参见 + +- [CSS 值定义语法](/zh-CN/docs/Web/CSS/Value_definition_syntax) +- StackOverflow 上的[“规范顺序”对 CSS 属性的意义有什么？](https://stackoverflow.com/questions/28963536/what-does-canonical-order-mean-with-respect-to-css-properties)给出了进一步有意义的讨论。 From 32b5677d2dffdffdd9f37661ffd7139058e0b70b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=87=AA=E7=94=B1=E7=9A=84=E4=B8=96=E7=95=8C=E4=BA=BA?= <144885467+Pleasurecruise@users.noreply.github.com> Date: Mon, 9 Sep 2024 15:52:50 +0800 Subject: [PATCH 006/489] [zh-cn] create the translation of "Attribution Reporting API" (#23368) Co-authored-by: Allo --- .../generating_reports/index.md | 308 ++++++++++++++++++ .../api/attribution_reporting_api/index.md | 117 +++++++ .../registering_sources/index.md | 287 ++++++++++++++++ .../registering_triggers/index.md | 231 +++++++++++++ 4 files changed, 943 insertions(+) create mode 100644 files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md create mode 100644 files/zh-cn/web/api/attribution_reporting_api/index.md create mode 100644 files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md create mode 100644 files/zh-cn/web/api/attribution_reporting_api/registering_triggers/index.md diff --git a/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md b/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md new file mode 100644 index 00000000000000..1586a30982b5aa --- /dev/null +++ b/files/zh-cn/web/api/attribution_reporting_api/generating_reports/index.md @@ -0,0 +1,308 @@ +--- +title: 生成归因报告 +slug: Web/API/Attribution_Reporting_API/Generating_reports +l10n: + sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("Attribution Reporting API")}} + +本文介绍了[归因报告 API](/zh-CN/docs/Web/API/Attribution_Reporting_API) 如何生成报告——包括归因报告和调试报告——以及如何控制生成的报告。内容包括处理噪声、报告优先级、过滤报告和生成调试报告。 + +## 基本流程 + +当触发器和来源匹配时，浏览器会生成报告，并通过无凭证的 [`POST`](/zh-CN/docs/Web/HTTP/Methods/POST) 请求将报告发送到报告来源的特定端点： + +- 对于事件级报告，端点为 `/.well-known/attribution-reporting/report-event-attribution`。 +- 对于汇总报告，端点为 `/.well-known/attribution-reporting/report-aggregate-attribution`。 + +`` 与注册的来源（source）和触发器同源（same-origin）。 + +报告数据包含在一个 JSON 结构中。 + +## 事件级报告 + +事件级报告会在其包含的**报告窗口**结束时生成并计划发送。报告窗口的长度由来源的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 [`"event_report_window"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_report_window) 或 [`"event_report_windows"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#event_report_windows) 字段决定。 + +如果未指定这些字段，报告窗口将回退到以下默认值： + +- 对于[基于事件的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)，默认报告窗口在来源的 `"expiry"` 到期时结束，该值在 `Attribution-Reporting-Register-Source` 的 [`"expiry"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#expiry) 字段中设置。如果未显式设置，则默认为注册后 30 天。 +- 对于[基于导航的来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)，默认报告窗口分别为 2 天、7 天和来源的 `"expiry"`。 + +有关详细信息，请参阅[自定义报告窗口](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows)。 + +一旦事件级报告到达相应的端点，数据如何处理、存储和显示完全取决于开发者。一个典型的事件级报告可能如下所示： + +```json +{ + "attribution_destination": "https://advertiser.example", + "source_event_id": "412444888111012", + "trigger_data": "4", + "report_id": "123e4567-e89b-12d3-a456-426614174000", + "source_type": "navigation", + "randomized_trigger_rate": 0.34, + "scheduled_report_time": "1692255696", + "source_debug_key": 647775351539539, + "trigger_debug_key": 647776891539539 +} +``` + +属性如下： + +- `"attribution_destination"` + - : 一个字符串，或者是一个包含 2-3 个字符串的数组，取决于来源是否注册了多个目标。这些字符串代表在来源注册时通过关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中设置的归因 [`"destination"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) 站点。 +- `"source_event_id"` + - : 一个表示归因来源 ID 的字符串。这等同于在来源注册时通过关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中设置的 [`"source_event_id"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#source_event_id)。 +- `"trigger_data"` + - : 一个表示归因触发器来源数据的字符串，在触发器注册时设置（通过关联的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 响应标头设置的 [`"trigger_data"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data)）。 +- `"report_id"` + - : 一个表示此报告的[通用唯一标识符（UUID）](/zh-CN/docs/Glossary/UUID)的字符串，可用于防止重复计算。 +- `"source_type"` + - : 一个字符串，值为 `"navigation"` 或 `"event"`，分别表示相关的归因来源是[基于导航的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)，还是[基于事件的](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)。 +- `"randomized_trigger_rate"` + - : 一个介于 0 和 1 之间的随机数，表示此特定来源配置应用[噪声](#为报告添加噪声)的频率。 +- `"scheduled_report_time"` + - : 一个字符串，表示从 Unix 纪元开始到浏览器最初计划发送报告的秒数（以避免因设备离线导致报告延迟而产生的不准确性）。 +- `"source_debug_key"` {{optional_inline}} + - : 一个 64 位无符号整数，表示归因来源的调试密钥。此值与关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中设置的值相同。有关更多信息，请参阅[调试报告](#调试报告)。 +- `"trigger_debug_key"` {{optional_inline}} + - : 一个 64 位无符号整数，表示归因触发器的调试密钥。此值与关联的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中的 `"debug_key"` 字段中设置的值相同。有关更多信息，请参阅[调试报告](#调试报告)。 + +## 汇总报告 + +汇总报告是从收到的多个可汇总报告创建的，并随后[批处理](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/summary-reports-intro#batching)以准备由[汇总服务](https://developers.google.com/privacy-sandbox/private-advertising/aggregation-service)处理。此后，数据如何处理、存储和显示完全取决于开发者。 + +默认情况下，可汇总报告是在触发器交互后生成并计划发送的，带有随机延迟以帮助模糊时序并提高隐私性。对于给定的已注册归因来源，从注册到来源过期期间会记录归因来源事件——这称为**报告窗口**。 + +到期时间由关联的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中的 `expiry` 值定义，如果未明确设置，则默认为注册后 30 天。请注意，可以通过在 `Attribution-Reporting-Register-Source` 标头中设置 `aggregatable_report_window` 值来进一步修改报告窗口的长度。有关详细信息，请参阅[自定义报告窗口](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/custom-report-windows)。 + +> [!NOTE] +> 为了进一步保护用户隐私，每个归因来源相关的汇总报告值具有有限的总值——这称为**贡献预算**。此值可能因 API 的不同实现而有所不同；在 Chrome 中为 65,536。任何会生成报告从而导致的总值超出此限制的转化将不被记录。请确保跟踪预算并在你尝试测量的不同指标之间共享它。 + +典型的可汇总报告可能如下所示： + +```json +{ + "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://advertiser.example\",\"report_id\":\"123e4567-e89b-12d3-a456-426614174000\",\"reporting_origin\":\"https://reporter.example\",\"scheduled_report_time\":\"1692255696\",\"source_registration_time\":\"1692230400\",\"version\":\"3\"}", + "aggregation_service_payloads": [ + { + "payload": "[base64 编码的 HPKE 加密数据，仅供汇总服务读取]", + "key_id": "[标识用于加密有效负载的公钥的字符串]", + "debug_cleartext_payload": "[base64 编码的未加密有效负载]" + } + ], + "aggregation_coordinator_origin": "https://publickeyservice.aws.privacysandboxservices.com", + "source_debug_key": 647775351539539, + "trigger_debug_key": 647776891539539 +} +``` + +属性如下： + +- `"shared_info"` + - : 这是一个序列化的 JSON 对象，提供汇总服务使用的信息。这些数据使用 [AEAD](https://zh.wikipedia.org/wiki/认证加密) 进行加密，以防篡改。序列化字符串中包含以下属性： + - `"api"` + - : 表示触发报告生成的 API 的枚举值。目前，这个值将始终等于 `"attribution-reporting"`，但将来可能会扩展以支持其他 API。 + - `"attribution_destination"` + - : 一个表示归因 [`"destination"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#destination) URL 的字符串，该 URL 在来源注册时通过相关的 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头设置。 + - `"report_id"` + - : 一个表示此报告的[全局唯一标识符（UUID）](/zh-CN/docs/Glossary/UUID)的字符串，可用于防止重复计数。 + - `"reporting_origin"` + - : 触发报告生成的来源。 + - `"scheduled_report_time"` + - : 一个字符串，表示从 Unix 纪元到浏览器最初计划发送报告的时间，以秒为单位（避免由于设备离线导致的报告延迟）。 + - `"source_registration_time"` + - : 一个字符串，表示从 Unix 纪元到归因来源注册的时间，四舍五入到整天。 + - `"version"` + - : 一个表示生成报告的 API 版本的字符串。 +- `"aggregation_service_payloads"` + + - : 一个对象数组，表示汇总服务用来组装报告中数据的直方图贡献的有效负载对象。目前，每个报告只支持一个由浏览器配置的有效负载。将来可能会支持多个可定制的有效负载。每个有效负载对象包含以下属性： + + - `"payload"` + + - : 一个通过 [HPKE](https://datatracker.ietf.org/doc/rfc9180/) 加密并经过 [base64](/zh-CN/docs/Glossary/Base64) 编码的 [CBOR](https://cbor.io/) 映射，结构如下： + + ```js + { + "operation": "histogram", // 允许服务支持将来其他操作 + "data": [{ + "bucket": <分桶，编码为 16 字节（即 128 位）的大端字节串>, + "value": <桶值，编码为 4 字节（即 32 位）的大端字节串> + }, ...] + } + ``` + + - `"key_id"` + - : 一个字符串，标识用于加密有效负载的公钥。 + - `"debug_cleartext_payload"` {{optional_inline}} + - : 可选的调试信息。 + +- `"aggregation_coordinator_origin"` + - : 汇总服务的部署选项。 +- `"source_debug_key"` {{optional_inline}} + - : 一个 64 位无符号整数，表示归因来源的调试密钥。此值与相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头的 [`"debug_key"`](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Source#debug_key) 字段中的值一致。更多信息请参见[调试报告](#调试报告)。 +- `"trigger_debug_key"` {{optional_inline}} + - : 一个 64 位无符号整数，表示归因触发器的调试密钥。此值与相关 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头的 `"debug_key"` 字段中的值一致。更多信息请参见[调试报告](#调试报告)。 + +## 为报告添加噪声 + +噪声被添加到报告中，以模糊与特定来源相关的输出，从而保护用户隐私。确切的来源数据无法被识别并归因到用户个体，但从数据中提取的总体模式仍然可以提供相同的意义。 + +关于归因报告中噪声的工作原理，请参见： + +- [理解汇总报告中的噪声](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/understanding-noise) +- [数据限制和噪声](https://github.com/WICG/attribution-reporting-api/blob/main/EVENT.md#data-limits-and-noise) +- [处理噪声](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/working-with-noise) + +## 报告优先级和限制 + +默认情况下，所有归因来源的优先级相同，并且归因模型是最后接触（last-touch）模型，这意味着转化被归因到最新的匹配来源事件。对于事件级和可汇总的报告，你可以通过在相关 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中设置 `"priority"` 字段的新值来更改来源优先级。默认值为 `0`；如果你将特定来源的 `"priority"` 值设置为 `1`，则该来源将首先匹配，优先于任何优先级为 `0` 的来源。优先级为 `2` 的来源将在优先级为 `1` 的来源之前匹配，依此类推。 + +归因触发器优先级的工作方式相同；你也可以通过在相关 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中添加 `"priority"` 字段来设置触发器优先级，但仅适用于事件级报告。 + +不同的来源类型有不同的默认限制： + +- [基于导航的归因来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于导航的归因来源)默认限制为三个报告。例如，如果用户点击了一个广告并进行了四次转化：他们访问了广告商网站主页，然后访问了产品页面，注册了时事通讯，最后进行了购买。由于这是第四次转化，购买报告将被丢弃。 +- [基于事件的归因来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources#基于事件的归因来源)默认限制为一个报告。 + +> [!NOTE] +> 可以通过在关联的 `Attribution-Reporting-Register-Source` 标头的 `"event_report_windows"` 字段中设置不同的 `"end_times"` 来调整报告限制。 + +当为给定的来源事件触发归因时，如果该来源已达到最大归因次数（点击为 3 次，图像/脚本为 1 次），浏览器将： + +- 将新报告的优先级与同一来源的现有计划报告的优先级进行比较。 +- 删除优先级最低的报告以安排新的报告。如果新报告的优先级最低，则忽略新报告，不会收到它。 + +如果未设置优先级，浏览器将回退到其默认行为：在点击后的第三次转化或查看后的第一次转化后发生的任何转化都将被丢弃。 + +## 过滤器 + +你可以使用过滤器定义哪些转化会生成报告。例如，你可以选择只计算特定产品类别的转化，并过滤掉其他类别的转化。 + +要声明过滤器： + +1. 在来源注册时，将 `filter_data` 字段添加到 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中，该字段定义了你将在触发端用于过滤转化的过滤键。这些是完全自定义的字段。例如，要指定仅特定子域名和特定产品的转化： + + ```json + "filter_data": { + "conversion_subdomain": ["electronics.megastore", "electronics2.megastore"], + "product": ["1234"] + } + ``` + +2. 在触发注册时，将 `filters` 字段添加到 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中。例如，以下内容会使触发交互匹配上述来源注册，因为它们都包含 `"electronics.megastore"` 的 `"conversion_subdomain"` 字段。而 `"directory"` 过滤器则在尝试匹配时被忽略，因为它未包含在上述来源注册中。 + + ```json + "filters": { + "conversion_subdomain": ["electronics.megastore"], + "directory": ["/store/electronics"] + } + ``` + +如果 `"filter_data"` 和 `"filters"` 字段包含匹配的子字段（如上例中的 `"conversion_subdomain"`），但这些子字段的值没有匹配项，则会忽略触发器，导致没有匹配。 + +### 过滤触发数据 + +可以扩展 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头中的 `event_trigger_data` 字段，以根据在 {{httpheader("Attribution-Reporting-Register-Source")}} 标头中定义的 `filter_data` 选择性地设置 `trigger_data`、`priority` 或 `deduplication_key`。 + +例如： + +```json +{ + "event_trigger_data": [ + { + "trigger_data": "2", + "filters": { "source_type": ["navigation"] } + }, + { + "trigger_data": "1", + "filters": { "source_type": ["event"] } + } + ] +} +``` + +> **备注：** `"source_type"` 是在来源的 `"filter_data"` 上自动填充的字段。 + +> **备注：** `not_filters`，即否定过滤器，也受支持。 + +在此上下文中，`filters` 可以是对象或对象数组。当指定列表时，只需一个字典匹配即可将触发器视为匹配。 + +```json +{ + "event_trigger_data": [ + { + "trigger_data": "2", + "filters": [ + { + "product": ["1234"], + "conversion_subdomain": ["electronics.megastore"] + }, + { + "product": ["4321"], + "conversion_subdomain": ["electronics4.megastore"] + } + ] + } + ] +} +``` + +如果事件触发器的过滤器都不匹配，则不会创建事件级报告。如果过滤器匹配多个事件触发器，则使用第一个匹配的事件触发器。 + +## 调试报告 + +你可以启用调试报告，以返回有关归因报告的故障排除信息。这些报告可用于检查你的设置是否正常工作，并了解基于 cookie 的旧实现和新归因报告实现之间的测量结果差距。调试报告会立即发送；它们不受事件级和汇总报告相同的调度约束。 + +有两种不同类型的调试报告： + +- **成功调试报告**跟踪特定归因报告的成功生成。成功调试报告在注册相应触发器后立即生成并发送。 +- **详细调试报告**为与归因报告关联的归因来源和归因触发事件提供更多可见性。它们使你能够确保来源已成功注册，或跟踪丢失的报告并确定其原因（例如，由于来源或触发事件注册失败或发送或生成报告时失败）。详细调试报告在来源或触发器注册时立即发送。 + +> [!NOTE] +> 要使用调试报告，报告来源（origin）需要设置 cookie。如果配置为接收报告的来源是第三方，则该 cookie 将是[第三方 cookie](/zh-CN/docs/Web/Privacy/Third-party_cookies)，这意味着在禁用/不可用第三方 cookie 的浏览器中将无法使用调试报告。 + +### 使用调试报告 + +要使用调试报告，你需要： + +1. 在报告来源上设置 `ar_debug` cookie。在来源和触发注册期间，该 cookie 需要存在： + + ```http + Set-Cookie: ar_debug=1; SameSite=None; Secure; Path=/; HttpOnly + ``` + +2. 在与你希望为其公开调试信息的归因报告相关的所有 {{httpheader("Attribution-Reporting-Register-Source")}} 和 {{httpheader("Attribution-Reporting-Register-Trigger")}} 响应标头中设置 `debug_key` 字段。每个 `debug_key` 值必须是格式为十进制字符串的 64 位无符号整数。使每个调试键成为唯一的 ID——例如，可以将每个键设置为 cookie ID + 来源/触发时间戳（如果希望将其与旧的基于 cookie 的系统进行比较，则可以在旧系统中捕获相同的时间戳）。 + + ```json + { + "debug_key": "647775351539539" + } + ``` + + > [!NOTE] + > 使来源端的调试键与 `source_event_id` 不同，以便区分具有相同来源事件 ID 的单个报告。 + +3. 可选地，在 `Attribution-Reporting-Register-Source` 和 `Attribution-Reporting-Register-Trigger` 标头中将 `debug_reporting` 字段设置为 `true`。如果执行此操作，将生成详细的调试报告。如果不执行此操作，将生成反映你正在生成的归因报告类型（事件级或汇总）的成功调试报告。 + + ```json + { + "debug_key": "647775351539539", + "debug_reporting": true + } + ``` + +4. 设置适当的端点以接收你希望生成的调试报告。调试报告发送到报告来源中的三个单独端点： + + - 事件级成功调试报告的端点：`/.well-known/attribution-reporting/debug/report-event-attribution` + - 汇总成功调试报告的端点：`/.well-known/attribution-reporting/debug/report-aggregate-attribution` + - 详细调试报告的端点：`/.well-known/attribution-reporting/debug/verbose` + +生成的成功调试报告与归因报告相同，并包含来源端和触发器端的调试键（分别位于 `"source_debug_key"` 和 `"trigger_debug_key"` 字段中）。 + +有关更多信息和示例，请参见： + +- developers.google.com 上的[调试报告介绍](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/)（2023） +- developers.google.com 上的[设置调试报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-2/)（2023） +- developers.google.com 上的[调试宝典](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/attribution-reporting-debugging/part-3/)（2023） diff --git a/files/zh-cn/web/api/attribution_reporting_api/index.md b/files/zh-cn/web/api/attribution_reporting_api/index.md new file mode 100644 index 00000000000000..22dc0fa6fb70c8 --- /dev/null +++ b/files/zh-cn/web/api/attribution_reporting_api/index.md @@ -0,0 +1,117 @@ +--- +title: 归因报告 API +slug: Web/API/Attribution_Reporting_API +l10n: + sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef +--- + +{{SeeCompatTable}}{{securecontext_header}}{{DefaultAPISidebar("Attribution Reporting API")}} + +**归因报告 API**（Attribution Reporting API）使开发者能够衡量转化——比如当用户点击嵌入在某个网站上的广告，然后在供应商的网站上购买商品——并随后访问这些转化的报告。它在不依赖第三方跟踪 cookie 的情况下完成这一过程。 + +## 概念和用法 + +广告主通常希望衡量有多少用户看到了广告后，接着查看并购买了产品（转化）。这使他们能够了解哪些广告投放带来了最大的投资回报率（ROI），从而可以相应地调整他们的广告策略。衡量转化的过程通常包括捕捉以下数据： + +- 哪些用户进行了转化（例如购买了商品或注册了服务），以及转化的数量。 +- 他们所在的地理区域。 +- 广告投放的位置。 +- 销售了多少产品、注册了多少服务等。 +- 产生了多少收入。 + +传统上，Web 上的转化测量依赖于第三方跟踪 cookie。广告通常嵌入在网页的一个 {{htmlelement("iframe")}} 中，这样可以设置一个包含用户及其与广告互动信息的 cookie。 + +之后，当用户决定访问广告主的网站时，只要该网站来自与广告相同的域名，该网站就可以访问之前由广告设置的第三方 cookie。广告主可以将广告的数据与自己的第一方数据关联起来，以回答诸如“用户在与另一个网站的产品广告互动后是否购买了该产品？”的问题。 + +这对用户[隐私](/zh-CN/docs/Web/Privacy)不友好。在这种情况下，来自相同域名的任何页面都可以访问该 cookie，以及嵌入这些页面的网站的信息。许多方可以访问这些数据，并根据用户的浏览习惯推测其他数据。 + +归因报告 API 提供了一种保护用户隐私的广告转化测量方式。 + +### 它是如何工作的？ + +让我们通过一个例子来说明归因报告 API 的工作原理。 + +假设我们有一个在线商店 `shop.example`（即广告主），它在一个内容网站 `news.example`（即发布者）上嵌入了一个关于其产品的广告。广告内容位于 `ad.shop.example`。 + +在线商店的拥有者希望衡量从与广告互动、查看其网站上的产品页面并将产品放入购物车的用户那里获得多少转化。 + +![下面图像表示了描述的步骤](ara-flow.png) + +涉及的步骤如下： + +1. 当用户访问 `news.example` 网站时，可以为与嵌入广告的特定用户交互注册一个**归因来源**。用户可以通过多种方式与页面上的广告互动。为了使广告交互注册归因来源，广告必须发送一个带有 {{httpheader("Attribution-Reporting-Eligible")}} 标头的请求，以表明响应有资格注册归因来源。如果响应中包含适当的 {{httpheader("Attribution-Reporting-Register-Source")}} 标头，则完成归因来源的注册。归因来源可以是，例如： + - 一个链接。在这种情况下，交互是用户点击链接（直接通过 {{htmlelement("a")}} 元素，或通过 {{domxref("Window.open()")}} 调用）。通过对导航请求的响应来注册来源。 + - 一张图片，例如广告横幅或 1x1 透明跟踪像素。在这种情况下，交互是用户访问页面。图片加载时，即服务器响应图片请求时，注册来源。 + - 一个 fetch 请求（即 {{domxref("Window/fetch", "fetch()")}} 或 {{domxref("XMLHttpRequest")}}）。在这种情况下，交互可以根据你的应用程序的需要进行指定——例如，fetch 请求可以由 `click` 或 `submit` 事件触发。来源在响应返回时注册。 +2. 当归因来源交互发生时，{{httpheader("Attribution-Reporting-Register-Source")}} 标头中返回的来源数据会存储在仅浏览器可访问的私有本地缓存中。此数据包括页面和广告主可用的上下文和第一方数据、收集转化数据的广告技术公司的来源以及一个或多个期望从该广告发生转化的目标（[eTLD+1](/zh-CN/docs/Glossary/eTLD)）（即广告主的网站，例如 `shop.example`）。 +3. 当用户稍后访问 `shop.example` 时，当交互指示转化发生时，该网站可以注册一个**归因触发器**（例如，用户点击 `shop.example` 上的“添加到购物车”按钮）。浏览器将发送一个带有 {{httpheader("Attribution-Reporting-Eligible")}} 标头的请求，以表明响应有资格注册归因触发器，如果响应中包含适当的 {{httpheader("Attribution-Reporting-Register-Trigger")}} 标头，则完成注册。归因触发器可以是，例如： + - 一张图片，例如购物车图标或 1x1 透明跟踪像素。在这种情况下，交互是用户访问页面。触发器在图片加载时注册，即当服务器响应图片请求时。 + - 一个 fetch 请求（即 {{domxref("Window/fetch", "fetch()")}} 或 {{domxref("XMLHttpRequest")}}）。在这种情况下，交互可以根据你的应用程序的需要进行指定——例如，fetch 请求可以由 `click` 或 `submit` 事件触发。触发器在响应返回时注册。 +4. 当触发器归因完成后，浏览器会尝试将 [Attribution-Reporting-Register-Trigger](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger) 标头中的数据与私有本地缓存中保存的来源数据条目进行匹配（见第 2 步）。有关匹配方法和要求，请参阅[注册归因触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)。 +5. 如果找到匹配，浏览器将把报告数据发送到通常由广告技术提供商拥有的报告服务器上的端点，在那里可以安全地进行分析。与 cookie 不同，这些数据仅对你发送数据的特定网站可用——不会在其他地方共享数据。这些报告可以是： + - **事件级报告**：基于归因来源事件的报告，其中详细的来源数据与粗略的触发器数据相关联。例如，报告可能看起来像“`ad.shop.example` 上的点击 ID 200498 导致了 `shop.example` 的购买”，其中“点击 ID 200498”是详细的来源数据，“购买”是粗略的触发器数据。详细的来源数据可能包含来源页面的第一方或上下文数据，而触发器数据可能编码来自触发器页面的事件。 + - **汇总报告**：更详细的报告，结合来自来源和触发器侧的多个转化数据。例如“`news.example` 上的广告活动 ID 774653 导致了 `shop.example` 上来自意大利用户的 654 笔销售，总收入为 $9540。”汇总报告的编制需要使用聚合服务（例如 [Google 聚合服务](https://github.com/privacysandbox/aggregation-service)）。 + +有关实现上述步骤所需功能的更多信息，请参阅： + +1. [注册归因来源](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_sources) +2. [注册归因触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers) +3. [生成报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports) + +## 接口 + +归因报告 API 并未定义任何独立的接口。 + +### 其他接口的扩展 + +- {{domxref("HTMLAnchorElement.attributionSrc")}}、{{domxref("HTMLImageElement.attributionSrc")}}、{{domxref("HTMLScriptElement.attributionSrc")}} + - : `attributionSrc` 属性允许你以编程方式获取和设置 {{htmlelement("a")}}、{{htmlelement("img")}}、和 {{htmlelement("script")}} 元素上的 `attributionsrc` 属性。它反映了该属性的值。 +- {{domxref("Window/fetch", "fetch()")}} 和 {{domxref("Request.Request", "Request()")}} 构造函数中的 `attributionReporting` 选项 + - : 当通过 {{domxref("Window/fetch", "fetch()")}} 生成请求时，这表示你希望响应能够注册归因来源或触发器。 +- {{domxref("XMLHttpRequest.setAttributionReporting()")}} + - : 当通过 {{domxref("XMLHttpRequest")}} 生成请求时，这表示你希望响应能够注册归因来源或触发器。 +- {{domxref("Window.open()")}} 中的 `attributionsrc` 特性关键字 + - : 当 `open()` 方法完成时，完成归因来源的注册*并*触发浏览器存储相关的来源数据（如 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供的）。请注意，`Window.open()` 调用不能用于注册归因触发器。 + +## HTML 元素 + +- {{htmlelement("a")}}、{{htmlelement("img")}} 和 {{htmlelement("script")}}——`attributionsrc` 属性 + - : 指定你希望浏览器在相关资源请求中发送 {{httpheader("Attribution-Reporting-Eligible")}} 标头。在服务器端，此标头用于触发发送 {{httpheader("Attribution-Reporting-Register-Source")}} 或 {{httpheader("Attribution-Reporting-Register-Trigger")}} 响应标头。当注册归因来源时，这是必需的；当注册归因触发器时，只有在你希望指定与 `src` 属性指向的资源不同的注册服务器时才需要。请注意，`` 元素不能用于注册归因触发器。 + +## HTTP 标头 + +- {{httpheader("Attribution-Reporting-Eligible")}} + - : 表示相应响应有资格注册归因来源或触发器的 HTTP 请求。 +- {{httpheader("Attribution-Reporting-Register-Source")}} + - : 注册页面特性作为归因来源的 HTTP 响应。这作为对包含 `Attribution-Reporting-Eligible` 标头的请求的响应的一部分。 +- {{httpheader("Attribution-Reporting-Register-Trigger")}} + - : 注册页面特性作为归因触发器的 HTTP 响应。这作为对包含 `Attribution-Reporting-Eligible` 标头的请求的响应的一部分。 +- {{httpheader("Permissions-Policy")}} {{httpheader('Permissions-Policy/attribution-reporting','attribution-reporting')}} 指令 + - : 控制当前文档是否被允许使用归因报告。 + +## 注册和本地测试 + +要在你的网站上使用归因报告 API，你必须在[隐私沙盒注册过程](/zh-CN/docs/Web/Privacy/Privacy_sandbox/Enrollment)中指定它。如果不这样做，API 流程将在响应时被阻止，即响应标头将被忽略，来源和触发器将不会被注册。 + +你仍然可以在没有注册的情况下本地测试你的归因报告 API 代码。要允许本地测试，请启用以下 Chrome 开发者标志： + +`chrome://flags/#privacy-sandbox-enrollment-overrides` + +## 示例 + +请参阅[演示：归因报告 API](https://arapi-home.web.app/) 以获取示例实现（也可查看[源代码](https://github.com/GoogleChromeLabs/trust-safety-demo/tree/main/attribution-reporting)）。 + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [归因报告标头验证工具](https://wicg.github.io/attribution-reporting-api/validate-headers) +- developers.google.com 上的[归因报告](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/)（2023） +- developers.google.com 上的[启用转化测量](https://developers.google.com/privacy-sandbox/private-advertising/attribution-reporting/enable-conversion-measurement)（2023） +- developers.google.com 上的[隐私沙盒](https://developers.google.com/privacy-sandbox/)（2023） diff --git a/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md b/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md new file mode 100644 index 00000000000000..a29cfa83d150b3 --- /dev/null +++ b/files/zh-cn/web/api/attribution_reporting_api/registering_sources/index.md @@ -0,0 +1,287 @@ +--- +title: 注册归因来源 +slug: Web/API/Attribution_Reporting_API/Registering_sources +l10n: + sourceCommit: ec1006afdf68a5808a48ab6301f9ccff3cd7ecc2 +--- + +{{SeeCompatTable}}{{DefaultAPISidebar("Attribution Reporting API")}} + +本文解释了如何在使用[归因报告 API](/zh-CN/docs/Web/API/Attribution_Reporting_API) 时注册归因来源。 + +## 基本方法 + +归因来源的形式包括链接、图片或脚本，它们会被包含在你想要衡量交互行为的内容中（例如，想要衡量转化的广告）。当发生特定用户交互时，浏览器会将来源数据存储在一个私有的本地缓存中（仅浏览器可访问）。不同的归因来源类型有不同的注册和信号交互方式，它们可以分为以下几类： + +- 导航来源，指浏览器在响应导航时存储源数据。例如，当用户点击链接或用键盘激活它时，或者通过 {{domxref("Window.open()")}} 调用发生导航时。有关示例，请参见[基于导航的归因来源](#基于导航的归因来源)。 +- 事件来源，指浏览器在事件触发时存储源数据。有关示例，请参见[基于事件的归因来源](#基于事件的归因来源)。 + +注册来源和检索、存储来源数据的过程在这两种情况下是相同的： + +1. 当用户与归因来源进行交互时，它会在请求中发送 {{httpheader("Attribution-Reporting-Eligible")}} 标头给测量交互的服务器（通常是广告主的服务器），以表明响应有资格注册来源。例如： + + ```http + Attribution-Reporting-Eligible: navigation-source + ``` + +2. 当服务器接收到包含 `Attribution-Reporting-Eligible` 标头的请求时，它可以在响应中包含 {{httpheader("Attribution-Reporting-Register-Source")}} 标头以完成来源注册。其值是一个 JSON 字符串，提供了浏览器应存储的有关与之交互的归因来源的信息。该标头中包含的信息还决定了浏览器生成哪些类型的报告： + + - 以下示例将导致在[触发器](/zh-CN/docs/Web/API/Attribution_Reporting_API/Registering_triggers)与来源匹配时生成一个[事件级报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#事件级报告)： + + ```js + res.set( + "Attribution-Reporting-Register-Source", + JSON.stringify({ + source_event_id: "412444888111012", + destination: "https://advertiser.example", + trigger_data: [0, 1, 2, 3, 4], + trigger_data_matching: "exact", + expiry: "604800", + priority: "100", + debug_key: "122939999", + event_report_window: "86400", + }), + ); + ``` + + 在这种情况下，唯一必需的字段是 `destination`，它指定 1–3 个触发器预期触发的站点。它们用于在与触发器交互时将归因触发器与来源进行匹配。上述指定的其他字段如下： + + - `"source_event_id"`：一个表示归因来源的 ID 的字符串，可以用于在归因来源被交互时将其映射到其他信息，或在报告端点（见[生成报告 > 基本流程](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#基本流程)获取端点信息）聚合信息。 + - `"trigger_data"`：一个 32 位无符号整数数组，表示可能匹配此来源的不同触发事件的数据。例如，“用户将商品添加到购物车”或“用户注册了邮件列表”可以是触发站点上发生的事件，这些事件可以匹配此来源并表示广告主试图衡量的某种转化。它们必须与[触发器](/zh-CN/docs/Web/HTTP/Headers/Attribution-Reporting-Register-Trigger#trigger_data)中指定的 `"trigger_data"` 匹配，以便进行事件级归因。 + > [!NOTE] + > 用于表示每个事件的值，以及数组中的元素数量，都是完全任意的，由作为开发者的你定义。数组中可以包含未使用的值，但必须存在值，以便浏览器在触发器注册时将其归因于来源。 + - `"trigger_data_matching"`：一个字符串，指定如何将触发器的 `"trigger_data"` 与来源的 `"trigger_data"` 匹配。`"exact"` 是你几乎总是会使用的值，它匹配精确值。 + - `"expiry"`：一个表示归因来源过期时间的字符串，以秒为单位，过期后该源将不再有效（即，后续触发器将无法归因到此来源）。 + - `"priority"`：一个表示归因来源优先级的字符串值。有关更多信息，请参见[报告优先级和限制](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#报告优先级和限制)。 + - `"debug_key"`：一个以十进制格式表示的 64 位无符号整数，表示调试密钥。如果你希望生成一个[调试报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#调试报告)以配合关联的归因报告，则设置此项。 + - `"event_report_window"`：一个表示时间的字符串（以秒为单位），在此时间后，后续触发器将无法归因到此来源（以生成事件级报告）。 + + 参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有可用字段的详细描述。 + + - 要使浏览器在触发器匹配到来源时生成[汇总报告](/zh-CN/docs/Web/API/Attribution_Reporting_API/Generating_reports#汇总报告)，需要在生成事件级报告所需的字段*之外*，额外包含一些字段。 + + ```js + res.set( + "Attribution-Reporting-Register-Source", + JSON.stringify({ + source_event_id: "412444888111012", + destination: "https://advertiser.example", + trigger_data: [0, 1, 2, 3, 4], + trigger_data_matching: "exact", + expiry: "604800", + priority: "100", + debug_key: "122939999", + event_report_window: "86400", + + aggregation_keys: { + campaignCounts: "0x159", + geoValue: "0x5", + }, + aggregatable_report_window: "86400", + }), + ); + ``` + + 在此示例中，额外的字段包括： + + - `"aggregation_keys"`：一个包含用户提供的键的对象，表示在生成的报告值下汇总不同数据点。 + - `"aggregatable_report_window"`：一个表示时间的字符串（以秒为单位），在此时间后，触发数据将不再包含在生成的可汇总报告中。 + + 同样，请参见 {{httpheader("Attribution-Reporting-Register-Source")}} 以获取此标头中所有字段的详细描述。 + +3. 成功注册来源后，浏览器将提供的来源数据存储在其私有本地缓存中。 + +## 基于导航的归因来源 + +导航来源对于测量与链接的交互非常有用——例如，用户可能在发布者页面上看到广告，然后点击它以导航到希望发生转化的广告主的页面。 + +有几种不同类型的基于导航的归因来源（例如，点击广告）可以注册——基于 HTML 的（使用 `attributionsrc` 属性）和基于 {{domxref("Window.open()")}} 调用的（使用 `attributionsrc` 窗口特性）。 + +### 基于 HTML 的导航来源 + +要注册基于导航的归因来源，你可以将 `attributionsrc` 属性添加到适当的 {{htmlelement("a")}} 元素中，这指定了注册请求将被发送到的位置。 + +如果你将属性值留空，则注册请求将发送到链接到的位置。也可以在值中指定一个或多个额外的 URL 以发送注册请求；有关详细信息，请参见[在 attributionsrc 中指定 URL](#在_attributionsrc_中指定_url)。 + +`attributionsrc` 可以通过声明的方式添加： + +```html + + 点击访问我们的商店 + +``` + +或者通过 {{domxref("HTMLAnchorElement.attributionSrc")}} 属性： + +```js +const aElem = document.querySelector("a"); +aElem.attributionSrc = ""; +``` + +在这种情况下，交互发生时，浏览器在用户点击链接并且浏览器接收到响应时，会存储与基于导航的归因来源（如在 {{httpheader("Attribution-Reporting-Register-Source")}} 响应标头中提供的）相关的来源数据。 + +### 基于 Window.open() 的导航来源 + +你还可以将 `attributionsrc` 特性关键字添加到 {{domxref("Window.open()")}} 调用的特性属性中。在此示例中，我们在响应 `click` 事件时运行它： + +```js +elem.addEventListener("click", () => { + window.open("https://shop.example", "targetWindow", "attributionsrc"); +}); +``` + +> [!NOTE] +> 在设置像上面示例中的 [`click`](/zh-CN/docs/Web/API/Element/click_event) 事件时，建议将其设置在预期会点击的控件上，例如 {{htmlelement("button")}} 或 {{htmlelement("a")}} 元素上。这在语义上更合理，并且对屏幕阅读器和键盘用户更友好。 + +> [!NOTE] +> 要通过 `open()` 注册归因来源，必须在[瞬态激活](/zh-CN/docs/Glossary/Transient_activation)（即用户交互事件处理程序内部，如 `click`）中调用，并且必须在用户交互后的五秒内完成。 + +## 基于事件的归因来源 + +基于事件的归因来源会在某些事件——例如在 `` 或 ` + + + + + +

Page title

+ +
+
最初の節
+
二番目の節
+
+ + +``` + +その結果、リードコンテンツである `
` が解釈できるまで、文書内のレンダリングがブロックされ、一貫したビュー遷移を保証できます。 + +また、 [`media`](/ja/docs/Web/HTML/Element/link#media) 属性を `` 要素に指定することもできます。例えば、画面が狭い端末でページを読み込んだ際には、広い画面の端末で読み込む場合よりも、コンテンツのレンダリングをブロックしたい場合があるかもしれません。これは理にかなっています。モバイル端末では、デスクトップの場合よりも、ページが最初に読み込まれた際にはコンテンツが少なく表示されるからです。 + +これは、次の HTML で実現できます。 + +```html + + +``` From c9657aa0406112239eb3a60e7481fa34aa0238b7 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 8 Sep 2024 22:51:58 +0900 Subject: [PATCH 063/489] =?UTF-8?q?2024/07/27=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/pagerevealevent/index.md | 103 ++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 files/ja/web/api/pagerevealevent/index.md diff --git a/files/ja/web/api/pagerevealevent/index.md b/files/ja/web/api/pagerevealevent/index.md new file mode 100644 index 00000000000000..c5519c8a648ad2 --- /dev/null +++ b/files/ja/web/api/pagerevealevent/index.md @@ -0,0 +1,103 @@ +--- +title: PageRevealEvent +slug: Web/API/PageRevealEvent +l10n: + sourceCommit: 6336af7a3880c350919e5b29f83b938fb1594362 +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`PageRevealEvent`** イベントオブジェクトは、{{domxref("Window.pagereveal_event", "pagereveal")}} イベントのハンドラー関数内で利用できます。 + +文書間の移動中、ナビゲーションによってビュー遷移が起動された場合、移動先の文書から関連する[ビュー遷移](/ja/docs/Web/API/View_Transitions_API)（関連の {{domxref("ViewTransition")}} オブジェクトにアクセスする）を操作することができます。 + +ビュー遷移以外にも、このイベントは、開始アニメーションの起動やページビューの報告などの場合に役立ちます。これは、文書の {{htmlelement("head")}} 内で `requestAnimationFrame()` を起動した場合、文書間移動後に最初の {{domxref("Window.requestAnimationFrame()")}} が実行されるのと同じです。例えば、次の `reveal()` 関数を `` 内で実行した場合: + +```js +function reveal() { + // 開始アニメーションをここに入れる +} +/* これは、読み込んだ後にレンダリングされる最初のフレームで発行されます。 */ +requestAnimationFrame(() => reveal()); + +/* ページが BFCache から復元された場合に発行されます。 */ +window.onpagehide = () => requestAnimationFrame(() => reveal()); +``` + +## コンストラクター + +- {{domxref("PageRevealEvent.PageRevealEvent", "PageRevealEvent()")}} {{experimental_inline}} + - : 新しい `PageRevealEvent` オブジェクトのインスタンスを作成します。 + +## インスタンスプロパティ + +- {{domxref("PageRevealEvent.viewTransition", "viewTransition")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : 文書間のナビゲーションにおけるアクティブなビュー遷移を 表す {{domxref("ViewTransition")}} オブジェクトを保持しています。 + +## 例 + +```js +window.addEventListener("pagereveal", async (e) => { + // "from" 履歴項目が存在しない場合は戻る + if (!navigation.activation.from) return; + + // アクティブなビュー遷移が存在する場合のみ実行 + if (e.viewTransition) { + const fromUrl = new URL(navigation.activation.from.url); + const currentUrl = new URL(navigation.activation.entry.url); + + // プロフィールページからホームページに移動 + // ~> VT 名を関連するリストアイテムに設定 + if (isProfilePage(fromUrl) && isHomePage(currentUrl)) { + const profile = extractProfileNameFromUrl(fromUrl); + + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#${profile} span`).style.viewTransitionName = + "name"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、名前を除去 + // そうすることで、次のナビゲーションの準備ができる + await e.viewTransition.ready; + document.querySelector(`#${profile} span`).style.viewTransitionName = + "none"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "none"; + } + + // Went to profile page + // ~> Set VT names on the main title and image + if (isProfilePage(currentUrl)) { + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#detail main h1`).style.viewTransitionName = + "name"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、名前を除去 + // そうすることで、次のナビゲーションの準備ができる + await e.viewTransition.ready; + document.querySelector(`#detail main h1`).style.viewTransitionName = + "none"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "none"; + } + } +}); +``` + +> [!NOTE] +> このコードの採取元のライブデモは、[List of Chrome DevRel team members](https://view-transitions.netlify.app/profiles/mpa/) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From 39b21c739069adf48653a8ec9ca2f2a7ac6bd03b Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 8 Sep 2024 23:00:24 +0900 Subject: [PATCH 064/489] =?UTF-8?q?2024/07/25=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pagerevealevent/pagerevealevent/index.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 files/ja/web/api/pagerevealevent/pagerevealevent/index.md diff --git a/files/ja/web/api/pagerevealevent/pagerevealevent/index.md b/files/ja/web/api/pagerevealevent/pagerevealevent/index.md new file mode 100644 index 00000000000000..eeda9105249dc5 --- /dev/null +++ b/files/ja/web/api/pagerevealevent/pagerevealevent/index.md @@ -0,0 +1,42 @@ +--- +title: "PageRevealEvent: PageRevealEvent() コンストラクター" +short-title: PageRevealEvent() +slug: Web/API/PageRevealEvent/PageRevealEvent +l10n: + sourceCommit: cd809f324e890917837ebe5194c934543d4a5464 +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`PageRevealEvent()`** コンストラクターは、新しい {{domxref("PageRevealEvent")}} オブジェクトインスタンスを作成します。 + +## 構文 + +```js-nolint +new PageRevealEvent(type, init) +``` + +### 引数 + +- `type` + - : イベントの種類の表す文字列。 `PageRevealEvent` の場合は、常に `pagereveal` です。 +- `init` + - : 以下のプロパティを持つオブジェクト。 + - `viewTransition` {{optional_inline}} + - : {{domxref("ViewTransition")}} オブジェクトで、関連するナビゲーションにおけるアクティブなビュー遷移を表します。アクティブなビュー遷移がない場合は、既定で `null` となります。 + +## 例 + +開発者はこのコンストラクターを手動で使用することはありません。 {{domxref("Window.pagereveal_event", "pagereveal")}} イベントが発生した結果としてハンドラーが呼び出されたときに、新しい `PageRevealEvent` オブジェクトが構築されます。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From fd01646e67c5086930fa11653643e744629ba3e7 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 8 Sep 2024 23:07:16 +0900 Subject: [PATCH 065/489] =?UTF-8?q?2024/06/23=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../pagerevealevent/viewtransition/index.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 files/ja/web/api/pagerevealevent/viewtransition/index.md diff --git a/files/ja/web/api/pagerevealevent/viewtransition/index.md b/files/ja/web/api/pagerevealevent/viewtransition/index.md new file mode 100644 index 00000000000000..979c1b62adc4f4 --- /dev/null +++ b/files/ja/web/api/pagerevealevent/viewtransition/index.md @@ -0,0 +1,32 @@ +--- +title: "PageRevealEvent: viewTransition プロパティ" +short-title: viewTransition +slug: Web/API/PageRevealEvent/viewTransition +l10n: + sourceCommit: 722311032dbf520bf6aeba3d1f432aca38779ffd +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`viewTransition`** は {{domxref("PageRevealEvent")}} インターフェイスの読み取り専用プロパティで、文書間のナビゲーションでアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトが含まれています。 + +## 値 + +{{domxref("ViewTransition")}} オブジェクト、またはイベントが発行される際にアクティブなビュー遷移がない場合は `null`。 + +## 例 + +{{domxref("PageRevealEvent")}} のメインページを参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ナビゲーション API](/ja/docs/Web/API/Navigation_API) +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From 234e6e93f29908e6144e2ea622f3d9abfc7b83d9 Mon Sep 17 00:00:00 2001 From: Takayoshi Sawada Date: Fri, 13 Sep 2024 00:17:08 +0900 Subject: [PATCH 066/489] fix: patch webxr document for ja (#23475) fix: patch webxr document --- files/ja/web/api/webxr_device_api/fundamentals/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/ja/web/api/webxr_device_api/fundamentals/index.md b/files/ja/web/api/webxr_device_api/fundamentals/index.md index 5cd70dc45ca888..01ab96802cbb84 100644 --- a/files/ja/web/api/webxr_device_api/fundamentals/index.md +++ b/files/ja/web/api/webxr_device_api/fundamentals/index.md @@ -149,7 +149,7 @@ XR ゴーグルは、シミュレーションシーンの奥行きを再現す 没入型仮想現実のもう一つの潜在的な問題は、ユーザーがヘッドセットを装着したまま部屋の中を移動した場合、物理的な障害物に衝突してしまうことです。安全な環境でない限り、物理的な環境の中で安全だとわかっている空間をシミュレーションするなど、ユーザーの動きを制限する手がかりを提供することが重要です。 -ユーザーのヘッドセットが機器につながれている場合、ユーザーがヘッドセットのコードを引っ張ったり引っ張ったりするような動きを促したり誘惑したりしないようにするのがよいでしょう。これは、怪我を引き起こすだけでなく、ユーザーのヘッドセットまたは機器（電話かコンピュータかにかかわらず）に大きな損傷を与える可能性があります。 +ユーザーのヘッドセットが機器につながれている場合、ユーザーがヘッドセットのコードを引っ張ったりするような動きを促したり誘惑したりしないようにするのがよいでしょう。これは、怪我を引き起こすだけでなく、ユーザーのヘッドセットまたは機器（電話かコンピュータかにかかわらず）に大きな損傷を与える可能性があります。 どのようなユーザーにとっても危険な状況になる可能性があるコンテンツがある場合は、警告メッセージを表示する必要があります。同様に、可能であれば座ったままでいること、完全没入型バーチャルリアリティを体験する場合は、ヘッドセットを装着したまま動き回ることに注意するよう、ユーザーに注意を促すとよいでしょう。後悔するよりも、安全であることが一番です。 From dd2e9072ecda89dec7de7b7bcefef1a9cc4521fe Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 13 Sep 2024 08:53:09 +0800 Subject: [PATCH 067/489] build(deps): bump husky from 9.1.5 to 9.1.6 (#23524) --- package.json | 2 +- yarn.lock | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package.json b/package.json index 5caa1f10656461..0adf8aabd2276c 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "cld": "^2.10.0", "fdir": "^6.3.0", "front-matter": "^4.0.2", - "husky": "9.1.5", + "husky": "9.1.6", "lint-staged": "15.2.10", "markdown-it": "^14.1.0", "markdownlint-cli2": "0.14.0", diff --git a/yarn.lock b/yarn.lock index 752e67ea06ee4f..96df4edfd2f8dc 100644 --- a/yarn.lock +++ b/yarn.lock @@ -402,10 +402,10 @@ human-signals@^5.0.0: resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-5.0.0.tgz#42665a284f9ae0dade3ba41ebc37eb4b852f3a28" integrity sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ== -husky@9.1.5: - version "9.1.5" - resolved "https://registry.yarnpkg.com/husky/-/husky-9.1.5.tgz#2b6edede53ee1adbbd3a3da490628a23f5243b83" - integrity sha512-rowAVRUBfI0b4+niA4SJMhfQwc107VLkBUgEYYAOQAbqDCnra1nYh83hF/MDmhYs9t9n1E3DuKOrs2LYNC+0Ag== +husky@9.1.6: + version "9.1.6" + resolved "https://registry.yarnpkg.com/husky/-/husky-9.1.6.tgz#e23aa996b6203ab33534bdc82306b0cf2cb07d6c" + integrity sha512-sqbjZKK7kf44hfdE94EoX8MZNk0n7HeW37O4YrVGCF4wzgQjp+akPAkfUK5LZ6KuR/6sqeAVuXHji+RzQgOn5A== ignore@^5.2.4: version "5.2.4" From c5a252c219f22bbd5be1d0d5e5d0e84cd1ea7aec Mon Sep 17 00:00:00 2001 From: abing Date: Fri, 13 Sep 2024 10:56:27 +0800 Subject: [PATCH 068/489] zh-CN: update 'images in html' (#23515) --- .../images_in_html/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/files/zh-cn/learn/html/multimedia_and_embedding/images_in_html/index.md b/files/zh-cn/learn/html/multimedia_and_embedding/images_in_html/index.md index 4eaf45067f5a81..c0c28e44d35e30 100644 --- a/files/zh-cn/learn/html/multimedia_and_embedding/images_in_html/index.md +++ b/files/zh-cn/learn/html/multimedia_and_embedding/images_in_html/index.md @@ -306,12 +306,12 @@ window.addEventListener("load", updateCode); // 而是在当前光标位置插入一个制表符 textarea.onkeydown = (e) => { - if (e.keyCode === 9) { + if (e.code === "Tab") { e.preventDefault(); insertAtCaret("\t"); } - if (e.keyCode === 27) { + if (e.code === "Escape") { textarea.blur(); } }; @@ -370,7 +370,7 @@ textarea.onkeyup = function () { #### 自由许可 -如果图像是根据自由许可发布的，例如 [MIT](https://mit-license.org/)、[BSD](https://opensource.org/license/BSD-3-clause/) 或适当的[知识共享（CC）许可](https://creativecommons.org/choose/)，你无需支付许可费用或寻求许可即可使用它。但是，你仍需履行各种许可条件，这些条件因许可而异。 +如果图像是根据自由许可发布的，例如 [MIT](https://mit-license.org/)、[BSD](https://opensource.org/license/BSD-3-clause) 或适当的[知识共享（CC）许可](https://chooser-beta.creativecommons.org/)，你无需支付许可费用或寻求许可即可使用它。但是，你仍需履行各种许可条件，这些条件因许可而异。 例如，你可能需要： @@ -394,7 +394,7 @@ Copyleft 许可在软件界中很常见。其基本思想是使用 copyleft 许 进入公共领域的作品有时被称为“无版权保留”——它们不受版权保护，可以在未经许可且无需履行任何许可条件的情况下使用。作品可以因为版权到期或特定放弃权利等方式进入公共领域。 -将作品置于公共领域的最有效方法之一是将其许可为 [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/)，这是一种特定的创作共用许可，为此目的提供了清晰明确的法律工具。 +将作品置于公共领域的最有效方法之一是将其许可为 [CC0](https://creativecommons.org/public-domain/cc0/)，这是一种特定的创作共用许可，为此目的提供了清晰明确的法律工具。 在使用公共领域图像时，请获取证明该图像属于公共领域的证据，并将该证据保存记录。例如，使用截图记录原始来源（该来源需要清晰显示许可状态），并考虑在你的网站上添加一个页面，列出所获得的图像及其许可要求。 @@ -406,7 +406,7 @@ Copyleft 许可在软件界中很常见。其基本思想是使用 copyleft 许 某些搜索引擎会提供工具，帮助你查找具有自由许可的图像。例如，使用 Google 时，转到“图片”选项卡搜索图像，然后单击“工具”。在结果工具栏中有一个“使用权限”下拉菜单，你可以选择专门搜索根据创作共用许可授权的图像。 -图像存储库网站，例如 [Flickr](https://flickr.com/)、[ShutterStock](https://www.shutterstock.com) 和 [Pixabay](https://pixabay.com/)，具有搜索选项，允许你仅搜索具有自由许可的图像。一些网站专门分发具有自由许可的图像和图标，例如 [Picryl](https://picryl.com) 和 [The Noun Project](https://thenounproject.com/)。 +图像存储库网站，例如 [Flickr](https://flickr.com/)、[ShutterStock](https://www.shutterstock.com/) 和 [Pixabay](https://pixabay.com/)，具有搜索选项，允许你仅搜索具有自由许可的图像。一些网站专门分发具有自由许可的图像和图标，例如 [Picryl](https://picryl.com/) 和 [The Noun Project](https://thenounproject.com/)。 要想遵守图像发布的许可条件，你需要找到许可详细信息，阅读来源提供的许可证或指示页面，然后按照这些说明操作。值得信赖的图像存储库会清楚地列出其许可条件，并且易于查找。 @@ -551,12 +551,12 @@ window.addEventListener("load", updateCode); // 而是在当前光标位置插入一个制表符 textarea.onkeydown = (e) => { - if (e.keyCode === 9) { + if (e.code === "Tab") { e.preventDefault(); insertAtCaret("\t"); } - if (e.keyCode === 27) { + if (e.code === "Escape") { textarea.blur(); } }; From a6a6691053b5e22acbdf2861bb3875585d99ded2 Mon Sep 17 00:00:00 2001 From: contradiction29 Date: Mon, 9 Sep 2024 22:25:17 +0900 Subject: [PATCH 069/489] Correct notation distortion --- files/ja/learn/server-side/express_nodejs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/ja/learn/server-side/express_nodejs/index.md b/files/ja/learn/server-side/express_nodejs/index.md index cc12427f57cd2b..ea3b09f7e5f21f 100644 --- a/files/ja/learn/server-side/express_nodejs/index.md +++ b/files/ja/learn/server-side/express_nodejs/index.md @@ -20,7 +20,7 @@ Express は、JavaScript で書かれ、Node.js 実行環境内でホストさ ## ガイド -- [Express/Node の入門](/ja/docs/Learn/Server-side/Express_Nodejs/Introduction) +- [Express/Node の紹介](/ja/docs/Learn/Server-side/Express_Nodejs/Introduction) - : この最初の Express 記事では、"Node とは何ですか？"、"Express とは何ですか？" という質問に答えます。Express ウェブフレームワークが特別になった理由の概要を説明します。主な機能の概要を説明し、Express アプリケーションの主な構成要素をいくつか紹介します (ただし、現時点ではテスト用の開発環境はまだありません)。 - [Node (Express) 開発環境の設定](/ja/docs/Learn/Server-side/Express_Nodejs/development_environment) - : Express の目的がわかったので、Windows、Linux (Ubuntu)、および macOS 上で Node/Express 開発環境を設定およびテストする方法を説明します。この記事は、オペレーティングシステム共通の、Express アプリの開発を始めるために必要なものを提供します。 From fe98c353451e8d9045337240ddde56b193d23cd0 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 00:13:43 +0900 Subject: [PATCH 070/489] =?UTF-8?q?2024/07/27=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/pageswapevent/index.md | 91 +++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 files/ja/web/api/pageswapevent/index.md diff --git a/files/ja/web/api/pageswapevent/index.md b/files/ja/web/api/pageswapevent/index.md new file mode 100644 index 00000000000000..cf6867173a23e4 --- /dev/null +++ b/files/ja/web/api/pageswapevent/index.md @@ -0,0 +1,91 @@ +--- +title: PageSwapEvent +slug: Web/API/PageSwapEvent +l10n: + sourceCommit: 6336af7a3880c350919e5b29f83b938fb1594362 +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`PageSwapEvent`** イベントオブジェクトは、 {{domxref("Window.pageswap_event", "pageswap")}} イベントのハンドラー関数内で利用できます。 + +`pageswap` イベントは、前の文書がアンロードされようとしているときに、文書間を移動するときに発行されます。文書間の移動中に、`PageSwapEvent` イベントオブジェクトを使用すると、移動元の文書から関連する[ビュー遷移](/ja/docs/Web/API/View_Transitions_API)（関連する {{domxref("ViewTransition")}} オブジェクトにアクセス）を操作することができます。また、ナビゲーションの種類や現在の文書と出力先文書に関する情報にもアクセスできます。 + +## コンストラクター + +- {{domxref("PageSwapEvent.PageSwapEvent", "PageSwapEvent()")}} {{experimental_inline}} + - : 新しい `PageSwapEvent` オブジェクトインスタンスを作成します。 + +## インスタンスプロパティ + +- {{domxref("PageSwapEvent.activation", "activation")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : {{domxref("NavigationActivation")}} オブジェクトを保持しており、これは、同一オリジン内の移動に関するナビゲーション種別と、移動元および移動先の文書履歴項目が含まれています。ナビゲーションのリダイレクトチェーンのどこかにオリジンをまたぐ URL がある場合は、`null` が返されます。 +- {{domxref("PageSwapEvent.viewTransition", "viewTransition")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : 文書間のナビゲーションにおけるアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトを保持しています。 + +## 例 + +```js +window.addEventListener("pageswap", async (e) => { + // アクティブなビュー遷移が存在する場合のみ実行 + if (e.viewTransition) { + const currentUrl = e.activation.from?.url + ? new URL(e.activation.from.url) + : null; + const targetUrl = new URL(e.activation.entry.url); + + // プロフィールページからホームページへ移動 + // ~> それぞれの大きな画像とタイトル + if (isProfilePage(currentUrl) && isHomePage(targetUrl)) { + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#detail main h1`).style.viewTransitionName = + "name"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、view-transition-names を除去 + // BFCacheにページの状態が保持されたことによる名前の競合を回避 + await e.viewTransition.finished; + document.querySelector(`#detail main h1`).style.viewTransitionName = + "none"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "none"; + } + + // プロフィールページへ移動 + // ~> クリックしたアイテム + if (isProfilePage(targetUrl)) { + const profile = extractProfileNameFromUrl(targetUrl); + + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#${profile} span`).style.viewTransitionName = + "name"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、view-transition-names を除去 + // BFCacheにページの状態が保持されたことによる名前の競合を回避 + await e.viewTransition.finished; + document.querySelector(`#${profile} span`).style.viewTransitionName = + "none"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "none"; + } + } +}); +``` + +> [!NOTE] +> このコードの採取元のライブデモは、[List of Chrome DevRel team members](https://view-transitions.netlify.app/profiles/mpa/) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From a77a88a4b74f5d44e9c0fc1da40e000a01d10504 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 00:21:39 +0900 Subject: [PATCH 071/489] =?UTF-8?q?2024/07/25=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../api/pageswapevent/pageswapevent/index.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 files/ja/web/api/pageswapevent/pageswapevent/index.md diff --git a/files/ja/web/api/pageswapevent/pageswapevent/index.md b/files/ja/web/api/pageswapevent/pageswapevent/index.md new file mode 100644 index 00000000000000..50ab3ffe07a984 --- /dev/null +++ b/files/ja/web/api/pageswapevent/pageswapevent/index.md @@ -0,0 +1,44 @@ +--- +title: "PageSwapEvent: PageSwapEvent() コンストラクター" +short-title: PageSwapEvent() +slug: Web/API/PageSwapEvent/PageSwapEvent +l10n: + sourceCommit: cd809f324e890917837ebe5194c934543d4a5464 +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`PageSwapEvent()`** コンストラクターは、新しい {{domxref("PageSwapEvent")}} オブジェクトのインスタンスを作成します。 + +## 構文 + +```js-nolint +new PageSwapEvent(type, init) +``` + +### 引数 + +- `type` + - : イベントの型を表す文字列。`PageSwapEvent` の場合、これは常に `pageswap` です。 +- `init` + - : 以下のプロパティを持つオブジェクト。 + - `activation` + - : {{domxref("NavigationActivation")}} オブジェクトを保持しており、これは、同一オリジン内の移動に関するナビゲーション種別と、移動元および移動先の文書履歴項目が含まれています。ナビゲーションのリダイレクトチェーンのどこかにオリジンをまたぐ URL がある場合は、`null` が返されます。 + - `viewTransition` + - : 文書間のナビゲーションにおけるアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトを保持しています。アクティブなビュー遷移がない場合は既定で `null` です。 + +## 例 + +開発者はこのコンストラクターを手動で使用することはありません。 {{domxref("Window.pageswap_event", "pageswap")}} イベントが発生した結果としてハンドラーが呼び出されたときに、新しい `PageSwapEvent` オブジェクトが構築されます。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From b3cb32b01410f77a13b227bbc8afaf4c32962c4f Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 00:25:42 +0900 Subject: [PATCH 072/489] =?UTF-8?q?2024/06/23=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../web/api/pageswapevent/activation/index.md | 31 +++++++++++++++++++ .../api/pageswapevent/viewtransition/index.md | 31 +++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 files/ja/web/api/pageswapevent/activation/index.md create mode 100644 files/ja/web/api/pageswapevent/viewtransition/index.md diff --git a/files/ja/web/api/pageswapevent/activation/index.md b/files/ja/web/api/pageswapevent/activation/index.md new file mode 100644 index 00000000000000..7086fca5ed9def --- /dev/null +++ b/files/ja/web/api/pageswapevent/activation/index.md @@ -0,0 +1,31 @@ +--- +title: "PageSwapEvent: activation プロパティ" +short-title: activation +slug: Web/API/PageSwapEvent/activation +l10n: + sourceCommit: 722311032dbf520bf6aeba3d1f432aca38779ffd +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`activation`** は {{domxref("PageSwapEvent")}} インターフェイスの読み取り専用プロパティで、これは、同一オリジン内の移動に関するナビゲーション種別と、移動元および移動先の文書履歴項目が含む {{domxref("NavigationActivation")}} オブジェクトを保持しています。 + +## 値 + +{{domxref("NavigationActivation")}} オブジェクト、または関連するナビゲーションのリダイレクトチェーンのどこかに別オリジンの URL が含まれる場合は `null` です。 + +## 例 + +{{domxref("PageSwapEvent")}} ページを参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) diff --git a/files/ja/web/api/pageswapevent/viewtransition/index.md b/files/ja/web/api/pageswapevent/viewtransition/index.md new file mode 100644 index 00000000000000..88fcd39fc29c71 --- /dev/null +++ b/files/ja/web/api/pageswapevent/viewtransition/index.md @@ -0,0 +1,31 @@ +--- +title: "PageSwapEvent: viewTransition プロパティ" +short-title: viewTransition +slug: Web/API/PageSwapEvent/viewTransition +l10n: + sourceCommit: 722311032dbf520bf6aeba3d1f432aca38779ffd +--- + +{{APIRef("HTML DOM")}}{{SeeCompatTable}} + +**`viewTransition`** は {{domxref("PageRevealEvent")}} インターフェイスの読み取り専用プロパティで、文書間のナビゲーションにおけるアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトを保持しています。 + +## 値 + +{{domxref("ViewTransition")}} オブジェクト、またはイベントが発行される際にアクティブなビュー遷移がない場合は `null`。 + +## 例 + +{{domxref("PageSwapEvent")}} ページを参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) From 9267f7e30d0b6c83a6867d71ae3f44561834b995 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 00:39:26 +0900 Subject: [PATCH 073/489] =?UTF-8?q?2024/07/27=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../web/api/window/pagereveal_event/index.md | 102 +++++++++++++++++ .../ja/web/api/window/pageswap_event/index.md | 105 ++++++++++++++++++ 2 files changed, 207 insertions(+) create mode 100644 files/ja/web/api/window/pagereveal_event/index.md create mode 100644 files/ja/web/api/window/pageswap_event/index.md diff --git a/files/ja/web/api/window/pagereveal_event/index.md b/files/ja/web/api/window/pagereveal_event/index.md new file mode 100644 index 00000000000000..f5850fbf4db6a7 --- /dev/null +++ b/files/ja/web/api/window/pagereveal_event/index.md @@ -0,0 +1,102 @@ +--- +title: "Window: pagereveal イベント" +short-title: pagereveal +slug: Web/API/Window/pagereveal_event +l10n: + sourceCommit: e561fa67af347b9770b359ba93e8579d2a540682 +--- + +{{APIRef("HTML DOM")}}{{seecompattable}} + +**`pagereveal`** イベントは、ネットワークから新しい文書を読み込んだり、文書（[バック/フォワードキャッシュ](/ja/docs/Glossary/bfcache) (bfcache) または[事前レンダリング](/ja/docs/Glossary/Prerender)）をアクティブにしたりして、文書が最初にレンダリングされたときに発行されます。 + +これは、文書間 (MPA) の移動の[ビュー遷移](/ja/docs/Web/API/View_Transitions_API)において、移動の流入ページからのアクティブな遷移を操作する場合に便利です。例えば、遷移をスキップしたり、JavaScript で流入遷移アニメーションをカスタマイズしたりしたい場合などです。 + +## 構文 + +このイベント名を {{domxref("EventTarget.addEventListener", "addEventListener()")}} 等のメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。 + +```js +addEventListener("pagereveal", (event) => {}); +onpagereveal = (event) => {}; +``` + +## イベント型 + +{{domxref("PageRevealEvent")}} です。{{domxref("Event")}} を継承しています。 + +{{InheritanceDiagram("PageRevealEvent")}} + +## インスタンスプロパティ + +- {{domxref("PageRevealEvent.viewTransition")}} {{ReadOnlyInline}} +- : イベントが発生したときに、アクティブなものがあれば、文書間のナビゲーションにおけるアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトを返します。それ以外の場合は `null` を返します。 + +## 例 + +```js +window.addEventListener("pagereveal", async (e) => { + // "from" 履歴項目が存在しない場合は戻る + if (!navigation.activation.from) return; + + // アクティブなビュー遷移が存在する場合のみ実行 + if (e.viewTransition) { + const fromUrl = new URL(navigation.activation.from.url); + const currentUrl = new URL(navigation.activation.entry.url); + + // プロフィールページからホームページに移動 + // ~> VT 名を関連するリストアイテムに設定 + if (isProfilePage(fromUrl) && isHomePage(currentUrl)) { + const profile = extractProfileNameFromUrl(fromUrl); + + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#${profile} span`).style.viewTransitionName = + "name"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、名前を除去 + // そうすることで、次のナビゲーションの準備ができる + await e.viewTransition.ready; + document.querySelector(`#${profile} span`).style.viewTransitionName = + "none"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "none"; + } + + // プロフィールページに移動 + // ~> VT 名をメインタイトルと画像に設定 + if (isProfilePage(currentUrl)) { + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#detail main h1`).style.viewTransitionName = + "name"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、名前を除去 + // そうすることで、次のナビゲーションの準備ができる + await e.viewTransition.ready; + document.querySelector(`#detail main h1`).style.viewTransitionName = + "none"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "none"; + } + } +}); +``` + +> [!NOTE] +> このコードの採取元のライブデモは、[List of Chrome DevRel team members](https://view-transitions.netlify.app/profiles/mpa/) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API の使用](/ja/docs/Web/API/View_Transitions_API/Using) +- {{domxref("Window.pageswap_event", "pageswap")}} event diff --git a/files/ja/web/api/window/pageswap_event/index.md b/files/ja/web/api/window/pageswap_event/index.md new file mode 100644 index 00000000000000..c72cf4754ec42d --- /dev/null +++ b/files/ja/web/api/window/pageswap_event/index.md @@ -0,0 +1,105 @@ +--- +title: "Window: pageswap イベント" +short-title: pageswap +slug: Web/API/Window/pageswap_event +l10n: + sourceCommit: e561fa67af347b9770b359ba93e8579d2a540682 +--- + +{{APIRef("HTML DOM")}}{{seecompattable}} + +**`pageswap`** イベントは、文書間の移動時、つまり前回表示していた文書がアンロードされようとする際に発行されます。 + +これは、文書間 (MPA) の[ビュー遷移](/ja/docs/Web/API/View_Transitions_API)において、移動の流出ページからアクティブな遷移を操作する場合に便利です。例えば、遷移をスキップしたり、JavaScript で流出遷移のアニメーションをカスタマイズしたい場合などです。 + +また、ナビゲーションの種類や、移動元及び移動先文書内の履歴項目にアクセスすることもできます。 + +## 構文 + +このイベント名を {{domxref("EventTarget.addEventListener", "addEventListener()")}} 等のメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。 + +```js +addEventListener("pageswap", (event) => {}); +onpageswap = (event) => {}; +``` + +## イベント型 + +{{domxref("PageSwapEvent")}} です。{{domxref("Event")}} を継承しています。 + +{{InheritanceDiagram("PageSwapEvent")}} + +## インスタンスプロパティ + +- {{domxref("PageSwapEvent.activation")}} {{ReadOnlyInline}} + - : 同一オリジン内の移動に関するナビゲーション種別と、移動元および移動先の文書履歴項目を含む {{domxref("NavigationActivation")}} オブジェクトを返します。ナビゲーションのリダイレクトチェーンのどこかにオリジンをまたぐ URL がある場合は、`null` が返されます。 +- {{domxref("PageSwapEvent.viewTransition")}} {{ReadOnlyInline}} + - : イベント発生時にアクティブなものがあれば、文書間のナビゲーションにおけるアクティブなビュー遷移を表す {{domxref("ViewTransition")}} オブジェクトを返します。そうでない場合は `null` を返します。 + +## 例 + +```js +window.addEventListener("pageswap", async (e) => { + // アクティブなビュー遷移が存在する場合のみ実行 + if (e.viewTransition) { + const currentUrl = e.activation.from?.url + ? new URL(e.activation.from.url) + : null; + const targetUrl = new URL(e.activation.entry.url); + + // プロフィールページからホームページへ移動 + // ~> それぞれの大きな画像とタイトル + if (isProfilePage(currentUrl) && isHomePage(targetUrl)) { + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#detail main h1`).style.viewTransitionName = + "name"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、view-transition-names を除去 + // BFCacheにページの状態が保持されたことによる名前の競合を回避 + await e.viewTransition.finished; + document.querySelector(`#detail main h1`).style.viewTransitionName = + "none"; + document.querySelector(`#detail main img`).style.viewTransitionName = + "none"; + } + + // プロフィールページへ移動 + // ~> クリックしたアイテム + if (isProfilePage(targetUrl)) { + const profile = extractProfileNameFromUrl(targetUrl); + + // view-transition-name の値をアニメーションする要素に設定 + document.querySelector(`#${profile} span`).style.viewTransitionName = + "name"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "avatar"; + + // スナップショットが採られた後、view-transition-names を除去 + // BFCacheにページの状態が保持されたことによる名前の競合を回避 + await e.viewTransition.finished; + document.querySelector(`#${profile} span`).style.viewTransitionName = + "none"; + document.querySelector(`#${profile} img`).style.viewTransitionName = + "none"; + } + } +}); +``` + +> [!NOTE] +> このコードの採取元のライブデモは、[List of Chrome DevRel team members](https://view-transitions.netlify.app/profiles/mpa/) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ビュー遷移 API の使用](/ja/docs/Web/API/View_Transitions_API/Using) +- {{domxref("Window.pagereveal_event", "pagereveal")}} イベント From 016bf4ba10f439200b24690d0770eb97b1317ce9 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 00:58:57 +0900 Subject: [PATCH 074/489] =?UTF-8?q?Web=20API=E3=81=AE=E6=97=A5=E6=9C=AC?= =?UTF-8?q?=E8=AA=9E=E7=B4=A2=E5=BC=95=E3=82=92=E6=8B=A1=E5=85=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/index.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/files/ja/web/api/index.md b/files/ja/web/api/index.md index d6f2f9cdd4d079..09fc63ecdcc4c7 100644 --- a/files/ja/web/api/index.md +++ b/files/ja/web/api/index.md @@ -5,30 +5,63 @@ l10n: sourceCommit: 387d0d4d8690c0d2c9db1b85eae28ffea0f3ac1f --- -ウェブのコードを書く時は、数多くの Web API が利用できます。以下に、ウェブアプリやサイトを開発する際に利用することができる可能性があるすべてのインターフェイス（オブジェクト型）のリストを挙げます。j +ウェブのコードを書く時は、数多くの Web API が利用できます。以下に、ウェブアプリやサイトを開発する際に利用することができる可能性があるすべてのインターフェイス（オブジェクト型）のリストを挙げます。 Web API は通常 JavaScript とともに使用されますが、常にそうとは限りません。 -## API 日本語索引 +## API 仕様書日本語索引 ### ア - [位置情報 API](/ja/docs/Web/API/Geolocation_API) +- [IndexedDB](/ja/docs/Web/API/IndexedDB_API) +- [ウィンドウ制御 API](/ja/docs/Web/API/Window_Management_API) +- [ウィンドウ制御オーバーレイ API](/ja/docs/Web/API/Window_Controls_Overlay_API) +- [ウェブ音声 API](/ja/docs/Web/API/Web_Speech_API) ### カ - [CSS カウンタースタイル](/ja/docs/Web/API/CSS_Counter_Styles) +- [画面起動ロック API](/ja/docs/Web/API/Screen_Wake_Lock_API) +- [ウェブ共有 API](/ja/docs/Web/API/Web_Share_API) +- [決済ハンドラー API](/ja/docs/Web/API/Payment_Handler_API) +- [決済リクエスト API](/ja/docs/Web/API/Payment_Request_API) +- [権限 API](/ja/docs/Web/API/Permissions_API) - [交差オブザーバー API](/ja/docs/Web/API/Intersection_Observer_API) +### サ + +- [ストレージ API](/ja/docs/Web/API/Storage_API) +- [ストレージアクセス API](/ja/docs/Web/API/Storage_Access_API) +- [センサー API](/ja/docs/Web/API/Sensor_APIs) + ### タ +- [通知 API](/ja/docs/Web/API/Notifications_API) +- [ウェブ定期バックグラウンド同期 API](/ja/docs/Web/API/Web_Periodic_Background_Synchronization_API) - [DOM](/ja/docs/Web/API/Document_Object_Model) +### ナ + +- [ネットワーク情報 API](/ja/docs/Web/API/Network_Information_API) + ### ハ +- [バックグラウンド同期 API](/ja/docs/Web/API/Background_Synchronization_API) +- [バックグラウンドフェッチ API](/ja/docs/Web/API/Background_Fetch_API) +- [バッジ API](/ja/docs/Web/API/Badging_API) +- [パフォーマンス API](/ja/docs/Web/API/Performance_API) +- [ビュー遷移 API](Web/API/View_Transitions_API) - [フェッチ API](/ja/docs/Web/API/Fetch_API) +- [プッシュ通知 API](/ja/docs/Web/API/Push_API) +- [プレゼンテーション API](/ja/docs/Web/API/Presentation_API) + +### マ + +- [ウェブ MIDI API](/ja/docs/Web/API/Web_MIDI_API) +- [メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Capture_and_Streams_API) ## 仕様書 From d3c40f51d3bffdcde594fadbcf0bad11f88c8c30 Mon Sep 17 00:00:00 2001 From: familyboat <84062528+familyboat@users.noreply.github.com> Date: Sat, 14 Sep 2024 10:01:24 +0800 Subject: [PATCH 075/489] zh-cn: Update learn html (#23486) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: A1lo --- files/zh-cn/learn/html/index.md | 36 +++++++++++++++++---------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/files/zh-cn/learn/html/index.md b/files/zh-cn/learn/html/index.md index 56cf6e76a7ff29..95e4965614ffc7 100644 --- a/files/zh-cn/learn/html/index.md +++ b/files/zh-cn/learn/html/index.md @@ -1,41 +1,43 @@ --- -title: 使用 HTML 组织网站内容 +title: 使用 HTML 构建 Web slug: Learn/HTML +l10n: + sourceCommit: 26e2f9883e0e73def04c0e86fec6da3ec42e66b3 --- {{LearnSidebar}} -为了创建一个网站，你需要了解 {{Glossary('HTML')}}——一项用于定义网页结构的基本技术。HTML 用于标识你的网页内容是应该被解析为段落、列表、头部、链接、图像、多媒体播放器、表单或是其他众多可用的元素之一，亦或是你定义的新元素。 +构建网站时，你应该了解 {{Glossary('HTML')}}——用于定义网页结构的基本技术。HTML 用于指定你的网页内容应被识别为段落、列表、标题、链接、图像、多媒体播放器、表单或是其他可用元素之一，甚至是你定义的新元素。 -## 须知 +## 前提 -在开始这个主题的学习之前，你至少要基本熟悉使用电脑和被动地使用网络（即单纯地查看内容）。你应该设置好一个基础的工作环境，详细参照[安装基础软件](/zh-CN/docs/Learn/Getting_started_with_the_web/Installing_basic_software)，并且理解如何新建和管理文件，详细参照[文件处理](/zh-CN/docs/Learn/Getting_started_with_the_web/Dealing_with_files)——这两者都在 [web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)的零基础模块里。 +在开始本主题之前，你应该至少熟悉如何使用电脑，如何被动地使用 Web（例如，只是浏览和消费内容）。你应该按照[安装基本软件](/zh-CN/docs/Learn/Getting_started_with_the_web/Installing_basic_software)中的详细内容搭建基本的工作环境，以及按照[处理文件](/zh-CN/docs/Learn/Getting_started_with_the_web/Dealing_with_files)中的内容理解如何创建和管理文件——这两个都是 [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)纯新手模块的一部分。 -在尝试学习这个主题之前，建议先完成 [web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)主题，不过这并不是必要的。[HTML 基础](/zh-CN/docs/Learn/Getting_started_with_the_web/HTML_basics)里大多数的文章在 [HTML 介绍](/zh-CN/docs/Learn/HTML/Introduction_to_HTML)中也有涉及，不过要详细得多。 +在开始本主题之前，还是建议你先学习 [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web)。不过，这并不是绝对必要的；[HTML 基础](/zh-CN/docs/Learn/Getting_started_with_the_web/HTML_basics)这篇文章中涉及的大部分内容在 [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML)模块中也有所涉及，而且更详细。 -在学习了 HTML 之后，你就可以继续学习其他进阶主题了，例如： +学习 HTML 后，你可以继续学习更高级的主题，例如： -- [CSS](/zh-CN/docs/Learn/CSS)，以及如何用它装饰 HTML (例如：更改你的文本字号和字体，添加边框和阴影，将你的页面设计成多栏布局，添加动画和其他视觉效果。) -- [JavaScript](/zh-CN/docs/Learn/JavaScript)，以及如何用它为网页添加动态功能（例如：找到并在地图上绘制出你的地址，触发按钮时让 UI 元素显示或消失，将用户的数据本地储存在他们的电脑里等等。） +- [CSS](/zh-CN/docs/Learn/CSS)，以及如何使用它为 HTML 添加样式（例如，更改文本大小和使用的字体、添加边框和阴影、使用多列布局页面，添加动画和其他视觉效果）。 +- [JavaScript](/zh-CN/docs/Learn/JavaScript)，以及如何使用它为 Web 页面添加动态功能（例如，查找你的位置并在地图上标记、切换按钮时让 UI 元素出现/消失、在用户的电脑上本地保存用户数据，等等）。 ## 模块 -这个主题由包含以下模块，建议从第一个开始，按顺序进行学习。 +本主题包含以下模块，建议按顺序学习。你应该从第一个模块开始。 -- [HTML 介绍](/zh-CN/docs/Learn/HTML/Introduction_to_HTML) - - : 这一模块将为你铺路，帮你习惯一些重要的概念和语法，着眼于如何对文本应用 HTML，创造超链接，以及使用 HTML 构造一个网页。 +- [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML) + - : 这个模块为学习 HTML 奠定了基础，让你熟悉重要的概念和语法，了解如何在文本中应用 HTML，如何创建超链接以及如何使用 HTML 构建网页结构。 - [多媒体和嵌入](/zh-CN/docs/Learn/HTML/Multimedia_and_embedding) - - : 这个模块带你探索如何使用 HTML 在你的网页里如何包含多媒体信息，例如用各种方法包含图片，以及嵌入视频、音频，甚至是嵌入其他完整的网页。 + - : 这个模块探讨如何使用 HTML 在网页中包含多媒体内容，包括：包含图像的不同方式，以及如何嵌入视频、音频，甚至整个其他网页。 - [HTML 表格](/zh-CN/docs/Learn/HTML/Tables) - - : 在网页上用易于理解和{{glossary("Accessibility", "无障碍")}}的方式来表示表格数据是一项挑战。这个模块包括了基本的表格标记及更多复杂的特性，例如实现标题和总结。 + - : 在网页上以易于理解、{{glossary("Accessibility", "无障碍")}}的方式表示表格数据可能是个挑战。这个模块涵盖基本的表格标记，以及更复杂的特性（诸如实现标题和摘要）。 ## 解决常见的 HTML 问题 -[使用 HTML 解决常见问题](/zh-CN/docs/Learn/HTML/Howto)提供了一系列在创建网页过程中可能遇到的常见问题的解决方案：处理标题，添加图片或视频，强调内容，创建一个基础表单等等。 +[使用 HTML 解决常见问题](/zh-CN/docs/Learn/HTML/Howto)提供了用于解释如何使用 HTML 解决创建网页时非常常见的问题的内容的链接：处理标题、添加图像或视频、强调内容、创建基本表单，等等。 ## 参见 -- [web 表单](/zh-CN/docs/Learn/Forms) - - : 本模块提供了一系列文章以助你掌握 web 表单的要领。web 表单是一种非常强大的用户交互工具--其最常见的应用是收集用户的数据，或允许他们控制用户界面。然而，由于历史和技术原因，想要充分发挥他们的潜能并不是一件易事。本模块将介绍 web 表单的所有基本要素，包括标记其 HTML 结构、表单控件的样式、验证表单数据以及向服务器提交数据。 +- [Web 表单](/zh-CN/docs/Learn/Forms) + - : 这个模块提供的系列文章意在帮助你掌握 Web 表单的基本知识。Web 表单是用于和用户交互的强大工具——其常用于收集用户数据和控制用户界面。然而，由于历史和技术原因，如何发挥 Web 表单的全部潜力并不总是显而易见的。我们将涵盖 Web 表单的全部基本内容，包括：标记表单的 HTML 结构、为表单控件添加样式、验证表单数据，以及向服务器提交数据。 - [MDN 上的 HTML（超文本标记语言）](/zh-CN/docs/Web/HTML) - - : MDN 上 HTML 相关参考文档的主入口，涵盖了详细的元素和属性参考——比如说如果你想知道一个元素有什么属性或者一个属性有什么值，此页面是一个查询它们的好地方。 + - : 这是 MDN 上 HTML 参考文档的主要入口，包括详细的元素和属性参考——如果你想了解一个元素有什么属性或者一个属性有什么值，这是个很好的去处。 From b62fddadf1752b69604ee01b0952325f2c188955 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 10 Sep 2024 23:58:14 +0900 Subject: [PATCH 076/489] =?UTF-8?q?2024/08/08=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/css/@view-transition/index.md | 105 +++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 files/ja/web/css/@view-transition/index.md diff --git a/files/ja/web/css/@view-transition/index.md b/files/ja/web/css/@view-transition/index.md new file mode 100644 index 00000000000000..9668854da208b4 --- /dev/null +++ b/files/ja/web/css/@view-transition/index.md @@ -0,0 +1,105 @@ +--- +title: "@view-transition" +slug: Web/CSS/@view-transition +l10n: + sourceCommit: b60bc79c7ad36c56dddf6760d2fd4dbb642d2023 +--- + +{{CSSRef}}{{SeeCompatTable}} + +**`@view-transition`** は [CSS](/ja/docs/Web/CSS) の[アットルール](/ja/docs/Web/CSS/At-rule)で、文書間のナビゲーションの場合に、移動元及び移動先の文書で[ビュー遷移](/ja/docs/Web/API/View_Transitions_API)を行うように指定するために使用します。 + +文書間のビュー遷移を機能させるには、ナビゲーションの移動元と移動先の文書が同じオリジンにある必要があります。 + +## 構文 + +```css +@view-transition { + navigation: auto; +} +``` + +### 記述子 + +- `navigation` + + - : このアットルールが文書内のビュー遷移の動作に与える効果を指定します。 可能な値は以下のとおりです。 + + - `auto`: この文書でビュー遷移が発生するのは、同一オリジン内のナビゲーションで、オリジン間リダイレクトがなく、{{domxref("NavigateEvent.navigationType", "navigationType")}} が`traverse`、`push`、`replace` のいずれかである場合です。`push` または `replace` の場合、ナビゲーションはブラウザーの UI 機能ではなく、ページコンテンツを操作するユーザーによって開始されたものでなければなりません。 + + - `none`: この文書でビュー遷移は発生しません。 + +## 形式文法 + +{{csssyntax}} + +## 例 + +### ページビューの遷移 + +以下のコードスニペットは、ページ遷移のデモで使用される主要な概念を示しています。 +このデモでは、文書間のビュー遷移を使用しています。これは、同一サイトの 2 つのページ間を移動する際に発生する 0.5 秒の遷移です。 +デモ全体については、[View transitions multi-page app demo](https://mdn.github.io/dom-examples/view-transitions/mpa/) をご覧ください。 + +`@view-transition` アットルールは、ナビゲーションの移動元と移動先の両方の文書内の CSS で指定することで、ビュー遷移が有効になります。 + +```css +@view-transition { + navigation: auto; +} +``` + +`@view-transition` アットルールに加えて、2 つの {{cssxref("@keyframes")}} アニメーションを定義し、{{cssxref("animation")}} 一括指定プロパティを使用して、アニメーションさせたい流出側 ({{cssxref("::view-transition-old()")}}) および流入側 ({{cssxref("::view-transition-new()")}}) ページの要素にそれらのキーフレームアニメーションを適用します。 + +```css +/* 独自アニメーションの作成 */ +@keyframes move-out { + from { + transform: translateY(0%); + } + + to { + transform: translateY(-100%); + } +} + +@keyframes move-in { + from { + transform: translateY(100%); + } + + to { + transform: translateY(0%); + } +} + +/* 独自アニメーションを新旧のページ状態に適用 */ +::view-transition-old(root) { + animation: 0.4s ease-in both move-out; +} + +::view-transition-new(root) { + animation: 0.4s ease-in both move-in; +} +``` + +[transitions multi-page app](https://mdn.github.io/dom-examples/view-transitions/mpa/) デモをライブで参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{cssxref("::view-transition", "::view-transition")}} +- {{cssxref("::view-transition-new", "::view-transition-new()")}} +- {{cssxref("::view-transition-old", "::view-transition-old()")}} +- {{cssxref("::view-transition-group", "::view-transition-group()")}} +- {{cssxref("::view-transition-image-pair", "::view-transition-image-pair()")}} +- [ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) +- [CSS アットルール](/ja/docs/Web/CSS/At-rule) +- [CSS アットルール関数](/ja/docs/Web/CSS/At-rule_functions) From 19adf180a334b3ea5fbfb78390fde98e01e77922 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 00:07:22 +0900 Subject: [PATCH 077/489] =?UTF-8?q?2024/08/07=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../ja/web/css/css_view_transitions/index.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 files/ja/web/css/css_view_transitions/index.md diff --git a/files/ja/web/css/css_view_transitions/index.md b/files/ja/web/css/css_view_transitions/index.md new file mode 100644 index 00000000000000..6e2ca003f7cc8b --- /dev/null +++ b/files/ja/web/css/css_view_transitions/index.md @@ -0,0 +1,80 @@ +--- +title: CSS ビュー遷移 +slug: Web/CSS/CSS_view_transitions +l10n: + sourceCommit: ef793e5764cf3b6371f275233a8e278e692d2ff8 +--- + +{{CSSRef}} + +**CSS ビュー遷移**モジュールは、[ビュー遷移 API](/ja/docs/Web/API/View_Transitions_API) の動作を定義します。これにより、開発者は文書内の異なる状態間や文書間でアニメーションする遷移を作成することができます。このモジュールは、これらの遷移をスタイル設定するための CSS プロパティと擬似要素も定義します。 + +## リファレンス + +### プロパティ + +- {{cssxref("view-transition-name")}} {{experimental_inline}} + +> [!NOTE] +> このモジュールでは、`view-transition-class` プロパティも定義していますが、いまのところ、どのブラウザーも対応していません。 + +### アットルールと記述子 + +- {{cssxref("@view-transition")}} + - [`navigation`](/ja/docs/Web/CSS/@view-transition#navigation) 記述子 + +### セレクターと擬似要素 + +- {{cssxref("::view-transition")}} {{experimental_inline}} +- {{cssxref("::view-transition-image-pair()")}} {{experimental_inline}} +- {{cssxref("::view-transition-group()")}} {{experimental_inline}} +- {{cssxref("::view-transition-new()")}} {{experimental_inline}} +- {{cssxref("::view-transition-old()")}} {{experimental_inline}} + +> [!NOTE] +> このモジュールでは、`:active-view-transition` および `:active-view-transition-type()` 擬似クラスも定義していますが、いまのところ、どのブラウザーも対応していません。 + +### インターフェイス + +- {{domxref("CSSViewTransitionRule")}} +- {{domxref("ViewTransition")}} + - {{domxref("ViewTransition.skipTransition()")}} メソッド + - {{domxref("ViewTransition.updateCallbackDone")}} + - {{domxref("ViewTransition.ready")}} + - {{domxref("ViewTransition.finished")}} +- {{domxref("Document.startViewTransition()")}} メソッド + +## ガイド + +- [ビュー遷移 API の使用](/ja/docs/Web/API/View_Transitions_API/Using) + + - : ビュー遷移を作成する方法と、ビュー遷移のアニメーションをカスタマイズする方法について説明します。アクティブなビュー遷移の操作方法についても記載しています。 + +## 関連概念 + +- {{domxref("PageRevealEvent", "pagereveal")}} イベント +- {{domxref("PageSwapEvent", "pageswap")}} イベント +- {{domxref("Document.visibilityState")}} + +- [CSS アニメーション](/ja/docs/Web/CSS/CSS_animations)モジュール + + - {{cssxref("animation")}} + - {{cssxref("@keyframes")}} + - {{domxref("CSSKeyframesRule")}} + - {{domxref("CSSStyleRule")}} + - [ウェブアニメーション API](/ja/docs/Web/API/Web_Animations_API) + +- [CSS 座標変換](/ja/docs/Web/CSS/CSS_transforms)モジュール + + - {{cssxref("transform")}} + - {{cssxref("transform-function")}} + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- [擬似要素](/ja/docs/Web/CSS/Pseudo-elements) +- [関数擬似クラス](/ja/docs/Web/CSS/Pseudo-classes#関数擬似クラス) +- [CSS の構成要素: 擬似クラスと擬似要素](/ja/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements) From 1a9bc00e01330731bdb5713e1980b009d506190e Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 00:19:56 +0900 Subject: [PATCH 078/489] =?UTF-8?q?API=E5=90=8D=E3=81=AE=E6=8F=BA=E3=82=8C?= =?UTF-8?q?=E3=82=92=E7=B5=B1=E4=B8=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/document/index.md | 2 +- files/ja/web/api/document/startviewtransition/index.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/files/ja/web/api/document/index.md b/files/ja/web/api/document/index.md index 5b55b0c99423f7..9d88342ea53b50 100644 --- a/files/ja/web/api/document/index.md +++ b/files/ja/web/api/document/index.md @@ -263,7 +263,7 @@ _このインターフェイスは、{{DOMxRef("Node")}} インターフェイ - {{DOMxRef("Document.requestStorageAccessFor()")}} {{experimental_inline}} - : 最上位のサイトが、同じ[関連ウェブサイト設定](/ja/docs/Web/API/Storage_Access_API/Related_website_sets)内の別のウェブサイトから発信された埋め込みコンテンツの代わりに、サードパーティクッキーへのアクセスをリクエストできるようにします。 - {{domxref("Document.startViewTransition()")}} - - : 新しい{{domxref("View Transitions API", "ビュートランジション", "", "nocode")}}を開始し、それを表すための {{domxref("ViewTransition")}} オブジェクトを返します。 + - : 新しい{{domxref("View Transitions API", "ビュー遷移", "", "nocode")}}を開始し、それを表すための {{domxref("ViewTransition")}} オブジェクトを返します。 `Document` インターフェイスは、{{DOMxRef("XPathEvaluator")}} インターフェイスによって拡張されています。 diff --git a/files/ja/web/api/document/startviewtransition/index.md b/files/ja/web/api/document/startviewtransition/index.md index 88d3ded5d6ff3d..e34846e619decc 100644 --- a/files/ja/web/api/document/startviewtransition/index.md +++ b/files/ja/web/api/document/startviewtransition/index.md @@ -8,9 +8,9 @@ l10n: {{APIRef("View Transitions API")}} -**`startViewTransition()`** は {{domxref("Document")}} インターフェイスのメソッドで、新しいビュートランジションを始め、それを表す {{domxref("ViewTransition")}} オブジェクトを返します。 +**`startViewTransition()`** は {{domxref("Document")}} インターフェイスのメソッドで、新しいビュー遷移を始め、それを表す {{domxref("ViewTransition")}} オブジェクトを返します。 -`startViewTransition()` を呼び出すと、[ビュートランジションのプロセス](/ja/docs/Web/API/View_Transitions_API#ビュートランジションのプロセス)で説明されている一連の手順が続きます。 +`startViewTransition()` を呼び出すと、[ビュー遷移のプロセス](/ja/docs/Web/API/View_Transitions_API#ビュー遷移のプロセス)で説明されている一連の手順が続きます。 ## 構文 @@ -22,7 +22,7 @@ startViewTransition(updateCallback) ### 引数 - `updateCallback` {{optional_inline}} - - : 通常、ビュートランジションプロセス中に DOM を更新するために呼び出されるオプションのコールバック関数で、プロミス ({{jsxref("Promise")}}) を返します。コールバックは、 API が現在のページのスクリーンショットを導いたら呼び出されます。コールバックが返すプロミスが履行されると、次のフレームでビュートランジションが始まります。コールバックが返すプロミスが拒否された場合、トランジションは放棄されます。 + - : 通常、ビュー遷移プロセス中に DOM を更新するために呼び出されるオプションのコールバック関数で、プロミス ({{jsxref("Promise")}}) を返します。コールバックは、 API が現在のページのスクリーンショットを導いたら呼び出されます。コールバックが返すプロミスが履行されると、次のフレームでビュー遷移が始まります。コールバックが返すプロミスが拒否された場合、トランジションは放棄されます。 ### 返値 @@ -32,7 +32,7 @@ startViewTransition(updateCallback) ### 基本的な使用方法 -[基本的なビュートランジションのデモ](https://mdn.github.io/dom-examples/view-transitions/)では、 `updateView()` 関数はビュートランジション API に対応しているブラウザーと対応していないブラウザーの両方に対応しています。対応しているブラウザーで、返値を気にせずにビュートランジションのプロセスを設定するには `startViewTransition()` を呼び出します。 +[基本的なビュー遷移のデモ](https://mdn.github.io/dom-examples/view-transitions/)では、 `updateView()` 関数はビュー遷移 API に対応しているブラウザーと対応していないブラウザーの両方に対応しています。対応しているブラウザーで、返値を気にせずにビュー遷移のプロセスを設定するには `startViewTransition()` を呼び出します。 ```js function updateView(event) { From 253101131034646f1db5314e9c6c4e0cba392717 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 00:09:36 +0900 Subject: [PATCH 079/489] =?UTF-8?q?2024/08/27=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/css/css_pseudo-elements/index.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/files/ja/web/css/css_pseudo-elements/index.md b/files/ja/web/css/css_pseudo-elements/index.md index 2ffb120439a98d..dbc5d03b0ff446 100644 --- a/files/ja/web/css/css_pseudo-elements/index.md +++ b/files/ja/web/css/css_pseudo-elements/index.md @@ -2,7 +2,7 @@ title: CSS 擬似要素 slug: Web/CSS/CSS_pseudo-elements l10n: - sourceCommit: cebbd9095ac12557c55157355181672027fffc14 + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 --- {{CSSRef}} @@ -61,7 +61,6 @@ l10n: - {{cssxref("::cue")}} - {{cssxref("::cue", "::cue()")}} - - {{cssxref("::cue-region")}} - [CSS スコープ化](/ja/docs/Web/CSS/CSS_scoping)モジュール @@ -74,6 +73,14 @@ l10n: - {{CSSXref("::part")}} +- [CSS ビュー遷移](/ja/docs/Web/CSS/CSS_view_transitions)モジュール + + - {{cssxref("::view-transition")}} {{Experimental_Inline}} + - {{cssxref("::view-transition-image-pair()")}} {{Experimental_Inline}} + - {{cssxref("::view-transition-group()")}} {{Experimental_Inline}} + - {{cssxref("::view-transition-new()")}} {{Experimental_Inline}} + - {{cssxref("::view-transition-old()")}} {{Experimental_Inline}} + - [CSS セレクター](/ja/docs/Web/CSS/CSS_selectors) - [属性セレクター](/ja/docs/Web/CSS/Attribute_selectors) @@ -92,7 +99,7 @@ l10n: - {{cssxref("content")}} プロパティ - {{cssxref("quotes")}} プロパティ -- [テキストフラグメント](/ja/docs/Web/Text_fragments) +- [テキストフラグメント](/ja/docs/Web/URI/Fragment/Text_fragments) - {{DOMXref("AnimationEvent.pseudoElement")}} プロパティ - {{DOMXref("KeyframeEffect.pseudoElement")}} プロパティ From d344712321bb187800485c9568dae7a4076e4a91 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Sun, 15 Sep 2024 11:10:25 +0800 Subject: [PATCH 080/489] [zh-cn]: sync translation for User-Agent Client Hints API & Network Information API (#23555) --- .../web/api/navigatoruadata/gethighentropyvalues/index.md | 2 +- files/zh-cn/web/api/navigatoruadata/index.md | 2 +- files/zh-cn/web/api/navigatoruadata/tojson/index.md | 2 +- files/zh-cn/web/api/workernavigator/connection/index.md | 4 ++-- files/zh-cn/web/api/workernavigator/useragentdata/index.md | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/files/zh-cn/web/api/navigatoruadata/gethighentropyvalues/index.md b/files/zh-cn/web/api/navigatoruadata/gethighentropyvalues/index.md index 6dc2fa06b502cc..671a066ce59c5e 100644 --- a/files/zh-cn/web/api/navigatoruadata/gethighentropyvalues/index.md +++ b/files/zh-cn/web/api/navigatoruadata/gethighentropyvalues/index.md @@ -2,7 +2,7 @@ title: NavigatorUAData：getHighEntropyValues() 方法 slug: Web/API/NavigatorUAData/getHighEntropyValues l10n: - sourceCommit: 825bc25e89a95f985f329521bcededf073bb42b6 + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- {{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} diff --git a/files/zh-cn/web/api/navigatoruadata/index.md b/files/zh-cn/web/api/navigatoruadata/index.md index bf998e7d3c3012..7ae47c697b0ca1 100644 --- a/files/zh-cn/web/api/navigatoruadata/index.md +++ b/files/zh-cn/web/api/navigatoruadata/index.md @@ -2,7 +2,7 @@ title: NavigatorUAData slug: Web/API/NavigatorUAData l10n: - sourceCommit: 8ccdd482e4723b5393278bba686adc24d1769d0f + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- {{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} diff --git a/files/zh-cn/web/api/navigatoruadata/tojson/index.md b/files/zh-cn/web/api/navigatoruadata/tojson/index.md index b63e061d4f29c5..f5215e7e994229 100644 --- a/files/zh-cn/web/api/navigatoruadata/tojson/index.md +++ b/files/zh-cn/web/api/navigatoruadata/tojson/index.md @@ -2,7 +2,7 @@ title: NavigatorUAData：toJSON() 方法 slug: Web/API/NavigatorUAData/toJSON l10n: - sourceCommit: ea68d8f5b27af9c11247dc7d8115c0cfa6bffd1b + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- {{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} diff --git a/files/zh-cn/web/api/workernavigator/connection/index.md b/files/zh-cn/web/api/workernavigator/connection/index.md index b0fafbaf7f07e7..ff78808e38c1ad 100644 --- a/files/zh-cn/web/api/workernavigator/connection/index.md +++ b/files/zh-cn/web/api/workernavigator/connection/index.md @@ -2,10 +2,10 @@ title: WorkerNavigator：connection 属性 slug: Web/API/WorkerNavigator/connection l10n: - sourceCommit: 5671055d63552c5a4dc22ce7f6bea408afa1521a + sourceCommit: e8fe043f7d2ad7cd9804d1bf96e0310949f1dac7 --- -{{APIRef("Network Information API")}} +{{APIRef("Network Information API")}}{{AvailableInWorkers("worker")}} {{domxref("WorkerNavigator")}} 接口的 **`connection`** 只读属性返回一个包含有关系统网络连接信息的 {{domxref("NetworkInformation")}} 对象，例如用户设备的当前带宽或连接是否按流量计费。这可以用于根据用户的连接状态来选择高清晰度内容或低清晰度内容。 diff --git a/files/zh-cn/web/api/workernavigator/useragentdata/index.md b/files/zh-cn/web/api/workernavigator/useragentdata/index.md index 7e42b1623521e0..72db7cb293fbcb 100644 --- a/files/zh-cn/web/api/workernavigator/useragentdata/index.md +++ b/files/zh-cn/web/api/workernavigator/useragentdata/index.md @@ -2,10 +2,10 @@ title: WorkerNavigator：userAgentData 属性 slug: Web/API/WorkerNavigator/userAgentData l10n: - sourceCommit: 8ccdd482e4723b5393278bba686adc24d1769d0f + sourceCommit: e8fe043f7d2ad7cd9804d1bf96e0310949f1dac7 --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{securecontext_header}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{securecontext_header}}{{AvailableInWorkers("worker")}} {{domxref("WorkerNavigator")}} 接口的 **`userAgentData`** 只读属性返回一个 {{domxref("NavigatorUAData")}} 对象，其可用于访问{{domxref("User-Agent Client Hints API", "用户代理客户端提示 API", "", "nocode")}}。 From 003d875afcd8b479d98207c8de315255726fb137 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 15 Sep 2024 16:11:15 +0900 Subject: [PATCH 081/489] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0=20(#23509)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/26 時点の英語版に基づき更新 * 2024/07/26 時点の英語版に基づき更新 --- .../symbol/isconcatspreadable/index.md | 53 +++++++++++-------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md b/files/ja/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md index 4ea6adaee2fa81..50596ca77d7ab9 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/isconcatspreadable/index.md @@ -1,58 +1,64 @@ --- title: Symbol.isConcatSpreadable slug: Web/JavaScript/Reference/Global_Objects/Symbol/isConcatSpreadable +l10n: + sourceCommit: 8421c0cd94fa5aa237c833ac6d24885edbc7d721 --- {{JSRef}} -**`Symbol.isConcatSpreadable`** は、{{jsxref("Array.prototype.concat()")}} メソッドを使用してオブジェクトを配列の要素に平坦化する場合の設定として使用されます。 +**`Symbol.isConcatSpreadable`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.isConcatSpreadable` を表します。{{jsxref("Array.prototype.concat()")}} メソッドは、連結される各オブジェクトに対してこのシンボルを探し、配列風オブジェクトとして扱って配列要素を平坦化すべきかどうかを判断します。 {{EmbedInteractiveExample("pages/js/symbol-isconcatspreadable.html")}} -## 説明 +## 値 -`@@isConcatSpreadable` シンボル（`Symbol.isConcatSpreadable`）は直接、または継承されたプロパティとして定義でき、その値は boolean です。これは、配列や配列状のオブジェクトの振る舞いを制御します： +ウェルノウンシンボル `Symbol.isConcatSpreadable` です。 -- 配列オブジェクトにとって、既定の動作は要素の展開（平坦化）です。`Symbol.isConcatSpreadable` はこれらの場合に平坦化を避けます。 -- 配列状のオブジェクトにとって、既定の動作は展開や平坦化を行いません。`Symbol.isConcatSpreadable` はこれらの場合に平坦化を強制します。 +{{js_property_attributes(0, 0, 0)}} -{{js_property_attributes(0,0,0)}} +## 解説 + +`[Symbol.isConcatSpreadable]` プロパティは、直接または継承されたプロパティとして定義でき、その値は論理値です。これが配列や配列風オブジェクトの挙動を制御できます。 + +- 配列オブジェクトでは、既定の動作は要素の展開（平坦化）です。`Symbol.isConcatSpreadable` により、これらの場合に平坦化を避けることができます。 +- 配列風オブジェクトでは、既定の動作は展開や平坦化を行いません。`Symbol.isConcatSpreadable` により、これらの場合に平坦化を強制することができます。 ## 例 ### 配列 -既定で、{{jsxref("Array.prototype.concat()")}} は配列を次の結果のように展開（平坦化）します： +既定で、{{jsxref("Array.prototype.concat()")}} は配列を次の結果のように展開（平坦化）します。 ```js -let alpha = ['a', 'b', 'c'], -let numeric = [1, 2, 3] +const alpha = ["a", "b", "c"]; +const numeric = [1, 2, 3]; -let alphaNumeric = alpha.concat(numeric) +const alphaNumeric = alpha.concat(numeric); -console.log(alphaNumeric) // Result: ['a', 'b', 'c', 1, 2, 3] +console.log(alphaNumeric); // 結果: ['a', 'b', 'c', 1, 2, 3] ``` -`Symbol.isConcatSpreadable` を `false` に設定した場合、既定の動作を使用できなくなります： +`Symbol.isConcatSpreadable` を `false` に設定すると、既定の動作を無効にすることができます。 ```js -let alpha = ['a', 'b', 'c'], -let numeric = [1, 2, 3] +const alpha = ["a", "b", "c"]; +const numeric = [1, 2, 3]; -numeric[Symbol.isConcatSpreadable] = false -let alphaNumeric = alpha.concat(numeric) +numeric[Symbol.isConcatSpreadable] = false; +const alphaNumeric = alpha.concat(numeric); -console.log(alphaNumeric) // Result: ['a', 'b', 'c', [1, 2, 3] ] +console.log(alphaNumeric); // 結果: ['a', 'b', 'c', [1, 2, 3] ] ``` -### 配列状のオブジェクト +### 配列風オブジェクト -配列状のオブジェクトは、既定で展開しません。`Symbol.isConcatSpreadable` 平坦化した配列を取得するには、`true` に設定する必要があります： +配列風オブジェクトは、既定で展開されません。平坦化された配列を取得するには、`Symbol.isConcatSpreadable` を `true` に設定する必要があります。 ```js -let x = [1, 2, 3]; +const x = [1, 2, 3]; -let fakeArray = { +const fakeArray = { [Symbol.isConcatSpreadable]: true, length: 2, 0: "hello", @@ -64,14 +70,15 @@ x.concat(fakeArray); // [1, 2, 3, "hello", "world"] > **メモ:** `length` プロパティは、追加するオブジェクトプロパティの数を制御するために使用されます。上記の例では、`length:2` は 2 つのプロパティを追加する必要があることを示しています。 -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザー実装状況 +## ブラウザーの互換性 {{Compat}} ## 関連情報 +- [`Symbol.isConcatSpreadable` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-symbol) - {{jsxref("Array.prototype.concat()")}} From 1cf56c43ed7d8377236031910cfbbcf40850a24b Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Sun, 15 Sep 2024 16:11:37 +0900 Subject: [PATCH 082/489] =?UTF-8?q?2024/07/13=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0=20(#23510)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/13 時点の英語版に基づき更新 * 2024/07/13 時点の英語版に基づき更新 --- .../reference/global_objects/symbol/asynciterator/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/asynciterator/index.md b/files/ja/web/javascript/reference/global_objects/symbol/asynciterator/index.md index f7eebaa72bbec0..2b2158f2b6de08 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/asynciterator/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/asynciterator/index.md @@ -7,7 +7,7 @@ l10n: {{JSRef}} -**`Symbol.asyncIterator`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.asyncIterator` を表します。[非同期反復可能プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#非同期イテレーターと非同期反復可能プロトコル)は、オブジェクトの非同期反復子を返すメソッドについてこのシンボルを検索します。オブジェクトが非同期反復可能であるためには、`[Symbol.asyncIterator]` キーを持つ必要があります。 +**`Symbol.asyncIterator`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.asyncIterator` を表します。[非同期反復可能プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#非同期イテレーターと非同期反復可能プロトコル)は、オブジェクトの非同期反復子を返すメソッドをこのシンボルで探します。オブジェクトが非同期反復可能であるためには、`[Symbol.asyncIterator]` キーを持つ必要があります。 {{EmbedInteractiveExample("pages/js/symbol-asynciterator.html", "taller")}} From a9e1834ebf100dc576325e1ddc30c8371441513a Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 14:48:54 +0900 Subject: [PATCH 083/489] =?UTF-8?q?2024/07/15=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../symbol/hasinstance/index.md | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/hasinstance/index.md b/files/ja/web/javascript/reference/global_objects/symbol/hasinstance/index.md index 2bfcfd72ec4535..45242bee0f5f59 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/hasinstance/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/hasinstance/index.md @@ -1,13 +1,30 @@ --- title: Symbol.hasInstance slug: Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance +l10n: + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`Symbol.hasInstance`** は、コンストラクターオブジェクトが、そのインスタンスのオブジェクトとして認識されるかどうかを決定するために使用されます。このシンボルで、{{jsxref("Operators/instanceof", "instanceof")}} 演算子の動作をカスタマイズすることができます。 +**`Symbol.hasInstance`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.hasInstance` を表します。{{jsxref("Operators/instanceof", "instanceof")}} 演算子は右辺オペランドに対して、コンストラクターオブジェクトがオブジェクトをそのインスタンスとして認識するかどうかを判断する際に使用されるメソッドを、このシンボルで探します。 -{{EmbedInteractiveExample("pages/js/symbol-hasinstance.html")}}{{js_property_attributes(0,0,0)}} +{{EmbedInteractiveExample("pages/js/symbol-hasinstance.html")}} + +## 値 + +ウェルノウンシンボル `Symbol.hasInstance` です。 + +{{js_property_attributes(0, 0, 0)}} + +## 解説 + +`instanceof` 演算子は、`object instanceof constructor` の返値を計算するために以下のアルゴリズムを使用します。 + +1. `constructor` に `[Symbol.hasInstance]()` メソッドがあった場合、`object` を最初のオブジェクトとして呼び出し、結果を[論理値に変換](/ja/docs/Web/JavaScript/Reference/Global_Objects/Boolean##論理値への型強制)して返します。`constructor` がオブジェクトでない場合、または `constructor[Symbol.hasInstance]` が `null`、`undefined`、関数のいずれでもでない場合、{{jsxref("TypeError")}} が発生します。 +2. それ以外の場合、`constructor` に `[Symbol.hasInstance]()` メソッドがない場合（`constructor[Symbol.hasInstance]` が `null` または `undefined`）、 [`Function.prototype[Symbol.hasInstance]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/Symbol.hasInstance) と同じアルゴリズムを使用して結果を決定します。`constructor` が関数でない場合、{{jsxref("TypeError")}} が発生します。 + +Because all functions inherit from `Function.prototype` by default, most of the time, the [`Function.prototype[Symbol.hasInstance]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/Symbol.hasInstance) method specifies the behavior of `instanceof` when the right-hand side is a function. ## 例 @@ -27,7 +44,7 @@ console.log([] instanceof MyArray); // true ```js function MyArray() {} Object.defineProperty(MyArray, Symbol.hasInstance, { - value: function (instance) { + value(instance) { return Array.isArray(instance); }, }); @@ -48,7 +65,7 @@ const cat = new Animal(); console.log(Animal[Symbol.hasInstance](cat)); // true ``` -## 仕様 +## 仕様書 {{Specifications}} @@ -59,3 +76,4 @@ console.log(Animal[Symbol.hasInstance](cat)); // true ## 関連情報 - {{jsxref("Operators/instanceof", "instanceof")}} +- [`Function.prototype[Symbol.hasInstance]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Function/Symbol.hasInstance) From 5ea0a725023573daf54cb65f4b849e1f4849db8f Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 19:12:09 +0900 Subject: [PATCH 084/489] =?UTF-8?q?2024/07/15=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/symbol/iterator/index.md | 52 +++++++++++-------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/iterator/index.md b/files/ja/web/javascript/reference/global_objects/symbol/iterator/index.md index f36e07b96cbf24..70fc2dfda79437 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/iterator/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/iterator/index.md @@ -1,33 +1,39 @@ --- title: Symbol.iterator slug: Web/JavaScript/Reference/Global_Objects/Symbol/iterator +l10n: + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- -
{{JSRef}}
+{{JSRef}} -**`Symbol.iterator`** はウェルノウンシンボルで、オブジェクトの既定のイテレーターを指定します。 [`for...of`](/ja/docs/Web/JavaScript/Reference/Statements/for...of) で使用されます。 +**`Symbol.iterator`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.iterator` を表します。[反復可能プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#反復可能プロトコル)は、オブジェクトのイテレーターを返すメソッドを、このシンボルで探します。オブジェクトが反復可能であるためには、`[Symbol.iterator]` キーを持っていなければなりません。 {{EmbedInteractiveExample("pages/js/symbol-iterator.html")}} +## 値 + +ウェルノウンシンボル `Symbol.iterator` です。 + +{{js_property_attributes(0, 0, 0)}} + ## 解説 -オブジェクトを反復処理する必要がある場合（`for..of` ループの開始時など）は常に、その `@@iterator` メソッドが引数なしで呼び出され、返された**イテレーター**を使用して反復処理される値が取得されます。 +オブジェクトを反復処理する必要がある場合（`for..of` ループの開始時など）は、その `[Symbol.iterator]()` メソッドが引数なしで呼び出され、返された**イテレーター**を使用して反復処理される値が取得されます。 -一部の組み込み型には既定の反復動作がありますが、他の型（{{jsxref("Object")}} など）にはありません。`@@iterator` メソッドの組み込み型は次のとおりです。 +一部の組み込み型には既定の反復動作がありますが、他の型（{{jsxref("Object")}} など）にはありません。`[Symbol.iterator]()` メソッドの組み込み型は次のとおりです。 -- {{jsxref("Array.@@iterator", "Array.prototype[@@iterator]()")}} -- {{jsxref("TypedArray.@@iterator", "TypedArray.prototype[@@iterator]()")}} -- {{jsxref("String.@@iterator", "String.prototype[@@iterator]()")}} -- {{jsxref("Map.@@iterator", "Map.prototype[@@iterator]()")}} -- {{jsxref("Set.@@iterator", "Set.prototype[@@iterator]()")}} +- [`Array.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/Symbol.iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/Symbol.iterator) +- [`String.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator) +- [`Map.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Map/Symbol.iterator) +- [`Set.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Set/Symbol.iterator) 詳細については、[反復処理プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols)も参照してください。 -{{js_property_attributes(0,0,0)}} - ## 例 -### ユーザー定義の反復可能項目 +### ユーザー定義の反復可能オブジェクト 次のように独自の反復可能オブジェクトを作成できます。 @@ -41,7 +47,7 @@ myIterable[Symbol.iterator] = function* () { [...myIterable]; // [1, 2, 3] ``` -または、[計算されたプロパティ](/ja/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names)を使用して、クラスやオブジェクト内で反復可能オブジェクトを直接定義できます。 +または、[計算プロパティ](/ja/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names)を使用して、クラスやオブジェクト内で反復可能オブジェクトを直接定義できます。 ```js class Foo { @@ -65,12 +71,12 @@ console.log(...someObj); // 'a', 'b' ### 非整形反復処理 -もし反復可能項目の `@@iterator` メソッドがイテレーターオブジェクトを返さない場合、それは非整形反復可能項目です。それを使用すると、実行時に例外が発生したり、バグが発生したりする可能性があります。 +もし反復可能項目の `[Symbol.iterator]()` メソッドがイテレーターオブジェクトを返さない場合、それは非整形反復可能項目です。それを使用すると、実行時に例外が発生したり、バグが発生したりする可能性があります。 ```js example-bad -const nonWellFormedIterable = {} -nonWellFormedIterable[Symbol.iterator] = () => 1 -[...nonWellFormedIterable] // TypeError: [] is not a function +const nonWellFormedIterable = {}; +nonWellFormedIterable[Symbol.iterator] = () => 1; +[...nonWellFormedIterable]; // TypeError: [Symbol.iterator]() returned a non-object value ``` ## 仕様書 @@ -85,8 +91,10 @@ nonWellFormedIterable[Symbol.iterator] = () => 1 - [`Symbol.iterator` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-symbol) - [反復処理プロトコル](/ja/docs/Web/JavaScript/Reference/Iteration_protocols) -- {{jsxref("Array.@@iterator", "Array.prototype[@@iterator]()")}} -- {{jsxref("TypedArray.@@iterator", "TypedArray.prototype[@@iterator]()")}} -- {{jsxref("String.@@iterator", "String.prototype[@@iterator]()")}} -- {{jsxref("Map.@@iterator", "Map.prototype[@@iterator]()")}} -- {{jsxref("Set.@@iterator", "Set.prototype[@@iterator]()")}} +- [`Array.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/Symbol.iterator) +- [`TypedArray.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/Symbol.iterator) +- [`String.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/String/Symbol.iterator) +- [`Map.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Map/Symbol.iterator) +- [`Set.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Set/Symbol.iterator) +- [`arguments[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Functions/arguments/Symbol.iterator) +- [`Segments.prototype[Symbol.iterator]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter/segment/Segments/Symbol.iterator) From e205de83827b39c64c4a6766638425ea35cbe0f3 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 11 Sep 2024 19:25:07 +0900 Subject: [PATCH 085/489] =?UTF-8?q?2024/07/15=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../global_objects/symbol/match/index.md | 35 ++++++++++------ .../global_objects/symbol/matchall/index.md | 40 +++++++++---------- .../global_objects/symbol/replace/index.md | 23 ++++++++--- 3 files changed, 59 insertions(+), 39 deletions(-) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/match/index.md b/files/ja/web/javascript/reference/global_objects/symbol/match/index.md index 17897b9f5e68a5..f8a1af80e56cff 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/match/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/match/index.md @@ -1,19 +1,27 @@ --- title: Symbol.match slug: Web/JavaScript/Reference/Global_Objects/Symbol/match +l10n: + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`Symbol.match`** は、文字列に対して正規表現のマッチングを指定します。この関数は {{jsxref("String.prototype.match()")}} メソッドによって呼び出されます。 +**`Symbol.match`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.match` を表します。{{jsxref("String.prototype.match()")}} メソッドは第 1 引数に対して、入力文字列と現在のオブジェクトとの照合に使われるメソッドを、このシンボルで探します。このシンボルは、オブジェクトが[正規表現として扱われる](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes)べきかどうかを決定するためにも使用されます。 -{{EmbedInteractiveExample("pages/js/symbol-match.html")}} +詳しくは、[`RegExp.prototype[Symbol.match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.match) および {{jsxref("String.prototype.match()")}} を参照してください。 -## 説明 +{{EmbedInteractiveExample("pages/js/symbol-match.html", "taller")}} -この関数は、オブジェクトが正規表現の動作をするかどうかを識別するためにも使用されます。たとえば、{{jsxref("String.prototype.startsWith()")}}, {{jsxref("String.prototype.endsWith()")}}, {{jsxref("String.prototype.includes()")}} メソッドは、最初の引数が正規表現であるかどうかを確認し、正規表現である場合は {{jsxref("TypeError")}} を投げます。ここで、`一致`記号が `false`（または[偽値](/ja/docs/Glossary/Falsy)）に設定されている場合、そのオブジェクトが正規表現オブジェクトとして使用されることを意図していないことを示します。 +## 値 -{{js_property_attributes(0,0,0)}} +ウェルノウンシンボル `Symbol.match` です。 + +{{js_property_attributes(0, 0, 0)}} + +## 解説 + +この関数は、[オブジェクトが正規表現の動作をするかどうか](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp#正規表現の特殊な扱い)を識別するためにも使用されます。たとえば、{{jsxref("String.prototype.startsWith()")}}, {{jsxref("String.prototype.endsWith()")}}, {{jsxref("String.prototype.includes()")}} メソッドは、最初の引数が正規表現であるかどうかを確認し、正規表現である場合は {{jsxref("TypeError")}} が発生します。ここで、`match` シンボルが `false`（または[偽値](/ja/docs/Glossary/Falsy)、ただし `undefined` でないもの）に設定されている場合、そのオブジェクトが正規表現オブジェクトとして使用されることを意図していないことを示します。 ## 例 @@ -24,30 +32,33 @@ slug: Web/JavaScript/Reference/Global_Objects/Symbol/match ```js "/bar/".startsWith(/bar/); -// Throws TypeError, as /bar/ is a regular expression -// and Symbol.match is not modified. +// TypeError が発生。/bar/ が正規表現であり、 +// Symbol.match が変更されていないため。 ``` -ただし、`Symbol.match` を `false` に設定すると、（`match` プロパティを使用する）`isRegExp` チェックは、オブジェクトが正規表現オブジェクトではないことを示します。結果として、`startsWith` と `endsWith` メソッドは、TypeError を投げません。 +ただし、`Symbol.match` を `false` に設定すると、オブジェクトが[正規表現オブジェクトではない](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp#正規表現の特殊な扱い)ことを示します。結果として、`startsWith` と `endsWith` メソッドは、`TypeError` を発生させません。 ```js -var re = /foo/; +const re = /foo/; re[Symbol.match] = false; "/foo/".startsWith(re); // true "/baz/".endsWith(re); // false ``` -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザー実装状況 +## ブラウザーの互換性 {{Compat}} ## 関連情報 +- [`Symbol.match` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-symbol) +- {{jsxref("Symbol.matchAll")}} - {{jsxref("Symbol.replace")}} - {{jsxref("Symbol.search")}} - {{jsxref("Symbol.split")}} -- {{jsxref("RegExp.@@match", "RegExp.prototype[@@match]()")}} +- {{jsxref("String.prototype.match()")}} +- [`RegExp.prototype[Symbol.match]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.match) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/matchall/index.md b/files/ja/web/javascript/reference/global_objects/symbol/matchall/index.md index 8fbeca029fbffe..21a2e610359f3d 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/matchall/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/matchall/index.md @@ -1,35 +1,30 @@ --- title: Symbol.matchAll slug: Web/JavaScript/Reference/Global_Objects/Symbol/matchAll +l10n: + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`Symbol.matchAll`** は、文字列に対する正規表現の一致を生成するイテレーターを返します。この関数は {{jsxref("String.prototype.matchAll()")}} メソッドによって呼び出されます。 +**`Symbol.matchAll`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.match` を表します。{{jsxref("String.prototype.matchAll()")}} メソッドは最初の引数に対して、文字列に対する現在のオブジェクトの照合を行うイテレーターを返すメソッドを、このシンボルで探します。 -{{EmbedInteractiveExample("pages/js/symbol-matchall.html","shorter")}} +詳しくは、[`RegExp.prototype[Symbol.matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.matchAll) および {{jsxref("String.prototype.matchAll()")}} を参照してください。 -## 説明 +{{EmbedInteractiveExample("pages/js/symbol-matchall.html")}} -このシンボルは {{jsxref("String.prototype.matchAll()")}}、特に {{jsxref("RegExp.@@matchAll", "RegExp.prototype[@@matchAll]()")}} で使用されます。以下の 2 つの例は同じ結果を返します。 +## 値 -```js -"abc".matchAll(/a/); - -/a/[Symbol.matchAll]("abc"); -``` +ウェルノウンシンボル `Symbol.matchAll` です。 -このメソッドは、{{jsxref("RegExp")}} サブクラス内の一致動作をカスタマイズするために存在します。 - -{{js_property_attributes(0,0,0)}} +{{js_property_attributes(0, 0, 0)}} ## 例 -### Symbol.matchAll を使用する +### Symbol.matchAll の使用 ```js -let re = /[0-9]+/g; -let str = "2016-01-02|2019-03-07"; +const str = "2016-01-02|2019-03-07"; const numbers = { *[Symbol.matchAll](str) { @@ -38,20 +33,23 @@ const numbers = { }; console.log(Array.from(str.matchAll(numbers))); -// Array ["2016", "01", "02", "2019", "03", "07"] +// ["2016", "01", "02", "2019", "03", "07"] ``` -その他の例については、{{jsxref("String.prototype.matchAll()")}} と {{jsxref("RegExp.@@matchAll", "RegExp.prototype[@@matchAll]()")}} を参照してください。 - -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザー実装状況 +## ブラウザーの互換性 {{Compat}} ## 関連情報 +- [`Symbol.matchAll` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-symbol) +- {{jsxref("Symbol.match")}} +- {{jsxref("Symbol.replace")}} +- {{jsxref("Symbol.search")}} +- {{jsxref("Symbol.split")}} - {{jsxref("String.prototype.matchAll()")}} -- {{jsxref("RegExp.@@matchAll", "RegExp.prototype[@@matchAll]()")}} +- [`RegExp.prototype[Symbol.matchAll]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.matchAll) diff --git a/files/ja/web/javascript/reference/global_objects/symbol/replace/index.md b/files/ja/web/javascript/reference/global_objects/symbol/replace/index.md index 2862353e59134c..9b55fe3d8acbad 100644 --- a/files/ja/web/javascript/reference/global_objects/symbol/replace/index.md +++ b/files/ja/web/javascript/reference/global_objects/symbol/replace/index.md @@ -1,15 +1,23 @@ --- title: Symbol.replace slug: Web/JavaScript/Reference/Global_Objects/Symbol/replace +l10n: + sourceCommit: 6fbdb78c1362fae31fbd545f4b2d9c51987a6bca --- {{JSRef}} -**`Symbol.replace`** ウェルノウンシンボルは、文字列の一致した部分を置き換えるメソッドを指定します。この関数は {{jsxref("String.prototype.replace()")}} メソッドから呼び出されます。 +**`Symbol.replace`** は静的データプロパティで、[ウェルノウンシンボル](/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol#ウェルノウンシンボル)である `Symbol.replace` を表します。{{jsxref("String.prototype.replace()")}} および {{jsxref("String.prototype.replaceAll()")}} メソッドは第 1 引数で、現在のオブジェクトに一致する部分文字列を置き換えるメソッドを、このシンボルで探します。 -詳しくは、 {{jsxref("RegExp.@@replace", "RegExp.prototype[@@replace]()")}} と {{jsxref("String.prototype.replace()")}} を参照してください。 +詳しくは、[`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace)、{{jsxref("String.prototype.replace()")}}、{{jsxref("String.prototype.replaceAll()")}} を参照してください。 -{{EmbedInteractiveExample("pages/js/symbol-replace.html")}}{{js_property_attributes(0,0,0)}} +{{EmbedInteractiveExample("pages/js/symbol-replace.html")}} + +## 値 + +ウェルノウンシンボル `Symbol.replace` です。 + +{{js_property_attributes(0, 0, 0)}} ## 例 @@ -25,8 +33,7 @@ class CustomReplacer { } } -console.log("football".replace(new CustomReplacer("foo"))); -// expected output: "#!@?tball" +console.log("football".replace(new CustomReplacer("foo"))); // "#!@?tball" ``` ## 仕様書 @@ -39,7 +46,11 @@ console.log("football".replace(new CustomReplacer("foo"))); ## 関連情報 +- [`Symbol.replace` のポリフィル (`core-js`)](https://github.com/zloirock/core-js#ecmascript-symbol) - {{jsxref("Symbol.match")}} +- {{jsxref("Symbol.matchAll")}} - {{jsxref("Symbol.search")}} - {{jsxref("Symbol.split")}} -- {{jsxref("RegExp.@@replace", "RegExp.prototype[@@replace]()")}} +- {{jsxref("String.prototype.replace()")}} +- {{jsxref("String.prototype.replaceAll()")}} +- [`RegExp.prototype[Symbol.replace]()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/RegExp/Symbol.replace) From a81941476b39992e1cc3c7418fa9a24892e0d951 Mon Sep 17 00:00:00 2001 From: Vitor Schirmer Date: Sun, 15 Sep 2024 10:28:06 -0300 Subject: [PATCH 086/489] [pt-br] update of `web/http/cookies` (#22449) * [pt-br] update Cookie HTTP. - Improve `Lax` attribute description. - Fix `note` card with the backend languages. - Fix `SameSite` description * [pt-br] update `web/http/cookies/` update note block Co-authored-by: Josiel Rocha <1158643+josielrocha@users.noreply.github.com> --------- Co-authored-by: Josiel Rocha <1158643+josielrocha@users.noreply.github.com> --- files/pt-br/web/http/cookies/index.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/files/pt-br/web/http/cookies/index.md b/files/pt-br/web/http/cookies/index.md index c2cee46557631a..a3cee5521207c9 100644 --- a/files/pt-br/web/http/cookies/index.md +++ b/files/pt-br/web/http/cookies/index.md @@ -36,11 +36,7 @@ Set-Cookie: = Este cabeçalho de servidor informa ao cliente para armazenar um cookie. > [!NOTE] -> Eis as formas de utilização do cabeçalho `Set-Cookie` em várias aplicações de servidor:- [PHP](https://secure.php.net/manual/en/function.setcookie.php) -> -> - [Node.JS](https://nodejs.org/dist/latest-v8.x/docs/api/http.html#http_response_setheader_name_value) -> - [Python](https://docs.python.org/3/library/http.cookies.html) -> - [Ruby on Rails](http://api.rubyonrails.org/classes/ActionDispatch/Cookies.html) +> Eis as formas de utilização do cabeçalho `Set-Cookie` em várias aplicações de servidor: [PHP](https://secure.php.net/manual/en/function.setcookie.php), [Node.JS](https://nodejs.org/dist/latest-v8.x/docs/api/http.html#http_response_setheader_name_value), [Python](https://docs.python.org/3/library/http.cookies.html), [Ruby on Rails](http://api.rubyonrails.org/classes/ActionDispatch/Cookies.html) ``` HTTP/1.0 200 OK @@ -117,11 +113,11 @@ O atributo SameSite pode receber um ou dois valores (case-insensitive): - `None` - : O navegador irá enviar os cookies tanto para as requisições _cross-site_ quanto _same-site_. - `Strict` - - : Se o cookie same-site possuir este atributo, o navegador enviará cookies apenas se a requisição for enviada do website que configurou este cookie, Se a requisição tem origem em outra URL, nenhum cookie com o atributo`Strict` será incluído. + - : Se o cookie same-site possuir este atributo, o navegador enviará cookies apenas se a requisição for enviada do website que configurou este cookie, Se a requisição tem origem em outra URL, nenhum cookie com o atributo `Strict` será incluído. - `Lax` - - : Se o atributo receber o valor Lax, os cookies same-site ficarão retidos nas sub-requisições entre sites, como chamadas para carregar imagens ou frames, mas serão enviadas quando um usuário navegar para o URL de um site externo. + - : Se o atributo receber o valor Lax, os cookies same-site ficarão retidos nas sub-requisições entre sites, como chamadas para carregar imagens ou frames, e também quando o usuário navegar para o URL de um site externo através de métodos "seguros" (ex.: [GET](/pt-BR/docs/Web/HTTP/Methods/GET) ou [HEAD](/pt-BR/docs/Web/HTTP/Methods/GET)) como cliques em links, mas não serão enviados em requisições "não seguras" como [POST](/pt-BR/docs/Web/HTTP/Methods/POST). -O comportamento padrão se a flag não estiver setada ou sem suporte do navegador é incluir os cookies em qualquer solicitação, incluindo solicitações cross-origin. +Se a flag não estiver setada, o atributo recebe o valor `Lax` por padrão. ### Acesso via JavaScript usando `Document.cookie` From d7a513e6fbb4cd30242ba463046ecc7de17dec22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o?= <102933429+joaugustoo@users.noreply.github.com> Date: Sun, 15 Sep 2024 10:28:28 -0300 Subject: [PATCH 087/489] Translating SSL to pt-br (#23370) * Translating SSL to Portuguese * Translating SSL to pt-br * Update files/pt-br/glossary/ssl/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/pt-br/glossary/ssl/index.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 files/pt-br/glossary/ssl/index.md diff --git a/files/pt-br/glossary/ssl/index.md b/files/pt-br/glossary/ssl/index.md new file mode 100644 index 00000000000000..5e4220fbda81d3 --- /dev/null +++ b/files/pt-br/glossary/ssl/index.md @@ -0,0 +1,16 @@ +--- +title: SSL +slug: Glossary/SSL +--- + +{{GlossarySidebar}} + +Secure Sockets Layer, ou SSL, era a antiga tecnologia padrão de segurança para criar um link de rede criptografado entre um servidor e um cliente, garantindo que todos os dados transmitidos fossem privados e seguros. A versão atual do SSL é a versão 3.0, lançada pela Netscape em 1996, e foi substituída pelo protocolo {{Glossary("TLS", "Transport Layer Security (TLS)")}}. + +## Veja também + +- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (Wikipedia) +- [Transport Layer Security (TLS)](/pt-BR/docs/Web/Security/Transport_Layer_Security) +- Termos relacionados do glossário: + - {{Glossary("HTTPS")}} + - {{Glossary("TLS")}} From 205e0b529b31a6b9344c0882d5e2cf285762db29 Mon Sep 17 00:00:00 2001 From: Fabricio Fodi <159970835+FabricioFodi@users.noreply.github.com> Date: Sun, 15 Sep 2024 10:34:37 -0300 Subject: [PATCH 088/489] Update index.md (#23553) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit algumas palavras pelo que andei percebendo estavam com a escrita errada. "caraceteres" e "diponíveis" --- .../javascript/first_steps/useful_string_methods/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/pt-br/learn/javascript/first_steps/useful_string_methods/index.md b/files/pt-br/learn/javascript/first_steps/useful_string_methods/index.md index 7b6b7ccc8de654..da4f0218ff8e68 100644 --- a/files/pt-br/learn/javascript/first_steps/useful_string_methods/index.md +++ b/files/pt-br/learn/javascript/first_steps/useful_string_methods/index.md @@ -36,7 +36,7 @@ Como dissemos antes e diremos novamente — _tudo_ é um objeto em JavaScript. Q var string = "This is my string"; ``` -sua variável torna-se uma instância do objeto string e, como resultado, tem um grande número de propriedades e métodos diponíveis para ela. Você pode ver isso se você for na página do objeto {{jsxref("String")}} e olhar para baixo na lista do lado da página! +sua variável torna-se uma instância do objeto string e, como resultado, tem um grande número de propriedades e métodos disponíveis para ela. Você pode ver isso se você for na página do objeto {{jsxref("String")}} e olhar para baixo na lista do lado da página! **Agora, antes de seu cérebro começar a derreter, não se preocupe!** Você não precisa saber sobre a maioria deles no início da sua jornada de aprendizado. Mas há alguns que você potencialmente usará com bastante frequência que veremos aqui. @@ -180,7 +180,7 @@ O comprimento de "mozilla" é 7, mas porque a contagem começa de 0, a posição browserType.indexOf("zilla"); ``` - Isso nos dá o resultado 2, porque a substring "zilla" se inicia na posição 2 (0, 1, 2 — então, 3 caraceteres) dentro de "mozilla". Esse código poderia ser usado para filtrar cadeias de caracteres. Por exemplo, podemos ter uma lista de endereços da web e apenas queremos imprimir aqueles que contenham "mozilla". + Isso nos dá o resultado 2, porque a substring "zilla" se inicia na posição 2 (0, 1, 2 — então, 3 caracteres) dentro de "mozilla". Esse código poderia ser usado para filtrar cadeias de caracteres. Por exemplo, podemos ter uma lista de endereços da web e apenas queremos imprimir aqueles que contenham "mozilla". 2. Isso pode ser feito de outro jeito, que é possivelmente mais eficaz. Experimente isso: @@ -215,7 +215,7 @@ browserType.slice(2); Isso retornará "zilla" — isso é porque a posição de caracter 2 é a letra z, e porque você não incluiu o segundo parametro, a substring retornou todos os caracteres restantes na string. > [!NOTE] -> O segundo parametro do `slice()` é opcional: Se você não incluir ele, o slice finaliza no fim da string original. Existem outras opções também; estude a {{jsxref("String.prototype.slice()", "slice()")}} pagina para ver o que mais você pode descobrir. +> O segundo parametro do `slice()` é opcional: Se você não incluir ele, o slice finaliza no fim da string original. Existem outras opções também; estude a {{jsxref("String.prototype.slice()", "slice()")}} página para ver o que mais você pode descobrir. ### Mudando entre maiúsculas e minúsculas From af6764e478b4a4a37acef66486526162f5ffa974 Mon Sep 17 00:00:00 2001 From: Edgar Santos Estevam <167450710+Edd-Estevam@users.noreply.github.com> Date: Sun, 15 Sep 2024 10:34:57 -0300 Subject: [PATCH 089/489] Update index.md (#23574) Fix a typo --- files/pt-br/web/html/element/code/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/pt-br/web/html/element/code/index.md b/files/pt-br/web/html/element/code/index.md index 088faca66073ae..8526e5a62877a3 100644 --- a/files/pt-br/web/html/element/code/index.md +++ b/files/pt-br/web/html/element/code/index.md @@ -75,7 +75,7 @@ Um parágrafo que inlcui ``:

``` -A sainda gerada por esse trecho HTML se parece com isso: +A saída gerada por esse trecho HTML se parece com isso: {{EmbedLiveSample("Example", 640, 70)}} From 0e397f1316e2aaca7c251c3bf4be060d7ef70611 Mon Sep 17 00:00:00 2001 From: RoXoM Date: Mon, 16 Sep 2024 23:11:19 +0800 Subject: [PATCH 090/489] zh-cn: translate for visual viewport api (#23278) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- .../web/api/visual_viewport_api/index.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 files/zh-cn/web/api/visual_viewport_api/index.md diff --git a/files/zh-cn/web/api/visual_viewport_api/index.md b/files/zh-cn/web/api/visual_viewport_api/index.md new file mode 100644 index 00000000000000..60b0f4232dddfa --- /dev/null +++ b/files/zh-cn/web/api/visual_viewport_api/index.md @@ -0,0 +1,116 @@ +--- +title: 可视视口 API +slug: Web/API/Visual_Viewport_API +l10n: + sourceCommit: 4b5b3e16c8260a429db07dd54420ae40794b96c2 +--- + +{{DefaultAPISidebar("Visual Viewport")}} + +**可视视口 API** 提供了一种用于查询和修改窗口{{Glossary("visual viewport", "可视视口")}}属性的显式机制。可视视口是屏幕的可视部分，不包括屏幕键盘、缩放区域以外的区域或任何其他不随页面尺寸缩放的屏幕工具。 + +## 概念和用法 + +移动 web 包含两个视口，即布局视口和可视视口。布局视口涵盖页面上的所有元素，而可视视口则是屏幕上实际可见的内容。当用户缩放页面时，可视视口会缩小，但布局视口保持不变。屏幕键盘（OSK）等用户界面功能可以缩小可视视口，而不影响布局视口。 + +如果网页元素需要在屏幕上可见，而与网页的可见部分无关，该怎么办？例如，如果你需要一组图像控件无论设备的捏合缩放级别如何都能保持在屏幕上，该怎么办？目前各浏览器在处理这个问题上存在差异。可视视口可让网页开发人员根据屏幕上显示的内容对元素进行相对定位，从而解决这个问题。 + +要访问窗口的可视视口，可以从 {{domxref("window.visualViewport")}} 属性中获取 {{domxref("VisualViewport")}} 对象。该对象包含一组描述视口的属性。它包含三个事件：{{domxref("VisualViewport/resize_event", "resize")}}、{{domxref("VisualViewport/scroll_event", "scroll")}} 和 {{domxref("VisualViewport/scrollend_event", "scrollend")}}，分别在视口调整大小、滚动和完成滚动操作时触发。 + +通过前两个事件，可以在滚动或缩放时相对于可视视口定位元素，这些元素通常会锚定在布局视口上。通过 `scrollend` 事件，可以在滚动操作完成时更新元素。例如，你可以使用这些事件在缩放和滚动时将元素固定在可视视窗上，并在滚动结束时对其进行更新。 + +## 接口 + +- {{DOMxRef("VisualViewport")}} + - : 表示给定窗口的可视视口。窗口的 `VisualViewport` 对象提供有关视口位置和大小的信息，并接收 {{domxref("VisualViewport.resize_event", "resize")}}、{{domxref("VisualViewport.scroll_event", "scroll")}} 和 {{domxref("VisualViewport.scrollend_event", "scrollend")}} 事件。 + +### 对其他接口的扩展 + +- {{domxref("Window.visualViewport")}} {{ReadOnlyInline}} + - : 窗口 {{domxref("VisualViewport")}} 对象的只读引用。如果该属性不存在，则不支持此 API。 + +## 示例 + +[可视视口 API 示例](https://mdn.github.io/dom-examples/visual-viewport-api/)提供了不同可视视口特性（包括三种事件类型）如何工作的基本演示。在支持的台式机和手机浏览器中加载页面，并尝试滚动页面和缩放。当调整大小和滚动时，信息框会重新定位，以保持相对于可视视口的位置不变，同时更新其显示的视口和滚动信息。此外，在调整大小（`resize`）和滚动（`scroll`）时，我们会改变方框的颜色，以显示正在发生的事情，而在滚动结束（`scrollend`）时又会变回原来的颜色。 + +你会发现，在桌面浏览器上，{{domxref("Window.scrollX")}} 和 {{domxref("Window.scrollY")}} 值会随着窗口的滚动而更新，视觉视口位置不会改变。不过，在移动浏览器上，{{domxref("VisualViewport.offsetLeft")}} 和 {{domxref("VisualViewport.offsetTop")}} 值通常会被更新——通常是可视视口发生变化，而不是窗口位置发生变化。 + +HTML 示例如下。信息框由 `id` 为 `output` 的 {{htmlelement("div")}} 表示。 + +```html +

尝试滚动和缩放，看看报告的数值有什么变化。

+
+

+
+

+
+``` + +为了简洁起见，我们将不解释示例的 CSS，因为这对理解演示并不重要。你可以通过上面的示例链接查看。 + +在 JavaScript 中，我们首先要获取信息框的引用，以便在页面缩放和滚动时更新信息框，以及信息框中的两个段落。第一个将包含报告的 {{domxref("VisualViewport.offsetLeft")}} 和 {{domxref("VisualViewport.offsetTop")}} 值，第二个将包含报告的 {{domxref("Window.scrollX")}} 和 {{domxref("Window.scrollY")}} 值。 + +```js +const output = document.getElementById("output"); +const visualInfo = document.getElementById("visual-info"); +const windowInfo = document.getElementById("window-info"); +``` + +接下来，我们定义事件触发时要运行的两个关键函数： + +- `scrollUpdater()` 将在 `resize` 和 `scroll` 事件触发时调用：此函数通过查询 {{domxref("VisualViewport.offsetTop")}} 和 {{domxref("VisualViewport.offsetLeft")}} 属性更新信息框相对于可视视图的位置，并使用它们的值更新相关 {{glossary("inset properties", "inset 属性")}}的值。我们还更改了信息框的背景颜色，以显示正在发生的事情，并运行 `updateText()` 函数更新框中显示的值。 +- `scrollEndUpdater()` 函数将在 `scrollend` 事件触发时调用：它会将信息框恢复为原来的颜色，并运行 `updateText()` 函数以确保在滚动结束时显示最新值。 + +```js +const scrollUpdater = () => { + output.style.top = `${visualViewport.offsetTop + 10}px`; + output.style.left = `${visualViewport.offsetLeft + 10}px`; + output.style.background = "yellow"; + updateText(); +}; + +const scrollendUpdater = () => { + output.style.background = "lime"; + updateText(); +}; +``` + +`updateText()` 函数如下所示。它将第一段的 {{domxref("HTMLElement.innerText")}} 设置为显示当前的 {{domxref("VisualViewport.offsetLeft")}} 和 {{domxref("VisualViewport.offsetTop")}} 值，并将第二段的 {{domxref("HTMLElement.innerText")}} 设置为显示当前的 {{domxref("Window.scrollX")}} 和 {{domxref("Window.scrollY")}} 值。定义 `updateText()` 后，我们立即调用它，以便在页面加载时正确显示信息框。 + +```js +function updateText() { + visualInfo.innerText = `可视视口 left: ${visualViewport.offsetLeft.toFixed(2)} + top: ${visualViewport.offsetTop.toFixed(2)}`; + windowInfo.innerText = `当前窗口（window）scrollX: ${window.scrollX.toFixed(2)} + scrollY: ${window.scrollY.toFixed(2)}`; +} + +updateText(); +``` + +> [!NOTE] +> 我们使用 {{jsxref("Number.toFixed()")}} 方法将所有数值截断到小数点后两位，因为有些浏览器会将它们显示为亚像素数值，可能会有大量小数位。 + +现在，我们在可视视口和 {{domxref("Window")}} 对象上都设置了事件处理器属性，以便在移动设备和桌面设备上的适当时间运行关键功能： + +- 我们在 `window` 上设置了处理器，这样信息框的位置和内容就能在常规的窗口滚动操作中更新，例如在桌面浏览器上滚动页面时。 +- 我们在 `visualViewport` 上设置了处理器，这样信息框的位置和内容就会在视觉视口滚动或缩放操作时更新，例如在移动浏览器上滚动和缩放页面时。 + +```js +visualViewport.onresize = scrollUpdater; +visualViewport.onscroll = scrollUpdater; +visualViewport.onscrollend = scrollendUpdater; +window.onresize = scrollUpdater; +window.onscroll = scrollUpdater; +window.onscrollend = scrollendUpdater; +``` + +`scrollUpdater()` 会在 `resize` 和 `scroll` 事件触发时执行，而 `scrollEndUpdater()` 会在 `scrollend` 事件触发时执行。 + +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} From af7eb4c4249dd5010ae7b661f6bfa2e675fc13b1 Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Mon, 16 Sep 2024 23:22:44 +0800 Subject: [PATCH 091/489] [zh-cn]: sync translation for `MessagePort` (#23554) sync --- files/zh-cn/web/api/messageport/postmessage/index.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/files/zh-cn/web/api/messageport/postmessage/index.md b/files/zh-cn/web/api/messageport/postmessage/index.md index 27f1272d970bcf..9f68a3e8794ab2 100644 --- a/files/zh-cn/web/api/messageport/postmessage/index.md +++ b/files/zh-cn/web/api/messageport/postmessage/index.md @@ -2,7 +2,7 @@ title: MessagePort：postMessage() 方法 slug: Web/API/MessagePort/postMessage l10n: - sourceCommit: e4c0939929e1b3e1fa3fd3da82b827fca3ed4c79 + sourceCommit: e0310b3f565d3147fa80d9e63ace41e0fc244fa6 --- {{APIRef("Channel Messaging API")}} {{AvailableInWorkers}} @@ -13,18 +13,20 @@ l10n: ```js-nolint postMessage(message) -postMessage(message, options) postMessage(message, transfer) +postMessage(message, options) ``` ### 参数 - `message` - : 需要通过 channel 发送的消息。可以是任何基本数据类型。多个数据项可以作为数组发送。 -- `options` {{optional_inline}} - - : 一个可选对象，包含一个带有[数组](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array)的 `transfer` 的字段，数组中包含要转让所有权的[可转移对象](/zh-CN/docs/Web/API/Web_Workers_API/Transferable_objects)。这些对象的所有权将转移到接收方，发送方将不能再使用它们。 - `transfer` {{optional_inline}} - - : 一个可选[数组](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array)，包含要转让所有权的[可转移对象](/zh-CN/docs/Web/API/Web_Workers_API/Transferable_objects)。这些对象的所有权将转移到接收方，发送方将不能再使用它们。 + - : 一个包含要转让所有权的[可转移对象](/zh-CN/docs/Web/API/Web_Workers_API/Transferable_objects)的可选的[数组](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array)。这些对象的所有权将转移到接收方，发送方将不能再使用它们。这些可转移对象应附加到消息中；否则它们将被转移，但实际上在接收方无法访问。 +- `options` {{optional_inline}} + - : 包含以下属性的可选对象： + - `transfer` {{optional_inline}} + - : 与 `transfer` 参数含义相同。 ### 返回值 From 25de931700ffa04a271f5c71420c2deef0b65b1f Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 17 Sep 2024 11:46:10 +0900 Subject: [PATCH 092/489] =?UTF-8?q?2024/07/27=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3=20(#23527)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/27 時点の英語版に基づき新規翻訳 * Update files/ja/web/api/webvtt_api/web_video_text_tracks_format/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../web_video_text_tracks_format/index.md | 636 ++++++++++++++++++ 1 file changed, 636 insertions(+) create mode 100644 files/ja/web/api/webvtt_api/web_video_text_tracks_format/index.md diff --git a/files/ja/web/api/webvtt_api/web_video_text_tracks_format/index.md b/files/ja/web/api/webvtt_api/web_video_text_tracks_format/index.md new file mode 100644 index 00000000000000..82ef3f69e4f1e0 --- /dev/null +++ b/files/ja/web/api/webvtt_api/web_video_text_tracks_format/index.md @@ -0,0 +1,636 @@ +--- +title: ウェブ動画テキストトラック形式 (WebVTT) +slug: Web/API/WebVTT_API/Web_Video_Text_Tracks_Format +l10n: + sourceCommit: 44c4ec928281dc2d7c5ea42b7d2c74a2013f16ac +--- + +{{DefaultAPISidebar("WebVTT")}} + + + +**ウェブ動画テキストトラック形式 (WebVTT)** は、{{HTMLElement("video")}} および {{HTMLElement("audio")}} 要素内のコンテンツと同期するタイミング設定されたテキストトラックを表示するためのプレーンテキストファイル形式です。 +例えば、クローズドキャプションや字幕テキストを {{HTMLElement("video")}} に追加する際に使用することができます。 + +メディア要素に関連付けられた WebVTT ファイルは、{{HTMLElement("track")}} 要素を使用して追加します。[ファイルで定義された VTT コンテンツの表示](/ja/docs/Web/API/WebVTT_API#ファイルで定義された_vtt_コンテンツの表示)を参照してください。 +メディア要素は、異なる時点のデータを表す複数のファイルに関連付けることができます。例えば、さまざまなロケールに翻訳された、クローズドキャプション、字幕、チャプター見出しなどです。 + +> [!NOTE] +> WebVTT コンテンツは、[WebVTT API](/ja/docs/Web/API/WebVTT_API) を使用してプログラムで作成し、管理することもできます。 + +## 概要 + +WebVTT ファイルは、MIME タイプが `text/vtt` で、ファイル拡張子が `.vtt` です。 +コンテンツは {{Glossary("UTF-8")}} を使用してエンコードする必要があります。 + +WebVTT の構造は、以下の部品から構成されます。オプションの部品も含まれますが、この順序に則って構成されます。 + +- ヘッダーは、オプションのバイトオーダーマーク (BOM) と、"`WEBVTT`" という文字列に続き、1 つ以上の空白またはタブ文字で区切られたオプションのテキストヘッダーが続きます（WebVTT ファイルでは、タブと空白は同等です）。 +- 1 つ以上の空行は、それぞれ 2 つの連続した改行に相当します。 +- 1 行以上の空白行で区切られた、ゼロ個以上の `STYLE`、`REGION`、`NOTE` ブロックのいずれか。 +- 1 行以上の空白行で区切られた、ゼロ個以上のキューまたは `NOTE` ブロック。 + +下記に、`WEBVTT` 文字列（ヘッダーテキストなし）、メモブロック、および 2 つのキューを保有する単純な WebVTT ファイルを示します。 + +```plain +WEBVTT + +NOTE これは複数行のノートブロックです。 +これらは著者のコメントに使用します。 +2 つのキューブロックが以下で定義されています。 + +00:01.000 --> 00:04.000 +- 液体窒素を絶対に飲まないでください。 + +00:05.000 --> 00:09.000 +なぜなら、 +- 胃に穴をあけます。 +- 死ぬ可能性があります。 +``` + +以下の節では、上記の例で使用されていないものも含め、ファイルの各部分について説明します。 + +## WebVTT ヘッダー + +WebVTT ファイルは、以下の内容が格納されたヘッダーブロックから始まります。 + +- オプションのバイトオーダーマーク (BOM)、Unicode 文字 `U+FEFF` です。 +- "`WEBVTT`" という文字列。 +- オプションで、`WEBVTT` の右側のテキストヘッダー。 + + - `WEBVTT` の後に少なくとも 1 つの空白が必要です。 + - このヘッダーを使用して、ファイルに説明を追加することができます。 + - テキストヘッダーでは、改行または "`-->`" という文字列を除いて、どのようなものも使用することができます。 + +`WEBVTT` 文字列は、`WEBVTT` ファイルで唯一要求される部分であるため、最もシンプルな　`WEBVTT` ファイルは次のようになります。 + +```plain +WEBVTT +``` + +例えば、下記はテキスト入りのヘッダーを示しています。 +このテキストは、少なくとも 1 つの空白またはタブで隔てる必要があります。 + +```plain +WEBVTT このファイルにはキューがありません。 +``` + +## WebVTT キュー + +キューは、具体的な時間経過に伴って表示される単一のキャプション、字幕、その他のテキストブロックを定義します。 +キューはヘッダーと、`STYLE` または `REGION` ブロックの後に現れなければなりません。 + +各キューは 3 行以上の行で構成されます。 + +- オプションのキュー識別子に続く改行。 +- 本文テキストをどの時点に表示すべきかを示すキューのタイミング。これらはオプションで、最初の設定の前に少なくとも1つの空間があり、各設定の間にも空間があり、単一の改行が続くキュー設定に従うことができます。 + キューの本文テキストは、複数行にまたがる可能性があり、空行で終了します。 + +単純なキューの例を以下に示します。 +最初の行では、文字列 "`-->`" を使用して別個の時刻を指定することで、キューの表示開始時点と終了時点を指定します。 +2 行目は表示するテキストを定義します。 + +```plain +00:01.000 --> 00:04.000 +Never drink liquid nitrogen. +``` + +次のキューは少し複雑です。 +キュー識別子 "`1 - Title Crawl`" で始まり、これは JavaScript や CSS でキューを参照するために使用することができます。 +また、キューの時点の後にキュー設定があり、キューの位置を設定します。 + +```plain +1 - Title Crawl +00:05.000 --> 00:09.000 line:0 position:20% size:60% align:start +Because: +- It will perforate your stomach. +- You could die. +``` + +出力は内容テキスト内の改行をそのまま反映しますので、表示されているように、ハイフン (`-`) 文字を用いて箇条書きリストを作成することができます。 +一般的に、ブラウザーがテキストを適切に折り返すため、改行は必要な場合のみ挿入するようにしましょう。 + +キューの中で「余分な」空行を使用しないことが重要です。例えば、タイミングラインとキューの内容の間や、キューの内容の中に空行を入れないようにしてください。 +これは、空行があると現在のキューがそこで終わってしまうからです。 + +キューの各部分については、以下の節でさらに詳しく説明します。 + +### キュー識別子 + +識別子は、キューを識別する名前です。スクリプトからキューを参照するために使用できます。改行を含むことはできず、文字列 "`-->`" を含むことはできません。それは単一の改行で終わらなければなりません。番号をつけるのが一般的ですが（例えば、1、2、3、...）、それらは一意である必要はありません。 + +例えば、下記は識別子を記載した複数のキューを含むファイルを示しています。 + +```plain +WEBVTT + +1 +00:00:22.230 --> 00:00:24.606 +これは最初の字幕です。 + +2 Some Text +00:00:30.739 --> 00:00:34.074 +これは 2 番目です。 + +3 +00:00:34.159 --> 00:00:35.743 +これは 3 番目です。 +``` + +### キューのタイミング + +キューのタイミングは、キューがいつ表示されるかを示します。タイムスタンプで表される開始時刻と終了時刻があります。終了時刻は開始時刻より後でなければならず、開始時刻は前のすべての開始時刻より後でなければなりません。キューは、タイミングが重複するかもしれません。 + +WebVTT ファイルをチャプターに使用している場合（{{HTMLElement("track")}} の [`kind`](/ja/docs/Web/HTML/Element/track#kind) は `chapters` です）、ファイルは重複するタイミングを持つことはできません。 + +各キューのタイミングには次の 5 つの要素があります。 + +- 開始時刻のタイムスタンプ。 +- 少なくとも 1 つのスペース。 +- 文字列 "`-->`"。 +- 少なくとも 1 つのスペース。 +- 終了時刻のタイムスタンプ。開始時刻より後でなければなりません。 + +タイムスタンプは、次の 2 つの形式のいずれかになります。 + +- `mm:ss.ttt` +- `hh:mm:ss.ttt` + +そのコンポーネントは次のように定義されています。 + +- `hh` + - : 時を表し、2 桁以上でなければなりません。2 桁を超えることがあります（例えば、`9999:00:00.00`）。 +- `mm` + - : 分を表し、00 以上 59 以下でなければなりません。 +- `ss` + - : 秒を表し、00 以上 59 以下でなければなりません。 +- `ttt` + - : ミリ秒を表し、000 以上 999 以下でなければなりません。 + +キューのタイミングの例をいくつか示します。 + +- 基本的なキューのタイミングの例 + + ```plain + 00:00:22.230 --> 00:00:24.606 + 00:00:30.739 --> 00:00:34.074 + 00:00:34.159 --> 00:00:35.743 + 00:00:35.827 --> 00:00:40.122 + ``` + +- 重複するキューのタイミングの例 + + ```plain + 00:00:00.000 --> 00:00:10.000 + 00:00:05.000 --> 00:01:00.000 + 00:00:30.000 --> 00:00:50.000 + ``` + +- 重複しないキューのタイミングの例 + + ```plain + 00:00:00.000 --> 00:00:10.000 + 00:00:10.000 --> 00:01:00.581 + 00:01:00.581 --> 00:02:00.100 + 00:02:01.000 --> 00:02:01.000 + ``` + +### キュー設定 + +キュー設定は、動画上にキュー本体のテキストを表示する位置を決めるために使用するオプションのコンポーネントです。これには、テキストを水平に表示するか垂直に表示するかが含まれます。それらは 0 個以上存在することができ、各設定が 2 回以上使用されない限り、それらは任意の順序で使用できます。 + +キュー設定は、キューのタイミングの右側に追加します。キューのタイミングと最初の設定の間、および各設定の間には 1 つ以上のスペースが必要です。設定の名前と値はコロンで区切ります。設定では大文字と小文字が区別されるため、次のように小文字を使用してください。次の 5 つのキュー設定があります。 + +- `vertical` + - : 一部のアジアの言語のように、テキストを水平ではなく垂直に表示することを示します。取りうる値は 2 つあります。 + - `rl` + - : 書字方向は右から左 + - `lr` + - : 書字方向は左から右 +- `line` + + - : vertical が設定されていない場合は、テキストを垂直方向に表示する場所を指定します。vertical が設定されている場合、line はテキストを水平方向に表示する場所を指定します。値は次の何れかです。 + + - 行番号 + - : 数値は、映像に表示されるキューの最初の行の垂直位置です。正の数値はトップダウン、負の数値はボトムアップを示します。 + - パーセント値 + - : 0 から 100 までの整数（小数点を含まない）で、その後にパーセント記号 (%) を付けなければなりません。 + + | line | `vertical` を省略 | `vertical:rl` | `vertical:lr` | + | ----------- | ----------------- | ------------- | ------------- | + | `line:0` | 上端 | 右端 | 左端 | + | `line:-1` | 下端 | 左端 | 右端 | + | `line:0%` | 上端 | 右端 | 左端 | + | `line:100%` | 下端 | 左端 | 右端 | + +- `position` + + - : `vertical` を設定しなかった場合、`position` はテキストが水平に現れる位置を指定します。`vertical` を設定した場合、`position` はテキストが垂直に現れる位置を指定します。値は 0 以上 100 以下のパーセント値です。 + + | position | `vertical` を省略 | `vertical:rl` | `vertical:lr` | + | --------------- | ----------------- | ------------- | ------------- | + | `position:0%` | 左端 | 上端 | 上端 | + | `position:100%` | 右端 | 下端 | 下端 | + +- `size` + + - : `vertical` を設定しなかった場合、`size` はテキスト領域の幅を指定します。`vertical` を設定した場合、`size` はテキスト領域の高さを指定します。値は 0 以上 100 以下のパーセント値です。 + + | size | `vertical` を省略 | `vertical:rl` | `vertical:lr` | + | ----------- | ----------------- | ------------- | ------------- | + | `size:100%` | 幅全体 | 高さ全体 | 高さ全体 | + | `size:50%` | 半分の幅 | 半分の高さ | 半分の高さ | + +- `align` + + - : テキストの配置を指定します。設定している場合、テキストは size キュー設定で指定された領域内に配置されます。 + + | align | `vertical` を省略 | `vertical:rl` | `vertical:lr` | + | -------------- | ------------------ | ------------------ | ------------------ | + | `align:start` | 左端 | 上端 | 上端 | + | `align:center` | 水平方向に中央揃え | 垂直方向に中央揃え | 垂直方向に中央揃え | + | `align:end` | 右端 | 下端 | 下端 | + +キュー設定の例を見てみましょう。 +最初の行は設定がないことを示しています。2 行目は、サインやラベルの上にテキストを重ねるために使用します。3 行目はタイトルに使用できます。最後の行はアジアの言語に使われるかもしれません。 + +```plain +00:00:05.000 --> 00:00:10.000 +00:00:05.000 --> 00:00:10.000 line:63% position:72% align:start +00:00:05.000 --> 00:00:10.000 line:0 position:20% size:60% align:start +00:00:05.000 --> 00:00:10.000 vertical:rt line:-1 align:end +00:00:05.000 --> 00:00:10.000 position:10%,line-left align:left size:31% +00:00:05.000 --> 00:00:10.000 position:90% align:right size:35% +00:00:05.000 --> 00:00:10.000 position:45%,line-right align:center size:90% +``` + +### キュー本体 + +本体は、字幕やクローズドキャプションのテキストのようなキューのコンテンツを定義するところです。 +本体のテキストには改行を含めることができますが、空白行を含めることはできません。これは、2 つの連続する改行に相当します。空白行はキューの終わりを表します。 + +キュー本体のテキストには、文字列 `-->`、アンパサンド文字 (`&`)、小なり記号 (`<`) を含めることはできません。 +必要であれば、代わりに{{glossary("character reference", "文字参照")}}を使用することができます。たとえば、アンパサンドには `&` を、小なりには `<` を使用します。 +タグとの混同を避けるために、大なり記号 (`>`) の代わりに大なりエスケープシーケンス `>` を使用することをお勧めします。 +メタデータに WebVTT ファイルを使用している場合、これらの制限は適用されません。 + +すべての主要ブラウザーでは、キュー、メモ、または他のテキストに任意の{{glossary("character reference", "文字参照")}}を使用できます。 +古いバージョンのブラウザーでは、名前付き文字参照の以下のサブセットのみに対応している場合があります。 + +| 名前 | 文字 | エスケープシーケンス | +| ------------ | ------ | -------------------- | +| アンパサンド | `&` | `&` | +| 小なり | `<` | `<` | +| 大なり | `>` | `>` | +| 左書きマーク | _なし_ | `‎` | +| 右書きマーク | _なし_ | `‏` | +| 無改行空白 | | ` ` | + +### キュー本体テキストタグ + +キュー内のテキストのマークアップやスタイル設定には、`` などの多数のタグを使用することができます。 +ただし、WebVTT ファイルが {{HTMLElement("track")}} 要素の中で使われていて、その属性 [`kind`](/ja/docs/Web/HTML/Element/track#kind) が `chapters` である場合は、タグを使うことができません。 + +- タイムスタンプタグ + + - : タイムスタンプは、キューの開始タイムスタンプより大きく、キュー本体内の前のタイムスタンプより大きく、キューの終了タイムスタンプより小さくなければなりません。*アクティブテキスト*は、タイムスタンプと次のタイムスタンプの間、または本体に別のタイムスタンプがない場合は本体の最後までのテキストです。本体内の*アクティブテキスト*より前のテキストはすべて*過去のテキスト*です。*アクティブテキスト*より後のテキストはすべて*将来のテキスト*です。これによりカラオケ風のキャプションが実現できます。 + + ```plain + 1 + 00:16.500 --> 00:18.500 + When the moon <00:17.500>hits your eye + + 1 + 00:00:18.500 --> 00:00:20.500 + Like a <00:19.000>big-a <00:19.500>pizza <00:20.000>pie + + 1 + 00:00:20.500 --> 00:00:21.500 + That's <00:00:21.000>amore + ``` + +次のタグは、キューで使用できる HTML タグで、開始タグと終了タグ（例えば、`テキスト`）が必要です。 +これらのタグでマークアップされたテキストは、{{cssxref("::cue")}} 擬似要素を使用して [`STYLE` ブロック](#style_ブロック)で書式化することができます。 + +- イタリック体タグ (``) + + - : 含まれているテキストをイタリック体にします。 + + ```xml + text + ``` + +- 太字タグ (``) + + - : 含まれているテキストを太字にします。 + + ```xml + text + ``` + +- 下線タグ (``) + + - : 含まれているテキストに下線を引きます。 + + ```xml + text + ``` + +- クラスタグ (``) + + - : CSS クラスを使用して含まれているテキストをスタイルします。 + + ```xml + text + ``` + +- ルビタグ (``) + + - : [ルビ文字](https://ja.wikipedia.org/wiki/%E3%83%AB%E3%83%93)（すなわち、他の文字の上にある小さな注釈文字）を表示するためにルビテキストタグと共に使用します。 + + ```xml + WWWWorld Wide Webouiyes + ``` + +- ルビテキストタグ (``) + + - : [ルビ文字](https://ja.wikipedia.org/wiki/%E3%83%AB%E3%83%93)（つまり、他の文字の上にある小さな注釈文字）を表示するためにルビタグとともに使用します。 + + ```xml + WWWWorld Wide Webouiyes + ``` + +- ボイスタグ (``) + + - : クラスタグと同様に、CSS を使用して含まれているテキストをスタイル設定するためにも使用します。 + + ```xml + text + ``` + +- 言語タグ (``) + + - : {{RFC(5646, "Tags for Identifying Languages (別名 BCP 47)")}} で定義された形式を使用して、具体的な言語または言語のバリエーションに属するものとしてマークアップされたテキストをハイライトする際に使用します。 + + ```xml + Engish text as spoken in Great Britain! + ``` + +## NOTE ブロック + +NOTE ブロックは、WebVTT ファイルにコメントを追加するために使用できるオプションの節です。 +これは、ファイルを読む人々を意図したものであり、ユーザーには表示されません。 +例えば、作成者の連絡先を記録したり、構造の概要を提供したり、まだ書く必要があるキューのプレースホルダを追加したりするために使用することができます。 + +これらは、ヘッダーの後に続く WebVTT ファイル内のどこでも使用することができます。 + +NOTE ブロックには改行を入れることができますが、2 つの改行を連続して格納することはできません。2 つの改行を連続して格納すると、ブロックの終わりを示す空行が作成されます。 + +コメントには、文字列 `-->`、アンパサンド文字 (`&`)、小なり記号 (`<`) を含めることはできません。 +必要であれば、代わりに{{glossary("character reference", "文字参照")}}を使用することができます。たとえば、アンパサンドには `&` を、小なりには `<` を使用します。 +タグとの混同を避けるために、大なり記号 (`>`) の代わりに大なりエスケープシーケンス `>` を使用することをお勧めします。 + +コメントは 3 つの部分から構成されます。 + +- 文字列 `NOTE` +- 空白または改行 +- 上記に示した以外の 0 以上の文字。 + +いくつか例を示します。 + +```plain +NOTE これは単一行コメントです + +NOTE +これは単純な複数行コメントです + +NOTE +複数行にまたがる +単一のコメントです。 + +NOTE このように複数行にまたがる +コメントを作成できます。 + +NOTE TODO まだ作業が残っていることを示す行を追加することができます。 +``` + +## STYLE ブロック + +`STYLE` ブロックはオプションの節で、WebVTT ファイル内にキューの CSS スタイルを埋め込むために使用することができます。 +これらのスタイルはキューの外観とサイズを指定するために使用しますが、位置やレイアウトは指定できません。これらは[キュー設定](#キュー設定)で制御できます。 + +> [!NOTE] +> WebVTT キューは、[video/audio 要素を埋め込んだ]((/ja/docs/Web/API/WebVTT_API#styling_webvtt_in_html_or_a_stylesheet))関連文書から読み込まれた CSS スタイルにも一致します。 + +`STYLE` ブロックは、ファイル内のすべてのキューブロックより前に現れなければなりません。 + +各ブロックは以下の行で構成されています。 + +- 文字列 `STYLE` に続く、0 個以上の空白またはタブ文字、そして改行。 +- 一致する CSS スタイルを定義し、適用する文字列は、{{cssxref("::cue")}} 擬似要素を使用します。 + +ブロックには文字列 `-->` を含めることはできません。 +改行は含めることができますが、2 行の改行を連続して含めることはできません。2 行の改行は空白行を作成し、ブロックの終わりを示します。 + +下記に、2 つの `STYLE` ブロックを含む単純な WebVTT ファイルを示します。 +{{cssxref("::cue")}} を使用して、すべてのキューテキストにテキスト色を適用し、`` タグでタグ付けされたテキストだけに異なるテキスト色を適用しています。 + +```plain +WEBVTT + +STYLE +::cue { + background-image: linear-gradient(to bottom, dimgray, lightgray); + color: papayawhip; +} +/* スタイルブロックでは、空行や「ダッシュダッシュ大なり」を使用することはできません。 */ + +NOTE コメントブロックはスタイルブロックの間に使用することができます。 + +STYLE +::cue(b) { + color: peachpuff; +} + +00:00:00.000 --> 00:00:10.000 +- Hello world. + +NOTE スタイルブロックは最初のキューの後には現れることができません。 +``` + +> [!NOTE] +> WebVTT API の[キュースタイル設定例](/ja/docs/Web/API/WebVTT_API#more_cue_styling_examples)では、次の多くの例に従うことで、ライブの例が示されています。 + +### すべてのキュー本体テキストとの照合 + +{{cssxref("::cue")}} を使用して、キューの内容テキストすべてについて照合します。 + +例えば、次の `STYLE` ブロックは、すべてのキューテキストと一致し、それを黄色に色付けするというものです。 + +```plain +STYLE +cue { + color: yellow; +} +``` + +### タグ型との照合 + +{{cssxref("::cue()")}} にタグを型セレクターとして入力すると、`c`、`i`、`b`、`u`、`ruby`、`rt`、`v`、`lang`な どの具体的なキュー本体テキストタグでマークアップされたキューテキストと一致するキューテキストと一致します。 + +例えば、次のブロックは、 `lang` で黄色にマークアップされたキュー本体テキストと、その他のタグが赤でマークアップされたものに一致します。 + +```plain +STYLE +cue(c), +cue(i), +cue(b), +cue(u), +cue(ruby), +cue(rt), +cue(v) { + color: red; +} +cue(lang) { + color: yellow; +} +``` + +### クラスセレクターの照合 + +クラスセレクターを `::cue()` で使用すると、マークアップされたすべてのタグと照合します。 + +次の WebVTT ファイルの `STYLE` ブロックは、すべてのタグが `myclass` クラスを保有しているため、続くすべてのテキストと一致します。 + +```plain +WEBVTT + +STYLE +::cue(.myclass) { + color: yellow; +} + +00:00:00.000 --> 00:00:08.000 +Yellow! +Yellow! +Yellow! +Yellow! +Yellow! +Yellow! Yellow! +Yellow! +Yellow! +``` + +具体的なタグとクラスを選択するには、`::cue()` のどちらも指定する必要があります。 + +```css +STYLE ::cue(b.myclass) { + color: yellow; +} +``` + +### 属性の照合 + +特定のタグと属性でマークアップされたキュー本体テキストは、属性セレクターを使用して照合することができます。 + +例えば、次の WebVTT ファイルを考えてみましょう。このファイルには、`v` と `lang` の[キュー本体テキストタグ](#キュー本体テキストタグ)を使用してマークアップされたテキストがあり、属性を使用して具体的な音声 ("Salame") と言語を指定します。 + +```plain +WEBVTT + +STYLE +::cue([lang="en-US"]) { +color: yellow; +} +::cue(lang[lang="en-GB"]) { +color: cyan; +} +::cue(v[voice="Salame"]) { +color: lime; +} + +00:00:00.000 --> 00:00:08.000 +Yellow! + +00:00:08.000 --> 00:00:16.000 +Cyan! + +00:00:16.000 --> 00:00:24.000 +I like lime. +``` + +### 擬似クラスの照合 + +例えば、属性の照合を使用して、具体的な言語のテキストにスタイル設定を行うことができます。 +下記 `STYLE` ブロックで示されているように、`:lang()` 疑似クラスを使用して言語を照合することもできます。 + +```plain +STYLE +::cue(:lang(en)) { + color: yellow; +} +::cue(:lang(en-GB)) { + color: cyan; +} +``` + +同様に、`:past` および `:future` 擬似クラスと照合させることで、カラオケのような体験を提供することができます。 + +```css +video::cue(:past) { + color: yellow; +} +video::cue(:future) { + color: cyan; +} +``` + +他にも、`link`、`nth-last-child`、`nth-child` などの疑似クラスも同様に動作します。 + +### キュー ID の照合 + +{{cssxref("::cue()")}} 内の `id` を指定することで、特定のキューの `id` と照合します。 + +> [!NOTE] +> これを書いている時点では、主要ブラウザーのいずれにも対応していないようです。 + +例えば、次の WebVTT ファイルは、識別子 `cue1` のキューを緑色にスタイル設定するでしょう。 + +```plain +WEBVTT + +STYLE ::cue(#cue1) { + color: green; +} + +cue1 +00:00:00.000 --> 00:00:08.000 +Green! +``` + +WebVTT CSS では、HTML ページと同様にエスケープシーケンスを使用します。下記は、キュー識別子内の空間をエスケープする方法を示す例です。 + +```plain +WEBVTT + +STYLE +::cue(#crédit\ de\ transcription) { + color: red; +} + +crédit de transcription +00:04.000 --> 00:05.000 +Transcrit par Célestes™ +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- CSS の [`::cue` および `::cue()`](/ja/docs/Web/CSS/::cue) 擬似要素 From d112517208c94d4ba61830ab878720faa8e5a9f6 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 17 Sep 2024 11:46:34 +0900 Subject: [PATCH 093/489] =?UTF-8?q?2024/08/09=20=E6=99=82=E7=82=B9?= =?UTF-8?q?=E3=81=AE=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5?= =?UTF-8?q?=E3=81=8D=E6=9B=B4=E6=96=B0=20(#23528)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/08/09 時点の英語版に基づき更新 * Update files/ja/web/api/webvtt_api/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- files/ja/web/api/webvtt_api/index.md | 739 ++++++++++----------------- 1 file changed, 259 insertions(+), 480 deletions(-) diff --git a/files/ja/web/api/webvtt_api/index.md b/files/ja/web/api/webvtt_api/index.md index d6bdf1b9d40aed..d27e070e3ec19d 100644 --- a/files/ja/web/api/webvtt_api/index.md +++ b/files/ja/web/api/webvtt_api/index.md @@ -1,589 +1,376 @@ --- -title: ウェブビデオテキストトラック形式 (WebVTT) +title: WebVTT API slug: Web/API/WebVTT_API l10n: - sourceCommit: c6dbc4ff96451887b908b46c8e70bcfec1c2c48c + sourceCommit: c99afd3cafe73c93831bd73ad1dac285c3c713b1 --- {{DefaultAPISidebar("WebVTT")}} -**ウェブビデオテキストトラック形式 (WebVTT)** は、{{HTMLElement("track")}} 要素を使用して時間指定のテキストトラック（字幕やキャプションなど）を表示するための形式です。 WebVTT ファイルの主な目的は、テキストオーバーレイを {{HTMLElement("video")}} に追加することです。WebVTT はテキストベースの形式であり、{{Glossary("UTF-8")}} を使用してエンコードする必要があります。スペースを使用できる場所では、タブも使用できます。これらのトラックと、正しい時刻にテキストの再生を実行するために必要なデータを表現および管理するために使用できる小さな API もあります。 +**ウェブ動画テキストトラック** (**WebVTT**) 動画や音声トラックなどの他のメディアと時間軸を合わせて配置された特定のテキスト「キュー」を提供するテキストトラックです。**WebVTT API** は、これらのテキストトラックを定義し、操作するための機能を提供します。 +WebVTT API は主に、動画コンテンツに重ねて表示される字幕やキャプションの表示に使用されますが、他にも、ナビゲーションを容易にするためのチャプター情報の提供や、音声や動画コンテンツと時間軸を合わせて配置する必要がある一般的なメタデータの提供など、他にも用途があります。 -## WebVTT ファイル +## 概念と使用方法 -WebVTT の MIME タイプは `text/vtt` です。 +テキストトラックとは、時間軸に沿って配置されたテキストデータを格納するコンテナーで、映像や音声トラックと並行して再生することで、コンテンツの翻訳、文字起こし、概要を提供することができます。 +動画や音声のメディア要素は、異なる種類や言語のトラックを定義することができ、ユーザーは好みやニーズに応じて適切なトラックを表示することができます。 -WebVTT ファイル（`.vtt`）にはキューが含まれています。キューは、次のように単一行または複数行になります。 +指定できるテキストデータの種類は以下の一覧に掲載されています。 +ブラウザーがテキストトラックのすべてに対応しているとは限らないことに注意してください。 -```plain -WEBVTT - -00:01.000 --> 00:04.000 -- 液体窒素を絶対に飲まないでください。 +- `subtitles` は、音声のダイアログにテキスト翻訳を提供します。 + これは既定のテキストトラックの型であり、使用する場合はソース言語を指定する必要があります。 +- `captions` は、話されたテキストの文字起こしを提供し、音楽や背景の音など、の音声に関する情報を記載することができます。 + これらは聴覚障害のあるユーザーのためのものです。 +- `chapters` は、高レベルなナビゲーション情報を提供し、ユーザーが関連するコンテンツに簡単に切り替えられるようにします。 +- `metadata` は、他にもあらゆる時系列情報に用いられます。 -00:05.000 --> 00:09.000 -- それはあなたの胃に穴をあけます。 -- あなたは死ぬ可能性があります。 -``` - -## WebVTT の本体 +トラック内の時間軸に沿って配置された個々のテキストデータの単位は「キュー」と呼ばれます。 +各キューには開始時刻、終了時刻、テキスト本文が含まれます。 +また、表示領域、位置指定、配置、サイズに影響を与える「キュー設定」を持つこともできます。 +最後に、キューにはラベルを付けることができ、CSS スタイル指定のためにキューを選択する際に使用することができます。 -WebVTT の構造は、以下のコンポーネントで構成されています。一部のコンポーネントはオプションです。 +テキストトラックとキューは、[WebVTT ファイル形式](/ja/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format)を使用してファイル内で定義し、その後、特定の {{HTMLElement("video")}} 要素に {{HTMLElement("track")}} 要素を使用して関連付けられます。 -- オプションのバイトオーダーマーク (BOM)。 -- 文字列 "`WEBVTT`"。 -- `WEBVTT` の右側にあるオプションのテキストヘッダー。 +あるいは、{{domxref("TextTrack")}} を JavaScript で [`HTMLMediaElement.addTextTrack()`](/ja/docs/Web/API/HTMLMediaElement/addTextTrack) を使用してメディア要素にテキストトラックを追加し、個々の {{domxref("VTTCue")}} オブジェクトを {{domxref("TextTrack.addCue()")}} によってトラックに追加することができます。 - - `WEBVTT` の後には少なくとも 1 つのスペースが必要です。 - - これを使用してファイルに説明を追加できます。 - - 改行または文字列 "`-->`" を除いて、テキストヘッダーには何でも使用できます。 +{{cssxref("::cue")}} は [CSS](/ja/docs/Web/CSS) [擬似要素](/ja/docs/Web/CSS/Pseudo-elements)で、HTML と WebVTT ファイルのどちらでも使用することができ、特定の要素、キュー内の特定のタグ、VTT クラス、または特定のラベルを持つキューのスタイルを設定することができます。 +`::cue-region` 擬似要素は、特定の領域のキューをスタイル設定するためのものですが、どのブラウザーも対応していません。 -- 空白行。2 つの連続した改行に相当します。 -- ゼロ個以上のキューまたはコメント。（訳注：これらのブロックは 1 つ以上の空白行で互いに区切られています。） -- ゼロ行以上の空白行。（訳注：ファイルの終りも空白行という扱いです。） +WebVTTの最も重要な機能は、ファイル形式またはウェブ API を使用してアクセスすることができます。 -### 例 +## インターフェイス -- 最も単純な WebVTT ファイル +- {{domxref("VTTCue")}} + - : メディア要素に関連付けられたテキストトラックの特定の時間枠に表示されるテキスト、つまりキューを表します。 +- {{domxref("VTTRegion")}} + - : 動画要素の一部を表し、{{domxref("VTTCue")}} がレンダリングされることがあります。 +- {{domxref("TextTrack")}} + - : テキストトラックを表し、再生中にさまざまなポイントで関連するメディア要素とともに表示するキューのリストを保持します。 +- {{domxref("TextTrackCue")}} + - : {{domxref("VTTCue")}} などのさまざまなキュー型用の抽象ベースクラスです。 +- {{domxref("TextTrackCueList")}} + - : 配列風オブジェクトで、{{domxref("TextTrackCue")}} オブジェクトの動的に更新されるリストを表します。 + この型のインスタンスは {{domxref('TextTrack.cues')}} から、{{domxref("TextTrack")}} オブジェクト内のすべてのキューを取得するために取得します。 +- {{domxref("TextTrackList")}} + - : メディア要素に対して定義されたテキストトラックの一覧を表し、各トラックは、一覧に別個の {{domxref("TextTrack")}} インスタンスとして表されます。 - ```plain - WEBVTT - ``` +### 関連するインターフェイス -- テキストヘッダーを持つ非常に単純な WebVTT ファイル +- {{domxref("TrackEvent")}} + - : HTML DOM API の一部で、{{domxref("TextTrackList")}} にトラックが追加されたり削除されたりしたとき（より一般的には、HTML のメディア要素にトラックが追加されたり削除されたりしたとき）に発生する `addtrack` イベントと `removetrack` イベントのインターフェイスです。 - ```plain - WEBVTT - このファイルにはキューがありません。 - ``` +### 関連する CSS の拡張 -- ヘッダーとキューを使用した一般的な WebVTT の例 +これらの [CSS](/ja/docs/Web/CSS) [擬似要素](/ja/docs/Web/CSS/Pseudo-elements)は、VTT トラックを持つメディアのキューをスタイルするために使用されます。 - ```plain - WEBVTT - このファイルにはキューがあります。 +- {{CSSxRef("::cue")}} + - : メディアの中で選択された要素内のキューを VTT トラックと照合します。 - 14 - 00:01:14.815 --> 00:01:18.114 - - What? - - Where are we now? +> [!NOTE] +> この仕様では、もう一つの擬似要素である `::cue-region` を定義していますが、これはどのブラウザーも対応していません。 - 15 - 00:01:18.171 --> 00:01:20.991 - - This is big bat country. +## 例 - 16 - 00:01:21.058 --> 00:01:23.868 - - [ Bats Screeching ] - - They won't get in your hair. They're after the bugs. - ``` +### WebVTT API を使用してキャプションを追加 -### WebVTT ファイルの内部構造 +#### HTML -前の例の 1 つを再検討し、キューの構造をもう少し詳しく見てみましょう。 +次の例では、新しい {{domxref("TextTrack")}} を動画に追加し、{{domxref("TextTrack.addCue()")}} メソッドを使用して、作成した `VTTCue` オブジェクトを引数としてキューを追加しています。 -```plain -WEBVTT - -00:01.000 --> 00:04.000 -- 液体窒素を絶対に飲まないでください。 - -00:05.000 --> 00:09.000 -- それはあなたの胃に穴をあけます。 -- あなたは死ぬ可能性があります。 +```html + ``` -各キューは、 - -- 最初の行は時刻で始まります。これは、下にあるテキストを表示するための開始時刻です。 -- 同じ行に、`-->` という文字列があります。 -- 最初の行を 2 つ目の時刻で終了します。これは、関連するテキストを表示するための終了時刻です。 -- ハイフン (-) で始まる 1 行以上の行を表示できます。各行には表示するテキストトラックの一部が含まれています。 - -ファイルの一部に関する重要な情報を思い出すのに役立つように、`.vtt` ファイルにコメントを入れることもできます。これらは、文字列 `NOTE` で始まる別々の行にあるべきです。以下のセクションでこれらについての詳細を見つけるでしょう。 - -タイミング行とキュー本体の間など、キュー内で「余分な」空白行を使用しないことが重要です。WebVTT は行ベースで、空白行がキューを閉じます。 - -## WebVTT のコメント - -コメントは、WebVTT ファイルに情報を追加するために使用できるオプションのコンポーネントです。コメントはファイルを読む人のためのものであり、ユーザーには見えません。コメントには改行を含めることができますが、空白行を含めることはできません。これは、連続する 2 行の改行と同じです。空白行はコメントの終わりを表します。 - -コメントには、文字列 "`-->`"、アンパサンド文字 (`&`)、小なり記号 (`<`) を含めることはできません。このような文字を使用したい場合は、アンパサンドには `&`、小なりには `<` を使用してエスケープする必要があります。タグとの混同を避けるために、大なり記号（`>`）の代わりに大なりエスケープシーケンス (`>`) を使用することをお勧めします。 - -コメントは次の 3 つの部分で構成されています。 - -- 文字列 `NOTE`。 -- スペースまたは改行。 -- 上記以外のゼロ個以上の文字。 - -### 例 - -- 一般的な WebVTT の例 - - ```plain - NOTE これはコメントです - ``` +#### CSS -- 複数行のコメント +```css +video { + width: 420px; + height: 300px; +} +``` - ```plain - NOTE - 複数行に - またがる別のコメント。 +#### JavaScript + +```js +let video = document.querySelector("video"); +let track = video.addTextTrack("captions", "Captions", "en"); +track.mode = "showing"; +track.addCue(new VTTCue(0, 0.9, "Hildy!")); +track.addCue(new VTTCue(1, 1.4, "How are you?")); +track.addCue(new VTTCue(1.5, 2.9, "Tell me, is the lord of the universe in?")); +track.addCue(new VTTCue(3, 4.2, "Yes, he's in - in a bad humor")); +track.addCue(new VTTCue(4.3, 6, "Somebody must've stolen the crown jewels")); +console.log(track.cues); +``` - NOTE このように複数行にまたがって - コメントすることもできます。 - ``` +#### 結果 -- 一般的なコメントの使い方 +{{EmbedLiveSample('Using the WebVTT API to add captions','400','330')}} - ```plain - WEBVTT - 好きな映画の翻訳 +### ファイルで定義された VTT コンテンツの表示 - NOTE - 何人かの友人が両親と一緒に見ることができるように、 - Kyle が翻訳しました。 +この例では、上記の [WebVTT API を使用してキャプションを追加](#webvtt_api_を使用してキャプションを追加)の例で見たのと同じテロップを、動画に設定する方法を示します。ただし今回は、{{htmlelement("track")}} 要素を使用して宣言的に行います。 - 1 - 00:02:15.000 --> 00:02:20.000 - - Ta en kopp varmt te. - - Det är inte varmt. +まず、"captions.vtt" ファイルでキャプションを定義します。 - 2 - 00:02:20.000 --> 00:02:25.000 - - Har en kopp te. - - Det smakar som te. +```plain +WEBVTT - NOTE この最後の行はうまく翻訳されていないかもしれません。 +00:00.000 --> 00:00.900 +Hildy! - 3 - 00:02:25.000 --> 00:02:30.000 - - Ta en kopp - ``` +00:01.000 --> 00:01.400 +How are you? -## WebTT キューのスタイル設定 +00:01.500 --> 00:02.900 +Tell me, is the lord of the universe in? -{{cssxref("::cue")}} 擬似要素に一致する要素を探すことで WebTT キューをスタイル設定することができます。 +00:03.000 --> 00:04.200 +Yes, he's in - in a bad humor -### サイトの CSS の中 +00:04.300 --> 00:06.000 +Somebody must've stolen the crown jewels +``` -```css -video::cue { - background-image: linear-gradient(to 下端, dimgray, lightgray); - color: papayawhip; -} +これを {{HTMLElement("video")}} 要素に {{HTMLElement("track")}} 要素を用いて追加することができます。 +次の HTML は前回と同じテキストトラックになります。 -video::cue(b) { - color: peachpuff; -} +```html + ``` -ここでは、すべての動画要素は背景として灰色の線形グラデーションを使用するようにスタイル設定しており、前景色は `"papayawhip"` です。また、{{HTMLElement("b")}} 要素を使用して太字になっているテキストは、`"peachpuff"` で色づけしています。 - -以下の HTML スニペットは実際にメディア自体の表示を処理します。 +複数の {{HTMLElement("track")}} 要素を追加して、`kind` 属性と `srclang` 属性を用いると、複数の言語で異なる種類のトラックを指定することができます。`kind` を指定する場合は、`srclang` も設定しなければならないことに注意してください。 +`default` 属性は 1 つの `` だけに追加することができます。これはユーザーの環境設定で具体的な言語や種類を指定しない場合に再生されるものです。 ```html -