diff --git a/files/fr/learn/javascript/asynchronous/introducing_workers/index.md b/files/fr/learn/javascript/asynchronous/introducing_workers/index.md index 22e9ff263ec540..4277a777937e31 100644 --- a/files/fr/learn/javascript/asynchronous/introducing_workers/index.md +++ b/files/fr/learn/javascript/asynchronous/introducing_workers/index.md @@ -40,7 +40,7 @@ Il existe trois types de workers : Dans cet article, nous allons voir un exemple décrivant le premier type, puis discuter brièvement des deux autres. -## Utiliser les web workers Vous souvenez-vous du premier article où nous avions une page qui calculait les nombres premiers ? Nous allons ici utiliser un worker pour calculer les nombres premiers afin que notre page reste réactive aux actions des utilisatrices et utilisateurs. diff --git a/files/ja/learn/tools_and_testing/cross_browser_testing/index.md b/files/ja/learn/tools_and_testing/cross_browser_testing/index.md index fd9db320933e47..4020073cacb6dd 100644 --- a/files/ja/learn/tools_and_testing/cross_browser_testing/index.md +++ b/files/ja/learn/tools_and_testing/cross_browser_testing/index.md @@ -1,31 +1,33 @@ --- -title: クロスブラウザーテスト +title: ブラウザー横断テスト slug: Learn/Tools_and_testing/Cross_browser_testing +l10n: + sourceCommit: 26e2f9883e0e73def04c0e86fec6da3ec42e66b3 --- {{LearnSidebar}} -このモジュールでは、色々なウェブブラウザー間でウェブプロジェクトをテストすることに焦点を当てます。あなたのターゲット視聴者 (例 どのユーザー、ブラウザー、デバイスに一番関心があるのか?) の特定や、テストをどう動かすかや、主な問題としてさまざまな種類のコードと対面してそれらを緩和する方法や、テストを楽にして問題を解決するのに最も役立つツールが何かや、自動化を利用してテストをスピードアップする方法を見て行きます。 +このモジュールでは、色々なウェブブラウザー間でウェブプロジェクトをテストすることに焦点を当てます。あなたのターゲット視聴者（例 どのユーザー、ブラウザー、デバイスに一番関心があるのか?）の特定や、テストをどう動かすかや、主な問題としてさまざまな種類のコードと対面してそれらを緩和する方法や、テストを楽にして問題を解決するのに最も役立つツールが何かや、自動化を利用してテストをスピードアップする方法を見て行きます。 ## 前提条件 -ここで述べるツールを使ってみる前に、基本的な [HTML](/ja/docs/Learn/HTML)、[CSS](/ja/docs/Learn/CSS)、 [JavaScript](/ja/docs/Learn/JavaScript) 言語をよく理解しておきます。 +ここで述べるツールを使ってみる前に、基本的な [HTML](/ja/docs/Learn/HTML)、[CSS](/ja/docs/Learn/CSS)、[JavaScript](/ja/docs/Learn/JavaScript) 言語をよく理解しておく必要があります。 ## ガイド -- [はじめてのクロスブラウザーテスト](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Introduction) - - : この記事ではクロスブラウザーテストの概観を提供し始めます。その過程で「ブラウザーテストとは何？」「どんな種類の問題によく出くわしますか？」「テストと、問題の特定・修正の主なアプローチは？」といった質問に答えたりします。 -- [テスト実行戦略](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Testing_strategies) - - : 次に、テスト実行について掘り下げ、ターゲット視聴者(例、どのブラウザー、デバイス、その他のセグメントでテストを確実にするのか)を特定し、ローファイテスト戦略(ある範囲のデバイスと仮装マシンにて必要ならアドホックテストを行う)、高度なテスト戦略(専用テストアプリを使った自動化)、ユーザーグループを使ったテストまで見て行きます。 -- [よくある HTML や CSS の問題を扱う](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/HTML_and_CSS) - - : シーンがセットされたら、HTML と CSS コードの中でよく出くわすクロスブラウザー問題と、問題を防いだり、問題発生を修正するのに使えるツールを詳しく見ていきます。これにはコードの lint や、CSS プレフィックスを手渡したり、問題を監視するブラウザーの開発ツールを使ったり、ブラウザーサポート追加に polyfill を使ったり、レスポンシブデザインの問題に取り組んだり、といった事が含まれます -- [よくある JavaScript の問題を扱う](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/JavaScript) - - : 今度はクロスブラウザー JavaScript の問題と、その修正方法を見て行きます。ここにはブラウザーの開発ツールを使って問題を突き止めて修正したり、問題を回避するのに pollyfill やライブラリーを使用したり、古いブラウザーの対応にモダン JavaScript の機能を掴んだり、といった事が含まれます。 +- [はじめてのブラウザー横断テスト](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Introduction) + - : この記事ではブラウザー横断テストの概観を提供するところから始めます。その過程で「ブラウザーテストとは何か」「どんな種類の問題によく出くわすのか」「テストと、問題の特定・修正の主なアプローチは何か」といった疑問に答えたりします。 +- [テスト実行のための戦略](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Testing_strategies) + - : 次に、テスト実行について掘り下げ、ターゲット視聴者（例、どのブラウザー、デバイス、その他のセグメントでテストを確実にするのか）を特定し、ローファイテスト戦略（ある範囲のデバイスと仮装マシンにて必要ならアドホックテストを行う）、高度なテスト戦略（専用テストアプリを使った自動化）、ユーザーグループを使ったテストまで見て行きます。 +- [一般的な HTML と CSS の問題への対処](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/HTML_and_CSS) + - : 場面を設定したところで、HTML と CSS のコードでよくあるブラウザー間の問題と、問題の発生を防いだり、発生した問題を修正したりするために使用することができます。これには、コードのリンティング、CSS 接頭辞の扱い、ブラウザーの開発ツールを使用した問題の追跡、ポリフィルを使用したブラウザーの対応追加、レスポンシブデザインの問題への対処などが含まれます。 +- [よくある JavaScript の問題の扱い](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/JavaScript) + - : これで、よくあるブラウザー間の JavaScript 問題と、それを修正する方法を見ていきます。この情報には、問題を追跡し修正するためにブラウザー開発ツールを使用すること、問題を回避するためにポリフィルやライブラリーを使用すること、現行の JavaScript 機能を古いブラウザーで動作させること、などが記載されています。 - [よくあるアクセシビリティの問題を扱う](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Accessibility) - - : 次にアクセシビリティに注意を向けて、良くある問題の情報、簡単なテスト実施の方法、アクセシビリティの問題を見つけるための監査/自動化ツールの利用方法を提供します。 + - : 次にアクセシビリティに注目し、一般的な問題、単純なテストの方法、アクセシビリティの問題を探すための監査/自動化ツールの使用方法に関する情報を提供します。 - [機能検出の実装](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) - - : 機能検出はブラウザーがあるコードブロックをサポートしているか考えたり、サポートする/しないによって他のコードを実行したりして、いくつかのブラウザーでクラッシュ/エラー起こすことなく、常に動作の体験を提供できるようにすることです。この記事では簡単な機能検出を書く方法や、 `@supports` のようなネイティブ機能について詳しく記載します。 -- [はじめての自動テスト](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Automated_testing) - - : いくつかのブラウザーと端末で、一日に何度もテストを手動実行するのはつまらないし時間をつぶします。これを効率良く扱うには、自動化ツールに詳しくなるべきです。この記事では何を入手できるかや、タスクランナーの使い方や、Sauce Labs と Browser Stack のような商用ブラウザーテスト自動化ツールの使い方の基本を見て行きます。 -- [テスト自動化環境をセットアップする](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Your_own_automation_environment) - - : この記事では、Selenium/WebDriver や selenium-webdriver for Node のようなテストライブラリーを使って、自動化環境のインストールとテストを実行する方法を教えます。またあなたのローカルテスト環境と、以前の記事で見てきたような商用アプリとを統合する方法についても見て行きます。 + - : 機能検出は、ブラウザーがあるコードブロックに対応しているかどうかを調べ、対応している（または対応していない）かどうかによって異なるコードを実行することで、さまざまなブラウザーでクラッシュしたりエラーになったりすることなく、常に快適な使用感を提供できるようにします。この記事では、自分自身で単純な機能検出を書く方法、実装を高速化するためにライブラリーを使用する方法、そして `@supports` のような機能検出のためのネイティブ機能について詳しく説明します。 +- [自動テストの紹介](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Automated_testing) + - : 複数のブラウザーや端末で、 1 日に何度もテストを手動で実行するのは、面倒で時間のかかる作業です。これを効率的に処理するためには、自動化ツールに慣れることです。この記事では、利用できるもの、タスクランナーの使い方、Sauce Labs や Browser Stack などの商用ブラウザーテスト自動化アプリを使用する方法の基本を見ていきます。 +- [テスト自動化環境のセットアップ](/ja/docs/Learn/Tools_and_testing/Cross_browser_testing/Your_own_automation_environment) + - : この記事では、Selenium/WebDriver と selenium-webdriver for Node のようなテストライブラリーを使用して、自分自身で自動化環境をインストールし、テストを実行する方法を説明します。この記事では、前回説明したような商用アプリとローカルのテスト環境を統合する方法も見ていきます。 diff --git a/files/ja/web/accessibility/aria/attributes/aria-level/index.md b/files/ja/web/accessibility/aria/attributes/aria-level/index.md new file mode 100644 index 00000000000000..5984f49c4cda4a --- /dev/null +++ b/files/ja/web/accessibility/aria/attributes/aria-level/index.md @@ -0,0 +1,68 @@ +--- +title: aria-level +slug: Web/Accessibility/ARIA/Attributes/aria-level +l10n: + sourceCommit: 904cdf09c7e328b7a15a6a4db6bc6bd31f969cce +--- + +`aria-level` 属性は、構造内の要素の階層レベルを定義します。 + +## 解説 + +階層レベルは見出し、ツリー、入れ子グリッド、入れ子タブリストなどに現れます。 DOM の祖先が正確なレベルを表していない場合、 `aria-level` 属性を使用して、階層構造内の階層レベル要素を定義してください。レベルは深さと共に増加します。 `aria-level` の値は `1` 以上の整数です。 + +文書構造内の見出しに関しては、最初のレベルの見出し、 2 つ目のレベルの見出し、 3 つ目のレベルの見出しなどがあります。ツリーでは、ルート要素、その子要素、子要素の子要素（または孫要素）などがあります。 + +`aria-level` 属性は支援技術に階層を公開するので、ユーザーに伝えることができます。すべての ARIA 属性と同様に、ユーザーエージェントに影響を与えず、従ってユーザーエージェントによる文書構造の決定にも影響を与えません。 + +DOM の祖先がレベルを正確に表している場合、ユーザーエージェントは文書構造からアイテムのレベルを計算することができますので、 `aria-level` は冗長であるだけでなく、誤った情報を作成する危険性があります。 `aria-level` は、本当に文書構造から計算することが可能でない場合に、レベルの明示的な表示を提供するためにのみ使用しましょう。この属性が必要かどうかをテストしてください。ユーザーエージェントがレベルを計算できる場合は、 `aria-level` 属性を省略することが最善です。 + +### `heading` ロール内の場合 + +`aria-level` 属性は [`heading`](/ja/docs/Web/Accessibility/ARIA/Roles/heading_role) ロールの要求される属性で、要素が見出しとして扱われるべきことを支援技術に示します。 `
` は `
` をページの主見出しとして定義します。 `aria-level="2"` を定義するレベル 2 の見出しは最初のサブセクション、レベル 3 はそのサブセクション、といった具合になります。 + +```html +
このサブセクションの見出し
+``` + +代わりに {{htmlelement("Heading_Elements", "h1")}} から {{htmlelement("Heading_Elements", "h6")}} 要素を使用してください。 + +### `treegrid` ロール内の場合 + +[`treegrid`](/ja/docs/Web/Accessibility/ARIA/Roles/treegrid_role) の場合、 `aria-level` はロール [`row`](/ja/docs/Web/Accessibility/ARIA/Roles/row_role) を持つ要素に対応しており、ロール [`gridcell`](/ja/docs/Web/Accessibility/ARIA/Roles/gridcell_role) を持つ要素には対応していません。行はグリッドの垂直方向の葉ノードとして動作します。グリッドセルは各行の水平方向の葉ノードです。 `aria-level` は行内のセルには対応していません。したがって、ツリーグリッドでは、 `aria-level` 属性は `row` ロールを持つ要素に適用されます。 + +利用できるノードの完全なセットが、ユーザーがツリー内でフォーカスを移動したり、ツリーをスクロールしたりする動的な読み込みのために DOM に存在しない場合、各ノードには `aria-level`, [`aria-setsize`](/ja/docs/Web/Accessibility/ARIA/Attributes/aria-setsize), [`aria-posinset`](/ja/docs/Web/Accessibility/ARIA/Attributes/aria-posinset) が含まれています。 + +## 値 + +- `` + - : 1 以上の値です。 + +## 関連するインターフェイス + +- {{domxref("Element.ariaLevel")}} + - : [`ariaLevel`](/ja/docs/Web/API/Element/ariaLevel) プロパティは {{domxref("Element")}} インターフェイスの一部で、 `aria-level` 属性の値を反映します。 +- {{domxref("ElementInternals.ariaLevel")}} + - : [`ariaLevel`](/ja/docs/Web/API/ElementInternals/ariaLevel) プロパティは {{domxref("ElementInternals")}} インターフェイスの一部で、 `aria-level` 属性の値を反映します。 + +## 関連するロール + +以下のロール内で使用されます。 + +- [`associationlistitemkey`](/ja/docs/Web/Accessibility/ARIA/Roles/structural_roles) +- [`comment`](/ja/docs/Web/Accessibility/ARIA/Roles/comment_role) +- [`heading`](/ja/docs/Web/Accessibility/ARIA/Roles/heading_role) +- [`row`](/ja/docs/Web/Accessibility/ARIA/Roles/row_role) + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- [`

` から `

`: HTML 見出し要素](/ja/docs/Web/HTML/Element/Heading_Elements) ({{htmlelement("Heading_Elements", "h1")}}, {{htmlelement("Heading_Elements", "h2")}}, {{htmlelement("Heading_Elements", "h3")}}, {{htmlelement("Heading_Elements", "h4")}}, {{htmlelement("Heading_Elements", "h5")}}, {{htmlelement("Heading_Elements", "h6")}}) + + diff --git a/files/ja/web/api/canvasrenderingcontext2d/strokestyle/index.md b/files/ja/web/api/canvasrenderingcontext2d/strokestyle/index.md index cdf2e470602d37..fe5103a7259a22 100644 --- a/files/ja/web/api/canvasrenderingcontext2d/strokestyle/index.md +++ b/files/ja/web/api/canvasrenderingcontext2d/strokestyle/index.md @@ -1,23 +1,27 @@ --- title: "CanvasRenderingContext2D: strokeStyle プロパティ" +short-title: strokeStyle slug: Web/API/CanvasRenderingContext2D/strokeStyle l10n: - sourceCommit: 1f216a70d94c3901c5767e6108a29daa48edc070 + sourceCommit: c8b447485fd893d5511d88f592f5f3aec29a725b --- {{APIRef}} **`CanvasRenderingContext2D.strokeStyle`** はキャンバス 2D API のプロパティで、図形の辺（輪郭）に使用する色、グラデーション、またはパターンを指定します。既定値は `#000` （黒色）です。 -> **メモ:** 輪郭と塗りつぶしのスタイル例については、 [canvas チュートリアル](/ja/docs/Web/API/Canvas_API/Tutorial)の [スタイルと色の適用](/ja/docs/Web/API/Canvas_API/Tutorial/Applying_styles_and_colors) をご覧ください。 +> **メモ:** 輪郭と塗りつぶしのスタイル例については、[キャンバスのチュートリアル](/ja/docs/Web/API/Canvas_API/Tutorial)の [スタイルと色の適用](/ja/docs/Web/API/Canvas_API/Tutorial/Applying_styles_and_colors) をご覧ください。 ## 値 以下のいずれかです。 -- CSS の {{cssxref("<color>")}} 値として解釈される文字列。 -- {{domxref("CanvasGradient")}} オブジェクト（線形または放射状のグラデーション）。 -- {{domxref("CanvasPattern")}} オブジェクト（繰り返し画像）。 +- `color` + - : CSS の {{cssxref("<color>")}} 値として解釈される文字列。 +- `gradient` + - : {{domxref("CanvasGradient")}} オブジェクト（線形または放射グラデーション）。 +- `pattern` + - : {{domxref("CanvasPattern")}} オブジェクト（繰り返し画像）。 ## 例 @@ -59,8 +63,8 @@ const ctx = document.getElementById("canvas").getContext("2d"); for (let i = 0; i < 6; i++) { for (let j = 0; j < 6; j++) { ctx.strokeStyle = `rgb( - 0, - ${Math.floor(255 - 42.5 * i)}, + 0 + ${Math.floor(255 - 42.5 * i)} ${Math.floor(255 - 42.5 * j)})`; ctx.beginPath(); ctx.arc(12.5 + j * 25, 12.5 + i * 25, 10, 0, Math.PI * 2, true); @@ -71,8 +75,7 @@ for (let i = 0; i < 6; i++) { 結果はこのようになります。 -{{EmbedLiveSample("Creating_multiple_stroke_colors_using_loops", "180", "180", - "canvas_strokestyle.png")}} +{{EmbedLiveSample("Creating_multiple_stroke_colors_using_loops", "", "180")}} ## 仕様書 diff --git a/files/ja/web/api/canvasrenderingcontext2d/textalign/index.md b/files/ja/web/api/canvasrenderingcontext2d/textalign/index.md index cfa06b48ecc1ac..231d54b5110820 100644 --- a/files/ja/web/api/canvasrenderingcontext2d/textalign/index.md +++ b/files/ja/web/api/canvasrenderingcontext2d/textalign/index.md @@ -1,23 +1,20 @@ --- -title: CanvasRenderingContext2D.textAlign +title: "CanvasRenderingContext2D: textAlign プロパティ" +short-title: textAlign slug: Web/API/CanvasRenderingContext2D/textAlign +l10n: + sourceCommit: 1f216a70d94c3901c5767e6108a29daa48edc070 --- {{APIRef}} **`CanvasRenderingContext2D.textAlign`** はキャンバス 2D API のプロパティで、テキストを描画するときに用いられる現在のテキスト配置を指定します。 -配置は {{domxref("CanvasRenderingContext2D.fillText", "fillText()")}} メソッドの x の値からの相対になります。 `textAlign` が `"center"` であれば、テキストの左端は `x - (textWidth / 2)` になります。 +配置は {{domxref("CanvasRenderingContext2D.fillText", "fillText()")}} メソッドの x の値からの相対位置になります。 `textAlign` が `"center"` であれば、テキストの左端は `x - (textWidth / 2)` になります。 -## 構文 +## 値 -```js -ctx.textAlign = "left" || "right" || "center" || "start" || "end"; -``` - -### オプション - -指定可能な値は次の通りです。 +取りうる値は次の通りです。 - `"left"` - : テキストを左揃えにします。 @@ -26,9 +23,9 @@ ctx.textAlign = "left" || "right" || "center" || "start" || "end"; - `"center"` - : テキストを中央揃えにします。 - `"start"` - - : テキストをその行の標準的な先頭位置に配置します（左書きロケールでは左揃え、右書きのロケールでは右揃え）。 + - : テキストをその行の標準的な先頭位置に配置します（左書きロケールでは左揃え、右書きロケールでは右揃え）。 - `"end"` - - : テキストをその行の標準的な末尾位置に配置します（左書きロケールでは右揃え、右書きのロケールでは左揃え）。 + - : テキストをその行の標準的な末尾位置に配置します（左書きロケールでは右揃え、右書きロケールでは左揃え）。 既定値は `"start"` です。 diff --git a/files/ja/web/api/canvasrenderingcontext2d/textbaseline/index.md b/files/ja/web/api/canvasrenderingcontext2d/textbaseline/index.md index d125bf13921755..e3d1acde921d93 100644 --- a/files/ja/web/api/canvasrenderingcontext2d/textbaseline/index.md +++ b/files/ja/web/api/canvasrenderingcontext2d/textbaseline/index.md @@ -1,20 +1,16 @@ --- -title: CanvasRenderingContext2D.textBaseline +title: "CanvasRenderingContext2D: textBaseline プロパティ" +short-title: textBaseline slug: Web/API/CanvasRenderingContext2D/textBaseline +l10n: + sourceCommit: 1f216a70d94c3901c5767e6108a29daa48edc070 --- {{APIRef}} **`CanvasRenderingContext2D.textBaseline`** はキャンバス 2D API のプロパティで、テキストを描画するときに用いられる現在のテキストのベースライン（基準線）を指定します。 -## 構文 - -```js -ctx.textBaseline = - "top" || "hanging" || "middle" || "alphabetic" || "ideographic" || "bottom"; -``` - -### オプション +## 値 指定可能な値は次の通りです。 @@ -62,14 +58,14 @@ const baselines = [ ctx.font = "36px serif"; ctx.strokeStyle = "red"; -baselines.forEach(function (baseline, index) { +baselines.forEach((baseline, index) => { ctx.textBaseline = baseline; const y = 75 + index * 75; ctx.beginPath(); ctx.moveTo(0, y + 0.5); ctx.lineTo(550, y + 0.5); ctx.stroke(); - ctx.fillText("Abcdefghijklmnop (" + baseline + ")", 0, y); + ctx.fillText(`Abcdefghijklmnop (${baseline})`, 0, y); }); ``` @@ -77,6 +73,53 @@ baselines.forEach(function (baseline, index) { {{ EmbedLiveSample('Comparison_of_property_values', 700, 550) }} +### 同じ行におけるプロパティの比較 + +前回の例と同様に、この例でもさまざまな `textBaseline` プロパティの値を示しますが、この例ではすべて同じ行に水平に並べて、それぞれの違いがわかりやすいようにしています。 + +#### HTML + +```html + +``` + +#### JavaScript + +```js +const canvas = document.getElementById("canvas"); +const ctx = canvas.getContext("2d"); + +const baselines = [ + "top", + "hanging", + "middle", + "alphabetic", + "ideographic", + "bottom", +]; +ctx.font = "20px serif"; +ctx.strokeStyle = "red"; + +ctx.beginPath(); +ctx.moveTo(0, 100); +ctx.lineTo(840, 100); +ctx.moveTo(0, 55); +ctx.stroke(); + +baselines.forEach((baseline, index) => { + ctx.save(); + ctx.textBaseline = baseline; + let x = index * 120 + 10; + ctx.fillText("Abcdefghijk", x, 100); + ctx.restore(); + ctx.fillText(baseline, x + 5, 50); +}); +``` + +#### 結果 + +{{ EmbedLiveSample('同じ行におけるプロパティの比較', 900, 200) }} + ## 仕様書 {{Specifications}} diff --git a/files/ja/web/api/canvasrenderingcontext2d/textrendering/index.md b/files/ja/web/api/canvasrenderingcontext2d/textrendering/index.md new file mode 100644 index 00000000000000..f20d40586a0c3c --- /dev/null +++ b/files/ja/web/api/canvasrenderingcontext2d/textrendering/index.md @@ -0,0 +1,80 @@ +--- +title: "CanvasRenderingContext2D: textRendering プロパティ" +short-title: textRendering +slug: Web/API/CanvasRenderingContext2D/textRendering +l10n: + sourceCommit: e7eb0e7c8c9e23554bb4f85ce6f86dc4991c419b +--- + +{{APIRef}} + +**`CanvasRenderingContext2D.textRendering`** は[キャンバス API](/ja/docs/Web/API/Canvas_API) のプロパティで、テキストを描画するときに何を最適化するかについての情報をレンダリングエンジンに提供します。 + +値は SVG の [`text-rendering`](/ja/docs/Web/SVG/Attribute/text-rendering) 属性（および CSS の [`text-rendering`](/ja/docs/Web/CSS/text-rendering) プロパティ）に相当します。 + +## 値 + +ブラウザーのエンジンへ渡す、テキストを描画するヒントです。 +以下のいずれかです。 + +- `auto` + - : ブラウザーは、テキストを描画する際に、速度、読みやすさ、幾何学的な精度を最適化するタイミングについて、経験に基づいて推測します。 +- `optimizeSpeed` + - : ブラウザーはテキストを描画する際、読みやすさや幾何学的精度よりも描画速度を重視します。 + カーニングと合字を無効にします。 +- `optimizeLegibility` + - : ブラウザーは、レンダリング速度や幾何学的精度よりも読みやすさを重視します。 + これによりカーニングとオプションの合字が有効になります。 +- `geometricPrecision` + + - : ブラウザーは、描画速度や読みやすさよりも幾何学的な正確さを 重視します。 + フォントのある側面（カーニングなど）は直線的に変倍するわけではありません。 + 変倍率が大きい場合、テキストの描画があまり美しくないことがありますが、サイズは期待通りになります（基盤のオペレーティングシステムを対応している最も近いフォントサイズに切り上げも切り下げもされません）。 + +プロパティは、値を取得または設定するために使用することができます。 + +## 例 + +この例では、`textRendering`プロパティの対応している値をそれぞれ使用して、テキスト "Hello World "を表示しています。 +また、プロパティを読み込むことで、それぞれの場合の値も表示されます。 + +### HTML + +```html + +``` + +### JavaScript + +```js +const canvas = document.getElementById("canvas"); +const ctx = canvas.getContext("2d"); +ctx.font = "20px serif"; + +// Default (auto) +ctx.fillText(`Hello world (default: ${ctx.textRendering})`, 5, 20); + +// Text rendering: optimizeSpeed +ctx.textRendering = "optimizeSpeed"; +ctx.fillText(`Hello world (${ctx.textRendering})`, 5, 50); + +// Text rendering: optimizeLegibility +ctx.textRendering = "optimizeLegibility"; +ctx.fillText(`Hello world (${ctx.textRendering})`, 5, 80); + +// Text rendering: geometricPrecision +ctx.textRendering = "geometricPrecision"; +ctx.fillText(`Hello world (${ctx.textRendering})`, 5, 110); +``` + +### 結果 + +{{ EmbedLiveSample('Examples', 700, 230) }} + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/canvasrenderingcontext2d/wordspacing/index.md b/files/ja/web/api/canvasrenderingcontext2d/wordspacing/index.md new file mode 100644 index 00000000000000..e40a8d2272f25b --- /dev/null +++ b/files/ja/web/api/canvasrenderingcontext2d/wordspacing/index.md @@ -0,0 +1,68 @@ +--- +title: "CanvasRenderingContext2D: wordSpacing プロパティ" +short-title: wordSpacing +slug: Web/API/CanvasRenderingContext2D/wordSpacing +l10n: + sourceCommit: 4d5e2c11f4b8cc32e54d2527d9576ed26ced9458 +--- + +{{APIRef}} + +**`CanvasRenderingContext2D.wordSpacing`** は[キャンバス API](/ja/docs/Web/API/Canvas_API) のプロパティで、テキストを描画する際の単語間の空間を指定します。 + +これは CSS の [`word-spacing`](/ja/docs/Web/CSS/word-spacing) プロパティに相当します。 + +## 値 + +単語間の空間を CSS の {{cssxref("length")}} データ形式の文字列として設定します。 +既定値はは `0px` です。 + +このプロパティは、空間を取得または設定するために使用することができます。 +プロパティ値は、不正な値/解析不可能な値に設定しても変更されません。 + +## 例 + +この例では、"Hello World "というテキストを 3 回表示し、それぞれの用途で間隔を変更するために `wordSpacing` プロパティを使用しています。 +空間もプロパティの値を使用して、それぞれの用途ごとに表示されます。 + +### HTML + +```html + +``` + +### JavaScript + +```js +const canvas = document.getElementById("canvas"); +const ctx = canvas.getContext("2d"); + +ctx.font = "30px serif"; + +// Default word spacing +ctx.fillText(`Hello world (既定値: ${ctx.wordSpacing})`, 10, 40); + +// Custom word spacing: 10px +ctx.wordSpacing = "10px"; +ctx.fillText(`Hello world (${ctx.wordSpacing})`, 10, 90); + +// Custom word spacing: 30px +ctx.wordSpacing = "30px"; +ctx.fillText(`Hello world (${ctx.wordSpacing})`, 10, 140); +``` + +### 結果 + +{{ EmbedLiveSample('Examples', 700, 180) }} + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("CanvasRenderingContext2D.letterSpacing")}} diff --git a/files/ja/web/api/elementinternals/arialevel/index.md b/files/ja/web/api/elementinternals/arialevel/index.md new file mode 100644 index 00000000000000..c9b7a23d38e652 --- /dev/null +++ b/files/ja/web/api/elementinternals/arialevel/index.md @@ -0,0 +1,37 @@ +--- +title: "ElementInternals: ariaLevel プロパティ" +short-title: ariaLevel +slug: Web/API/ElementInternals/ariaLevel +l10n: + sourceCommit: ce10da0e9d23d241b175d8d68bf93507734b7c48 +--- + +{{APIRef("Web Components")}} + +**`ariaLevel`** は {{domxref("ElementInternals")}} インターフェイスのプロパティで、 [`aria-level`](/ja/docs/Web/Accessibility/ARIA/Attributes/aria-level) 属性の値を反映し、構造内における要素の階層レベルを定義します。 + +> **メモ:** `ElementInternals` に aria 属性を設定すると、カスタム要素に既定の意味づけを定義することができます。これらは作成者が定義した属性によって上書きされる可能性がありますが、作成者が属性を削除したり、まったく追加しなかった場合でも、確実に既定の意味づけを保持することができます。より詳しい情報は、 [Accessibility Object Model explainer](https://wicg.github.io/aom/explainer.html#default-semantics-for-custom-elements-via-the-elementinternals-object) を参照してください。 + +## 値 + +整数の入った文字列です。 + +## 例 + +この例では、`ariaLevel`の値を "1" に設定しています。 + +```js +this.internals_.ariaLevel = "1"; +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ARIA: heading ロール](/ja/docs/Web/Accessibility/ARIA/Roles/heading_role) diff --git a/files/ja/web/api/eventcounts/index.md b/files/ja/web/api/eventcounts/index.md new file mode 100644 index 00000000000000..d454fa84f3b136 --- /dev/null +++ b/files/ja/web/api/eventcounts/index.md @@ -0,0 +1,69 @@ +--- +title: EventCounts +slug: Web/API/EventCounts +l10n: + sourceCommit: 904cdf09c7e328b7a15a6a4db6bc6bd31f969cce +--- + +{{APIRef("Performance API")}} + +**`EventCounts`** は[パフォーマンス API](/ja/docs/Web/API/Performance_API)のインターフェイスで、それぞれのイベント型で配信されたイベントの数を提供します。 + +`EventCounts` インスタンスは読み取り専用の [`Map` 風オブジェクト](/ja/docs/Web/JavaScript/Reference/Global_Objects/Map#map_風のブラウザー_api)で、各キーはイベント型の名前の文字列で、対応する値はそのイベント型で配信されたイベントの数を示す整数です。 + +## コンストラクター + +このインターフェイスにはコンストラクターがありません。通常は {{domxref("performance.eventCounts")}} プロパティを使用してこのオブジェクトのインスタンスを取得します。 + +## インスタンスプロパティ + +- `size` + - : 詳しくは {{jsxref("Map.prototype.size")}} を参照してください。 + +## インスタンスメソッド + +- `entries()` + - : 詳しくは {{jsxref("Map.prototype.entries()")}} を参照してください。 +- `forEach()` + - : 詳しくは {{jsxref("Map.prototype.forEach()")}} を参照してください。 +- `get()` + - : 詳しくは {{jsxref("Map.prototype.get()")}} を参照してください。 +- `has()` + - : 詳しくは {{jsxref("Map.prototype.has()")}} を参照してください。 +- `keys()` + - : 詳しくは {{jsxref("Map.prototype.keys()")}} を参照してください。 +- `values()` + - : 詳しくは {{jsxref("Map.prototype.values()")}} を参照してください。 + +## 例 + +### EventCount マップの使用 + +以下は `EventCounts` マップから情報を取得するいくつかの例です。マップは読み取り専用のため、 `clear()`, `delete()`, `set()` メソッドは利用できないことに注意してください。 + +```js +for (entry of performance.eventCounts.entries()) { + const type = entry[0]; + const count = entry[1]; +} + +const clickCount = performance.eventCounts.get("click"); + +const isExposed = performance.eventCounts.has("mousemove"); +const exposedEventsCount = performance.eventCounts.size; +const exposedEventsList = [...performance.eventCounts.keys()]; +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("performance.eventCounts")}} +- {{domxref("PerformanceEventTiming")}} +- {{jsxref("Map")}} diff --git a/files/ja/web/api/mediastream/active/index.md b/files/ja/web/api/mediastream/active/index.md index 8f40d07ec017f7..46074b3e11e10b 100644 --- a/files/ja/web/api/mediastream/active/index.md +++ b/files/ja/web/api/mediastream/active/index.md @@ -1,11 +1,14 @@ --- -title: MediaStream.active +title: "MediaStream: active プロパティ" +short-title: active slug: Web/API/MediaStream/active +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 --- {{APIRef("Media Capture and Streams")}} -**`active`** は {{domxref("MediaStream")}} インターフェイスの読み取り専用プロパティで、ストリームが現在アクティブであれば `true` を返し、それ以外の場合は `false` を返します。トラックの状態が {{domxref("MediaStreamTrack.ended")}} でないトラックが 1 本でもある場合は、ストリームがアクティブであるとみなされます。すべでのトラックが終了すると、このストリームの `active` プロパティは `false` になります。 +**`active`** は {{domxref("MediaStream")}} インターフェイスの読み取り専用プロパティで、論理値を返します。ストリームが現在アクティブであれば `true` 、それ以外の場合は `false` となります。 {{domxref("MediaStreamTrack")}} のうち {{domxref("MediaStreamTrack.readyState")}} が `ended` に設定されているトラックが 1 本でもある場合は、ストリームが**アクティブ**であるとみなされます。すべでのトラックが終了すると、このストリームの `active` プロパティは `false` になります。 ## 値 diff --git a/files/ja/web/api/mediastream/addtrack/index.md b/files/ja/web/api/mediastream/addtrack/index.md index f937c6e115a13c..6ca2b2f8e8763c 100644 --- a/files/ja/web/api/mediastream/addtrack/index.md +++ b/files/ja/web/api/mediastream/addtrack/index.md @@ -1,18 +1,21 @@ --- -title: MediaStream.addTrack() +title: "MediaStream: addTrack() メソッド" +short-title: addTrack() slug: Web/API/MediaStream/addTrack +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- {{APIRef("Media Capture and Streams")}} -**`MediaStream.addTrack()`** メソッドは、ストリームへ新しいトラックを追加します。このトラックは {{domxref("MediaStreamTrack")}} 型の引数して指定します。 +**`addTrack()`** は {{domxref("MediaStream")}} インターフェイスのメソッドで、ストリームへ新しいトラックを追加します。このトラックは {{domxref("MediaStreamTrack")}} 型の引数して指定します。 > **メモ:** 指定されたトラックが既にストリームのトラックセットにあった場合、このメソッドは何もしません。 ## 構文 -```js -stream.addTrack(track); +```js-nolint +addTrack(track) ``` ### 引数 @@ -22,7 +25,7 @@ stream.addTrack(track); ### 返値 -{{jsxref("undefined")}} +なし ({{jsxref("undefined")}})。 ## 例 @@ -36,4 +39,4 @@ stream.addTrack(track); ## 関連情報 -- {{domxref("MediaStream")}} （所属先のインターフェイス） +- 所属先のインターフェイスである {{domxref("MediaStream")}}。 diff --git a/files/ja/web/api/mediastream/addtrack_event/index.md b/files/ja/web/api/mediastream/addtrack_event/index.md index a8070ca03bff59..82d7a78303f7a2 100644 --- a/files/ja/web/api/mediastream/addtrack_event/index.md +++ b/files/ja/web/api/mediastream/addtrack_event/index.md @@ -1,11 +1,14 @@ --- title: "MediaStream: addtrack イベント" +short-title: addtrack slug: Web/API/MediaStream/addtrack_event +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- {{APIRef("Media Capture and Streams")}} -`addtrack` イベントは、新しい [`MediaStreamTrack`](/ja/docs/Web/API/MediaStreamTrack) オブジェクトが [`MediaStream`](/ja/docs/Web/API/MediaStream) に追加されたときに発行されます。 +**`addtrack`** イベントは、新しい [`MediaStreamTrack`](/ja/docs/Web/API/MediaStreamTrack) オブジェクトが [`MediaStream`](/ja/docs/Web/API/MediaStream) に追加されたときに発行されます。 このイベントはキャンセル不可で、バブリングしません。 @@ -29,7 +32,7 @@ onaddtrack = (event) => {}; _親インターフェイスである {{domxref("Event")}} から継承したプロパティもあります。_ -- `track` {{ReadOnlyInline}} +- {{domxref("MediaStreamTrackEvent.track")}} {{ReadOnlyInline}} - : {{domxref("MediaStreamTrack")}} オブジェクトで、このストリームに追加されたトラックを表します。 ## 例 @@ -37,7 +40,7 @@ _親インターフェイスである {{domxref("Event")}} から継承したプ `addEventListener()` を使用すると次にようになります。 ```js -let stream = new MediaStream(); +const stream = new MediaStream(); stream.addEventListener("addtrack", (event) => { console.log(`New ${event.track.kind} track added`); @@ -47,7 +50,7 @@ stream.addEventListener("addtrack", (event) => { `onaddtrack` イベントハンドラープロパティを使用すると次にようになります。 ```js -let stream = new MediaStream(); +const stream = new MediaStream(); stream.onaddtrack = (event) => { console.log(`New ${event.track.kind} track added`); @@ -67,5 +70,5 @@ stream.onaddtrack = (event) => { - 関連イベント: [`removetrack`](/ja/docs/Web/API/MediaStream/removetrack_event) - [`AudioTrackList`](/ja/docs/Web/API/AudioTrackList) をターゲットとしたこのイベント: [`addtrack`](/ja/docs/Web/API/AudioTrackList/addtrack_event) - [`VideoTrackList`](/ja/docs/Web/API/VideoTrackList) をターゲットとしたこのイベント: [`addtrack`](/ja/docs/Web/API/VideoTrackList/addtrack_event) -- [メディアストリーム API](/ja/docs/Web/API/Media_Streams_API) +- [メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Capture_and_Streams_API) - [WebRTC](/ja/docs/Web/API/WebRTC_API) diff --git a/files/ja/web/api/mediastream/clone/index.md b/files/ja/web/api/mediastream/clone/index.md index d3c78364c76e31..f52598bf75f8e5 100644 --- a/files/ja/web/api/mediastream/clone/index.md +++ b/files/ja/web/api/mediastream/clone/index.md @@ -1,6 +1,9 @@ --- -title: MediaStream.clone() +title: "MediaStream: clone() メソッド" +short-title: clone() slug: Web/API/MediaStream/clone +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 --- {{APIRef("Media Capture and Streams")}} @@ -9,8 +12,8 @@ slug: Web/API/MediaStream/clone ## 構文 -```js -var stream = MediaStream.clone(); +```js-nolint +clone() ``` ### 引数 diff --git a/files/ja/web/api/mediastream/getaudiotracks/index.md b/files/ja/web/api/mediastream/getaudiotracks/index.md index 4083603e20525e..d01d712226b48c 100644 --- a/files/ja/web/api/mediastream/getaudiotracks/index.md +++ b/files/ja/web/api/mediastream/getaudiotracks/index.md @@ -1,6 +1,9 @@ --- -title: MediaStream.getAudioTracks() +title: "MediaStream: getAudioTracks() メソッド" +short-title: getAudioTracks() slug: Web/API/MediaStream/getAudioTracks +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 --- {{APIRef("Media Capture and Streams")}} @@ -9,8 +12,8 @@ slug: Web/API/MediaStream/getAudioTracks ## 構文 -```js -var mediaStreamTracks = mediaStream.getAudioTracks(); +```js-nolint +getAudioTracks() ``` ### 引数 diff --git a/files/ja/web/api/mediastream/gettrackbyid/index.md b/files/ja/web/api/mediastream/gettrackbyid/index.md index e251617028d092..3040e7c3261e59 100644 --- a/files/ja/web/api/mediastream/gettrackbyid/index.md +++ b/files/ja/web/api/mediastream/gettrackbyid/index.md @@ -1,22 +1,25 @@ --- -title: MediaStream.getTrackById() +title: "MediaStream: getTrackById() メソッド" +short-title: getTrackById() slug: Web/API/MediaStream/getTrackById +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- {{APIRef("Media Capture and Streams")}} -**`MediaStream.getTrackById()`** メソッドは、指定された ID 文字列を持つトラックを表現する {{domxref("MediaStreamTrack")}} オブジェクトを返します。指定した ID を持つトラックが存在しない場合は、 `null` を返します。 +**`getTrackById()`** は {{domxref("MediaStream")}} インターフェイスのメソッドで、指定された ID 文字列を持つトラックを表現する {{domxref("MediaStreamTrack")}} オブジェクトを返します。指定した ID を持つトラックが存在しない場合は、 `null` を返します。 ## 構文 -```js -var track = MediaStream.getTrackById(id); +```js-nolint +getTrackById(id) ``` ### 引数 - `id` - - : 取得したいトラックを識別する {{domxref("DOMString")}} です。 + - : 取得したいトラックを識別する文字列です。 ### 返値 diff --git a/files/ja/web/api/mediastream/gettracks/index.md b/files/ja/web/api/mediastream/gettracks/index.md index e906b784f4bd91..45e414f9e01565 100644 --- a/files/ja/web/api/mediastream/gettracks/index.md +++ b/files/ja/web/api/mediastream/gettracks/index.md @@ -1,16 +1,19 @@ --- -title: MediaStream.getTracks() +title: "MediaStream: getTracks() メソッド" +short-title: getTracks() slug: Web/API/MediaStream/getTracks +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- -{{APIRef("Media Capture and Streams")}}{{SeeCompatTable}} +{{APIRef("Media Capture and Streams")}} **`getTracks()`** は {{domxref("MediaStream")}} インターフェイスのメソッドで、このストリームの[`トラックセット`](https://www.w3.org/TR/mediacapture-streams/#track-set)にあるすべての {{domxref("MediaStreamTrack")}} オブジェクトを {{domxref("MediaStreamTrack.kind")}} に関係なく表す配列を返します。 ## 構文 -```js -var mediaStreamTracks = mediaStream.getTracks(); +```js-nolint +getTracks() ``` ### 引数 diff --git a/files/ja/web/api/mediastream/getvideotracks/index.md b/files/ja/web/api/mediastream/getvideotracks/index.md index 41ce6141a5682e..64b45f1ea552e2 100644 --- a/files/ja/web/api/mediastream/getvideotracks/index.md +++ b/files/ja/web/api/mediastream/getvideotracks/index.md @@ -1,6 +1,9 @@ --- -title: MediaStream.getVideoTracks() +title: "MediaStream: getVideoTracks() メソッド" +short-title: getVideoTracks() slug: Web/API/MediaStream/getVideoTracks +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 --- {{APIRef("Media Capture and Streams")}} @@ -9,8 +12,8 @@ slug: Web/API/MediaStream/getVideoTracks ## 構文 -```js -var mediaStreamTracks[] = mediaStream.getVideoTracks(); +```js-nolint +getVideoTracks() ``` ### 引数 @@ -23,15 +26,13 @@ var mediaStreamTracks[] = mediaStream.getVideoTracks(); > **メモ:** トラックの順序は仕様で定義されておらず、 `getVideoTracks()` の呼び出しごとに同じ順序になるとは限りません。 -この API の初期の版では、特別な `VideoStreamTrack` インターフェイスがあり、動画ストリームのリストに含まれる各項目の型として使用されていましたが、これはその後でメインの {{domxref("MediaStreamTrack")}} インターフェイスに統合されました。 - ## 例 次の例は、 [Chrome's Image Capture / Photo Resolution Sample](https://googlechrome.github.io/samples/image-capture/photo-resolution.html) (英語)から抜粋したものであり、 `getVideoTracks()` を用いて取得したトラックを {{domxref("ImageCapture.ImageCapture", "ImageCapture()")}} コンストラクターへ渡しています。 ```js -var imageCapture; +let imageCapture; navigator.mediaDevices.getUserMedia({ video: true }).then((mediaStream) => { document.querySelector("video").srcObject = mediaStream; diff --git a/files/ja/web/api/mediastream/id/index.md b/files/ja/web/api/mediastream/id/index.md index 0936d2da5ad4da..9dddc62be90293 100644 --- a/files/ja/web/api/mediastream/id/index.md +++ b/files/ja/web/api/mediastream/id/index.md @@ -1,24 +1,28 @@ --- -title: MediaStream.id +title: "MediaStream: id プロパティ" +short-title: id slug: Web/API/MediaStream/id +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- {{APIRef("Media Capture and Streams")}} -**`MediaStream.id()`** は読み取り専用プロパティであり、このオブジェクトの固有識別子 (GUID) である 36 文字で表現される {{domxref("DOMString")}} を返します。 +**`id`** は {{domxref("MediaStream")}} インターフェイスの読み取り専用プロパティで、このオブジェクトの固有識別子 (GUID) である 36 文字で表現される文字列を返します。 -## 構文 +## 値 -```js -var id = mediaStream.id; -``` +文字列です。 ## 例 ```js -var p = navigator.mediaDevices.getUserMedia({ audio: true, video: true }); +const promise = navigator.mediaDevices.getUserMedia({ + audio: true, + video: true, +}); -p.then(function (stream) { +promise.then((stream) => { console.log(stream.id); }); ``` diff --git a/files/ja/web/api/mediastream/index.md b/files/ja/web/api/mediastream/index.md index c3bc08133d1d4b..6a29ee8d541aa0 100644 --- a/files/ja/web/api/mediastream/index.md +++ b/files/ja/web/api/mediastream/index.md @@ -1,63 +1,48 @@ --- title: MediaStream slug: Web/API/MediaStream +l10n: + sourceCommit: 75d6fc9821feb4288e5bc7580c9d8176264d76ae --- {{APIRef("Media Capture and Streams")}} -**`MediaStream`** インターフェイスは、メディアコンテンツのストリームを表します。ストリームは動画や音声など複数の**トラック**から成ります。それぞれのトラックは {{domxref("MediaStreamTrack")}} のインスタンスとして定義されます。 +**`MediaStream`** は{{domxref("Media Capture and Streams API", "メディアキャプチャとストリーム API", "", "nocode")}} のインターフェイスで、メディアコンテンツのストリームを表します。ストリームは動画や音声など複数の**トラック**から成ります。それぞれのトラックは {{domxref("MediaStreamTrack")}} のインスタンスとして定義されます。 `MediaStream` オブジェクトを取得するには、コンストラクターを使用するか {{domxref("MediaDevices.getUserMedia()")}}, {{domxref("MediaDevices.getDisplayMedia()")}}, {{domxref("HTMLCanvasElement.captureStream()")}}　などの関数を呼び出すかします。 -ユーザーエージェントによっては、このインターフェイスを {{domxref("CanvasCaptureMediaStreamTrack")}} のようにサブクラス化して、より詳細な情報や機能を提供しています。 - {{InheritanceDiagram}} ## コンストラクター - {{domxref("MediaStream.MediaStream", "MediaStream()")}} - - : 新しい MediaStream オブジェクトを作成して返します。空のストリーム、既存のストリームに基づいたストリーム、 ({{domxref("MediaStreamTrack")}} オブジェクトの配列として指定して) 特定のトラックのリストを含むストリームを作成することができます。 + - : 新しい `MediaStream` オブジェクトを作成して返します。空のストリーム、既存のストリームに基づいたストリーム、 ({{domxref("MediaStreamTrack")}} オブジェクトの配列として指定して) 特定のトラックのリストを含むストリームを作成することができます。 -## プロパティ +## インスタンスプロパティ _このインターフェイスは親である {{domxref("EventTarget")}} からプロパティを継承しています。_ -- {{domxref("MediaStream.active")}} {{readonlyinline}} +- {{domxref("MediaStream.active")}} {{ReadOnlyInline}} - : 論理値で、 `true` は `MediaStream` がアクティブな時、 `false` はそうでない場合です。 -- {{domxref("MediaStream.id")}} {{readonlyInline}} - - : {{domxref("DOMString")}} で 36 文字のオブジェクトの汎用一意識別子 (UUID) を表す文字列が入ります。 +- {{domxref("MediaStream.id")}} {{ReadOnlyInline}} + - : 文字列で、 36 文字のオブジェクトの汎用一意識別子 ({{Glossary("UUID")}}) を表します。 -## メソッド +## インスタンスメソッド _このインターフェイスは親である {{domxref("EventTarget")}} からメソッドを継承しています。_ - {{domxref("MediaStream.addTrack()")}} - : 引数で指定された {{domxref("MediaStreamTrack")}} のコピーを格納します。トラックが既に `MediaStream` オブジェクトに追加されていた場合は、何も起こりません。 - - - - {{domxref("MediaStream.clone()")}} - : `MediaStream` オブジェクトの複製を返します。ただし、複製は固有の {{domxref("MediaStream.id", "id")}} の値を持ちます。 - - - - {{domxref("MediaStream.getAudioTracks()")}} - : {{domxref("MediaStreamTrack")}} オブジェクトのリストで、 `MediaStream` オブジェクトに格納されているものの中で `kind` 属性が `audio` に設定されているものを返します。順序は未定義であり、ブラウザーによって異なるばかりでなく、呼び出し毎に異なる可能性もあります。 - - - - {{domxref("MediaStream.getTrackById()")}} - : 引数 `trackid` で与えられた ID を持つトラックを返します。引数が与えられなかった場合や、その ID を持つトラックが存在しなかった場合は、 `null` を返します。複数のトラックが同じ ID を持っている場合は、最初の一つを返します。 - {{domxref("MediaStream.getTracks()")}} - : {{domxref("MediaStreamTrack")}} オブジェクトのリストで、 MediaStream オブジェクトに格納されているものをすべて、 `kind` 属性の値に関わらず返します。順序は未定義であり、ブラウザーによって異なるばかりでなく、呼び出し毎に異なる可能性もあります。 - - - - {{domxref("MediaStream.getVideoTracks()")}} - : {{domxref("MediaStreamTrack")}} オブジェクトのリストで、 MediaStream オブジェクトに格納されているものの中で kind 属性が video に設定されているものを返します。順序は未定義であり、ブラウザーによって異なるばかりでなく、呼び出し毎に異なる可能性もあります。 - - - - {{domxref("MediaStream.removeTrack()")}} - : 引数として与えられた {{domxref("MediaStreamTrack")}} を除去します。トラックが `MediaStream` オブジェクトに含まれていなかった場合は、何もしません。 @@ -67,15 +52,9 @@ _このインターフェイスは親である {{domxref("EventTarget")}} から - : 新しい {{domxref("MediaStreamTrack")}} オブジェクトが追加されたときに発行されます。 - {{domxref("MediaStream/removetrack_event", "removetrack")}} - : {{domxref("MediaStreamTrack")}} オブジェクトが除去されたときに発行されます。 - - - -- {{domxref("MediaStream/active_event", "active")}} +- {{domxref("MediaStream/active_event", "active")}} {{Non-standard_Inline}} - : この MediaStream がアクティブになったときに発行されます。 - - - -- {{domxref("MediaStream/inactive_event", "inactive")}} +- {{domxref("MediaStream/inactive_event", "inactive")}} {{Non-standard_Inline}} - : この MediaStream がアクティブでなくなったときに発行されます。 ## 仕様書 diff --git a/files/ja/web/api/mediastream/mediastream/index.md b/files/ja/web/api/mediastream/mediastream/index.md index 79885641fa67a2..e7828f2c7e0b7d 100644 --- a/files/ja/web/api/mediastream/mediastream/index.md +++ b/files/ja/web/api/mediastream/mediastream/index.md @@ -1,6 +1,9 @@ --- -title: MediaStream() +title: "MediaStream: MediaStream() コンストラクター" +short-title: MediaStream() slug: Web/API/MediaStream/MediaStream +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 --- {{APIRef("Media Capture and Streams")}} @@ -11,17 +14,17 @@ slug: Web/API/MediaStream/MediaStream ## 構文 -```js -new MediaStream(); -new MediaStream(stream); -new MediaStream(tracks); +```js-nolint +new MediaStream() +new MediaStream(stream) +new MediaStream(tracks) ``` ### 引数 -- `stream` +- `stream` {{optional_inline}} - : 様々な {{domxref("MediaStream")}} オブジェクトで、そのトラックが新しく生成されたストリームに自動的に追加されます。トラックは元のストリームから除去されないので、 2 つのストリームで共用されることになります。 -- `tracks` +- `tracks` {{optional_inline}} - : {{domxref("MediaStreamTrack")}} オブジェクトの {{jsxref("Array")}} で、それぞれがストリームに追加するトラックです。 ### 返値 diff --git a/files/ja/web/api/mediastream/removetrack/index.md b/files/ja/web/api/mediastream/removetrack/index.md new file mode 100644 index 00000000000000..a4dd6c567776a6 --- /dev/null +++ b/files/ja/web/api/mediastream/removetrack/index.md @@ -0,0 +1,75 @@ +--- +title: "MediaStream: removeTrack() メソッド" +short-title: removeTrack() +slug: Web/API/MediaStream/removeTrack +l10n: + sourceCommit: 84f8672adab0fdb783d02676c42a2b7ae16b3606 +--- + +{{APIRef("Media Capture and Streams")}} + +**`removeTrack()`** は {{domxref("MediaStream")}} インターフェイスのメソッドで、ストリームから {{domxref("MediaStreamTrack")}} を除去します。 + +## 構文 + +```js-nolint +removeTrack(track) +``` + +### 引数 + +- `track` + - : ストリームから除去される {{domxref("MediaStreamTrack")}} です。 + +### 返値 + +なし ({{jsxref("undefined")}})。 + +## 例 + +次の例は、 {{domxref("MediaStream")}} から音声トラックと映像トラックを除去する方法を示しています。 `fetchStreamFunction` は、 `fetchStreamButton` のイベントハンドラーです。このボタンがクリックされると、システムの機器から音声と動画がキャプチャされます。 `removeTracksFunction` は、 `removeTracksButton` のイベントハンドラーです。このボタンがクリックされると、音声と映像トラックが {{domxref("MediaStream")}} から除去されます。 + +```js +let initialStream = null; +let newStream = null; + +let fetchStreamButton = document.getElementById("fetchStream"); +let removeTracksButton = document.getElementById("removeTracks"); + +async function fetchStreamFunction() { + initialStream = await navigator.mediaDevices.getUserMedia({ + video: { width: 620, height: 310 }, + audio: true, + }); + if (initialStream) { + await attachToDOM(initialStream); + } +} + +async function attachToDOM(stream) { + newStream = new MediaStream(stream.getTracks()); + document.querySelector("video").srcObject = newStream; +} + +async function removeTracksFunction() { + let videoTrack = newStream.getVideoTracks()[0]; + let audioTrack = newStream.getAudioTracks()[0]; + + newStream.removeTrack(videoTrack); + newStream.removeTrack(audioTrack); + + // ストリームが空になる + console.log(newStream.getTracks()); +} + +fetchStreamButton.addEventListener("click", fetchStreamFunction); +removeTracksButton.addEventListener("click", removeTracksFunction); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/mediastream/removetrack_event/index.md b/files/ja/web/api/mediastream/removetrack_event/index.md index 74f63205415c50..a635eb04fea50d 100644 --- a/files/ja/web/api/mediastream/removetrack_event/index.md +++ b/files/ja/web/api/mediastream/removetrack_event/index.md @@ -1,11 +1,14 @@ --- title: "MediaStream: removetrack イベント" +short-title: removetrack slug: Web/API/MediaStream/removetrack_event +l10n: + sourceCommit: ac67e6f05d337e52e39f02a978b8c00bc43d583b --- {{APIRef("Media Capture and Streams")}} -`removetrack` イベントは、新しい [`MediaStreamTrack`](/ja/docs/Web/API/MediaStreamTrack) オブジェクトが [`MediaStream`](/ja/docs/Web/API/MediaStream) から取り除かれたときに発行されます。 +**`removetrack`** イベントは、新しい {{domxref("MediaStreamTrack")}} オブジェクトが {{domxref("MediaStream")}} から除去されたときに発行されます。 このイベントはキャンセル不可で、バブリングしません。 @@ -29,15 +32,15 @@ onremovetrack = (event) => {}; _親インターフェイスである {{domxref("Event")}} から継承したプロパティもあります。_ -- `track` {{ReadOnlyInline}} - - : {{domxref("MediaStreamTrack")}} オブジェクトで、このストリームから削除されたトラックを表します。 +- {{domxref("MediaStreamTrackEvent.track")}} {{ReadOnlyInline}} + - : {{domxref("MediaStreamTrack")}} オブジェクトで、このストリームから除去されたトラックを表します。 ## 例 `addEventListener()` を使用すると次にようになります。 ```js -let stream = new MediaStream(); +const stream = new MediaStream(); stream.addEventListener("removetrack", (event) => { console.log(`${event.track.kind} track removed`); @@ -47,7 +50,7 @@ stream.addEventListener("removetrack", (event) => { `onremovetrack` イベントハンドラープロパティを使用すると次にようになります。 ```js -let stream = new MediaStream(); +const stream = new MediaStream(); stream.onremovetrack = (event) => { console.log(`${event.track.kind} track removed`); @@ -67,5 +70,5 @@ stream.onremovetrack = (event) => { - 関連イベント: [`addtrack`](/ja/docs/Web/API/MediaStream/addtrack_event) - [`AudioTrackList`](/ja/docs/Web/API/AudioTrackList) をターゲットとしたこのイベント: [`removetrack`](/ja/docs/Web/API/AudioTrackList/removetrack_event) - [`VideoTrackList`](/ja/docs/Web/API/VideoTrackList) をターゲットとしたこのイベント: [`removetrack`](/ja/docs/Web/API/VideoTrackList/removetrack_event) -- [メディアストリーム API](/ja/docs/Web/API/Media_Streams_API) +- [メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Capture_and_Streams_API) - [WebRTC](/ja/docs/Web/API/WebRTC_API) diff --git a/files/ja/web/api/navigator/sendbeacon/index.md b/files/ja/web/api/navigator/sendbeacon/index.md index 28548250e95e03..635d36f179f212 100644 --- a/files/ja/web/api/navigator/sendbeacon/index.md +++ b/files/ja/web/api/navigator/sendbeacon/index.md @@ -1,24 +1,32 @@ --- -title: Navigator.sendBeacon() +title: "Navigator: sendBeacon() メソッド" +short-title: sendBeacon() slug: Web/API/Navigator/sendBeacon +l10n: + sourceCommit: 904cdf09c7e328b7a15a6a4db6bc6bd31f969cce --- {{APIRef("HTML DOM")}} -**`navigator.sendBeacon()`** メソッドは、ウェブサーバーに{{glossary("Asynchronous", "非同期")}}に少量のデータを {{Glossary("HTTP")}} で送るために使用することができます。 +**`navigator.sendBeacon()`** メソッドは、ウェブサーバーに{{glossary("Asynchronous", "非同期")}}に少量のデータを [HTTP POST](/ja/docs/Web/HTTP/Methods/POST) リクエストで送ります。 + +これはウェブサーバーに分析データを送信するために使用することを意図しており、 {{domxref("XMLHttpRequest", "XMLHttpRequest")}} を使用するような、分析を送信するための古い技術の問題のいくつかを避けています。 + +> **メモ:** `POST` 以外のメソッドでリクエストを送信したり、リクエストプロパティを変更したり、サーバのレスポンスにアクセスしたりする必要がある用途では、[`fetch()`](/ja/docs/Web/API/fetch) メソッドに [`keepalive`](/ja/docs/Web/API/fetch#keepalive) を設定したものを使用してください。 ## 構文 -``` -navigator.sendBeacon(url, data); +```js-nolint +sendBeacon(url) +sendBeacon(url, data) ``` ### 引数 - `url` - : _data_ を受け取る URL です。相対でも絶対でも可能です。 -- `data` - - : 送るデータを含む {{domxref("ArrayBuffer")}}, {{domxref("ArrayBufferView")}}, {{domxref("Blob")}}, {{domxref("DOMString")}}, {{domxref("FormData")}}, {{domxref("ReadableStream")}}, {{domxref("URLSearchParams")}} のいずれかのオブジェクトです。 +- `data` {{Optional_inline}} + - : 送るデータを含む {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, {{jsxref("DataView")}}, {{domxref("Blob")}}, 文字列リテラルまたはオブジェクト、{{domxref("FormData")}}, {{domxref("URLSearchParams")}} のいずれかのオブジェクトです。 ### 返値 @@ -26,45 +34,69 @@ navigator.sendBeacon(url, data); ## 解説 -このメソッドは、アナリティクスや診断のために、データの送信が早すぎるとデータ収集の機会を失う可能性があるような場合、文書がアンロードされる前にサーバーにデータを送信するものです。例えば、他のページに移動してページがアンロードされる前にユーザーがどのリンクをクリックしたかなどです。 +このメソッドは、データをサーバーに送信する分析や診断コードのためのものです。 -文書のアンロード時に確実にデータが送信されるようにするのは開発者にとってずっと難しいことでした。ユーザーエージェントは通常 {{domxref("Window/unload_event", "unload")}} ハンドラーの中で生成された非同期 {{domxref("XMLHttpRequest")}} を無視するからです。 +分析を送信する際の問題点として、サイトが多いのは、ユーザーがページの閲覧を完了したときに分析を送信したい場合です。例えば、ユーザーが別のページに移動したときなどです。このような場合、ブラウザーはページをアンロードしようとしている可能性があり、ブラウザーは非同期 {{domxref("XMLHttpRequest")}} リクエストを送信しないことを選ぶかもしれません。 伝統的には、これは以下のような回避方法を使用して、ある URL にデータを送信するまでページのアンロードを遅らせるよう位置づけられていました。 -- ブロックする同期 `XMLHttpRequest` の呼び出しを `unload` または {{domxref("Window/beforeunload_event", "beforeunload")}} イベントハンドラーの中で行い、データを送信する。 +- データの送信をブロックする同期 `XMLHttpRequest` の呼び出しで行う。 - {{HTMLElement("img")}} 要素を作成し、その `src` を `unload` ハンドラーの中で設定する。ほとんどのユーザーエージェントは画像を読み込むためにアンロードを遅延させる。 -- `unload` ハンドラー内で何もしないループを作成する。 +- 数秒の何もしないループを作成する。 これらの方法はすべて、文書のアンロードをブロックするので、次への遷移が遅くなります。次のページがこれをやめさせる方法は存在しないので、前のページの問題であるにもかかわらず、次のページが遅いように見えます。 -次の例は `unload` ハンドラーで同期 `XMLHttpRequest` を送ってサーバにデータを送信しようとする理論的なアナリティクスのコードです。これは、次のページの読み込みが遅らせられる結果になります。 +`sendBeacon()` メソッドでは、ユーザーエージェントがその機会を持ったときに、アンロードや次のナビゲーションを遅らせることなく、非同期にデータを送信します。つまり、 + +- データは確実に送信されます。 +- 非同期に送信されます。 +- 次のページの読み込みには影響しません + +データは [HTTP POST](/ja/docs/Web/HTTP/Methods/POST) リクエストで送信されます。 + +### セッション終了時の分析の送信 + +ウェブサイトでは、ユーザーがページの閲覧を完了したときに、サーバーに分析結果や診断結果を送信したいことがよくあります。 +これを行う最も信頼性の高い方法は、[`visibilitychange`](/ja/docs/Web/API/Document/visibilitychange_event) イベントでデータを送信することです。 ```js -window.addEventListener("unload", function logData() { - var xhr = new XMLHttpRequest(); - xhr.open("POST", "/log", false); // third parameter of `false` means synchronous - xhr.send(analyticsData); +document.addEventListener("visibilitychange", function logData() { + if (document.visibilityState === "hidden") { + navigator.sendBeacon("/log", analyticsData); + } }); ``` -これが **`sendBeacon()`** で置き換わるところです。 `sendBeacon()` メソッドにより、ユーザーエージェントが行う機会があればデータが非同期に送信され、アンロードや次への遷移が遅れることはありません。**これはアナリティクスのデータを送信する際の問題をすべて解決します。** +#### unload および beforeunload を避ける -- データの送信の信頼性が高い -- 非同期に送信される -- 次のページの読み込みへの影響がない -- 加えて、どの古いテクニックよりも簡単にコードを書くことができる。 +これまで多くのウェブサイトは、セッションの終わりにアナリティクスを送信するために、 [`unload`](/ja/docs/Web/API/Window/unload_event) または [`beforeunload`](/ja/docs/Web/API/Window/beforeunload_event) イベントを使用してきました。 +しかし、これは非常に信頼性に欠けます。多くの場合、特にモバイルでは、ブラウザーは `unload`、`beforeunload`、`pagehide` イベントを発行しません。例えば、次の例ではこれらのイベントは発行されません。 -次の例は、 `sendBeacon()` メソッドを使用してサーバーにデータを送信する、理論的なアナリティクスのコードパターンです。 +1. ユーザーがページを読み込んで操作します。 +2. 完了語、タブを閉じずに別のアプリに切り替えます。 +3. その後、携帯電話のアプリマネージャーによってブラウザーアプリが閉じられました。 + +さらに、 `unload` イベントは現行ブラウザーに実装されているバック/フォワードキャッシュ ([bfcache](https://web.dev/articles/bfcache)) と互換性がありません。 Firefox のような一部のブラウザーは、アンロードハンドラーを格納したページを bfcache から除外することでこの非互換性を処理し、パフォーマンスを低下させています。他にも、 Safari や Android の Chrome などでは、ユーザーが同じタブで別のページに移動したときに `unload` イベントを発生させないように処理しています。 + +Firefox はまた、ページが `beforeunload` ハンドラーを格納している場合、bfcache からページを除外します。 + +#### pagehide をフォールバックとして使う + +`visibilitychange` を実装していないブラウザーに対応するには、 [`pagehide`](/ja/docs/Web/API/Window/pagehide_event) イベントを使用します。 +`beforeunload` と `unload` のように、このイベントは特にモバイルでは確実に発行されるわけではありません。しかし、 bfcache と互換性があります。 + +## 例 + +次の例では、　{{domxref("document.visibilitychange_event", "visibilitychange")}}　イベントのハンドラーを指定しています。ハンドラーは `sendBeacon()` を呼び出して分析を送信します。 ```js -window.addEventListener("unload", function logData() { - navigator.sendBeacon("/log", analyticsData); +document.addEventListener("visibilitychange", function logData() { + if (document.visibilityState === "hidden") { + navigator.sendBeacon("/log", analyticsData); + } }); ``` -ビーコンは HTTP リクエストを POST メソッドで送信し、関連する Cookie も呼び出し時にすべて利用できます。 - ## 仕様書 {{Specifications}} @@ -75,4 +107,9 @@ window.addEventListener("unload", function logData() { ## 関連情報 -- {{domxref("navigator", "navigator")}} +- [`visibilitychange`](/ja/docs/Web/API/Document/visibilitychange_event) イベント +- {{domxref("Beacon_API","ビーコン API", "", "true")}} 概要ページ +- [Don't lose user and app state, use Page Visibility](https://www.igvita.com/2015/11/20/dont-lose-user-and-app-state-use-page-visibility/) は、 `beforeunload`/`unload`ではなく、`visibilitychange`を使用する理由について詳しく説明しています。 +- [Page Lifecycle API](https://developer.chrome.com/blog/page-lifecycle-api/#developer-recommendations-for-each-state) は、ウェブアプリケーションでページのライフサイクル動作を処理するための最善の手法を提供します。 +- [PageLifecycle.js](https://github.com/GoogleChromeLabs/page-lifecycle): ページのライフサイクル動作におけるクロスブラウザーでの不整合に対処する JavaScript ライブラリーです。 +- [Back/forward cache](https://web.dev/articles/bfcache) は、バック/フォワードキャッシュとは何か、そして様々なページライフサイクルイベントに対するその意味について説明します。 diff --git a/files/ja/web/api/notificationevent/action/index.md b/files/ja/web/api/notificationevent/action/index.md index 46de2abc2cadd4..c35f70a71e65e4 100644 --- a/files/ja/web/api/notificationevent/action/index.md +++ b/files/ja/web/api/notificationevent/action/index.md @@ -1,15 +1,18 @@ --- -title: NotificationEvent.action +title: "NotificationEvent: action プロパティ" +short-title: action slug: Web/API/NotificationEvent/action +l10n: + sourceCommit: 212e53bbdaf88af59a57ec1f335bde5e828b68c5 --- {{APIRef("Web Notifications")}} -ユーザーがクリックした通知ボタンの文字列 ID を返します。ユーザーがアクションボタン以外の場所で通知をクリックした場合、または通知にボタンがない場合、この値は空の文字列を返します。通知 ID は、アクション配列属性を介した通知の作成中に設定され、通知が置き換えられない限り変更することはできません。 +**`action`** は {{domxref("NotificationEvent")}} インターフェイスの読み取り専用プロパティで、ユーザーがクリックした通知ボタンの文字列 ID を返します。ユーザーがアクションボタン以外の場所で通知をクリックした場合、または通知にボタンがない場合、この値は空の文字列を返します。通知 ID は、アクション配列属性を介した通知の作成中に設定され、通知が置き換えられない限り変更することはできません。 ## 返値 -{{domxref("DOMString")}} オブジェクト。 +文字列です。 ## 例 @@ -20,7 +23,7 @@ self.registration.showNotification("New articles available", { self.addEventListener( "notificationclick", - function (event) { + (event) => { event.notification.close(); if (event.action === "get") { synchronizeReader(); diff --git a/files/ja/web/api/pannernode/coneinnerangle/index.md b/files/ja/web/api/pannernode/coneinnerangle/index.md index 702eee31b3c81d..001f3029afe94c 100644 --- a/files/ja/web/api/pannernode/coneinnerangle/index.md +++ b/files/ja/web/api/pannernode/coneinnerangle/index.md @@ -1,6 +1,9 @@ --- -title: PannerNode.coneInnerAngle +title: "PannerNode: coneInnerAngle プロパティ" +short-title: coneInnerAngle slug: Web/API/PannerNode/coneInnerAngle +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- {{ APIRef("Web Audio API") }} diff --git a/files/ja/web/api/pannernode/coneouterangle/index.md b/files/ja/web/api/pannernode/coneouterangle/index.md index bc6e58f155d410..1e4d6157376faa 100644 --- a/files/ja/web/api/pannernode/coneouterangle/index.md +++ b/files/ja/web/api/pannernode/coneouterangle/index.md @@ -1,11 +1,14 @@ --- -title: PannerNode.coneOuterAngle +title: "PannerNode: coneOuterAngle プロパティ" +short-title: coneOuterAngle slug: Web/API/PannerNode/coneOuterAngle +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- {{ APIRef("Web Audio API") }} -`coneOuterAngle` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、倍精度実数値で円錐の外側の体積を一定値だけ減少させる角度を、度単位で記述します。 +`coneOuterAngle` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、 {{domxref("PannerNode.coneOuterGain","coneOuterGain")}} プロパティで定義する、倍精度実数値で円錐の外側の体積を一定値だけ減少させる角度を、度単位で記述します。 `coneOuterAngle` プロパティの既定の値は `0` です。 diff --git a/files/ja/web/api/pannernode/coneoutergain/index.md b/files/ja/web/api/pannernode/coneoutergain/index.md new file mode 100644 index 00000000000000..e0f44bdcd1eb86 --- /dev/null +++ b/files/ja/web/api/pannernode/coneoutergain/index.md @@ -0,0 +1,39 @@ +--- +title: "PannerNode: coneOuterGain プロパティ" +short-title: coneOuterGain +slug: Web/API/PannerNode/coneOuterGain +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`coneOuterGain` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、インターフェイスは倍精度浮動小数点値で、 {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}} 属性で定義される円錐の外側の体積減少量を記述します。 + +`coneOuterGain` プロパティの既定値は `0` で、コーンの外側に音が聞こえないことを意味しています。 + +## 値 + +倍精度浮動小数点値です。既定値は `0` で、その値は 0 ～ 1 の範囲で指定できます。 + +### 例外 + +- `InvalidStateError` {{domxref("DOMException")}} + - : プロパティに受け入れられる範囲 (0-1) の外の値が指定された場合に発生します。 + +## 例 + +[`PannerNode.orientationX`](/ja/docs/Web/API/PannerNode/orientationX#例) の例で、 {{domxref("PannerNode")}} の向きの引数を {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}} と {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}} の組み合わせで変更した場合の音量への影響の例を示しています。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) diff --git a/files/ja/web/api/pannernode/distancemodel/index.md b/files/ja/web/api/pannernode/distancemodel/index.md new file mode 100644 index 00000000000000..f10f20b18a7bad --- /dev/null +++ b/files/ja/web/api/pannernode/distancemodel/index.md @@ -0,0 +1,43 @@ +--- +title: "PannerNode: distanceModel プロパティ" +short-title: distanceModel +slug: Web/API/PannerNode/distanceModel +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`distanceModel` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースがリスナーから遠ざかるにつれて音量を縮小するために使用するアルゴリズムを決定する列挙値です。 + +取りうる値は次の通りです。 + +- `linear`: 線形距離モデルで、距離によって誘発されるゲインを計算します。 + `1 - rolloffFactor * (distance - refDistance) / (maxDistance - refDistance)` +- `inverse`: 逆距離モデルで、距離によって誘発されるゲインを計算します。 + `refDistance / (refDistance + rolloffFactor * (Math.max(distance, refDistance) - refDistance))` +- `exponential`: 指数距離モデルで、距離によって誘発されるゲインを計算します。 + `pow((Math.max(distance, refDistance) / refDistance, -rolloffFactor)`. + +`inverse` が `distanceModel` の既定値です。 + +## 値 + +列挙型です。 [`DistanceModelType`](https://webaudio.github.io/web-audio-api/#idl-def-DistanceModelType) を参照してください。 + +## 例 + +例のコードのについては [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#examples) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) diff --git a/files/ja/web/api/pannernode/index.md b/files/ja/web/api/pannernode/index.md index 32bf0c890618ae..f18cf0ec0f61b7 100644 --- a/files/ja/web/api/pannernode/index.md +++ b/files/ja/web/api/pannernode/index.md @@ -1,6 +1,8 @@ --- title: PannerNode slug: Web/API/PannerNode +l10n: + sourceCommit: 4e9294d45c5d338be7799cc6d65f1867b87d7fc0 --- {{ APIRef("Web Audio API") }} @@ -43,7 +45,7 @@ slug: Web/API/PannerNode - {{domxref("PannerNode.PannerNode", "PannerNode()")}} - : 新しい `PannerNode` オブジェクトを作成します。 -## プロパティ +## インスタンスプロパティ _親である {{domxref("AudioNode")}} からプロパティを継承しています。_ @@ -78,7 +80,7 @@ _親である {{domxref("AudioNode")}} からプロパティを継承してい - {{domxref("PannerNode.rolloffFactor")}} - : 音源が聴取者から離れていく際に起きる音量の低減量を定めます。この値は、全ての距離モデルで利用されます。 -## メソッド +## インスタンスメソッド _親である {{domxref("AudioNode")}} のメソッドを継承しています。_ @@ -86,12 +88,10 @@ _親である {{domxref("AudioNode")}} のメソッドを継承しています - : 聞き手（{{domxref("BaseAudioContext.listener")}} 属性に格納された {{domxref("AudioListener")}} オブジェクトで表される）からの音源の相対位置を定義します。 - {{domxref("PannerNode.setOrientation()")}} {{deprecated_inline}} - : 音源が再生されている方向を設定します。 -- {{domxref("PannerNode.setVelocity()")}} {{deprecated_inline}} - - : 音源の速度を表したベクトルです。移動する速さと方向を表しています。以前の仕様では下流に接続された{{domxref("AudioBufferSourceNode")}} のピッチを上げ下げするために、{{domxref("PannerNode")}} は速度を表す属性を持っていました。この機能は明確に定義されておらず、問題も多かったため、現在の仕様からは削除されています。 ## 例 -コード例については [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#example) を参照してください。 +コード例については [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#例) を参照してください。 ## 仕様書 diff --git a/files/ja/web/api/pannernode/maxdistance/index.md b/files/ja/web/api/pannernode/maxdistance/index.md new file mode 100644 index 00000000000000..c273dfa017d1ac --- /dev/null +++ b/files/ja/web/api/pannernode/maxdistance/index.md @@ -0,0 +1,38 @@ +--- +title: "PannerNode: maxDistance プロパティ" +short-title: maxDistance +slug: Web/API/PannerNode/maxDistance +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`maxDistance` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、インターフェイスは音声ソースとリスナーの間の最大距離を表す倍精度浮動小数点値です。それ以上音量を縮小しないようにします。この値は `linear` 距離モデルでのみ使用します。 + +`maxDistance` プロパティの既定値は `10000` です。 + +## 値 + +倍精度浮動小数点値です。既定値は `10000` であり、正ではない値は許可されません。 + +### 例外 + +- {{jsxref("RangeError")}} + - : プロパティに受け入れられる範囲外の値が指定された場合に発生します。 + +## 例 + +例のコードのについては [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#examples) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/pannernode/orientationx/index.md b/files/ja/web/api/pannernode/orientationx/index.md index dfa6e73b77976f..e5bc3222606bfe 100644 --- a/files/ja/web/api/pannernode/orientationx/index.md +++ b/files/ja/web/api/pannernode/orientationx/index.md @@ -1,11 +1,14 @@ --- -title: PannerNode.orientationX +title: "PannerNode: orientationX プロパティ" +short-title: orientationX slug: Web/API/PannerNode/orientationX +l10n: + sourceCommit: 1a91b0b63f0cbaca9125bd48d4e5bc8afed2a7a3 --- {{ APIRef("Web Audio API") }} -**`orientationX`** は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースが向いている方向の X (水平) 成分を 3D 直交座標空間で表示します。 +**`orientationX`** は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースが向いている方向の X （水平）成分を 3D 直交座標空間で表示します。 完全ベクトルは ({{domxref("PannerNode.positionX", "positionX")}}、{{domxref("PannerNode.positionY", "positionY")}}、{{domxref("PannerNode.positionZ", "positionZ")}}) として与えられた音声ソースの位置と、({{domxref("PannerNode.orientationX", "orientationX")}}、{{domxref("PannerNode.orientationY", "orientationY")}}、{{domxref("PannerNode.orientationZ", "orientationZ")}}) として与えられた音声ソースの向き (つまり、音声ソースが向いている方向) によって定義されます。 @@ -23,7 +26,7 @@ slug: Web/API/PannerNode/orientationX ![This chart visualizes how the PannerNode orientation vectors affect the direction of the sound cone.](pannernode-orientation.png) -まず、方向ベクトルを理解するためのユーティリティ関数を作成することから始めましょう。X 成分と Z 成分は常に互いに 90°であるため、ラジアン単位で同じ量だけオフセットされる正弦関数と余弦関数を使用できます。ただし、これは通常、{{ domxref("PannerNode") }} が 0°回転で聞き手の**左側**を指すことを意味します。`x= cos(0)= 1` および `z = sin(0) = 0` であるためです。角度を -90°オフセットするとより便利です。つまり、{{ domxref("PannerNode") }} は 0°の回転で**聞き手を直接**指します。 +まず、方向ベクトルを理解するためのユーティリティ関数を作成することから始めましょう。X 成分と Z 成分は常に互いに 90°であるため、ラジアン単位で同じ量だけオフセットされる正弦関数と余弦関数を使用できます。ただし、これは通常、{{ domxref("PannerNode") }} が 0°回転で聞き手の**左側**を指すことを意味します。`x= cos(0)= 1` および `z = sin(0) = 0` であるためです。角度を -90°オフセットするとより便利です。つまり、{{domxref("PannerNode")}} は 0°の回転で**聞き手を直接**指します。 ```js // このユーティリティは、Y 軸周りの回転量 (つまり「水平面」での回転) を @@ -41,7 +44,7 @@ const yRotationToVector = (degrees) => { }; ``` -これで、{{ domxref("AudioContext") }}、オシレーター、および {{ domxref("PannerNode") }} を作成できます。 +これで、{{ domxref("AudioContext") }}、発振器、および {{ domxref("PannerNode") }} を作成できます。 ```js const context = new AudioContext(); @@ -94,7 +97,7 @@ panner.orientationY.setValueAtTime(y2, context.currentTime + 2); panner.orientationZ.setValueAtTime(z2, context.currentTime + 2); ``` -最後に、すべてのノードを接続して、オシレーターを起動しましょう。 +最後に、すべてのノードを接続して、発振器を起動しましょう。 ```js osc.connect(panner).connect(context.destination); diff --git a/files/ja/web/api/pannernode/orientationx/pannernode-orientation.png b/files/ja/web/api/pannernode/orientationx/pannernode-orientation.png new file mode 100644 index 00000000000000..eddf82e5bc7d79 Binary files /dev/null and b/files/ja/web/api/pannernode/orientationx/pannernode-orientation.png differ diff --git a/files/ja/web/api/pannernode/orientationy/index.md b/files/ja/web/api/pannernode/orientationy/index.md new file mode 100644 index 00000000000000..3fba11db006a5e --- /dev/null +++ b/files/ja/web/api/pannernode/orientationy/index.md @@ -0,0 +1,39 @@ +--- +title: "PannerNode: orientationY プロパティ" +short-title: orientationY +slug: Web/API/PannerNode/orientationY +l10n: + sourceCommit: 1a91b0b63f0cbaca9125bd48d4e5bc8afed2a7a3 +--- + +{{ APIRef("Web Audio API") }} + +**`orientationY`** は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースが向いている方向の Y （垂直）成分を 3D 直交座標空間で表示します。 + +完全ベクトルは ({{domxref("PannerNode.positionX", "positionX")}}、{{domxref("PannerNode.positionY", "positionY")}}、{{domxref("PannerNode.positionZ", "positionZ")}}) として与えられた音声ソースの位置と、({{domxref("PannerNode.orientationX", "orientationX")}}、{{domxref("PannerNode.orientationY", "orientationY")}}、{{domxref("PannerNode.orientationZ", "orientationZ")}}) として与えられた音声ソースの向き (つまり、音声ソースが向いている方向) によって定義されます。 + +音の指向性（{{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}}、{{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}}、{{domxref("PannerNode.coneOuterGain", "coneOuterGain")}} の属性を使用して指定されている）に応じて、音の方向 (orientation) は、再生中の音が知覚される音量を変化させることがあります。音が聞き手の方に向けられている場合は、聞き手から離れたところに向けられている場合よりも大きな音になります。 + +このプロパティに含まれる {{domxref("AudioParam")}} は読み取り専用ですが、{{domxref("AudioParam.value")}} プロパティに新しい値を代入することで、引数の値を変更できます。 + +## 値 + +{{domxref("AudioParam")}} の `value` は、音声ソースが向いている方向の Y 成分であり、3D 直交座標空間での値です。 + +## 例 + +例のコードの付いては [`PannerNode.orientationX`](/ja/docs/Web/API/PannerNode/orientationX#例) を参照してください。これは、 {{domxref("PannerNode")}} の方向引数を {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}} および {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}} と結合して変更した場合の体積への影響を示しています。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) +- {{domxref("PannerNode")}} diff --git a/files/ja/web/api/pannernode/orientationz/index.md b/files/ja/web/api/pannernode/orientationz/index.md new file mode 100644 index 00000000000000..63dbc15e56e86c --- /dev/null +++ b/files/ja/web/api/pannernode/orientationz/index.md @@ -0,0 +1,39 @@ +--- +title: "PannerNode: orientationZ プロパティ" +short-title: orientationZ +slug: Web/API/PannerNode/orientationZ +l10n: + sourceCommit: 1a91b0b63f0cbaca9125bd48d4e5bc8afed2a7a3 +--- + +{{ APIRef("Web Audio API") }} + +**`orientationY`** は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースが向いている方向の Z （奥行）成分を 3D 直交座標空間で表示します。 + +完全ベクトルは ({{domxref("PannerNode.positionX", "positionX")}}、{{domxref("PannerNode.positionY", "positionY")}}、{{domxref("PannerNode.positionZ", "positionZ")}}) として与えられた音声ソースの位置と、({{domxref("PannerNode.orientationX", "orientationX")}}、{{domxref("PannerNode.orientationY", "orientationY")}}、{{domxref("PannerNode.orientationZ", "orientationZ")}}) として与えられた音声ソースの向き (つまり、音声ソースが向いている方向) によって定義されます。 + +音の指向性（{{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}}、{{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}}、{{domxref("PannerNode.coneOuterGain", "coneOuterGain")}} の属性を使用して指定されている）に応じて、音の方向 (orientation) は、再生中の音が知覚される音量を変化させることがあります。音が聞き手の方に向けられている場合は、聞き手から離れたところに向けられている場合よりも大きな音になります。 + +このプロパティに含まれる {{domxref("AudioParam")}} は読み取り専用ですが、{{domxref("AudioParam.value")}} プロパティに新しい値を代入することで、引数の値を変更できます。 + +## 値 + +{{domxref("AudioParam")}} の `value` は、音声ソースが向いている方向の Z 成分であり、3D 直交座標空間での値です。 + +## 例 + +例のコードの付いては [`PannerNode.orientationX`](/ja/docs/Web/API/PannerNode/orientationX#例) を参照してください。これは、 {{domxref("PannerNode")}} の方向引数を {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}} および {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}} と結合して変更した場合の体積への影響を示しています。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) +- {{domxref("PannerNode")}} diff --git a/files/ja/web/api/pannernode/pannernode/index.md b/files/ja/web/api/pannernode/pannernode/index.md new file mode 100644 index 00000000000000..4a0ace2011f525 --- /dev/null +++ b/files/ja/web/api/pannernode/pannernode/index.md @@ -0,0 +1,89 @@ +--- +title: "PannerNode: PannerNode() コンストラクター" +short-title: PannerNode() +slug: Web/API/PannerNode/PannerNode +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{APIRef("Web Audio API")}} + +**`PannerNode()`** は[ウェブオーディオ API](/ja/docs/Web/API/Web_Audio_API) のコンストラクターで、新しい {{domxref("PannerNode")}} オブジェクトインスタンスを生成します。 + +## 構文 + +```js-nolint +new PannerNode(context) +new PannerNode(context, options) +``` + +### 引数 + +- `context` + - : ノードを関連付けたい音声コンテキストを表す {{domxref("BaseAudioContext")}} です。 +- `options` {{optional_inline}} + + - : `PannerNode` に設定したいプロパティを定義する [`PannerOptions`](https://webaudio.github.io/web-audio-api/#idl-def-PannerOptions) 辞書オブジェクトです。 + + - `panningModel` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.panningModel")}} （既定値は `equalpower` です。） + - `distanceModel` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.distanceModel")}} （既定値は `inverse` です。） + - `positionX` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.positionX")}} （既定値は `0` です。） + - `positionY` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.positionY")}} （既定値は `0` です。） + - `positionZ` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.positionZ")}} （既定値は `0` です。） + - `orientationX` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.orientationX")}} （既定値は `1` です。） + - `orientationY` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.orientationY")}} （既定値は `0` です。） + - `orientationZ` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.orientationZ")}} （既定値は `0` です。） + - `refDistance` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.refDistance")}} です。既定値は `1` であり、負の値は許可されません。 + - `maxDistance` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.maxDistance")}} です。既定値は `10000` であり、正でない値は許可されません。 + - `rolloffFactor` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.rolloffFactor")}} です。既定値は `1` であり、負の値は許可されません。 + - `coneInnerAngle` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.coneInnerAngle")}} （既定値は `360` です。） + - `coneOuterAngle` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.coneOuterAngle")}} （既定値は `360` です。） + - `coneOuterGain` + - : {{domxref("PannerNode")}} に設定したい {{domxref("PannerNode.coneOuterGain")}} です。既定値は `0` であり、値は 0 ～ 1 の範囲を取ることができます。 + - `channelCount` + - : ノードへの任意の入力への[アップミキシングとダウンミキシング](/ja/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API#up-mixing_and_down-mixing)接続時に使用するチャンネル数を決定するための整数を表します。（詳細は {{domxref("AudioNode.channelCount")}} を参照してください。）使用法と正確な定義は `channelCountMode` の値に依存します。 + - `channelCountMode` + - : ノードの入出力間でチャンネルを照合する方法を記述する列挙値を表します。（既定値を含む詳細は {{domxref("AudioNode.channelCountMode")}} を参照してください。） + - `channelInterpretation` + - : チャンネルの意味を記述する列挙値を表します。この解釈によって、音声の[アップミキシングやダウンミキシング](/ja/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API#up-mixing_and_down-mixing)がどのように行われるかを定義します。可能な値は "speakers" または "discrete" です。（既定値を含む詳細は {{domxref("AudioNode.channelCountMode")}} を参照してください。） + +### 例外 + +- {{jsxref("RangeError")}} + - : `refDistance`、`maxDistance`、`rolloffFactor` プロパティに受け入れられる範囲外の値が指定された場合に発生します。 +- `InvalidStateError` {{domxref("DOMException")}} + - : `coneOuterGain` プロパティに受け入れられる範囲外 (0 ～ 1) の値が指定された場合に発生します。 + +## 例 + +```js +const ctx = new AudioContext(); + +const options = { + positionX: 1, + maxDistance: 5000, +}; + +const myPanner = new PannerNode(ctx, options); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/pannernode/panningmodel/index.md b/files/ja/web/api/pannernode/panningmodel/index.md new file mode 100644 index 00000000000000..f6d7f9f8334554 --- /dev/null +++ b/files/ja/web/api/pannernode/panningmodel/index.md @@ -0,0 +1,36 @@ +--- +title: "PannerNode: panningModel プロパティ" +short-title: panningModel +slug: Web/API/PannerNode/panningModel +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`panningModel` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、 3D 空間で音声を配置するために使用する空間化アルゴリズムを決定する列挙値です。 + +取りうる値は次の通りです。 + +- `equalpower`: 一般に単純で効率的と見なされる等出力のパンニングアルゴリズムを表します。 `equalpower` が既定値です。 +- `HRTF`: `equalpower` よりも高品質なステレオ出力をレンダリングします。人間の被験者から測定したインパルスレスポンスによるコンボリューションを使用します。 + +## 値 + +列挙値です。 [`PanningModelType`](https://webaudio.github.io/web-audio-api/#idl-def-PanningModelType) を参照してください。 + +## 例 + +例のコードのについては [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#examples) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/pannernode/positionx/index.md b/files/ja/web/api/pannernode/positionx/index.md new file mode 100644 index 00000000000000..8bb55519706133 --- /dev/null +++ b/files/ja/web/api/pannernode/positionx/index.md @@ -0,0 +1,54 @@ +--- +title: "PannerNode: positionX プロパティ" +short-title: positionX +slug: Web/API/PannerNode/positionX +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +**`positionX`** は {{ domxref("PannerNode")}} インターフェイスのプロパティで、水平軸（左右）に対応する、 3D 直交座標での音声ソースの位置の X 座標を指定します。 + +完全にベクトルを定義するのは、 ({{domxref("PannerNode.positionX", "positionX")}}, {{domxref("PannerNode.positionY", "positionY")}}, {{domxref("PannerNode.positionZ", "positionZ")}}) で指定された音声ソースの位置と、 ({{domxref("PannerNode.orientationX", "orientationX")}}, {{domxref("PannerNode.orientationY", "orientationY")}}, {{domxref("PannerNode.orientationZ", "orientationZ")}}) で指定された音声ソースの方向（つまり、それが向いている方向）です。 + +音の指向性（属性 {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}}, {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}}, {{domxref("PannerNode.coneOuterGain", "codeOuterGain")}} を使用して指定）によって、使用する音の方向が、知覚される音量を変えるこ とがあります。音が聞き手の方を向いている場合は、音が聞き手から離れている場合よりも大きくなります。 + +このプロパティが保持している {{domxref("AudioParam")}} は読み取り専用ですが、 {{domxref("AudioParam.value")}} プロパティに新しい値を割り当てることで、引数の値を変更することができます。 + +## 値 + +{{domxref("AudioParam")}} で、その `value` は音声ソースの位置の X 座標（3D 直交座標）です。既定値は 0 です。 + +## 例 + +次の例は発振器を発振し、 1 秒後に左に、 2 秒後に右に、 3 秒後に中央にパンします。 + +```js +const context = new AudioContext(); + +const osc = new OscillatorNode(context); +const panner = new PannerNode(context); + +panner.positionX.setValueAtTime(-1, context.currentTime + 1); +panner.positionX.setValueAtTime(1, context.currentTime + 2); +panner.positionX.setValueAtTime(0, context.currentTime + 3); + +osc.connect(panner).connect(context.destination); + +osc.start(0); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) +- {{domxref("PannerNode")}} diff --git a/files/ja/web/api/pannernode/positiony/index.md b/files/ja/web/api/pannernode/positiony/index.md new file mode 100644 index 00000000000000..f4ca52ed4560a2 --- /dev/null +++ b/files/ja/web/api/pannernode/positiony/index.md @@ -0,0 +1,53 @@ +--- +title: "PannerNode: positionY プロパティ" +short-title: positionY +slug: Web/API/PannerNode/positionY +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +**`positionY`** は {{ domxref("PannerNode")}} インターフェイスのプロパティで、垂直軸（上下）に対応する、 3D 直交座標での音声ソースの位置の Y 座標を指定します。完全にベクトルを定義するのは、 ({{domxref("PannerNode.positionX", "positionX")}}, {{domxref("PannerNode.positionY", "positionY")}}, {{domxref("PannerNode.positionZ", "positionZ")}}) で指定された音声ソースの位置と、 ({{domxref("PannerNode.orientationX", "orientationX")}}, {{domxref("PannerNode.orientationY", "orientationY")}}, {{domxref("PannerNode.orientationZ", "orientationZ")}}) で指定された音声ソースの方向（つまり、それが向いている方向）です。 + +音の指向性（属性 {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}}, {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}}, {{domxref("PannerNode.coneOuterGain", "codeOuterGain")}} を使用して指定）によって、使用する音の方向が、知覚される音量を変えることがあります。音が聞き手の方を向いている場合は、音が聞き手から離れている場合よりも大きくなります。 + +このプロパティが保持している {{domxref("AudioParam")}} は読み取り専用ですが、 {{domxref("AudioParam.value")}} プロパティに新しい値を割り当てることで、引数の値を変更することができます。 + +## 値 + +{{domxref("AudioParam")}} で、その `value` は音声ソースの位置の Y 座標（3D 直交座標）です。既定値は 0 です。 + +## 例 + +次の例は、発振器を開始し、 1 秒後にリスナーの上へ、 2 秒後にリスナーの下へ、 3 秒後に中央へパンします。この場合、単純なモノラル波なので、変化は主に発振器の音色に影響することに注意してください。 + +```js +const context = new AudioContext(); + +const osc = new OscillatorNode(context); +const panner = new PannerNode(context); +panner.panningModel = "HRTF"; + +panner.positionY.setValueAtTime(1, context.currentTime + 1); +panner.positionY.setValueAtTime(-1, context.currentTime + 2); +panner.positionY.setValueAtTime(0, context.currentTime + 3); + +osc.connect(panner).connect(context.destination); + +osc.start(0); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) +- {{domxref("PannerNode")}} diff --git a/files/ja/web/api/pannernode/positionz/index.md b/files/ja/web/api/pannernode/positionz/index.md new file mode 100644 index 00000000000000..ff684d33f76aa4 --- /dev/null +++ b/files/ja/web/api/pannernode/positionz/index.md @@ -0,0 +1,56 @@ +--- +title: "PannerNode: positionZ プロパティ" +short-title: positionZ +slug: Web/API/PannerNode/positionZ +l10n: + sourceCommit: 1a91b0b63f0cbaca9125bd48d4e5bc8afed2a7a3 +--- + +{{ APIRef("Web Audio API") }} + +**`positionZ`** は {{ domxref("PannerNode")}} インターフェイスのプロパティで、奥行軸（背後とリスナーの前）に対応する、 3D 直交座標での音声ソースの位置の Z 座標を指定します。完全にベクトルを定義するのは、 ({{domxref("PannerNode.positionX", "positionX")}}, {{domxref("PannerNode.positionY", "positionY")}}, {{domxref("PannerNode.positionZ", "positionZ")}}) で指定された音声ソースの位置と、 ({{domxref("PannerNode.orientationX", "orientationX")}}, {{domxref("PannerNode.orientationY", "orientationY")}}, {{domxref("PannerNode.orientationZ", "orientationZ")}}) で指定された音声ソースの方向（つまり、それが向いている方向）です。 + +音の指向性（属性 {{domxref("PannerNode.coneInnerAngle", "coneInnerAngle")}}, {{domxref("PannerNode.coneOuterAngle", "coneOuterAngle")}}, {{domxref("PannerNode.coneOuterGain", "codeOuterGain")}} を使用して指定）によって、使用する音の方向が、知覚される音量を変えるこ とがあります。音が聞き手の方を向いている場合は、音が聞き手から離れている場合よりも大きくなります。 + +このプロパティが保持している {{domxref("AudioParam")}} は読み取り専用ですが、 {{domxref("AudioParam.value")}} プロパティに新しい値を割り当てることで、引数の値を変更することができます。 + +## 値 + +{{domxref("AudioParam")}} で、その `value` は音声ソースの位置の Z 座標（3D 直交座標）です。既定値は 0 です。 + +## 例 + +次の例では、発振器を開始させ、 1 秒後にリスナーの前に移動させ、 2 秒後にリスナーの後ろに移動させ、 3 秒後にリスナーの位置に戻します。 +1 秒後にリスナーの前へ、 2 つ目にリスナーの後ろへ、 3 つ目にリスナーの位置へ戻ります。 +3 つ目。この場合、変化は主に音色と音量に影響することに注意してください。 +音の大きさに影響します。 + +```js +const context = new AudioContext(); + +const osc = new OscillatorNode(context); +const panner = new PannerNode(context); +panner.panningModel = "HRTF"; + +panner.positionZ.setValueAtTime(1, context.currentTime + 1); +panner.positionZ.setValueAtTime(-1, context.currentTime + 2); +panner.positionZ.setValueAtTime(0, context.currentTime + 3); + +osc.connect(panner).connect(context.destination); + +osc.start(0); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) +- {{domxref("PannerNode")}} diff --git a/files/ja/web/api/pannernode/refdistance/index.md b/files/ja/web/api/pannernode/refdistance/index.md new file mode 100644 index 00000000000000..7ddf0c028ed032 --- /dev/null +++ b/files/ja/web/api/pannernode/refdistance/index.md @@ -0,0 +1,77 @@ +--- +title: "PannerNode: refDistance プロパティ" +short-title: refDistance +slug: Web/API/PannerNode/refDistance +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`refDistance` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、音声ソースがリスナーから遠ざかるにつれて音量を縮小する参照距離、つまり音量の縮小が効果を始める距離を表す倍精度浮動小数点値です。この値は、すべての距離モデルで使用します。 + +`refDistance` プロパティの既定値は `1` です。 + +## 値 + +非負の数値。値を 0 未満に設定すると {{jsxref("RangeError")}} が発生します。 + +### 例外 + +- {{jsxref("RangeError")}} + - : プロパティに受け入れられる範囲外の値が指定された場合に発生します。 + +## 例 + +この例では、{{ domxref("PannerNode.refDistance", "refDistance") }} の値を変えることで、音が聞き手から遠ざかるにつれて音量が減衰する様子を示します。 {{ domxref("PannerNode.rolloffFactor", "rolloffFactor") }} とは異なり、この値を変えると、音が参照点を通過するまで音量の減衰されます。 + +```js +const context = new AudioContext(); +// all our test tones will last this many seconds +const NOTE_LENGTH = 6; +// this is how far we'll move the sound +const Z_DISTANCE = 20; + +// this function creates a graph for the test tone with a given refDistance +// and schedules it to move away from the listener along the Z (depth-wise) axis +// at the given start time, resulting in a decrease in volume (decay) +const scheduleTestTone = (refDistance, startTime) => { + const osc = new OscillatorNode(context); + + const panner = new PannerNode(context); + panner.refDistance = refDistance; + + // set the initial Z position, then schedule the ramp + panner.positionZ.setValueAtTime(0, startTime); + panner.positionZ.linearRampToValueAtTime(Z_DISTANCE, startTime + NOTE_LENGTH); + + osc.connect(panner).connect(context.destination); + + osc.start(startTime); + osc.stop(startTime + NOTE_LENGTH); +}; + +// this tone should decay immediately and fairly quickly +scheduleTestTone(1, context.currentTime); +// this tone should decay slower and later than the previous one +scheduleTestTone(4, context.currentTime + NOTE_LENGTH); +// this tone should decay only slightly, and only start decaying fairly late +scheduleTestTone(7, context.currentTime + NOTE_LENGTH * 2); +``` + +このコードを実行すると、波形は次のようになります。 + +![ウェブオーディオで生み出される、 3 つの発振器音の波形を視覚化したものです。それぞれの発振器は同じ速度でリスナーから遠ざかっていきますが、 refDistances が異なるため、結果として音量が減衰します。](screen_shot_2018-10-11_at_23.14.32.png) + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) diff --git a/files/ja/web/api/pannernode/rollofffactor/index.md b/files/ja/web/api/pannernode/rollofffactor/index.md new file mode 100644 index 00000000000000..52d0e3befc4be9 --- /dev/null +++ b/files/ja/web/api/pannernode/rollofffactor/index.md @@ -0,0 +1,82 @@ +--- +title: "PannerNode: rolloffFactor プロパティ" +short-title: rolloffFactor +slug: Web/API/PannerNode/rolloffFactor +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{ APIRef("Web Audio API") }} + +`rolloffFactor` は {{ domxref("PannerNode") }} インターフェイスのプロパティで、ソースがリスナーから離れるにつれて音量が縮小する速さを記述する倍精度浮動小数点値です。この値はすべての距離モデルで使用します。 `rolloffFactor` プロパティの既定値は `1` です。 + +## 値 + +数値で、その範囲はパナーの {{ domxref("PannerNode.distanceModel", "distanceModel") }} によって変わり、以下の通りとなります（負の値は許されません）。 + +- "`linear`" + - : 0 から 1 までの範囲です。 +- "`inverse`" + - : 0 から `Infinity` までの範囲です。 +- "`exponential`" + - : 0 から `Infinity` までの範囲です。 + +### 例外 + +- {{jsxref("RangeError")}} + - : プロパティに受け入れられる範囲外の値が指定された場合に発生します。 + +## 例 + +この例では、 {{ domxref("PannerNode.rolloffFactor", "rolloffFactor") }} の値の違いによって、リスナーからの距離が離れるにつれて、テストトーンの音量がどのように減少していくかを示しています： + +```js +const context = new AudioContext(); +// all our test tones will last this many seconds +const NOTE_LENGTH = 4; +// this is how far we'll move the sound +const Z_DISTANCE = 20; + +// this function creates a graph for the test tone with a given rolloffFactor +// and schedules it to move away from the listener along the Z (depth-wise) axis +// at the given start time, resulting in a decrease in volume (decay) +const scheduleTestTone = (rolloffFactor, startTime) => { + const osc = new OscillatorNode(context); + + const panner = new PannerNode(context); + panner.rolloffFactor = rolloffFactor; + + // set the initial Z position, then schedule the ramp + panner.positionZ.setValueAtTime(0, startTime); + panner.positionZ.linearRampToValueAtTime(Z_DISTANCE, startTime + NOTE_LENGTH); + + osc.connect(panner).connect(context.destination); + + osc.start(startTime); + osc.stop(startTime + NOTE_LENGTH); +}; + +// this tone should decay fairly quickly +scheduleTestTone(1, context.currentTime); +// this tone should decay slower than the previous one +scheduleTestTone(0.5, context.currentTime + NOTE_LENGTH); +// this tone should decay only slightly +scheduleTestTone(0.1, context.currentTime + NOTE_LENGTH * 2); +``` + +このコードを実行すると、波形は次のようになります： + +![ウェブオーディオでは、 3 つの発振器の音色を波形で視覚化しています。各発振器は同じ速度で遠ざかりますが、 RolloffFactors が異なるため、音量が減衰します。](screen_shot_2018-10-11_at_23.22.37.png) + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) +- [ウェブオーディオ空間化の基本](/ja/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics) diff --git a/files/ja/web/api/pannernode/setorientation/index.md b/files/ja/web/api/pannernode/setorientation/index.md new file mode 100644 index 00000000000000..d0d623c5ec9990 --- /dev/null +++ b/files/ja/web/api/pannernode/setorientation/index.md @@ -0,0 +1,52 @@ +--- +title: "PannerNode: setOrientation() メソッド" +short-title: setOrientation() +slug: Web/API/PannerNode/setOrientation +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{APIRef("Web Audio API")}}{{Deprecated_Header}} + +> **メモ:** この非推奨メソッドを置き換えるために推奨される方法は、 [`orientationX`](/ja/docs/Web/API/PannerNode/orientationX), [`orientationY`](/ja/docs/Web/API/PannerNode/orientationY), [`orientationZ`](/ja/docs/Web/API/PannerNode/orientationZ) 属性を直接設定することです。 + +`setOrientation()` は {{ domxref("PannerNode") }} インターフェイスのメソッドで、音声ソースの再生方向を定義します。 + +音にとても指向性がある場合、これは大きな効果があります。 3 つのコーン関連の属性 {{domxref("PannerNode.coneInnerAngle")}}、{{domxref("PannerNode.coneOuterAngle")}}、{{domxref("PannerNode.coneOuterGain")}} によって制御できます。このような場合、リスナーから遠ざかった音はとても小さく、あるいは無音にさえなります。 + +3 つの引数 `x`, `y`, `z` は単位を持たず、正しい直交座標系を用いて 3 次元空間の方向ベクトルを記述します。方向ベクトルの既定値は `(1, 0, 0)` です。 + +## 構文 + +```js-nolint +setOrientation(x, y, z) +``` + +### 引数 + +- `x` + - : 3D 空間におけるパンナーの方向ベクトルの x 値。 +- `y` + - : 3D 空間におけるパンナーの方向ベクトルの y 値。 +- `z` + - : 3D 空間におけるパンナーの方向ベクトルの z 値。 + +### Return value + +None ({{jsxref("undefined")}}). + +## 例 + +例のコードのについては [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#examples) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/pannernode/setposition/index.md b/files/ja/web/api/pannernode/setposition/index.md new file mode 100644 index 00000000000000..3bf22ffdc5d277 --- /dev/null +++ b/files/ja/web/api/pannernode/setposition/index.md @@ -0,0 +1,50 @@ +--- +title: "PannerNode: setPosition() メソッド" +short-title: setPosition() +slug: Web/API/PannerNode/setPosition +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{APIRef("Web Audio API")}}{{Deprecated_Header}} + +> **メモ:** この非推奨メソッドを置き換えるために推奨される方法は、 [`positionX`](/ja/docs/Web/API/PannerNode/positionX), [`positionY`](/ja/docs/Web/API/PannerNode/positionY), [`positionZ`](/ja/docs/Web/API/PannerNode/positionZ) 属性を直接設定することです。 + +`setPosition()` は {{ domxref("PannerNode") }} インターフェイスのメソッドで、リスナー（{{domxref("BaseAudioContext.listener")}} 属性に格納されている {{domxref("AudioListener")}} オブジェクトで表されます）に対する音源の相対位置を定義します。 3 つの引数 `x`, `y`, `z` は単位がなく、正しい直交座標系を使用して 3D 空間における音源の位置を記述します。 + +`setPosition()` メソッドの位置の既定値は `(0, 0, 0)` です。 + +## 構文 + +```js-nolint +setPosition(x, y, z) +``` + +### 引数 + +- `x` + - : 3D 空間におけるパンナーの x 位置指定。 +- `y` + - : 3D 空間におけるパンナーの y 位置指定。 +- `z` + - : 3D 空間におけるパンナーの z 位置指定。 + +### 返値 + +なし ({{jsxref("undefined")}})。 + +## 例 + +例のコードのについては [`BaseAudioContext.createPanner()`](/ja/docs/Web/API/BaseAudioContext/createPanner#examples) を参照してください。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- [ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API) diff --git a/files/ja/web/api/paymentmethodchangeevent/index.md b/files/ja/web/api/paymentmethodchangeevent/index.md index 531ed5037a95e1..ca593d19f842d4 100644 --- a/files/ja/web/api/paymentmethodchangeevent/index.md +++ b/files/ja/web/api/paymentmethodchangeevent/index.md @@ -1,27 +1,31 @@ --- title: PaymentMethodChangeEvent slug: Web/API/PaymentMethodChangeEvent +l10n: + sourceCommit: eb11f0bd259ff4aa109067c7714bbe229285a499 --- {{securecontext_header}}{{APIRef("Payment Request API")}} -**`PaymentMethodChangeEvent`** は [Payment Request API](/ja/docs/Web/API/Payment_Request_API) のインターフェイスで、ユーザーが支払方法を切り替えたとき (例えば、ユーザーが Apple Pay を使用する際に、「その店舗の」カードを選択する場合) に実行される一部の支払いハンドラーが発生する {{domxref("PaymentRequest/paymentmethodchange_event", "paymentmethodchange")}} イベントを説明します。 +**`PaymentMethodChangeEvent`** は[決済リクエスト API](/ja/docs/Web/API/Payment_Request_API) のインターフェイスで、ユーザーが支払方法を切り替えたとき (例えば、ユーザーが Apple Pay を使用する際に、「その店舗の」カードを選択する場合) に実行される一部の支払いハンドラーが発生する {{domxref("PaymentRequest/paymentmethodchange_event", "paymentmethodchange")}} イベントを説明します。 + +{{InheritanceDiagram}} ## コンストラクター - {{domxref("PaymentMethodChangeEvent.PaymentMethodChangeEvent", "PaymentMethodChangeEvent()")}} - - : 新しい `PaymentMethodChangeEvent` オブジェクトを作成して返し、オプションで与えられた {{domxref("PaymentMethodChangeEventInit")}} 辞書から得た値で初期化します。 + - : 新しい `PaymentMethodChangeEvent` オブジェクトを作成して返します。 -## プロパティ +## インスタンスプロパティ _以下のプロパティに加えて、このインターフェイスは {{domxref("PaymentRequestUpdateEvent")}} から継承したプロパティを含みます。_ -- {{domxref("PaymentMethodChangeEvent.methodDetails", "methodDetails")}} {{ReadOnlyInline}} {{securecontext_inline}} +- {{domxref("PaymentMethodChangeEvent.methodDetails", "methodDetails")}} {{ReadOnlyInline}} - : 支払方法の変更時に利用できる支払方法に依存したデータを含むオブジェクトです。そのような情報が利用できない場合は、この値は `null` です。 -- {{domxref("PaymentMethodChangeEvent.methodName", "methodName")}} {{ReadOnlyInline}} {{securecontext_inline}} - - : {{domxref("DOMString")}} で、特定の支払方法を固有に識別する文字列である支払方法識別子が入ります。この識別子はふつう、支払い手続で使用される URL ですが、 `basic-card` のような標準化された文字列にすることもできます。既定値は空文字列、 `""` です。 +- {{domxref("PaymentMethodChangeEvent.methodName", "methodName")}} {{ReadOnlyInline}} + - : 文字列で、特定の支払方法を固有に識別する文字列である支払方法識別子が入ります。この識別子はふつう、支払い手続で使用される URL ですが、 `basic-card` のような標準化された文字列にすることもできます。既定値は空文字列、 `""` です。 -## メソッド +## インスタンスメソッド _このインターフェイスは {{domxref("PaymentRequestUpdateEvent")}} から継承したメソッドを含みます。_ diff --git a/files/ja/web/api/performance/clearmarks/index.md b/files/ja/web/api/performance/clearmarks/index.md index 456fedd3482c72..1c1da8fc41f24a 100644 --- a/files/ja/web/api/performance/clearmarks/index.md +++ b/files/ja/web/api/performance/clearmarks/index.md @@ -1,60 +1,55 @@ --- -title: performance.clearMarks() +title: "Performance: clearMarks() メソッド" +short-title: clearMarks() slug: Web/API/Performance/clearMarks +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("User Timing API")}} +{{APIRef("Performance API")}} -**`clearMarks()`** メソッドは、ブラウザーのパフォーマンスエントリーバッファーから*名前付きマーク*を削除します。このメソッドが引数なしで呼び出された場合、{{domxref("PerformanceEntry.entryType","エントリー種別", "", 1)}}が "`mark`" の{{domxref("PerformanceEntry","パフォーマンスエントリー", "", 1)}}がすべてパフォーマンスエントリーバッファーから削除されます。 - -{{AvailableInWorkers}} +**`clearMarks()`** メソッドは、すべての、または特定の {{domxref("PerformanceMark")}} オブジェクトを、ブラウザーのパフォーマンスタイムラインから除去します。 ## 構文 -```js -performance.clearMarks(); -performance.clearMarks(name); +```js-nolint +clearMarks() +clearMarks(name) ``` ### 引数 -- name {{optional_inline}} - - : タイムスタンプの名前を表す {{domxref("DOMString")}} です。 この引数を省略すると、{{domxref("PerformanceEntry.entryType","エントリー種別", "", 1)}}が "`mark`" であるすべての{{domxref("PerformanceEntry","パフォーマンスエントリー", "", 1)}}が削除されます。 +- `name` {{optional_inline}} + - : 文字列で、 {{domxref("PerformanceMark")}} オブジェクトの{{domxref("PerformanceEntry.name", "名前", "", 1)}}を表します。この引数を省略すると、 {{domxref("PerformanceEntry.entryType","entryType")}} が "`mark`" であるすべての項目が除去されます。 ### 返値 -- void - - : +なし ({{jsxref("undefined")}})。 ## 例 -次の例は、`clearMarks()` メソッドの両方の使用法を示しています。 +### マーカーを除去 + +パフォーマンスマークをすべて、あるいは特定の項目だけを消去するには、次のように `clearMarks()` メソッドを使用します。 ```js -// PerformanceMark のエントリーがいくつあるかを表示する小さなヘルパーを作成します。 -function logMarkCount() { - console.log( - "Found this many entries: " + performance.getEntriesByType("mark").length, - ); -} - -// Create a bunch of marks. -performance.mark("squirrel"); -performance.mark("squirrel"); -performance.mark("monkey"); -performance.mark("monkey"); -performance.mark("dog"); -performance.mark("dog"); - -logMarkCount(); // "Found this many entries: 6" - -// Delete just the "squirrel" PerformanceMark entries. -performance.clearMarks("squirrel"); -logMarkCount(); // "Found this many entries: 4" - -// Delete all of the PerformanceMark entries. +// マークの束を作成 +performance.mark("login-started"); +performance.mark("login-started"); +performance.mark("login-finished"); +performance.mark("form-sent"); +performance.mark("video-loaded"); +performance.mark("video-loaded"); + +performance.getEntriesByType("mark").length; // 6 + +// "login-started" マーク項目のみを削除 +performance.clearMarks("login-started"); +performance.getEntriesByType("mark").length; // 4 + +// すべてのマーク項目を削除 performance.clearMarks(); -logMarkCount(); // "Found this many entries: 0" +performance.getEntriesByType("mark").length; // 0 ``` ## 仕様書 @@ -64,3 +59,7 @@ logMarkCount(); // "Found this many entries: 0" ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("PerformanceMark")}} diff --git a/files/ja/web/api/performance/clearmeasures/index.md b/files/ja/web/api/performance/clearmeasures/index.md index 909019e2b43d3c..c364178cc3e265 100644 --- a/files/ja/web/api/performance/clearmeasures/index.md +++ b/files/ja/web/api/performance/clearmeasures/index.md @@ -1,45 +1,39 @@ --- -title: performance.clearMeasures() +title: "Performance: clearMeasures() メソッド" +short-title: clearMeasures() slug: Web/API/Performance/clearMeasures +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("User Timing API")}} +{{APIRef("Performance API")}} -**`clearMeasures()`** メソッドは、ブラウザーのパフォーマンスエントリーバッファーから*名前付きメジャー*を削除します。このメソッドが引数なしで呼び出された場合、{{domxref("PerformanceEntry.entryType","エントリー種別", "", 1)}}が "`measure`" の{{domxref("PerformanceEntry","パフォーマンスエントリー", "", 1)}}がすべてパフォーマンスエントリーバッファーから削除されます。 - -{{AvailableInWorkers}} +**`clearMeasures()`** メソッドは、すべての、または特定の {{domxref("PerformanceMeasure")}} オブジェクトを、ブラウザーのパフォーマンスタイムラインから除去します。 ## 構文 -```js -performance.clearMeasures(); -performance.clearMeasures(name); +```js-nolint +clearMeasures() +clearMeasures(name) ``` ### 引数 -- name {{optional_inline}} - - : タイムスタンプの名前を表す {{domxref("DOMString")}} です。 この引数を省略すると、{{domxref("PerformanceEntry.entryType","エントリー種別", "", 1)}}が "`measure`" であるすべての{{domxref("PerformanceEntry","パフォーマンスエントリー", "", 1)}}が削除されます。 +- `name` {{optional_inline}} + - : 文字列で、 {{domxref("PerformanceMeasure")}} オブジェクトの{{domxref("PerformanceEntry.name", "名前", "", 1)}}を表します。この引数を省略すると、 {{domxref("PerformanceEntry.entryType","entryType")}} が "`measure`" であるすべての項目が除去されます。 ### 返値 -- void - - : +なし ({{jsxref("undefined")}})。 ## 例 -次の例は、`clearMeasures()` メソッドの両方の使用方法を示しています。 +### 測定値を除去 + +パフォーマンス測定値をすべて、あるいは特定の項目だけを消去するには、次のように `clearMeasures()` メソッドを使用します。 ```js -// Create a small helper to show how many PerformanceMeasure entries there are. -function logMeasureCount() { - console.log( - "Found this many entries: " + - performance.getEntriesByType("measure").length, - ); -} - -// Create a bunch of measures. +// 測定値の束を作成 performance.measure("from navigation"); performance.mark("a"); performance.measure("from mark a", "a"); @@ -50,11 +44,11 @@ performance.measure("between a and b", "a", "b"); logMeasureCount(); // "Found this many entries: 5" -// Delete just the "from navigation" PerformanceMeasure entries. +// "from navigation" PerformanceMeasure 項目のみを削除 performance.clearMeasures("from navigation"); logMeasureCount(); // "Found this many entries: 3" -// Delete all of the PerformanceMeasure entries. +// すべての PerformanceMeasure 項目を削除 performance.clearMeasures(); logMeasureCount(); // "Found this many entries: 0" ``` @@ -66,3 +60,7 @@ logMeasureCount(); // "Found this many entries: 0" ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("PerformanceMeasure")}} diff --git a/files/ja/web/api/performance/clearresourcetimings/index.md b/files/ja/web/api/performance/clearresourcetimings/index.md index 306cc2550b2921..3b2a2983340937 100644 --- a/files/ja/web/api/performance/clearresourcetimings/index.md +++ b/files/ja/web/api/performance/clearresourcetimings/index.md @@ -1,58 +1,59 @@ --- -title: performance.clearResourceTimings() +title: "Performance: clearResourceTimings() メソッド" +short-title: clearResourceTimings() slug: Web/API/Performance/clearResourceTimings +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Resource Timing API")}} +{{APIRef("Performance API")}} -**`clearResourceTimings()`** メソッドは、{{domxref("PerformanceEntry.entryType","entryType")}} が "`resource`" のすべての {{domxref("PerformanceEntry","パフォーマンスエントリー")}}をブラウザーのパフォーマンスデータバッファーから削除し、パフォーマンスデータバッファーのサイズをゼロに設定します。ブラウザーのパフォーマンスデータバッファーのサイズを設定するには、{{domxref("Performance.setResourceTimingBufferSize()")}} メソッドを使用してください。 +**`clearResourceTimings()`** メソッドは、{{domxref("PerformanceEntry.entryType","entryType")}} が "`resource`" のすべてのパフォーマンス項目をブラウザーのパフォーマンスタイムラインから削除し、パフォーマンスリソースデータバッファーのサイズをゼロに設定します。 -{{AvailableInWorkers}} +ブラウザーのリソースデータバッファーのサイズを設定するには、{{domxref("Performance.setResourceTimingBufferSize()")}} メソッドを使用してください。 + +ブラウザーのリソースタイミングバッファーがいっぱいになったときに通知を取得するには、 {{domxref("Performance.resourcetimingbufferfull_event", "resourcetimingbufferfull")}} イベントを待ち受けしてください。 ## 構文 -```js -performance.clearResourceTimings(); +```js-nolint +clearResourceTimings() ``` ### 引数 -- void - - : +なし。 ### 返値 -- なし - - : このメソッドに返値はありません。 +なし ({{jsxref("undefined")}})。 ## 例 +### パフォーマンスリソースバッファーをクリア + +すべてのリソースパフォーマンス項目をバッファーから除去するには、コードの適切な位置で `clearResourceTimings()` を呼び出すか、コンソールに貼り付けてください。 + ```js -function load_resource() { - var image = new Image(); - image.src = "https://developer.mozilla.org/mdn-social-share.png"; -} -function clear_performance_timings() { - if (performance === undefined) { - log("Browser does not support Web Performance"); - return; - } - // Create a resource timing performance entry by loading an image - load_resource(); - - var supported = typeof performance.clearResourceTimings == "function"; - if (supported) { - console.log("Run: performance.clearResourceTimings()"); - performance.clearResourceTimings(); - } else { - console.log("performance.clearResourceTimings() NOT supported"); - return; - } - // getEntries should now return zero - var p = performance.getEntriesByType("resource"); - if (p.length == 0) console.log("... Performance data buffer cleared"); - else console.log("... Performance data buffer NOT cleared!"); +performance.clearResourceTimings(); +performance.getEntriesByType("resource").length; // 0 +``` + +### 記録を取り、パフォーマンスオブザーバーを空にする + +{{domxref("PerformanceObserver")}} オブジェクトを使用する場合（特に `buffered` フラグを `true` に設定した場合）、パフォーマンスリソースバッファーがすばやくいっぱいになることがあります。しかし、バッファーをクリアする代わりに、現在のパフォーマンス項目のリストを格納し、 {{domxref("PerformanceObserver.takeRecords()")}} メソッドを使用してパフォーマンスオブザーバーを空にすることもできます。これは "`resource`" 項目だけでなく、すべてのパフォーマンス項目型で動作します。 + +```js +function perfObserver(list, observer) { + list.getEntries().forEach((entry) => { + // do something with the entries + }); } +const observer = new PerformanceObserver(perfObserver); +observer.observe({ type: "resource", buffered: true }); + +// Store entries and empty performance observer +const records = observer.takeRecords(); ``` ## 仕様書 @@ -62,3 +63,8 @@ function clear_performance_timings() { ## ブラウザーの互換性 {{Compat}} + +## See also + +- {{domxref("Performance.setResourceTimingBufferSize()")}} +- {{domxref("Performance.resourcetimingbufferfull_event", "resourcetimingbufferfull")}} diff --git a/files/ja/web/api/performance/eventcounts/index.md b/files/ja/web/api/performance/eventcounts/index.md new file mode 100644 index 00000000000000..4b8fceaaa60050 --- /dev/null +++ b/files/ja/web/api/performance/eventcounts/index.md @@ -0,0 +1,54 @@ +--- +title: "Performance: eventCounts プロパティ" +short-title: eventCounts +slug: Web/API/Performance/eventCounts +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 +--- + +{{APIRef("Performance API")}} + +読み取り専用の `performance.eventCounts` は {{domxref("EventCounts")}} マップで、イベント型ごとに配信されたイベントの数を含みます。 + +すべてのイベント型が公開されているわけではありません。 {{domxref("PerformanceEventTiming")}} インターフェイスで対応しているイベント型のみカウントを取得することができます。 + +## 値 + +{{domxref("EventCounts")}} のマップです。 +（読み取り専用の {{jsxref("Map")}} で、`clear()`、`delete()`、`set()` メソッドがありません。） + +## 例 + +### イベント型とその回数の報告 + +イベント回数をアナリティクスに送信したい場合は、 `sendToEventAnalytics` のような関数を実装して、 `performance.eventCounts` マップからイベント回数を取得し、[フェッチ API](/ja/docs/Web/API/Fetch_API) を使用してデータをエンドポイントに送信します。 + +```js +// 公開されるイベントをすべて報告 +for (entry of performance.eventCounts.entries()) { + const type = entry[0]; + const count = entry[1]; + // sendToEventAnalytics(type, count); +} + +// 特定のイベントの報告 +const clickCount = performance.eventCounts.get("click"); +// sendToEventAnalytics("click", clickCount); + +// ある型に対してイベントカウントが公開されているか調べる +const isExposed = performance.eventCounts.has("mousemove"); // false +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("EventCounts")}} +- {{domxref("PerformanceEventTiming")}} +- {{jsxref("Map")}} diff --git a/files/ja/web/api/performance/getentries/index.md b/files/ja/web/api/performance/getentries/index.md index 56222112c40fbd..f69238cb6ba4fd 100644 --- a/files/ja/web/api/performance/getentries/index.md +++ b/files/ja/web/api/performance/getentries/index.md @@ -1,85 +1,68 @@ --- -title: performance.getEntries() +title: "Performance: getEntries() メソッド" +short-title: getEntries() slug: Web/API/Performance/getEntries +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Performance Timeline API")}} +{{APIRef("Performance API")}} -**`getEntries()`** メソッドは、そのページのすべての {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。リストのメンバー（エントリー）は、明示的な時点でパフォーマンスマークまたはメジャーを作成することで（たとえば {{domxref("Performance.mark","mark()")}} メソッドを呼び出すことで）作成できます。特定の種類のパフォーマンスエントリーや特定の名前のパフォーマンスエントリーにのみ関心がある場合は、 {{domxref("Performance.getEntriesByType", "getEntriesByType()")}} と {{domxref("Performance.getEntriesByName", "getEntriesByName()")}} を参照してください。 +**`getEntries()`** メソッドは、現在パフォーマンスタイムラインにあるすべての {{domxref("PerformanceEntry")}} オブジェクトの配列を返します。 -{{AvailableInWorkers}} +特定の型や特定の名前を持つパフォーマンス項目だけに関心がある場合は、 {{domxref("Performance.getEntriesByType", "getEntriesByType()")}} や {{domxref("Performance.getEntriesByName", "getEntriesByName()")}} を参照してください。 -## 構文 +> **メモ:** このメソッドは新しいパフォーマンス項目を通知しません。このメソッドを呼び出した時点でパフォーマンスタイムラインに存在している項目のみを取得します。 +> 利用できるようになった項目の通知を受け取るには、 {{domxref("PerformanceObserver")}} を使用してください。 -一般的な構文: +以下の項目型はこのメソッドではまったく対応しておらず、これらの型の項目が存在したとしても返されません。 -```js -entries = window.performance.getEntries(); +- `"element"` ({{domxref("PerformanceElementTiming")}}) +- `"event"` ({{domxref("PerformanceEventTiming")}}) +- `"largest-contentful-paint"` ({{domxref("LargestContentfulPaint")}}) +- `"layout-shift"` ({{domxref("LayoutShift")}}) +- `"longtask"` ({{domxref("PerformanceLongTaskTiming")}}) + +これらの型の項目にアクセスするには、代わりに {{domxref("PerformanceObserver")}} を使用する必要があります。 + +## 構文 + +```js-nolint +getEntries() ``` +### 引数 + +なし。 + ### 返値 -- entries - - : {{domxref("PerformanceEntry")}} オブジェクトの配列。項目はエントリー '{{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並んでいます。 +{{domxref("PerformanceEntry")}} オブジェクトの配列 ({{jsxref("Array")}})。要素は項目の {{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並びます。 ## 例 -```js -function use_PerformanceEntry_methods() { - console.log("PerformanceEntry tests ..."); - - if (performance.mark === undefined) { - console.log("... performance.mark Not supported"); - return; - } +### パフォーマンスマーカーと測定値をすべてログ出力 - // Create some performance entries via the mark() method - performance.mark("Begin"); - do_work(50000); - performance.mark("End"); - performance.mark("Begin"); - do_work(100000); - performance.mark("End"); - do_work(200000); - performance.mark("End"); - - // Use getEntries() to iterate through the each entry - let p = performance.getEntries(); - for (var i = 0; i < p.length; i++) { - console.log("Entry[" + i + "]"); - check_PerformanceEntry(p[i]); - } +自分自身で {{domxref("PerformanceMark")}} および {{domxref("PerformanceMeasure")}} オブジェクトをコードの適切な配置に作成したと想定すると、次のようにすべてコンソールにログ出力したくなるかもしれません。 - // Use getEntriesByType() to get all "mark" entries - p = performance.getEntriesByType("mark"); - for (let i = 0; i < p.length; i++) { - console.log( - "Mark only entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); +```js +// Example markers/measures +performance.mark("login-started"); +performance.mark("login-finished"); +performance.mark("form-sent"); +performance.mark("video-loaded"); +performance.measure("login-duration", "login-started", "login-finished"); + +const entries = performance.getEntries(); + +entries.forEach((entry) => { + if (entry.entryType === "mark") { + console.log(`${entry.name}'s startTime: ${entry.startTime}`); } - - // Use getEntriesByName() to get all "mark" entries named "Begin" - p = performance.getEntriesByName("Begin", "mark"); - for (let i = 0; i < p.length; i++) { - console.log( - "Mark and Begin entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); + if (entry.entryType === "measure") { + console.log(`${entry.name}'s duration: ${entry.duration}`); } -} +}); ``` ## 仕様書 @@ -89,3 +72,8 @@ function use_PerformanceEntry_methods() { ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("Performance.getEntriesByType()")}} +- {{domxref("Performance.getEntriesByName()")}} diff --git a/files/ja/web/api/performance/getentriesbyname/index.md b/files/ja/web/api/performance/getentriesbyname/index.md index c37093e4aa0870..ab94f4ce2bbaf1 100644 --- a/files/ja/web/api/performance/getentriesbyname/index.md +++ b/files/ja/web/api/performance/getentriesbyname/index.md @@ -1,97 +1,60 @@ --- -title: performance.getEntriesByName() +title: "Performance: getEntriesByName() メソッド" +short-title: getEntriesByName() slug: Web/API/Performance/getEntriesByName +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Performance Timeline API")}} +{{APIRef("Performance API")}} -**`getEntriesByName()`** メソッドは、指定された*名前*と*種別*の {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。リストのメンバー（_エントリー_）は、明示的な時点でパフォーマンス*マーク*または*メジャー*を作成することで（たとえば {{domxref("Performance.mark","mark()")}} メソッドを呼び出すことで）作成できます。 +**`getEntriesByName()`** メソッドは、現在パフォーマンスタイムラインにある、指定された*名前*と*型*の {{domxref("PerformanceEntry")}} オブジェクトの配列を返します。 -{{AvailableInWorkers}} +特定の型のパフォーマンス項目だけに関心がある場合は、 {{domxref("Performance.getEntriesByType", "getEntriesByType()")}} を参照してください。すべてのパフォーマンス項目の場合は、 {{domxref("Performance.getEntries", "getEntries()")}} を参照してください。 + +> **メモ:** このメソッドは新しいパフォーマンス項目を通知しません。このメソッドを呼び出した時点でパフォーマンスタイムラインに存在している項目のみを取得します。 +> 利用できるようになった項目の通知を受け取るには、 {{domxref("PerformanceObserver")}} を使用してください。 + +以下の項目型はこのメソッドではまったく対応しておらず、これらの型の項目が存在したとしても返されません。 + +- `"element"` ({{domxref("PerformanceElementTiming")}}) +- `"event"` ({{domxref("PerformanceEventTiming")}}) +- `"largest-contentful-paint"` ({{domxref("LargestContentfulPaint")}}) +- `"layout-shift"` ({{domxref("LayoutShift")}}) +- `"longtask"` ({{domxref("PerformanceLongTaskTiming")}}) + +これらの型の項目にアクセスするには、代わりに {{domxref("PerformanceObserver")}} を使用する必要があります。 ## 構文 -```js -entries = window.performance.getEntriesByName(name, type); +```js-nolint +getEntriesByName(name) +getEntriesByName(name, type) ``` ### 引数 -- name - - : 取得するエントリーの名前 -- type {{optional_inline}} - - : "`mark`" など、取得するエントリーの種類。有効なエントリー種別の一覧は {{domxref("PerformanceEntry.entryType")}} にあります。 +- `name` + - : 取得する項目の名前です。 +- `type` {{optional_inline}} + - : "`mark`" など、取得する項目の型。有効な項目型の一覧は {{domxref("PerformanceEntry.entryType")}} にあります。 ### 返値 -- entries - - : 指定された `name` と `type` を持つ {{domxref("PerformanceEntry")}} オブジェクトのリスト。 `type` 引数が指定されていない場合は、返されるエントリーを決定するために名前だけが使用されます。項目はエントリー '{{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並んでいます。指定された基準を満たすオブジェクトがない場合は、空のリストが返されます。 +指定された `name` と `type` を持つ {{domxref("PerformanceEntry")}} オブジェクトの配列 ({{jsxref("Array")}}) です。 +要素は項目の {{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並びます。指定された基準を満たすオブジェクトがない場合は、空のリストが返されます。 ## 例 +### パフォーマンスマーカーをログ出力 + +次の例は、"`debug-mark`" という名前のオブジェクト {{domxref("PerformanceMark")}} をすべてログ出力します。 + ```js -function use_PerformanceEntry_methods() { - log("PerformanceEntry tests ..."); - - if (performance.mark === undefined) { - log("... performance.mark Not supported"); - return; - } - - // Create some performance entries via the mark() method - performance.mark("Begin"); - do_work(50000); - performance.mark("End"); - performance.mark("Begin"); - do_work(100000); - performance.mark("End"); - do_work(200000); - performance.mark("End"); - - // Use getEntries() to iterate through the each entry - var p = performance.getEntries(); - for (var i = 0; i < p.length; i++) { - log("Entry[" + i + "]"); - check_PerformanceEntry(p[i]); - } - - // Use getEntries(name, entryType) to get specific entries - p = performance.getEntries({ name: "Begin", entryType: "mark" }); - for (var i = 0; i < p.length; i++) { - log("Begin[" + i + "]"); - check_PerformanceEntry(p[i]); - } - - // Use getEntriesByType() to get all "mark" entries - p = performance.getEntriesByType("mark"); - for (var i = 0; i < p.length; i++) { - log( - "Mark only entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); - } - - // Use getEntriesByName() to get all "mark" entries named "Begin" - p = performance.getEntriesByName("Begin", "mark"); - for (var i = 0; i < p.length; i++) { - log( - "Mark and Begin entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); - } -} +const debugMarks = performance.getEntriesByName("debug-mark", "mark"); +debugMarks.forEach((entry) => { + console.log(`${entry.name}'s startTime: ${entry.startTime}`); +}); ``` ## 仕様書 @@ -101,3 +64,8 @@ function use_PerformanceEntry_methods() { ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("Performance.getEntries()")}} +- {{domxref("Performance.getEntriesByType()")}} diff --git a/files/ja/web/api/performance/getentriesbytype/index.md b/files/ja/web/api/performance/getentriesbytype/index.md index 6b59378505c346..89fd6e91fd07a6 100644 --- a/files/ja/web/api/performance/getentriesbytype/index.md +++ b/files/ja/web/api/performance/getentriesbytype/index.md @@ -1,95 +1,57 @@ --- -title: performance.getEntriesByType() +title: "Performance: getEntriesByType() メソッド" +short-title: getEntriesByType() slug: Web/API/Performance/getEntriesByType +l10n: + sourceCommit: 381c51574a3e6a07ee09c63493452440f046038d --- -{{APIRef("Performance Timeline API")}} +{{APIRef("Performance API")}} -**`getEntriesByType()`** メソッドは、指定された型の {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。リストのメンバー（エントリー）は、明示的な時点でパフォーマンス*マーク*または*メジャー*を作成することで（たとえば {{domxref("Performance.mark","mark()")}} メソッドを呼び出すことで）作成できます。 +**`getEntriesByType()`** メソッドは、現在パフォーマンスタイムラインにある、指定された*型*の {{domxref("PerformanceEntry")}} オブジェクトの配列を返します。 -{{AvailableInWorkers}} +特定の名前のパフォーマンス項目に関心がある場合は、 {{domxref("Performance.getEntriesByName", "getEntriesByName()")}} を参照してください。すべてのパフォーマンス項目の場合は、 {{domxref("Performance.getEntries", "getEntries()")}} を参照してください。 + +> **メモ:** このメソッドは新しいパフォーマンス項目を通知しません。このメソッドを呼び出した時点でパフォーマンスタイムラインに存在している項目のみを取得します。 +> 利用できるようになった項目の通知を受け取るには、 {{domxref("PerformanceObserver")}} を使用してください。 + +以下の項目型はこのメソッドではまったく対応しておらず、これらの型の項目が存在したとしても返されません。 + +- `"element"` ({{domxref("PerformanceElementTiming")}}) +- `"event"` ({{domxref("PerformanceEventTiming")}}) +- `"largest-contentful-paint"` ({{domxref("LargestContentfulPaint")}}) +- `"layout-shift"` ({{domxref("LayoutShift")}}) +- `"longtask"` ({{domxref("PerformanceLongTaskTiming")}}) + +これらの型の項目にアクセスするには、代わりに {{domxref("PerformanceObserver")}} を使用する必要があります。 ## 構文 -```js -entries = window.performance.getEntriesByType(type); +```js-nolint +getEntriesByType(type) ``` ### 引数 -- type - - : "`mark`" など、取得するエントリーの種類。有効なエントリー種別の一覧は {{domxref("PerformanceEntry.entryType")}} にあります。 +- `type` + - : 取得する項目の型。 "`mark`" など。有効な項目型は {{domxref("PerformanceEntry.entryType")}} に掲載されています。対応している `entryTypes` は、静的プロパティ {{domxref("PerformanceObserver.supportedEntryTypes_static", "PerformanceObserver.supportedEntryTypes")}} を使用して取得することができます。 ### 返値 -- entries - - : 指定された `type` を持つ {{domxref("PerformanceEntry")}} オブジェクトのリスト。項目はエントリーの {{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並んでいます。指定された `type` を持つオブジェクトがない場合、または引数が指定されていない場合は、空のリストが返されます。 +指定された `type` を持つ {{domxref("PerformanceEntry")}} オブジェクトの配列 ({{jsxref("Array")}}) です。 +要素は項目の {{domxref("PerformanceEntry.startTime","startTime")}} に基づいて時系列に並びます。指定された基準を満たすオブジェクトがない場合は、空のリストが返されます。 ## 例 +### リソース項目をログ出力 + +次の例は"`resource`"という項目型を持つすべての項目をログ出力します。 + ```js -function usePerformanceEntryMethods() { - log("PerformanceEntry tests ..."); - - if (performance.mark === undefined) { - log("... performance.mark Not supported"); - return; - } - - // Create some performance entries via the mark() method - performance.mark("Begin"); - doWork(50000); - performance.mark("End"); - performance.mark("Begin"); - doWork(100000); - performance.mark("End"); - doWork(200000); - performance.mark("End"); - - // Use getEntries() to iterate through the each entry - var p = performance.getEntries(); - for (var i = 0; i < p.length; i++) { - log("Entry[" + i + "]"); - checkPerformanceEntry(p[i]); - } - - // Use getEntries(name, entryType) to get specific entries - p = performance.getEntries({ name: "Begin", entryType: "mark" }); - for (var i = 0; i < p.length; i++) { - log("Begin[" + i + "]"); - checkPerformanceEntry(p[i]); - } - - // Use getEntriesByType() to get all "mark" entries - p = performance.getEntriesByType("mark"); - for (var i = 0; i < p.length; i++) { - log( - "Mark only entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); - } - - // Use getEntriesByName() to get all "mark" entries named "Begin" - p = performance.getEntriesByName("Begin", "mark"); - for (var i = 0; i < p.length; i++) { - log( - "Mark and Begin entry[" + - i + - "]: name = " + - p[i].name + - "; startTime = " + - p[i].startTime + - "; duration = " + - p[i].duration, - ); - } -} +const resources = performance.getEntriesByType("resource"); +resources.forEach((entry) => { + console.log(`${entry.name}'s startTime: ${entry.startTime}`); +}); ``` ## 仕様書 @@ -99,3 +61,9 @@ function usePerformanceEntryMethods() { ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("Performance.getEntries()")}} +- {{domxref("Performance.getEntriesByName()")}} +- {{domxref("PerformanceObserver.supportedEntryTypes_static", "PerformanceObserver.supportedEntryTypes")}} diff --git a/files/ja/web/api/performance/index.md b/files/ja/web/api/performance/index.md index ce6e3038bed850..3ad4c5bdef017d 100644 --- a/files/ja/web/api/performance/index.md +++ b/files/ja/web/api/performance/index.md @@ -1,62 +1,74 @@ --- title: Performance slug: Web/API/Performance +l10n: + sourceCommit: 95dff5ec1195f072b8e48a2273294933670b1e99 --- -{{APIRef("High Resolution Time")}} +{{APIRef("Performance API")}} -**`Performance`** インターフェイスは、現在のページのパフォーマンス関連情報へのアクセスを提供します。これは High Resolution Time API の一部ですが、Performance Timeline API、Navigation Timing API、User Timing API、および Resource Timing API によって拡張されています。 +**`Performance`** インターフェイスは、現在のページのパフォーマンス関連情報へのアクセスを提供します。 -このタイプのオブジェクトは読み取り専用属性 {{domxref("window.performance")}} を呼び出すことで取得できます。 +この型のオブジェクトは `window.performance` や `self.performance` をワーカーで呼び出すことで取得できます。パフォーマンス項目はコンテキスト単位であることに注意してください。メインスレッド（または他にもワーカー）でマークを作成した場合、ワーカースレッドではそのマークを見ることはできません。ウィンドウとワーカーのコンテキストで利用できる API は [`self.performance`](/ja/docs/Web/API/performance_property) を参照してください。 -> **メモ:** このインターフェイスとそのメンバーは、以下に示されている場合を除き、[Web Workers](/ja/docs/Web/API/Web_Workers_API) で利用可能です。 パフォーマンスマーカーと測定値はコンテキストごとにあることにも注意してください。メインスレッド (または他のワーカー) にマークを作成した場合、それを Worker スレッドには表示できません (その逆も同様)。 +{{InheritanceDiagram}} -## プロパティ +## インスタンスプロパティ _`Performance` インターフェイスはプロパティを継承しません。_ -- {{deprecated_inline}} {{domxref("performance.navigation")}} {{readonlyInline}} - - : ページがロードかリフレッシュか、リダイレクトの発生回数など、`timing` にリストされている時間に含まれる操作に関する有用なコンテキストを提供するレガシー {{domxref("PerformanceNavigation")}} オブジェクト。Worker では利用できません。 -- {{deprecated_inline}} {{domxref("performance.timing")}} {{readonlyInline}} - - : 待ち時間関連のパフォーマンス情報を含むレガシー {{domxref("PerformanceTiming")}} オブジェクト。Worker には利用できません。 -- {{domxref("performance.memory", "performance.memory")}} {{Non-standard_inline}} - - : Chrome で追加された*非標準の*拡張子で、このプロパティは基本的なメモリ使用量情報を持つオブジェクトを提供します。_この非標準の API を**使うべきではありません**_。 -- {{domxref("performance.timeOrigin")}} {{readonlyInline}} {{Non-standard_inline}} - - : パフォーマンス測定の開始時刻のハイレゾリューションタイムスタンプを返します。 +- {{domxref("Performance.eventCounts")}} {{ReadOnlyInline}} -## メソッド + - : イベント型ごとに配信されたイベント数を格納する {{domxref("EventCounts")}} マップです。 + +- {{domxref("Performance.navigation")}} {{ReadOnlyInline}} {{Deprecated_Inline}} + + - : 古い {{domxref("PerformanceNavigation")}} オブジェクトで、ページが読み込みか更新か、リダイレクトの発生回数など、`timing` にリストされている時間に含まれる操作に関する有用なコンテキストを提供します。 + +- {{domxref("Performance.timing")}} {{ReadOnlyInline}} {{Deprecated_Inline}} + + - : 古い {{domxref("PerformanceTiming")}} オブジェクトで、待ち時間関連のパフォーマンス情報を持っています。 + +- {{domxref("Performance.memory")}} {{ReadOnlyInline}} {{Non-standard_Inline}} {{Deprecated_Inline}} + - : Chrome で追加された*標準外の*拡張子で、このプロパティは基本的なメモリー使用量情報を持つオブジェクトを提供します。_この標準外の API を**使うべきではありません**_。 +- {{domxref("Performance.timeOrigin")}} {{ReadOnlyInline}} + - : パフォーマンス測定の開始時刻の高解像度タイムスタンプを返します。 + +## インスタンスメソッド _`Performance` インターフェイスはメソッドを継承しません。_ -- {{domxref("performance.clearMarks()")}} - - : ブラウザーのパフォーマンスエントリバッファから指定された*マーク*を削除します。 -- {{domxref("performance.clearMeasures()")}} - - : ブラウザーのパフォーマンスエントリバッファから指定された*数値*を削除します。 -- {{domxref("performance.clearResourceTimings()")}} - - : ブラウザーのパフォーマンスデータバッファから "`resource`" の {{domxref("PerformanceEntry.entryType","entryType")}} を持つすべての {{domxref("PerformanceEntry","performance entries")}} を削除します。 -- {{domxref("performance.getEntries()")}} - - : 与えられた*フィルタ*に基づく {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 -- {{domxref("performance.getEntriesByName()")}} - - : 指定された*名前*と*エントリタイプ*に基づいて {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 -- {{domxref("performance.getEntriesByType()")}} - - : 与えられた*エントリタイプ*の {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 -- {{domxref("performance.mark()")}} - - : 指定された名前でブラウザーの*パフォーマンスエントリバッファ*に{{domxref("DOMHighResTimeStamp","タイムスタンプ")}}を作成します。 -- {{domxref("performance.measure()")}} - - : 指定された 2 つのマーク (それぞれ*開始マーク*と*終了マーク*と呼ばれる) の間に、ブラウザーのパフォーマンスエントリバッファ内に名前付き{{domxref("DOMHighResTimeStamp","タイムスタンプ")}}を作成します。 -- {{domxref("performance.now()")}} +- {{domxref("Performance.clearMarks()")}} + - : ブラウザーのパフォーマンス項目バッファーから指定された*マーク*を削除します。 +- {{domxref("Performance.clearMeasures()")}} + - : ブラウザーのパフォーマンス項目バッファーから指定された*メジャー*を削除します。 +- {{domxref("Performance.clearResourceTimings()")}} + - : ブラウザーのパフォーマンスデータバッファーから "`resource`" の {{domxref("PerformanceEntry.entryType","entryType")}} を持つすべての{{domxref("PerformanceEntry","パフォーマンス項目", "", 1)}}を削除します。 +- {{domxref("Performance.getEntries()")}} + - : 与えられた*フィルター*に基づく {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 +- {{domxref("Performance.getEntriesByName()")}} + - : 指定された*名前*と*項目型*に基づいて {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 +- {{domxref("Performance.getEntriesByType()")}} + - : 与えられた*項目型*の {{domxref("PerformanceEntry")}} オブジェクトのリストを返します。 +- {{domxref("Performance.mark()")}} + - : 指定された名前でブラウザーの*パフォーマンス項目バッファー*に{{domxref("DOMHighResTimeStamp","タイムスタンプ")}}を作成します。 +- {{domxref("Performance.measure()")}} + - : 指定された 2 つのマーク (それぞれ*開始マーク*と*終了マーク*と呼ばれる) の間に、ブラウザーのパフォーマンス項目バッファー内に名前付き{{domxref("DOMHighResTimeStamp","タイムスタンプ")}}を作成します。 +- {{domxref("Performance.measureUserAgentSpecificMemory()")}} {{Experimental_Inline}} + - : すべての iframe とワーカーを含むウェブアプリケーションのメモリー使用量を推定します。 +- {{domxref("Performance.now()")}} - : 参照時点から経過したミリ秒数を表す {{domxref("DOMHighResTimeStamp")}} を返します。 -- {{domxref("performance.setResourceTimingBufferSize()")}} - - : ブラウザーのリソースタイミングバッファサイズを、指定された数の "`resource`" {{domxref("PerformanceEntry.entryType","タイプ")}} {{domxref("PerformanceEntry","パフォーマンスエントリ")}} オブジェクトに設定します。 -- {{domxref("performance.toJSON()")}} - - : `Performance` オブジェクトを表す json オブジェクトを返す jsonizer です。 +- {{domxref("Performance.setResourceTimingBufferSize()")}} + - : ブラウザーのリソースタイミングバッファーサイズを、指定された数の "`resource`" {{domxref("PerformanceEntry.entryType","型")}}の{{domxref("PerformanceEntry","パフォーマンス項目")}}オブジェクトに設定します。 +- {{domxref("Performance.toJSON()")}} + - : `Performance` オブジェクトの JSON 表現を返します。 ## イベント `addEventListener()` を使用するか、このインターフェイスの `oneventname` プロパティにイベントリスナを割り当てることで、イベントを監視します。 -- [`resourcetimingbufferfull`](/ja/docs/Web/API/Performance/resourcetimingbufferfull_event) - - : ブラウザーの[リソースタイミングバッファ](/ja/docs/Web/API/Performance/setResourceTimingBufferSize)がいっぱいになったときに発生します。[`onresourcetimingbufferfull`](/ja/docs/Web/API/Performance/onresourcetimingbufferfull) プロパティからも利用できます。 +- {{DOMxRef("Performance.resourcetimingbufferfull_event", "resourcetimingbufferfull")}} + - : ブラウザーの[リソースタイミングバッファー](/ja/docs/Web/API/Performance/setResourceTimingBufferSize)が満杯になったときに発生します。 ## 仕様書 diff --git a/files/ja/web/api/performance/mark/index.md b/files/ja/web/api/performance/mark/index.md index 43cfce35a7f69e..e361d56d3f66e9 100644 --- a/files/ja/web/api/performance/mark/index.md +++ b/files/ja/web/api/performance/mark/index.md @@ -1,70 +1,94 @@ --- -title: performance.mark() +title: "Performance: mark() メソッド" +short-title: mark() slug: Web/API/Performance/mark +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("User Timing API")}} +{{APIRef("Performance API")}} -**`mark()`** メソッドは、ブラウザーのパフォーマンスエントリーバッファーに、指定された名前で{{domxref("DOMHighResTimeStamp","timestamp")}} を作成します。 +**`mark()`** メソッドは、名前付き {{domxref("PerformanceMark")}} オブジェクトを生成し、ブラウザーのパフォーマンスタイムラインに高解像度のタイムスタンプマーカーを表示します。 -アプリケーション定義のタイムスタンプは、{{domxref("Performance")}} インタフェースの `getEntries*()` メソッド ({{domxref("Performance.getEntries","getEntries()")}}、{{domxref("Performance.getEntriesByName","getEntriesByName()")}} または{{domxref("Performance.getEntriesByType","getEntriesByType()")}}) のいずれかによって取得できます。 +## 構文 -`mark()` は内部的にデータを {{domxref("PerformanceEntry")}} として格納します。 +```js-nolint +mark(name) +mark(name, markOptions) +``` -{{AvailableInWorkers}} +### 引数 -## 構文 +- `name` + - : 文字列で、マークの名前を表します。非推奨の {{domxref("PerformanceTiming")}} インターフェイスのプロパティのいずれかと同じ名前であってはいけません。 +- `markOptions` {{optional_inline}} + - : このマークのためにタイムスタンプと追加のメタデータを指定するためのオブジェクトです。 + - `detail` {{optional_inline}} + - : マークに含める任意のメタデータです。既定値は `null` です。[構造化クローン可能](/ja/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)でなければなりません。 + - `startTime` {{optional_inline}} + - : マークの時刻として使用する {{domxref("DOMHighResTimeStamp")}} です。既定値は {{domxref("performance.now()")}} です。 + +### 返値 + +生成された {{domxref("PerformanceMark")}} 項目です。 + +### 例外 + +- {{jsxref("SyntaxError")}}: `name` が非推奨の {{domxref("PerformanceTiming")}} インターフェイスのプロパティのいずれかである場合に発生します。[下記の例](#予約済みの名前)を参照してください。 +- {{jsxref("TypeError")}}: `startTime` が負の場合に発生します。 + +## 例 + +### 名前付きのマーカーを生成 + +次の例では、`mark()` を使用して名前付き {{domxref("PerformanceMark")}} 項目を作成しています。同じ名前のマークを複数作成することができます。また、それらを割り当てて、作成した {{domxref("PerformanceMark")}} オブジェクトへの参照を保有することもできます。 ```js -performance.mark(name); -performance.mark(measureName, markOptions); +performance.mark("login-started"); +performance.mark("login-started"); +performance.mark("login-finished"); +performance.mark("form-sent"); + +const videoMarker = performance.mark("video-loaded"); ``` -### 引数 +### 詳細付きのマーカーを生成 -- name +パフォーマンスマークは `markOptions` オブジェクトを使用して設定することができ、`detail` プロパティに任意の型の追加情報を入力することができます。 - - : {{domxref("DOMString")}} で、マークの名前を表します。このメソッドで指定された `name` がすでに {{domxref("PerformanceTiming")}} インターフェイスに存在していた場合は、 {{jsxref("SyntaxError")}} が発生します。 +```js +performance.mark("login-started", { + detail: "ログインはトップメニューのログインボタンを使用して開始されました。", +}); -- `markOptions` {{optional_inline}} +performance.mark("login-started", { + detail: { htmlElement: myElement.id }, +}); +``` - - : このマークのためにタイムスタンプと追加のメタデータを指定するためのオブジェクトです。 +### 開始時刻付きのマーカーを作成 - - `detail` - - : マークに含める任意のメタデータです。 - - `startTime` - - : マークの時刻として使用する {{domxref("DOMHighResTimeStamp")}} です。 +`mark()` メソッドの既定では、タイムスタンプは {{domxref("performance.now()")}} です。`markOptions` の `startTime` オプションを使用すると、別の時刻に設定することができます。 -### 返値 +```js +performance.mark("start-checkout", { + startTime: 20.0, +}); -- entry - - : 生成された {{domxref("PerformanceMark")}} エントリーです。 +performance.mark("login-button-pressed", { + startTime: myEvent.timeStamp, +}); +``` -## 例 +### 予約済みの名前 -次の例は、`mark()` を使用して {{domxref("PerformanceMark")}} エントリーを作成および取得する方法を示しています。 +後方互換性を保つため、非推奨の {{domxref("PerformanceTiming")}} インターフェイスの一部である名前は使用できないことに注意してください。次の例は例外が発生します。 -```js -// たくさんの mark を作成します。 -performance.mark("squirrel"); -performance.mark("squirrel"); -performance.mark("monkey"); -performance.mark("monkey"); -performance.mark("dog"); -performance.mark("dog"); - -// PerformanceMark エントリーをすべて取得します。 -const allEntries = performance.getEntriesByType("mark"); -console.log(allEntries.length); -// 6 - -// "monkey" PerformanceMark エントリーをすべて入手します。 -const monkeyEntries = performance.getEntriesByName("monkey"); -console.log(monkeyEntries.length); -// 2 - -// すべての mark を消去します。 -performance.clearMarks(); +```js example-bad +performance.mark("navigationStart"); +// SyntaxError: "navigationStart" is part of +// the PerformanceTiming interface, +// and cannot be used as a mark name ``` ## 仕様書 diff --git a/files/ja/web/api/performance/measure/index.md b/files/ja/web/api/performance/measure/index.md index 7f2a9c7c99b627..ae9a79e68214de 100644 --- a/files/ja/web/api/performance/measure/index.md +++ b/files/ja/web/api/performance/measure/index.md @@ -1,67 +1,67 @@ --- -title: performance.measure() +title: "Performance: measure() メソッド" +short-title: measure() slug: Web/API/Performance/measure +l10n: + sourceCommit: 6539cd8d3ea65b2755ef5d5c7da202f53636f51f --- -{{APIRef("User Timing API")}} +{{APIRef("Performance API")}} -**`measure()`** メソッドは、マーク間、ナビゲーション開始時刻、または現在時刻の間に、ブラウザーの*パフォーマンスエントリーバッファー*に名前付き {{domxref("DOMHighResTimeStamp","timestamp")}} を作成します。 +**`measure()`** メソッドは、 2 つのマーク間の時間を表す名前付き {{domxref("PerformanceMeasure")}} オブジェクトを、ブラウザのパフォーマンスタイムラインに作成します。 2 つのマーク間を測定するときは、それぞれ*開始マーク*と*終了マーク*があります。名前付きタイムスタンプは、*メジャー*と呼ばれます。 -`measure` は、{{domxref("Performance")}} インターフェイスのうち、 -({{domxref("Performance.getEntries","getEntries()")}}, -{{domxref("Performance.getEntriesByName","getEntriesByName()")}}, -{{domxref("Performance.getEntriesByType","getEntriesByType()")}}) のいずれかを使用して取得できます。 - -{{AvailableInWorkers}} - ## 構文 -```js -measure(measureName); -measure(measureName, MeasureOptions); -measure(measureName, startMark); -measure(measureName, startMark, endMark); +```js-nolint +measure(measureName) +measure(measureName, startMark) +measure(measureName, startMark, endMark) +measure(measureName, measureOptions) +measure(measureName, measureOptions, endMark) ``` `measureName` のみが指定された場合、開始タイムスタンプはゼロに設定され、（時間を計算するために使用される）終了タイムスタンプは {{domxref("Performance.now()")}} から返される値になります。 +文字列を使用して {{domxref("PerformanceMark")}} オブジェクトを開始マークと終了マークとして識別することができます。 + +`endMark` のみ指定する場合、空の `measureOptions` オブジェクトを提供して `performance.measure("myMeasure", {}, "myEndMarker")` のようにする必要があります。 + ### 引数 - `measureName` - - : {{domxref("DOMString")}} で、メジャーの名前を表します。 + - : 文字列で、メジャーの名前を表します。 -- `MeasureOptions` {{optional_inline}} +- `measureOptions` {{optional_inline}} - - : メジャーのすべてのオプションを含むオブジェクトです（`startMark` と `endMark` はこのオブジェクト内で指定することも、独自の引数で指定することもできます）。 + - : メジャーのすべてのオプションを含むオブジェクトです。 - - `detail` - - : メジャーに含める任意のメタデータです。 - - `start` - - : 開始時刻として使用される {{domxref("DOMHighResTimeStamp")}} のタイムスタンプ、または開始マークとして使用される {{domxref("DOMString")}} です。 - これが開始マークの名前を表す場合は、 `startMark` の場合と同じように定義します（すなわち、既存のマークまたは {{domxref("PerformanceTiming")}} プロパティの名前でなければなりません）。 - - `duration` - - : 開始マークと終了マークのそれぞれの時刻 ({{domxref("DOMHighResTimeStamp")}}) 間の時間. - - `end` - - : 終了時刻として使用される {{domxref("DOMHighResTimeStamp")}} のタイムスタンプ、または終了マークとして使用される {{domxref("DOMString")}} です。 - これが終了マークの名前を表す場合は、 `endMark` の場合と同じように定義します（すなわち、既存のマークまたは {{domxref("PerformanceTiming")}} プロパティの名前でなければなりません）。 + - `detail` {{optional_inline}} + - : マークに含める任意のメタデータです。既定値は `null` です。[構造化クローン可能](/ja/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)でなければなりません。 + - `start` {{optional_inline}} -- `startMark` {{optional_inline}} + - : 開始時刻として使用される {{domxref("DOMHighResTimeStamp")}} のタイムスタンプ、または開始マークに使用される文字列です。 + + これが {{domxref("PerformanceMark")}} に名前を付ける文字列である場合、 `startMark` と同じ方法で定義されます。 + + - `duration` {{optional_inline}} + - : 開始と終了のマーク時刻間の時間（ミリ秒単位）。省略した場合は既定値が {{domxref("performance.now()")}} となり、コンテキストが作成されてから経過した時刻となります。指定された場合は `start` と `end` のどちらかを指定する必要がありますが、両方を指定することはできません。 + - `end` {{optional_inline}} - - : {{domxref("DOMString")}} で、このメジャーの開始マークの名前を表します。 - {{domxref("PerformanceTiming")}} プロパティの名前にすることもできます。 - 既存の {{domxref('PerformanceMark')}} または {{domxref("PerformanceTiming")}} を表していない名前を指定すると `SyntaxError` の {{domxref("DOMException")}} が発生します。 + - : 終了時刻として使用される {{domxref("DOMHighResTimeStamp")}} のタイムスタンプ、または終了時刻の {{domxref("PerformanceMark")}} に名前を付ける文字列です。 + これが {{domxref("PerformanceMark")}} に名前を付ける文字列である場合、 `endMark` と同じように定義します。 +- `startMark` {{optional_inline}} + - : パフォーマンスタイムラインの {{domxref("PerformanceMark")}} に名前を付ける文字列です。このマークの {{domxref("PerformanceEntry.startTime")}} プロパティがメジャーの計算に使用されます。 - `endMark` {{optional_inline}} - - : {{domxref("DOMString")}} で、このメジャーの終了マークの名前を表します。 - {{domxref("PerformanceTiming")}} プロパティの名前にすることもできます。 - 既存の {{domxref('PerformanceMark')}} または {{domxref("PerformanceTiming")}} を表していない名前を指定すると `SyntaxError` の {{domxref("DOMException")}} が発生します。 + - : パフォーマンスタイムラインの {{domxref("PerformanceMark")}} に名前を付ける文字列です。このマークの {{domxref("PerformanceEntry.startTime")}} プロパティがメジャーの計算に使用されます。 + この引数を渡したい場合は、 `startMark` または空の `measureOptions` オブジェクトも渡す必要があります。 ### 返値 -生成された {{domxref("PerformanceMeasure")}} のエントリーです。 +生成された {{domxref("PerformanceMeasure")}} の項目です。 返される*メジャー*には、以下のプロパティ値になります。 @@ -69,77 +69,84 @@ measure(measureName, startMark, endMark); - {{domxref("PerformanceEntry.name","name")}} - "`name`" 引数が設定されます。 - {{domxref("PerformanceEntry.startTime","startTime")}} - 以下のように設定されます。 - - `MeasureOptions.start` で指定された場合は {{domxref("DOMHighResTimeStamp","timestamp")}}。 - - `MeasureOptions.start` または `startMark` で指定された場合は、開始マークの{{domxref("DOMHighResTimeStamp","タイムスタンプ", "", 1)}}。 - - `MeasureOptions.end` と `MeasureOptions.duration` から計算されたタイムスタンプ（`MeasureOptions.start` が指定されていない場合）。 + - `measureOptions.start` で指定された場合は {{domxref("DOMHighResTimeStamp","timestamp")}}。 + - `measureOptions.start` または `startMark` で指定された場合は、開始マークの{{domxref("DOMHighResTimeStamp","タイムスタンプ", "", 1)}}。 + - `measureOptions.end` と `measureOptions.duration` から計算されたタイムスタンプ（`measureOptions.start` が指定されていない場合）。 - 指定されておらず、他の値から特定することができない場合は 0。 - {{domxref("PerformanceEntry.duration","duration")}} - {{domxref("DOMHighResTimeStamp")}} で、終了タイムスタンプから `startTime` を引いて計算されたメジャーの時間を設定します。 終了タイムスタンプは以下のいずれかになります。 - - `MeasureOptions.end` で指定された場合は {{domxref("DOMHighResTimeStamp","timestamp")}}。 - - `MeasureOptions.end` または `endMark` で指定された場合は、終了マークの{{domxref("DOMHighResTimeStamp","タイムスタンプ", "", 1)}}。 - - `MeasureOptions.start` と `MeasureOptions.duration` から計算されたタイムスタンプ（`MeasureOptions.end` が指定されていない場合）。 + - `measureOptions.end` で指定された場合は {{domxref("DOMHighResTimeStamp","timestamp")}}。 + - `measureOptions.end` または `endMark` で指定された場合は、終了マークの{{domxref("DOMHighResTimeStamp","タイムスタンプ", "", 1)}}。 + - `measureOptions.start` と `measureOptions.duration` から計算されたタイムスタンプ（`measureOptions.end` が指定されていない場合）。 - 終了マークが指定されていないか、他の値から特定することができない場合は、 {{domxref("Performance.now()")}} で返される値。 -- {{domxref("PerformanceMeasure","detail")}} - `MeasureOptions` で渡された値に設定されます。 +- {{domxref("PerformanceMeasure","detail")}} - `measureOptions` で渡された値に設定されます。 ## 例外 -- `TypeError` {{domxref("DOMException")}} +- {{jsxref("TypeError")}} - - : start, end, duration の何れかが曖昧になる場合に発生します。 + - : start, end, duration のいずれかが曖昧になる場合に発生します。 - - `endMark` と `MeasureOptions` の両方が指定された。 - - `MeasureOptions` が指定されたが、 `start` および `end` メンバーが指定されなかった。 - - `MeasureOptions` が `start`, `end`, `duration` のメンバーすべてある状態（そして不整合な状態）で指定された。 + - `endMark` と `measureOptions` の両方が指定された。 + - `measureOptions` が指定されたが、 `start` および `end` メンバーが指定されなかった。 + - `measureOptions` が `start`, `end`, `duration` のメンバーすべてある状態（そして不整合な状態）で指定された。 - `SyntaxError` {{domxref("DOMException")}} - : その名前のマークが存在しない場合に発生します。 - - `endMark` または `MeasureOptions.end` のどちらかを使用してエンドマークが指定されたが、一致する名前のパフォーマンスバッファーに {{domxref('PerformanceMark')}}がない。 - - `endMark` または `MeasureOptions.end` のどちらかを使用してエンドマークが指定されたが、 {{domxref("PerformanceTiming")}} インターフェイスの読み取り専用属性に変換することができない。 - - 開始マークが `startMark` または `MeasureOptions.start` のどちらかで指定されているが、一致する名前のパフォーマンスバッファーに {{domxref('PerformanceMark')}}がない。 - - 開始マークが `startMark` または `MeasureOptions.start` のどちらかで指定されているが、 {{domxref("PerformanceTiming")}} インターフェイスの読み取り専用属性に変換することができない。 + - `endMark` または `measureOptions.end` のどちらかを使用してエンドマークが指定されたが、一致する名前のパフォーマンスバッファーに {{domxref('PerformanceMark')}} がない。 + - `endMark` または `measureOptions.end` のどちらかを使用してエンドマークが指定されたが、 {{domxref("PerformanceTiming")}} インターフェイスの読み取り専用属性に変換することができない。 + - 開始マークが `startMark` または `measureOptions.start` のどちらかで指定されているが、一致する名前のパフォーマンスバッファーに {{domxref('PerformanceMark')}} がない。 + - 開始マークが `startMark` または `measureOptions.start` のどちらかで指定されているが、 {{domxref("PerformanceTiming")}} インターフェイスの読み取り専用属性に変換することができない。 - `DataCloneError` {{domxref("DOMException")}} - - : `MeasureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズできない場合です。 + - : `measureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズできない場合です。 -- `RangeError` - - : `MeasureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズする際にメモリーが割り当てられなかった場合です。 +- {{jsxref("RangeError")}} + - : `measureOptions.detail` が `null` 以外の値であり、 HTML の "StructuredSerialize" アルゴリズムでシリアライズする際にメモリーが割り当てられなかった場合です。 ## 例 -次の例は、ブラウザーのパフォーマンスエントリーバッファーに `measure()` を使用して新しい*メジャー*{{domxref("PerformanceEntry","パフォーマンスエントリー")}}を作成する方法を示しています。 +### 名前付きマーカー間の時間の測定 + +自分自身で 2 つのマーカー `"login-started"` と `"login-finished"` を指定した場合、次の例に示すように `"login-duration"` という名前の時間を作成することができます。返された {{domxref("PerformanceMeasure")}} オブジェクトは `duration` プロパティを提供し、2 つのマーカー間の経過時間を指示します。 + +```js +const loginMeasure = performance.measure( + "login-duration", + "login-started", + "login-finished", +); +console.log(loginMeasure.duration); +``` + +### 独自の開始と終了の時刻で時間を測定 + +より高度な計測を行うには、 `measureOptions` 引数を渡すことができます。例えば、開始時刻には [`click` イベント](/ja/docs/Web/API/Element/click_event) の [`event.timeStamp`](/ja/docs/Web/API/Event/timeStamp) プロパティを使用することができます。 + +```js +performance.measure("login-click", { + start: myClickEvent.timeStamp, + end: myMarker.startTime, +}); +``` + +### メジャーの追加の詳細を提供 + +`details` プロパティを使用することで、任意の型の追加情報を提供することができます。例えば、どの HTML 要素がクリックされたかを記録したいかもしれません。 ```js -const markerNameA = "example-marker-a" -const markerNameB = "example-marker-b" - -// いくつかのネストしたタイムアウトを実行し、それぞれに対して PerformanceMark を作成します。 -performance.mark(markerNameA); -setTimeout(function() { - performance.mark(markerNameB); - setTimeout(function() { - - // さまざまな測定値を作成します。 - performance.measure("measure a to b", markerNameA, markerNameB); - performance.measure("measure a to now", markerNameA); - performance.measure("measure from navigation start to b", undefined, markerNameB); - performance.measure("measure from the start of navigation to now"); - - // すべての測定値を引き出します。 - console.log(performance.getEntriesByType("measure")); - - // 最後に、エントリ- - を整理します。 - performance.clearMarks(); - performance.clearMeasures(); - }, 1000); -}, 1000); +performance.measure("login-click", { + detail: { htmlElement: myElement.id }, + start: myClickEvent.timeStamp, + end: myMarker.startTime, +}); ``` ## 仕様書 diff --git a/files/ja/web/api/performance/measureuseragentspecificmemory/index.md b/files/ja/web/api/performance/measureuseragentspecificmemory/index.md new file mode 100644 index 00000000000000..3f1c8c4c2f4779 --- /dev/null +++ b/files/ja/web/api/performance/measureuseragentspecificmemory/index.md @@ -0,0 +1,157 @@ +--- +title: "Performance: measureUserAgentSpecificMemory() メソッド" +short-title: measureUserAgentSpecificMemory() +slug: Web/API/Performance/measureUserAgentSpecificMemory +l10n: + sourceCommit: 6539cd8d3ea65b2755ef5d5c7da202f53636f51f +--- + +{{APIRef("Performance API")}} {{SeeCompatTable}} + +**`measureUserAgentSpecificMemory()`** メソッドは、すべての iframe とワーカーを含むウェブアプリケーションのメモリー使用量を推定するために使用します。 + +## 解説 + +ブラウザーはオブジェクトが作成されると自動的にメモリーを確保し、オブジェクトに到達できなくなるとメモリーを解放します（ガベージコレクション）。このガベージコレクション (GC) は、特定のメモリーがまだ必要かどうかを判断する一般的な問題が不可能であるため、近似的なものです（[JavaScript のメモリー管理](/ja/docs/Web/JavaScript/Memory_management)も参照）。ウェブ開発者は、オブジェクトがガベージコレクションされ、メモリーがリークせず、メモリー使用量が時間経過に伴って不必要に増加し、ウェブアプリケーションの動作が遅くなったり応答しなくなったりしないようにする必要があります。メモリーリークは通常、イベントリスナーの登録を解除し忘れたり、ワーカーを閉じなかったり、配列にオブジェクトを蓄積したりすることで発生します。 + +`measureUserAgentSpecificMemory()` API は、メモリー使用量データを集約して、メモリーリークを探すのに役立ちます。メモリーの回帰検出や A/B テスト機能のメモリーへの影響を評価するために使用することができます。このメソッドを単一のメソッドで呼び出すよりも、定期的に呼び出してセッションの再生時間中にメモリー使用量がどのように変化するかを追跡する方がよいでしょう。 + +この API が返す `byte` 値は実装に大きく依存するため、ブラウザー間や同じブラウザーの異なるバージョン間で比較することはできません。また、 `breakdown` と `attribution` 配列がどのように指定されたかはブラウザー次第です。このデータについてはハードコーディングしない方が良いでしょう。この API はむしろ、データを集計してサンプル間の違いを分析するために定期的に（ランダムな間隔で）呼び出されることを意味しています。 + +## 構文 + +```js-nolint +measureUserAgentSpecificMemory() +``` + +### 引数 + +None. + +### 返値 + +以下のプロパティを格納するオブジェクトに解決する {{jsxref("Promise")}} です。 + +- `bytes` + - : メモリーの総使用量を表す数値です。 +- `breakdown` + - : `bytes` の合計を分割し、属性と型情報を提供するオブジェクトの {{jsxref("Array")}} です。このオブジェクトは以下のプロパティを持ちます。 + - `bytes` + - : この項目が記述するメモリーのサイズ。 + - `attribution` + - : メモリーを使用する JavaScript 領域のコンテナー要素の {{jsxref("Array")}} です。このオブジェクトは以下のプロパティを持ちます。 + - `url` + - : この属性が同一オリジンの JavaScript 領域に対応する場合、このプロパティはその領域の URL を保持します。そうでない場合は文字列 "cross-origin-url" となります。 + - `container` + - : この JavaScript 領域を含む DOM 要素を記述するオブジェクト。このオブジェクトは以下のプロパティを持ちます。 + - `id` + - : コンテナー要素の `id` 属性。 + - `src` + - : コンテナー要素の `src` 属性。コンテナー要素が {{HTMLElement("object")}} 要素の場合、このフィールドには `data` 属性の値が格納されます。 + - `scope` + - : 同一オリジンの JavaScript 領域の型を記述する文字列です。 `"Window"`, `"DedicatedWorkerGlobalScope"`, `"SharedWorkerGlobalScope"`, `"ServiceWorkerGlobalScope"`, `"cross-origin-aggregated"` のいずれかです。 + - `types` + - : メモリーに関連付けられた実装で定義するメモリー型の配列です。 + +返値の例はこのようになります。 + +```js +{ + bytes: 1500000, + breakdown: [ + { + bytes: 1000000, + attribution: [ + { + url: "https://example.com", + scope: "Window", + }, + ], + types: ["DOM", "JS"], + }, + { + bytes: 0, + attribution: [], + types: [], + }, + { + bytes: 500000, + attribution: [ + { + url: "https://example.com/iframe.html" + container: { + id: "example-id", + src: "redirect.html?target=iframe.html", + }, + scope: "Window", + } + ], + types: ["JS", "DOM"], + }, + ], +} +``` + +### 例外 + +- `SecurityError` {{domxref("DOMException")}} + - : オリジン間情報漏えいを防ぐセキュリティ要求が履行されていなければ発生します。 + +## セキュリティ要件 + +ウェブサイトが[安全なコンテキスト](/ja/docs/Web/Security/Secure_Contexts)にある必要があります。 + +サイトをオリジン間分離するためには、 2 つのヘッダーを設定する必要があります。 + +- [`Cross-Origin-Opener-Policy`](/ja/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy) で `same-origin` を値として指定したもの（攻撃からオリジンを保護） +- [`Cross-Origin-Embedder-Policy`](/ja/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy) で `require-corp` または `credentialless` を値として指定したもの（オリジンから被害者を保護） + +```http +Cross-Origin-Opener-Policy: same-origin +Cross-Origin-Embedder-Policy: require-corp +``` + +オリジン間の分離が成功したかどうかを調べるには、ウィンドウとワーカーのコンテキストで利用可能な [`crossOriginIsolated`](/ja/docs/Web/API/crossOriginIsolated) プロパティをテストします。 + +```js +if (crossOriginIsolated) { + // Use measureUserAgentSpecificMemory +} +``` + +## 例 + +### メモリの使用状況を監視 + +以下のコードは、[指数分布](https://en.wikipedia.org/wiki/Exponential_distribution#Random_variate_generation)を使用して、 5 分に 1 回、ランダムな間隔で `measureUserAgentSpecificMemory()` メソッドを呼び出す方法を示しています。 + +```js +function runMemoryMeasurements() { + const interval = -Math.log(Math.random()) * 5 * 60 * 1000; + console.log(`Next measurement in ${Math.round(interval / 1000)} seconds.`); + setTimeout(measureMemory, interval); +} + +async function measureMemory() { + const memorySample = await performance.measureUserAgentSpecificMemory(); + console.log(memorySample); + runMemoryMeasurements(); +} + +if (crossOriginIsolated) { + runMemoryMeasurements(); +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("setTimeout()")}} +- [Monitor your web page's total memory usage with measureUserAgentSpecificMemory() - web.dev](https://web.dev/articles/monitor-total-page-memory-usage) diff --git a/files/ja/web/api/performance/memory/index.md b/files/ja/web/api/performance/memory/index.md new file mode 100644 index 00000000000000..b3f9941561bd59 --- /dev/null +++ b/files/ja/web/api/performance/memory/index.md @@ -0,0 +1,52 @@ +--- +title: "Performance: memory プロパティ" +short-title: memory +slug: Web/API/Performance/memory +l10n: + sourceCommit: 7b3ccaec4a93584da12939587ea746acaabe30bc +--- + +{{APIRef("Performance API")}} {{Deprecated_Header}}{{Non-standard_header}} + +標準外の古い `performance.memory` プロパティは、ウェブサイトのメモリフットプリントを測定し縮小するのに役立つ JavaScript ヒープのサイズを返します。 + +ウェブページが同じヒープを共有している場合、この API が提供する情報は実際のメモリー使用量を過大評価する可能性があり、またウェブページが別個のヒープに割り当てられているワーカーやクロスサイト iframe を使用している場合、実際のメモリー使用量を過小評価する可能性があるため、信頼できないことに注意してください。また「ヒープ」が何を意味しているかは標準化されていません。この API は Chromium ベースのブラウザーでのみ利用できます。 + +`performance.memory` を置き換える新しい API は {{domxref("Performance.measureUserAgentSpecificMemory()")}} です。これはウェブページが使用するメモリを推定しようとします。 + +## 値 + +読み取り専用の `performance.memory` プロパティは、以下のプロパティを持つオブジェクトです。 + +- `jsHeapSizeLimit` + - : このコンテキストで利用できるヒープの最大サイズ（バイト単位）。 +- `totalJSHeapSize` + - : 割り当てられたヒープサイズの合計（バイト単位）。 +- `usedJSHeapSize` + - : JS ヒープの現在アクティブなセグメント。 + +## 例 + +### JavaScript ヒープサイズを取得 + +`performance.memory` を呼び出すと、このようなオブジェクトを返します。 + +```js +{ + totalJSHeapSize: 39973671, + usedJSHeapSize: 39127515, + jsHeapSizeLimit: 4294705152 +} +``` + +## 仕様書 + +なし。 + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("Performance.measureUserAgentSpecificMemory()")}} diff --git a/files/ja/web/api/performance/navigation/index.md b/files/ja/web/api/performance/navigation/index.md index 982682521d8bef..2bac47320fd7d8 100644 --- a/files/ja/web/api/performance/navigation/index.md +++ b/files/ja/web/api/performance/navigation/index.md @@ -1,9 +1,12 @@ --- -title: Performance.navigation +title: "Performance: navigation プロパティ" +short-title: navigation slug: Web/API/Performance/navigation +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Navigation Timing")}}{{Deprecated_Header}} +{{APIRef("Performance API")}}{{Deprecated_Header}} 古い **`Performance.navigation`** は読み取り専用プロパティで、指定された閲覧コンテキスト内で発生するナビゲーションの種類を表す {{domxref("PerformanceNavigation")}} オブジェクトを返します。リソースを取得するまでに必要なリダイレクトの数などです。 @@ -11,11 +14,9 @@ slug: Web/API/Performance/navigation > **警告:** このプロパティは [Navigation Timing Level 2 仕様書](https://w3c.github.io/navigation-timing/#obsolete)では非推奨です。代わりに {{domxref("PerformanceNavigationTiming")}} を使用してください。 -## 構文 +## 値 -```js -navObject = performance.navigation; -``` +{{domxref("PerformanceNavigation")}} オブジェクトです。 ## 仕様書 diff --git a/files/ja/web/api/performance/now/index.md b/files/ja/web/api/performance/now/index.md index b8d8c8048f5df4..af70101768c99b 100644 --- a/files/ja/web/api/performance/now/index.md +++ b/files/ja/web/api/performance/now/index.md @@ -1,33 +1,73 @@ --- -title: performance.now() +title: "Performance: now() メソッド" +short-title: now() slug: Web/API/Performance/now +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("High Resolution Timing")}} +{{APIRef("Performance API")}} -**`performance.now()`** メソッドは、ミリ秒単位で計測された {{domxref("DOMHighResTimeStamp")}} を返します。 +**`performance.now()`** メソッドは高解像度のタイムスタンプをミリ秒で返します。これは {{domxref("Performance.timeOrigin")}} （ウィンドウコンテキストではナビゲーションを開始した時刻、 {{domxref("Worker")}} および {{domxref("ServiceWorker")}} コンテキストではワーカーを実行した時刻）からの経過時間を表します。 -{{AvailableInWorkers}} +## 構文 + +```js-nolint +now() +``` -返値は[時刻原点](/ja/docs/Web/API/DOMHighResTimeStamp#the_time_origin)からの経過時間を表します。 +### 引数 -次の点に留意してください。 +なし。 -- {{domxref("Window")}} コンテキストから生成された専用ワーカー (dedicated worker) では、この値は生成元の window における`performance.now()` の値よりも小さい値になります。従来はメインコンテキストの `t0` と同じでしたが、変更されました。 -- 共有ワーカー (shared worker) またはサービスワーカー (service worker) では、この値はメインコンテキストでの値よりも大きくなるかもしれません。 window はワーカーよりも後に生成される可能性があるからです。 +### 返値 -ブラウザーは通常、 [Spectre](https://spectreattack.com/) のような潜在的なセキュリティ脅威を軽減するために、予測可能性を低下させる目的で、返される値をある量で丸めることを覚えておくことが重要です。これは、タイマーの解像度や精度を制限することで、意図的にある程度不正確にします。例えば、 Firefox は返される時刻を 1 ミリ秒単位で丸めます。 +ミリ秒単位で計測した {{domxref("DOMHighResTimeStamp")}} を返します。 -返される値の精度は、セキュリティ上の懸念が他の手段で軽減された場合、またはされた場合に変更される可能性があります。 +## 解説 -## 構文 +### `Performance.now` と `Date.now` + +[`Date.now`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/now) とは異なり、`performance.now()` が返すタイムスタンプは 1 ミリ秒の解像度に制限されません。時刻をマイクロ秒精度までの浮動小数点数で表します。 + +また、 `Date.now()` は Unix 元期 (1970-01-01T00:00:00Z) からの相対値で、システムクロックに依存しているため、システムクロックやユーザークロックの調整、クロックスキューなどの影響を受ける可能性があります。 +一方、 `performance.now()` メソッドは、 [monotonic clock](https://w3c.github.io/hr-time/#dfn-monotonic-clock) である `timeOrigin` プロパティ空の相対値です。その現在時刻は決して減少せず、調整の対象にはなりません。 + +### `performance.now` の仕様の変更 + +高解像度時間レベル 1 とレベル 2 では、 `performance.now()` メソッドの意味づけが変わりました。 + +| 変更 | レベル 1 | レベル 2 | +| -------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 基点 | [`performance.timing.navigationStart`](/ja/docs/Web/API/PerformanceTiming/navigationStart) | {{domxref("Performance.timeOrigin")}} | +| 起動条件 | 文書の読み込みまたはアンロードのプロンプト（もしあれば）。 | 閲覧コンテキストの作成（前の文書がない場合）、アンロードプロンプト（ある場合）、またはナビゲーションの開始（HTML 内で定義しているように、取得のいくつか前の段階）。 | + +`performance.now()` メソッドは、ナビゲーションタイミング仕様書の [`performance.timing.navigationStart`](/ja/docs/Web/API/PerformanceTiming/navigationStart) プロパティからの相対値を使用していました。これが変更され、 `performance.now()` は {{domxref("Performance.timeOrigin")}} からの相対値となり、ウェブページ間でタイムスタンプを比較する際の時計の変化のリスクを避けることができるようになりました。 ```js -t = performance.now(); +// レベル 1 （時計の変更のリスクあり） +currentTime = performance.timing.navigationStart + performance.now(); + +// レベル 2 （時計の変更のリスクなし） +currentTime = performance.timeOrigin + performance.now(); ``` +### スリープ中のカウント + +詳細度（レベル2）では、スリープ中に `performance.now()` がカウント動作することが要求されています。Windows の Firefox と Windows の Chromium だけがスリープ中も動き続けているようです。他にも関連するブラウザーバグがあります。 + +- Chrome/Chromium ([bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1206450)) +- Firefox ([bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1709767)) +- Safari/WebKit ([bug](https://bugs.webkit.org/show_bug.cgi?id=225610)) + +詳細は仕様の issue [hr-time#115](https://github.com/w3c/hr-time/issues/115) でも得られます。 + ## 例 +### `performance.now()` の使用 + +コードの具体的な点からの経過時間を調べるには、次のようにします。 + ```js const t0 = performance.now(); doSomething(); @@ -35,46 +75,22 @@ const t1 = performance.now(); console.log(`Call to doSomething took ${t1 - t0} milliseconds.`); ``` -JavaScript で利用できる他の時刻のデータ（例えば [`Date.now`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/now)）とは異なり、 `performance.now()` が返すタイムスタンプは、 1 ミリ秒の分解能に制限されません。代わりに、マイクロ秒までの精度を持った浮動小数点の値で時刻を表します。 - -また、`Date.now()` とは違い、`performance.now()` が返す値は、（手動で調整、または NTP のようなソフトウェアで変更される可能性がある）システムクロックから独立しており、常に一定の割合で増加します。一方、 `performance.timing.navigationStart + performance.now()` は、おおよそ `Date.now()` と等しくなります。 - -## 時間精度の引き下げ +## セキュリティ要件 -タイミング攻撃やフィンガープリンティングから保護するため、ブラウザーの設定によっては、 `performance.now()` の精度が丸められることがあります。 -Firefox では、 `privacy.reduceTimerPrecision` の設定が既定で有効になっており、既定で 1 ミリ秒となっています。 +タイミング攻撃や[フィンガープリンティング](/ja/docs/Glossary/Fingerprinting)から保護するために、 `performance.now()` はサイトの分離状態に基づいて粗くなります。 -```js -// Firefox 60 での時間精度の引き下げ (1ms) -performance.now(); -// 8781416 -// 8781815 -// 8782206 -// ... - -// `privacy.resistFingerprinting` 有効化による時間精度の引き下げ` -performance.now(); -// 8865400 -// 8866200 -// 8866700 -// ... -``` - -Firefox では `privacy.resistFingerprinting` も有効にすることができます。これは、精度を 100 ミリ秒または `privacy.resistFingerprinting.reduceTimerPrecision.microseconds` のどちらか大きい方へ変更します。 +- 独立したコンテキストでの解像度: 5 ミリ秒 +- 独立していないコンテキストでの解像度: 100 ミリ秒 -Firefox 79 以降では、高精度タイマーは文書が {{HTTPHeader("Cross-Origin-Opener-Policy")}} および {{HTTPHeader("Cross-Origin-Embedder-Policy")}} ヘッダーを使用してクロスオリジン分離を行っている場合に使用することができるようになりました。 +{{HTTPHeader("Cross-Origin-Opener-Policy")}} と {{HTTPHeader("Cross-Origin-Embedder-Policy")}} ヘッダーを使用して、サイトをオリジン間分離します。 -```plain +```http Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp ``` これらのヘッダーは、最上位の文書がクロスオリジン文書と閲覧コンテキストグループを共有しないことを保証します。 COOP プロセスは、文書を分離し、潜在的な攻撃者がポップアップでそれを開いていたとしても、グローバルオブジェクトにアクセスできないようにし、 [XS-Leaks](https://github.com/xsleaks/xsleaks) と呼ばれる一連のクロスオリジン攻撃を防止しています。 -## 仕様 - -{{Specifications}} - ## 仕様書 {{Specifications}} @@ -85,4 +101,4 @@ Cross-Origin-Embedder-Policy: require-corp ## 関連情報 -- [When milliseconds are not enough: performance.now()](http://updates.html5rocks.com/2012/08/When-milliseconds-are-not-enough-performance-now) (HTML5 Rocks) +- {{domxref("Performance.timeOrigin")}} diff --git a/files/ja/web/api/performance/resourcetimingbufferfull_event/index.md b/files/ja/web/api/performance/resourcetimingbufferfull_event/index.md index 293df0036cb4e1..555ec25314f660 100644 --- a/files/ja/web/api/performance/resourcetimingbufferfull_event/index.md +++ b/files/ja/web/api/performance/resourcetimingbufferfull_event/index.md @@ -1,55 +1,47 @@ --- title: "Performance: resourcetimingbufferfull イベント" +short-title: resourcetimingbufferfull slug: Web/API/Performance/resourcetimingbufferfull_event +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef}} - -`resourcetimingbufferfull` イベントは、ブラウザーのリソースタイミングバッファーがいっぱいになると発生します。 - - - - - - - - - - - - - - - - - - - - -
バブリングはい
キャンセル可
インターフェイス{{domxref("Event")}}
イベントハンドラープロパティ - {{domxref("Performance.onresourcetimingbufferfull", "onresourcetimingbufferfull")}} -
+{{APIRef("Performance API")}} -## 例 +`resourcetimingbufferfull` イベントは、ブラウザーの[リソースタイミングバッファー](/ja/docs/Web/API/Performance/setResourceTimingBufferSize)がいっぱいになると発生します。 + +## 構文 -次の例では、`onresourcetimingbufferfull` プロパティにコールバック関数を設定します。 +このイベント名を {{domxref("EventTarget.addEventListener", "addEventListener()")}} 等のメソッドで使用するか、イベントハンドラープロパティを設定するかしてください。 ```js -function buffer_full(event) { - console.log("WARNING: Resource Timing Buffer is FULL!"); - performance.setResourceTimingBufferSize(200); -} -function init() { - // リソースバッファーが一杯になったときのコールバックを設定 - performance.onresourcetimingbufferfull = buffer_full; -} - +addEventListener("resourcetimingbufferfull", (event) => {}); + +onresourcetimingbufferfull = (event) => {}; ``` -addEventListener() 関数を使用してハンドラーを設定することもできます。 +## イベント型 + +一般的な {{domxref("Event")}} です。 + +## 例 + +### バッファーが満杯になったときにサイズを拡大 + +次の例は、 `resourcetimingbufferfull` イベントを待ち受け、 {{domxref("Performance.setResourceTimingBufferSize", "setResourceTimingBufferSize()")}} メソッドを使用してバッファーサイズを増やします。 ```js -performance.addEventListener("resourcetimingbufferfull", buffer_full); +function increaseFilledBufferSize(event) { + console.log( + "警告: リソースタイミングバッファが満杯です。バッファーサイズを 500 に増やします。", + ); + performance.setResourceTimingBufferSize(500); +} + +performance.addEventListener( + "resourcetimingbufferfull", + increaseFilledBufferSize, +); ``` ## 仕様書 @@ -62,5 +54,5 @@ performance.addEventListener("resourcetimingbufferfull", buffer_full); ## 関連情報 -- {{domxref("Performance.clearResourceTimings","Performance.clearResourceTimings()")}} -- {{domxref("Performance.setResourceTimingBufferSize","Performance.setResourceTimingBufferSize()")}} +- {{domxref("Performance.clearResourceTimings()")}} +- {{domxref("Performance.setResourceTimingBufferSize()")}} diff --git a/files/ja/web/api/performance/setresourcetimingbuffersize/index.md b/files/ja/web/api/performance/setresourcetimingbuffersize/index.md index 1ccc0d1870b914..042d8330828a1f 100644 --- a/files/ja/web/api/performance/setresourcetimingbuffersize/index.md +++ b/files/ja/web/api/performance/setresourcetimingbuffersize/index.md @@ -1,48 +1,55 @@ --- -title: performance.setResourceTimingBufferSize() +title: "Performance: setResourceTimingBufferSize() メソッド" +short-title: setResourceTimingBufferSize() slug: Web/API/Performance/setResourceTimingBufferSize +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Resource Timing API")}} +{{APIRef("Performance API")}} -**`setResourceTimingBufferSize()`** メソッドは、ブラウザーのリソースタイミングバッファーサイズを、指定された数の "`resource`" の {{domxref("PerformanceEntry.entryType","パフォーマンスエントリー種別")}}のオブジェクトに設定します。 +**`setResourceTimingBufferSize()`** メソッドは、 "`resource`" パフォーマンス項目を格納するブラウザーリソースタイミングバッファーの希望するサイズを設定します。 -ブラウザーの推奨リソースタイミングバッファサイズは少なくとも{{domxref("PerformanceEntry","パフォーマンスエントリー")}}オブジェクト 150 件分です。 +仕様書では、リソースタイミングバッファーの初期値が 250 以上であることが要求されています。 -{{AvailableInWorkers}} +ブラウザーのパフォーマンスリソースデータバッファーをクリアするには、次のメソッドを使用します。 {{domxref("Performance.clearResourceTimings()")}} メソッドを使用します。 + +ブラウザーのリソースタイミングバッファーがいっぱいになったときに通知を取得するには、 {{domxref("Performance.resourcetimingbufferfull_event", "resourcetimingbufferfull")}} イベントを待ち受けしてください。 ## 構文 -```js -performance.setResourceTimingBufferSize(maxSize); +```js-nolint +setResourceTimingBufferSize(maxSize) ``` ### 引数 -- maxSize - - : `number` で、ブラウザーがパフォーマンスエントリーバッファーに保持する必要がある{{domxref("PerformanceEntry","パフォーマンスエントリー")}}オブジェクトの最大数を表します。 +- `maxSize` + - : `number` で、ブラウザーがパフォーマンス項目バッファーに保持する必要がある{{domxref("PerformanceEntry","パフォーマンス項目")}}オブジェクトの最大数を表します。 ### 返値 -- なし - - : このメソッドには返値はありません。 +なし ({{jsxref("undefined")}})。 ## 例 +### リソースタイミングバッファーサイズを設定 + +以下の呼び出しにより、ブラウザーのパフォーマンスタイムラインに "`resource`" パフォーマンス項目が 500 個入るようになります。 + ```js -function setResourceTimingBufferSize(maxSize) { - if (performance === undefined) { - log("Browser does not support Web Performance"); - return; - } - var supported = typeof performance.setResourceTimingBufferSize == "function"; - if (supported) { - log("... Performance.setResourceTimingBufferSize() = Yes"); - performance.setResourceTimingBufferSize(maxSize); - } else { - log("... Performance.setResourceTimingBufferSize() = NOT supported"); - } -} +performance.setResourceTimingBufferSize(500); +``` + +バッファーサイズを現在の項目数より小さい数に設定すると、項目は除去されません。代わりに、バッファをクリアするには {{domxref("Performance.clearResourceTimings()")}} を呼び出してください。 + +```js +performance.getEntriesByType("resource").length; // 20 +performance.setResourceTimingBufferSize(10); +performance.getEntriesByType("resource").length; // 20 + +performance.clearResourceTimings(); +performance.getEntriesByType("resource").length; // 0 ``` ## 仕様書 @@ -52,3 +59,8 @@ function setResourceTimingBufferSize(maxSize) { ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{domxref("Performance.clearResourceTimings()")}} +- {{domxref("Performance.resourcetimingbufferfull_event", "resourcetimingbufferfull")}} diff --git a/files/ja/web/api/performance/timeorigin/index.md b/files/ja/web/api/performance/timeorigin/index.md index 62381212eb2c7c..fdec1274c4f93a 100644 --- a/files/ja/web/api/performance/timeorigin/index.md +++ b/files/ja/web/api/performance/timeorigin/index.md @@ -1,23 +1,71 @@ --- -title: Performance.timeOrigin +title: "Performance: timeOrigin プロパティ" +short-title: timeOrigin slug: Web/API/Performance/timeOrigin +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{SeeCompatTable}}{{APIRef("High Resolution Time")}} +{{APIRef("Performance API")}} -**`timeOrigin`** は {{domxref("Performance")}} インターフェイスの読み取り専用プロパティで、パフォーマンス測定の開始時刻の高解像度タイムスタンプを返します。 +**`timeOrigin`** は {{domxref("Performance")}} インターフェイスの読み取り専用プロパティで、パフォーマンス関連のタイムスタンプのベースラインとして使用する高解像度のタイムスタンプを返します。 -{{AvailableInWorkers}} +ウィンドウコンテキストでは、この値がナビゲーションを開始した時刻を表します。 {{domxref("Worker")}} および {{domxref("ServiceWorker")}} コンテキストでは、この値はワーカーが実行された時刻を表します。このプロパティを使用して、コンテキスト間で時刻の原点を同期することができます (下記例を参照)。 -## 構文 +> **メモ:** `performance.timeOrigin` の値は、その時刻で実行された {{jsxref("Date.now()")}} が返す値と異なる場合があります。これは、 `Date.now()` がシステムやユーザーのクロック調整、クロックスキューなどの影響を受けることがあるからです。 `timeOrigin` プロパティは [monotonic clock](https://w3c.github.io/hr-time/#dfn-monotonic-clock) であり、現在の時刻が減少することはなく、これらの調整の影響を受けません。 + +## 値 + +現在の文書のライフタイムの始まりとみなされる高解像度のタイムスタンプ。このように計算されます。 + +- スクリプトの{{Glossary("global object", "グローバルオブジェクト")}}が{{domxref("Window", "ウィンドウ")}}の場合、時刻の原点は以下のように決定されます。 + + - 現在の {{domxref("Document")}} が `Window` 内で最初に読み込まれたものである場合、時刻の原点はブラウザーコンテキストが作成された時刻になります。 + - ウィンドウ内の前回読み込んだ文書をアンロードする過程で、前のページから離れるかどうかをユーザーに確認させるための確認ダイアログが表示された場合、時刻の原点は、ユーザーが新しいページに移動することが受け入れられるかどうかを確認した時刻 `:` となります。 + - もし上記のどちらも時刻の原点を決定しない場合、時刻の原点はウィンドウの現在の `Document` を作成するナビゲーションが配置された時刻になります。 + +- スクリプトのグローバルオブジェクトが {{domxref("WorkerGlobalScope")}} の場合（つまり、スクリプトがウェブワーカーとして実行されている場合）、時刻の原点はワーカーが作成された時点になります。 +- 他のすべての場合、時刻の原点は不定です。 + +## 例 + +### コンテキスト間で時刻を同期 + +ウィンドウとワーカーのコンテキストで異なる時刻の原点を考慮するために、 `timeOrigin` プロパティの助けによりワーカースクリプトから来るタイムスタンプを変換することができます。 + +worker.js では ```js -var timeOrigin = performance.timeOrigin; +self.addEventListener("connect", (event) => { + const port = event.ports[0]; + + port.onmessage = function (event) { + const workerTaskStart = performance.now(); + // doSomeWork() + const workerTaskEnd = performance.now(); + }; + + // ワーカー相対のタイムスタンプを絶対タイムスタンプに変換し、ウィンドウに送信します。 + port.postMessage({ + startTime: workerTaskStart + performance.timeOrigin, + endTime: workerTaskEnd + performance.timeOrigin, + }); +}); ``` -### 値 +main.js では -高解像度のタイムスタンプです。 +```js +const worker = new SharedWorker("worker.js"); +worker.port.addEventListener("message", (event) => { + // 絶対タイムスタンプをウィンドウ相対タイムスタンプに変換 + const workerTaskStart = event.data.startTime - performance.timeOrigin; + const workerTaskEnd = event.data.endTime - performance.timeOrigin; + + console.log("ワーカータスクの開始: ", workerTaskStart); + console.log("ワーカータスクの終了: ", workerTaskEnd); +}); +``` ## 仕様書 diff --git a/files/ja/web/api/performance/timing/index.md b/files/ja/web/api/performance/timing/index.md index b98089e2b3e010..ae730487e0f8f7 100644 --- a/files/ja/web/api/performance/timing/index.md +++ b/files/ja/web/api/performance/timing/index.md @@ -1,9 +1,12 @@ --- -title: Performance.timing +title: "Performance: timing プロパティ" +short-title: timing slug: Web/API/Performance/timing +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("Navigation Timing")}}{{deprecated_header}} +{{APIRef("Performance API")}}{{deprecated_header}} 古い **`Performance.timing`** 読み取り専用プロパティは、遅延時間に関するパフォーマンス情報を含む {{domxref("PerformanceTiming")}} オブジェクトを返します。 @@ -11,11 +14,9 @@ slug: Web/API/Performance/timing > **警告:** このプロパティは [Navigation Timing Level 2 仕様書](https://w3c.github.io/navigation-timing/#obsolete)では非推奨です。代わりに {{domxref("PerformanceNavigationTiming")}} を使用してください。 -## 構文 +## 値 -```js -timingInfo = performance.timing; -``` +{{domxref("PerformanceTiming")}} オブジェクトです。 ## 仕様書 diff --git a/files/ja/web/api/performance/tojson/index.md b/files/ja/web/api/performance/tojson/index.md index 71f4d8cab1028f..5a9c3c7f9bb518 100644 --- a/files/ja/web/api/performance/tojson/index.md +++ b/files/ja/web/api/performance/tojson/index.md @@ -1,38 +1,80 @@ --- -title: performance.toJSON() +title: "Performance: toJSON() メソッド" +short-title: toJSON() slug: Web/API/Performance/toJSON +l10n: + sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 --- -{{APIRef("High Resolution Timing")}} +{{APIRef("Performance API")}} -**`toJSON()`** は {{domxref("Performance")}} インターフェイスのメソッドで、標準のシリアライザーです。パフォーマンスオブジェクトのプロパティの JSON 表現を返します。 - -{{availableinworkers}} +**`toJSON()`** は {{domxref("Performance")}} インターフェイスのメソッドで、{{Glossary("Serialization","シリアライザー")}}です。パフォーマンスオブジェクトのプロパティの JSON 表現を返します。 ## 構文 -```js -myPerf = performance.toJSON(); +```js-nolint +toJSON() ``` ### 引数 -- なし - - : +なし。 ### 返値 -- myPerf - - : {{domxref("Performance")}} オブジェクトをシリアライズした JSON オブジェクト。 +{{domxref("Performance")}} オブジェクトをシリアライズした {{jsxref("JSON")}} オブジェクトです。 + +返された JSON には {{domxref("Performance.eventCounts", "eventCounts")}} プロパティが格納されていません。これは、{{domxref("EventCounts")}} 型であり、`toJSON()` 操作を提供していないからです。 + +> **メモ:** JSON オブジェクトには、非推奨の {{domxref("performance.timing")}} および {{domxref("performance.navigation")}} プロパティのシリアライズが格納されています。新しい {{domxref("PerformanceNavigationTiming")}} インターフェイスの JSON 表現を取得するには、代わりに {{domxref("PerformanceNavigationTiming.toJSON()")}} を呼び出してください。 ## 例 +### toJSON メソッドの使用 + +この例では、`performance.toJSON()` を呼び出すと、`Performance` オブジェクトの JSON 表現が返されます。 + ```js -var js; -js = window.performance.toJSON(); -console.log("json = " + JSON.stringify(js)); +performance.toJSON(); ``` +これは次のような JSON オブジェクトをログ出力します。 + +```json +{ + "timeOrigin": 1668077531367.4, + "timing": { + "connectStart": 1668077531372, + "navigationStart": 1668077531367, + "secureConnectionStart": 0, + "fetchStart": 1668077531372, + "domContentLoadedEventStart": 1668077531580, + "responseStart": 1668077531372, + "domInteractive": 1668077531524, + "domainLookupEnd": 1668077531372, + "responseEnd": 1668077531500, + "redirectStart": 0, + "requestStart": 1668077531372, + "unloadEventEnd": 0, + "unloadEventStart": 0, + "domLoading": 1668077531512, + "domComplete": 1668077531585, + "domainLookupStart": 1668077531372, + "loadEventStart": 1668077531585, + "domContentLoadedEventEnd": 1668077531580, + "loadEventEnd": 1668077531585, + "redirectEnd": 0, + "connectEnd": 1668077531372 + }, + "navigation": { + "type": 0, + "redirectCount": 0 + } +} +``` + +JSON 文字列を取得するには、 [`JSON.stringify(performance)`](/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) を直接使用することができます。 + ## 仕様書 {{Specifications}} @@ -40,3 +82,7 @@ console.log("json = " + JSON.stringify(js)); ## ブラウザーの互換性 {{Compat}} + +## 関連情報 + +- {{jsxref("JSON")}} diff --git a/files/ja/web/api/performanceeventtiming/cancelable/index.md b/files/ja/web/api/performanceeventtiming/cancelable/index.md new file mode 100644 index 00000000000000..dcd6ce08721f7e --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/cancelable/index.md @@ -0,0 +1,43 @@ +--- +title: "PerformanceEventTiming: cancelable プロパティ" +short-title: cancelable +slug: Web/API/PerformanceEventTiming/cancelable +l10n: + sourceCommit: c58e8c1dd6ecbcb63894c7dd17fb9495b9511b4e +--- + +{{APIRef("Performance API")}} + +読み取り専用の **`cancelable`** プロパティは、関連付けられたイベントの [`cancelable`](/ja/docs/Web/API/Event/cancelable) プロパティを返し、イベントを取り消すことができるかどうかを示します。 + +## 値 + +論理値です。関連付けられたイベントが取り消し可能であれば `true`、そうでなければ `false` です。 + +## 例 + +### 取り消し不可のイベントを監視 + +cancelable` プロパティは、イベントタイミング項目 ({{domxref("PerformanceEventTiming")}}) を監視するときに使用することができます。例えば、取り消される可能性のないイベントのみをログ出力して測定する場合などです。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (!entry.cancelable) { + const delay = entry.processingStart - entry.startTime; + console.log(entry.name, delay); + } + }); +}); + +// イベントのオブザーバーを登録 +observer.observe({ type: "event", buffered: true }); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/performanceeventtiming/index.md b/files/ja/web/api/performanceeventtiming/index.md new file mode 100644 index 00000000000000..64e5d6a86ce6eb --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/index.md @@ -0,0 +1,256 @@ +--- +title: PerformanceEventTiming +slug: Web/API/PerformanceEventTiming +l10n: + sourceCommit: 1b6ae1c429b5a495fada425cc88ec2a3c7ab77db +--- + +{{APIRef("Performance API")}} + +`PerformanceEventTiming` はイベントタイミング API のインターフェイスで、ユーザー操作によって発生させる特定のイベント型の待ち時間に関する分析結果を提供します。 + +## 解説 + +この API により、特定のイベント型（[下記参照](#公開されるイベント)）のイベントのタイムスタンプと処理時間が提供されるので、遅いイベントを可視化することができるようになります。例えば、ユーザー操作からそのイベントハンドラーが始まるまでの時間や、イベントハンドラーが実行するまでにかかる時間を監視することができます。 + +この API は、{{Glossary("first input delay")}} (FID) （ユーザーがこのアプリを最初に操作した時点から、ブラウザーが実際にその操作に応答することができるまでの時間）を測定するのに特に有益です。 + +通常、 `PerformanceEventTiming` オブジェクトを扱うには、 {{domxref("PerformanceObserver")}} インスタンスを作成し、 [`observe()`](/ja/docs/Web/API/PerformanceObserver/observe) メソッドを呼び出して、 [`type`](/ja/docs/Web/API/PerformanceEntry/entryType) オプションに `"event"` または `"first-input"` を渡します。 `PerformanceObserver` オブジェクトのコールバックは、 `PerformanceEventTiming` オブジェクトのリストとともに呼び出されます。例えば[下記の例](#イベントタイミング情報の取得)をご覧ください。 + +既定では、`PerformanceEventTiming` 項目は `duration` が 104ms 以上の場合に公開されます。調査によると、 100ms 以内に処理されないユーザー入力は遅いと考えられており、 104ms は 100ms より大きい最初の 8 の倍数です（セキュリティ上の理由から、この API は最も近い 8 の倍数に丸められます）。 +しかし、[`observe()`](/ja/docs/Web/API/PerformanceObserver/observe) メソッドの `durationThreshold` オプションを使用して、{{domxref("PerformanceObserver")}} を別の閾値に設定することができます。 + +このインターフェイスは、親である {{domxref("PerformanceEntry")}} のメソッドとプロパティを継承しています。 + +{{InheritanceDiagram}} + +### 公開されるイベント + +イベントタイミング API で公開されるイベント型は以下の通りです。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
クリックイベント + {{domxref("Element/auxclick_event", "auxclick")}}, + {{domxref("Element/click_event", "click")}}, + {{domxref("Element/contextmenu_event", "contextmenu")}}, + {{domxref("Element/dblclick_event", "dblclick")}} +
変換イベント + {{domxref("Element/compositionend_event", "compositionend")}}, + {{domxref("Element/compositionstart_event", "compositionstart")}}, + {{domxref("Element/compositionupdate_event", "compositionupdate")}} +
ドラッグ & ドロップイベント + {{domxref("HTMLElement/dragend_event", "dragend")}}, + {{domxref("HTMLElement/dragenter_event", "dragenter")}}, + {{domxref("HTMLElement/dragleave_event", "dragleave")}}, + {{domxref("HTMLElement/dragover_event", "dragover")}}, + {{domxref("HTMLElement/dragstart_event", "dragstart")}}, + {{domxref("HTMLElement/drop_event", "drop")}} +
入力イベント + {{domxref("Element/beforeinput_event", "beforeinput")}}, + {{domxref("Element/input_event", "input")}} +
キーボードイベント + {{domxref("Element/keydown_event", "keydown")}}, + {{domxref("Element/keypress_event", "keypress")}}, + {{domxref("Element/keyup_event", "keyup")}} +
マウスイベント + {{domxref("Element/mousedown_event", "mousedown")}}, + {{domxref("Element/mouseenter_event", "mouseenter")}}, + {{domxref("Element/mouseleave_event", "mouseleave")}}, + {{domxref("Element/mouseout_event", "mouseout")}}, + {{domxref("Element/mouseover_event", "mouseover")}}, + {{domxref("Element/mouseup_event", "mouseup")}} +
ポインターイベント + {{domxref("Element/pointerover_event", "pointerover")}}, + {{domxref("Element/pointerenter_event", "pointerenter")}}, + {{domxref("Element/pointerdown_event", "pointerdown")}}, + {{domxref("Element/pointerup_event", "pointerup")}}, + {{domxref("Element/pointercancel_event", "pointercancel")}}, + {{domxref("Element/pointerout_event", "pointerout")}}, + {{domxref("Element/pointerleave_event", "pointerleave")}}, + {{domxref("Element/gotpointercapture_event", "gotpointercapture")}}, + {{domxref("Element/lostpointercapture_event", "lostpointercapture")}} +
タッチイベント + {{domxref("Element/touchstart_event", "touchstart")}}, + {{domxref("Element/touchend_event", "touchend")}}, + {{domxref("Element/touchcancel_event", "touchcancel")}} +
+ +なお、連続イベントであり、この時点では意味のあるイベントカウントやパフォーマンス指標を得ることができないため、リストに含まれていないイベントがあります。 {{domxref("Element/mousemove_event", "mousemove")}}, {{domxref("Element/pointermove_event", "pointermove")}}、{{domxref("Element/pointerrawupdate_event", "pointerrawupdate")}}、{{domxref("Element/touchmove_event", "touchmove")}}、{{domxref("Element/wheel_event", "wheel")}}、{{domxref("HTMLElement/drag_event", "drag")}} です。 + +公開されるすべてのイベントのリストを取得するには、 {{domxref("performance.eventCounts")}} マップのキーを見ていくこともできます。 + +```js +const exposedEventsList = [...performance.eventCounts.keys()]; +``` + +## コンストラクター + +このインターフェイスは自分自身でコンストラクター持っていません。 `PerformanceEventTiming` インターフェイスが保持している情報を取得する一般的な方法については、[下記の例](#イベントタイミング情報の取得)を参照してください。 + +## インスタンスプロパティ + +このインターフェイスは、イベントタイミングパフォーマンス項目型の以下の {{domxref("PerformanceEntry")}} プロパティを、次のように修飾子して拡張します。 + +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、 `startTime` から次の描画までの時間（8ms に丸めたもの）を返します。 +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} + - : `"event"` （長いイベント）または `"first-input"` （最初のユーザー操作）を返します。 +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} + - : 関連するイベントの型を返します。 +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、関連付けられたイベントの [`timestamp`](/ja/docs/Web/API/Event/timeStamp) プロパティを表す値を返します。これはイベントが作成された時刻であり、ユーザーの操作が発生した時刻のプロキシーと考えることができます。 + +このインターフェイスは以下のプロパティにも対応しています。 + +- {{domxref("PerformanceEventTiming.cancelable")}} {{ReadOnlyInline}} + - : 関連するイベントの [`cancelable`](/ja/docs/Web/API/Event/cancelable) プロパティを返します。 +- {{domxref("PerformanceEventTiming.interactionId")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : 関連するイベントを発生させたユーザー操作を一意に識別する ID を返します。 +- {{domxref("PerformanceEventTiming.processingStart")}} {{ReadOnlyInline}} + - : イベント配信が開始された時刻を表す {{domxref("DOMHighResTimeStamp")}} を返します。ユーザー操作からイベントハンドラーが実行し始めるまでの時間を計測するには、 `processingStart-startTime` を計算します。 +- {{domxref("PerformanceEventTiming.processingEnd")}} {{ReadOnlyInline}} + - : イベント配信が終わった時刻を表す {{domxref("DOMHighResTimeStamp")}} を返します。イベントハンドラーが実行するのにかかった時間を計測するには、 `processingEnd-processingStart` を計算します。 +- {{domxref("PerformanceEventTiming.target")}} {{ReadOnlyInline}} + - : 関連付けられたイベントの最後の対象が除去されていない場合、それを返します。 + +## インスタンスメソッド + +- {{domxref("PerformanceEventTiming.toJSON()")}} + - : この `PerformanceEventTiming` オブジェクトの JSON 表現を返します。 + +## 例 + +### イベントタイミング情報の取得 + +イベントのタイミング情報を取得するには、 {{domxref("PerformanceObserver")}} のインスタンスを作成し、 [`observe()`](/ja/docs/Web/API/PerformanceObserver/observe) メソッドを呼び出して、 [`type`](/ja/docs/Web/API/PerformanceEntry/entryType) オプションの値として `"event"` または `"first-input"` を渡してください。また、ユーザーエージェントが文書の構築中にバッファリングしたイベントにアクセスするには、 `buffered` を `true` に設定する必要があります。 `PerformanceObserver` オブジェクトのコールバックは、 `PerformanceEventTiming` オブジェクトのリストとともに呼び出されます。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // 時間全体 + const duration = entry.duration; + + // 入力遅延（イベント処理前） + const delay = entry.processingStart - entry.startTime; + + // 同期イベント処理時間 + // （配信の開始と終了） + const eventHandlerTime = entry.processingEnd - entry.processingStart; + console.log(`Total duration: ${duration}`); + console.log(`Event delay: ${delay}`); + console.log(`Event handler duration: ${eventHandlerTime}`); + }); +}); + +// イベントのオブザーバーを登録 +observer.observe({ type: "event", buffered: true }); +``` + +異なる [`durationThreshold`](/ja/docs/Web/API/PerformanceObserver/observe#durationthreshold) を設定することもできます。既定では 104ms で、最小可能な閾値は 16ms です。 + +```js +observer.observe({ type: "event", durationThreshold: 16, buffered: true }); +``` + +### First Input Delay (FID) の報告 + +{{Glossary("first input delay")}} または FID は、ユーザーが最初にページを操作した時（つまり、リンクをクリックしたりボタンをタップしたりした時）から、その操作に応答してブラウザーが実際にイベントハンドラーの処理を始めることができるまでの時刻を測定します。 + +```js +// Keep track of whether (and when) the page was first hidden, see: +// https://github.com/w3c/page-visibility/issues/29 +// NOTE: ideally this check would be performed in the document +// to avoid cases where the visibility state changes before this code runs. +let firstHiddenTime = document.visibilityState === "hidden" ? 0 : Infinity; +document.addEventListener( + "visibilitychange", + (event) => { + firstHiddenTime = Math.min(firstHiddenTime, event.timeStamp); + }, + { once: true }, +); + +// Sends the passed data to an analytics endpoint. This code +// uses `/analytics`; you can replace it with your own URL. +function sendToAnalytics(data) { + const body = JSON.stringify(data); + // Use `navigator.sendBeacon()` if available, + // falling back to `fetch()`. + (navigator.sendBeacon && navigator.sendBeacon("/analytics", body)) || + fetch("/analytics", { body, method: "POST", keepalive: true }); +} + +// Use a try/catch instead of feature detecting `first-input` +// support, since some browsers throw when using the new `type` option. +// https://webkit.org/b/209216 +try { + function onFirstInputEntry(entry) { + // Only report FID if the page wasn't hidden prior to + // the entry being dispatched. This typically happens when a + // page is loaded in a background tab. + if (entry.startTime < firstHiddenTime) { + const fid = entry.processingStart - entry.startTime; + + // Report the FID value to an analytics endpoint. + sendToAnalytics({ fid }); + } + } + + // Create a PerformanceObserver that calls + // `onFirstInputEntry` for each entry. + const po = new PerformanceObserver((entryList) => { + entryList.getEntries().forEach(onFirstInputEntry); + }); + + // Observe entries of type `first-input`, including buffered entries, + // i.e. entries that occurred before calling `observe()` below. + po.observe({ + type: "first-input", + buffered: true, + }); +} catch (e) { + // Do nothing if the browser doesn't support this API. +} +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/performanceeventtiming/interactionid/index.md b/files/ja/web/api/performanceeventtiming/interactionid/index.md new file mode 100644 index 00000000000000..a77044ecc175a0 --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/interactionid/index.md @@ -0,0 +1,64 @@ +--- +title: "PerformanceEventTiming: interactionId プロパティ" +short-title: interactionId +slug: Web/API/PerformanceEventTiming/interactionId +l10n: + sourceCommit: 989453176fd8756828b34b743a677a797d897156 +--- + +{{APIRef("Performance API")}}{{SeeCompatTable}} + +読み取り専用の **`interactionId`** プロパティは、一連の関連イベントを発生させたユーザー操作を一意に識別する ID を返します。 + +## 解説 + +ユーザーがウェブページを操作するとき、ユーザー操作（例えばクリック）は通常 `pointerdown`、`pointerup`、`click` イベントなどの一連のイベントを発生させます。この一連のイベントの待ち時間を計測するために、イベントは同じ `interactionId` を共有します。 + +`interactionId` はそのユーザー操作に属する以下のイベント型に対してのみ計算されます。それ以外は `0` です。 + +| イベント型 | ユーザー操作 | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | +| {{domxref("Element/pointerdown_event", "pointerdown")}}, {{domxref("Element/pointerup_event", "pointerup")}}, {{domxref("Element/click_event", "click")}} | クリック / タップ / ドラッグ | +| {{domxref("Element/keydown_event", "keydown")}}, {{domxref("Element/keyup_event", "keyup")}} | キー押下 | + +## 値 + +数値です。 + +## 例 + +### interactionId の使用 + +次の例では、ある操作に対応するすべてのイベントの時間を収集しています。 `eventLatencies` マップを使用して、例えばユーザーの操作の最大時間を持つイベントを探すことができます。 + +```js +// The key is the interaction ID. +let eventLatencies = {}; + +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (entry.interactionId > 0) { + const interactionId = entry.interactionId; + if (!eventLatencies.has(interactionId)) { + eventLatencies[interactionId] = []; + } + eventLatencies[interactionId].push(entry.duration); + } + }); +}); + +observer.observe({ type: "event", buffered: true }); + +// ユーザー操作の最大イベント再生時間でイベントをログ出力します +Object.entries(eventLatencies).forEach(([k, v]) => { + console.log(Math.max(...v)); +}); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/performanceeventtiming/processingend/index.md b/files/ja/web/api/performanceeventtiming/processingend/index.md new file mode 100644 index 00000000000000..8021594421b015 --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/processingend/index.md @@ -0,0 +1,51 @@ +--- +title: "PerformanceEventTiming: processingEnd プロパティ" +short-title: processingEnd +slug: Web/API/PerformanceEventTiming/processingEnd +l10n: + sourceCommit: c58e8c1dd6ecbcb63894c7dd17fb9495b9511b4e +--- + +{{APIRef("Performance API")}} + +読み取り専用の **`processingEnd`** プロパティは、最後のイベントハンドラーが実行を完了した時刻を返します。 + +そのようなイベントハンドラーがない場合は {{domxref("PerformanceEventTiming.processingStart")}} と等しくなります。 + +## 値 + +{{domxref("DOMHighResTimeStamp")}} タイムスタンプです。 + +## 例 + +### processingEnd プロパティの使用 + +`processingEnd` プロパティはイベントタイミング項目 ({{domxref("PerformanceEventTiming")}}) を監視するときに使用することができます。例えば、入力遅延やイベント処理時間を計算する場合などです。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // 時間全体 + const duration = entry.duration; + // 入力遅延（イベント処理前） + const delay = entry.processingStart - entry.startTime; + // 銅器イベント処理時間 + // （配信の開始から終了まで） + const time = entry.processingEnd - entry.processingStart; + }); +}); +// イベントのオブザーバーを登録 +observer.observe({ type: "event", buffered: true }); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("PerformanceEventTiming.processingStart")}} diff --git a/files/ja/web/api/performanceeventtiming/processingstart/index.md b/files/ja/web/api/performanceeventtiming/processingstart/index.md new file mode 100644 index 00000000000000..d751cc4a50beb2 --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/processingstart/index.md @@ -0,0 +1,49 @@ +--- +title: "PerformanceEventTiming: processingStart プロパティ" +short-title: processingStart +slug: Web/API/PerformanceEventTiming/processingStart +l10n: + sourceCommit: c58e8c1dd6ecbcb63894c7dd17fb9495b9511b4e +--- + +{{APIRef("Performance API")}} + +読み取り専用の **`processingStart`** プロパティは、イベント配信が開始された時刻を返します。これは、イベントハンドラーが実行されようとしている時点です。 + +## 値 + +{{domxref("DOMHighResTimeStamp")}} タイムスタンプです。 + +## 例 + +### processingStart プロパティの使用 + +`processingStart` プロパティはイベントタイミング項目 ({{domxref("PerformanceEventTiming")}}) を監視するときに使用することができます。例えば、入力遅延やイベント処理時間を計算する場合などです。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // 時間全体 + const duration = entry.duration; + // 入力遅延（イベント処理前） + const delay = entry.processingStart - entry.startTime; + // 銅器イベント処理時間 + // （配信の開始から終了まで） + const time = entry.processingEnd - entry.processingStart; + }); +}); +// イベントのオブザーバーを登録 +observer.observe({ type: "event", buffered: true }); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{domxref("PerformanceEventTiming.processingEnd")}} diff --git a/files/ja/web/api/performanceeventtiming/target/index.md b/files/ja/web/api/performanceeventtiming/target/index.md new file mode 100644 index 00000000000000..db47374cbb52e3 --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/target/index.md @@ -0,0 +1,45 @@ +--- +title: "PerformanceEventTiming: target プロパティ" +short-title: target +slug: Web/API/PerformanceEventTiming/target +l10n: + sourceCommit: ac2874857a3de0be38430e58068597edf0afa2b2 +--- + +{{APIRef("Performance API")}} + +読み取り専用の **`target`** プロパティは、関連付けられたイベントの最後の [`target`](/ja/docs/Web/API/Event/target) （イベントが最後に配信されたノード）を返します。 + +## 値 + +イベントが最後に配信された {{domxref("Node")}} です。 + +または、 `Node` が文書の DOM から切断されていたり、[シャドウ DOM](/ja/docs/Web/API/Web_components/Using_shadow_DOM) の中にあったりした場合は [`null`](/ja/docs/Web/JavaScript/Reference/Operators/null) です。 + +## 例 + +### 特定の最後のターゲットを持つイベントの監視 + +`target` プロパティはイベントタイミング項目 ({{domxref("PerformanceEventTiming")}}) を監視するときに使用することができます。例えば、指定された最後の対象に対してのみイベントをログ出力し、測定する場合などです。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (entry.target && entry.target.id === "myNode") { + const delay = entry.processingStart - entry.startTime; + console.log(entry.name, delay); + } + }); +}); + +// イベントのオブザーバーを登録 +observer.observe({ type: "event", buffered: true }); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} diff --git a/files/ja/web/api/performanceeventtiming/tojson/index.md b/files/ja/web/api/performanceeventtiming/tojson/index.md new file mode 100644 index 00000000000000..e48e70f8680f59 --- /dev/null +++ b/files/ja/web/api/performanceeventtiming/tojson/index.md @@ -0,0 +1,71 @@ +--- +title: "PerformanceEventTiming: toJSON() メソッド" +short-title: toJSON() +slug: Web/API/PerformanceEventTiming/toJSON +l10n: + sourceCommit: c58e8c1dd6ecbcb63894c7dd17fb9495b9511b4e +--- + +{{APIRef("Performance API")}} + +**`toJSON()`** は {{domxref("PerformanceEventTiming")}} インターフェイスのメソッドで、{{Glossary("Serialization","シリアライザー")}}です。これは {{domxref("PerformanceEventTiming")}} オブジェクトの JSON 表現を返します。 + +## 構文 + +```js-nolint +toJSON() +``` + +### 引数 + +なし。 + +### 返値 + +{{domxref("PerformanceEventTiming")}} オブジェクトをシリアライズした {{jsxref("JSON")}} オブジェクトです。 + +JSON は {{domxref("PerformanceEventTiming.target", "target")}} プロパティを含みません。これは {{domxref("Node")}} 型であり、 `toJSON()` 処理を提供していないからです。 + +## 例 + +### toJSON メソッドの使用 + +この例では、`entry.toJSON()` を呼び出すと、 `PerformanceEventTiming` オブジェクトの JSON 表現が返されます。 + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(entry.toJSON()); + }); +}); + +observer.observe({ type: "event", buffered: true }); +``` + +このように JSON オブジェクトをログ出力します。 + +```json +{ + "name": "dragover", + "entryType": "event", + "startTime": 67090751.599999905, + "duration": 128, + "processingStart": 67090751.70000005, + "processingEnd": 67090751.900000095, + "cancelable": true +} +``` + +JSON 文字列を取得するには、 [`JSON.stringify(entry)`](/ja/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) を直接使用することができます。これは `toJSON()` を自動的に呼び出します。 + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- {{jsxref("JSON")}} diff --git a/files/ja/web/api/performancenavigationtiming/index.md b/files/ja/web/api/performancenavigationtiming/index.md index b6bb736e99a5d0..af6289ec38f743 100644 --- a/files/ja/web/api/performancenavigationtiming/index.md +++ b/files/ja/web/api/performancenavigationtiming/index.md @@ -1,64 +1,69 @@ --- title: PerformanceNavigationTiming slug: Web/API/PerformanceNavigationTiming +l10n: + sourceCommit: 922c2b0f37e2f13887c50efe47e62bc23d94c3aa --- -{{APIRef("Navigation Timing")}}{{SeeCompatTable}} +{{APIRef("Performance API")}} **`PerformanceNavigationTiming`** インターフェイスは、ブラウザーの文書ナビゲーションイベントに関するメトリックを格納および取得するためのメソッドとプロパティを提供します。たとえば、このインターフェイスを使用して、文書のロードまたはアンロードにかかる時間を判断できます。 +パフォーマンスタイムラインに記載されるのは現在の文書のみなので、パフォーマンスタイムライン内の `PerformanceNavigationTiming` オブジェクトは 1 つだけです。このオブジェクトは {{domxref("PerformanceResourceTiming")}} と {{domxref("PerformanceEntry")}} のプロパティとメソッドをすべて継承します。 + {{InheritanceDiagram}} -## プロパティ +以下は `PerformanceNavigationTiming` で定義するタイムスタンププロパティをすべて表示させたものです。 + +![文書内の取得したタイムスタンプを記録順に並べたタイムスタンプ図](timestamp-diagram.svg) -このインターフェイスは、ナビゲーションパフォーマンスエントリタイプの以下の {{domxref('PerformanceEntry')}} プロパティを次のように限定して制限することで拡張します。 +## インスタンスプロパティ -- {{domxref("PerformanceEntry.entryType")}} {{readonlyInline}} +このインターフェイスは、以下の {{domxref('PerformanceEntry')}} プロパティを修飾および制約することで拡張します。 + +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} - : `"navigation"` を返します。 -- {{domxref("PerformanceEntry.name")}} {{readonlyInline}} - - : [文書のアドレス](https://dom.spec.whatwg.org/#concept-document-url) を返します。 -- {{domxref("PerformanceEntry.startTime")}} {{readonlyInline}} +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} + - : [文書の URL](/ja/docs/Web/API/Document/URL) を返します。 +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} - : 値 "`0`" を持つ {{domxref("DOMHighResTimeStamp")}} を返します。 -- {{domxref("PerformanceEntry.duration")}} {{readonlyInline}} +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} - : {{domxref("PerformanceNavigationTiming.loadEventEnd")}} と {{domxref("PerformanceEntry.startTime")}} の各プロパティの差である {{domxref("DOMHighResTimeStamp","timestamp")}} を返します。 -このインターフェイスは、ナビゲーションパフォーマンスエントリタイプの以下の {{domxref('PerformanceResourceTiming')}} プロパティも、次のように修飾して制約することで拡張します。 +このインターフェイスは、ナビゲーションパフォーマンス項目型の以下の {{domxref('PerformanceResourceTiming')}} プロパティも、次のように修飾して制約することで拡張します。 -- {{domxref('PerformanceResourceTiming.initiatorType')}}{{readonlyInline}} +- {{domxref('PerformanceResourceTiming.initiatorType')}} {{ReadOnlyInline}} - : `"navigation"` を返します。 -インターフェイスは以下のプロパティもサポートします。 - -- {{domxref('PerformanceNavigationTiming.domComplete')}} {{readonlyInline}} - - : ブラウザーが現在の文書の現在の文書レディネスを*[完了](https://html.spec.whatwg.org/multipage/syntax.html#the-end)*に設定する直前の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.domContentLoadedEventEnd')}} {{readonlyInline}} - - : 現在の文書の [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end) イベントが完了した直後の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.domContentLoadedEventStart')}} {{readonlyInline}} - - : 現在の文書でユーザーエージェントが [DOMContentLoaded](https://html.spec.whatwg.org/multipage/syntax.html#the-end) イベントを起動する直前の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.domInteractive')}} {{readonlyInline}} - - : ユーザーエージェントが現在の文書の現在の文書の準備状態を [interactive](https://html.spec.whatwg.org/multipage/syntax.html#the-end) に設定する直前の時間に等しい時間値を表す{{domxref("DOMHighResTimeStamp","タイムスタンプ")}}を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.loadEventEnd')}} {{readonlyInline}} - - : 現在の文書の load イベントが完了した時刻を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.loadEventStart')}} {{readonlyInline}} - - : 現在の文書の load イベントが発生する直前の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.redirectCount')}} {{readonlyInline}} +このインターフェイスは以下のプロパティにも対応しています。 + +- {{domxref('PerformanceNavigationTiming.activationStart')}} {{ReadOnlyInline}} {{experimental_inline}} + - : {{domxref("DOMHighResTimeStamp")}} で、文書が事前レンダリングを始めてから有効になるまでの時間を表します。 +- {{domxref('PerformanceNavigationTiming.domComplete')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、ブラウザーが現在の文書の現在の文書レディネスを*[完了](https://html.spec.whatwg.org/multipage/syntax.html#the-end)*に設定する直前の時間と等しい時間値を表します。 +- {{domxref('PerformanceNavigationTiming.domContentLoadedEventEnd')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、現在の文書の [`DOMContentLoaded`](/ja/docs/Web/API/Document/DOMContentLoaded_event) イベントが完了した直後の時間と等しい時間値を表します。 +- {{domxref('PerformanceNavigationTiming.domContentLoadedEventStart')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、現在の文書でユーザーエージェントが [`DOMContentLoaded`](/ja/docs/Web/API/Document/DOMContentLoaded_event) イベントを起動する直前の時間と等しい時間値を表します。 +- {{domxref('PerformanceNavigationTiming.domInteractive')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、ユーザーエージェントがこの文書の [`readyState`](/ja/docs/Web/API/Document/readyState) を `"interactive"` に設定する直前の時刻を表します。 +- {{domxref('PerformanceNavigationTiming.loadEventEnd')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、現在の文書の [`load`](/ja/docs/Web/API/Window/load_event) イベントが完了した時刻を表します。 +- {{domxref('PerformanceNavigationTiming.loadEventStart')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、現在の文書の [`load`](/ja/docs/Web/API/Window/load_event) イベントが発生する直前の時間と等しい時間値を表します。 +- {{domxref('PerformanceNavigationTiming.redirectCount')}} {{ReadOnlyInline}} - : 現在の閲覧コンテキストでの最後のリダイレクト以外のナビゲーション以降のリダイレクト数を表す数値。 - リダイレクトがなかった場合、またはリダイレクトが別のオリジンからのもので、そのオリジンが現在のオリジンにタイミング情報を公開することを許可していない場合、値は 0 になります。 -- {{domxref('PerformanceNavigationTiming.requestStart')}} {{readonlyInline}} - - : ユーザーエージェントがサーバー、または関連するアプリケーションキャッシュから、あるいはローカルリソースからリソースを要求し始める直前の時間を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.responseStart')}} {{readonlyInline}} - - : ユーザーエージェントの HTTP パーサーが関連するアプリケーションキャッシュ、またはローカルリソースから、あるいはサーバーからレスポンスの最初のバイトを受け取った直後の時間を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.type')}} {{readonlyInline}} - - : ナビゲーションタイプを表す {{domxref("DOMString","文字列")}}。"`navigate`"、"`reload`"、"`back_forward`"、"`prerender`"のいずれかです。 -- {{domxref('PerformanceNavigationTiming.unloadEventEnd')}} {{readonlyInline}} - - : ユーザーエージェントが前の文書の unload イベントを終了した直後の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 -- {{domxref('PerformanceNavigationTiming.unloadEventStart')}} {{readonlyInline}} - - : ユーザーエージェントが前の文書の unload イベントを開始する直前の時間と等しい時間値を表す {{domxref("DOMHighResTimeStamp")}}。 - -## メソッド +- {{domxref('PerformanceNavigationTiming.type')}} {{ReadOnlyInline}} + - : 文字列で、ナビゲーションの種類を表します。 `"navigate"`、`"reload"`、`"back_forward"`、`"prerender"` のいずれかです。 +- {{domxref('PerformanceNavigationTiming.unloadEventEnd')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、ユーザーエージェントが前の文書の [`unload`](/ja/docs/Web/API/Window/unload_event) イベントを完了した直後の時間と等しい時間値を表します。 +- {{domxref('PerformanceNavigationTiming.unloadEventStart')}} {{ReadOnlyInline}} + - : {{domxref("DOMHighResTimeStamp")}} で、ユーザーエージェントが前の文書の [`unload`](/ja/docs/Web/API/Window/unload_event) イベントを開始する直前の時間と等しい時間値を表します。 + +## インスタンスメソッド - {{domxref("PerformanceNavigationTiming.toJSON()")}} - - : {{domxref("PerformanceNavigationTiming")}} オブジェクトの JSON 表現である {{domxref("DOMString")}} を返します。 + - : `PerformanceNavigationTiming` オブジェクトの JSON 表現を返します。 ## 仕様書 diff --git a/files/ja/web/api/rtcsessiondescription/index.md b/files/ja/web/api/rtcsessiondescription/index.md index e083b1988e77ba..5a6e25c99fe29f 100644 --- a/files/ja/web/api/rtcsessiondescription/index.md +++ b/files/ja/web/api/rtcsessiondescription/index.md @@ -1,83 +1,71 @@ --- title: RTCSessionDescription slug: Web/API/RTCSessionDescription +l10n: + sourceCommit: acfe8c9f1f4145f77653a2bc64a9744b001358dc --- -{{APIRef("WebRTC")}}{{SeeCompatTable}} +{{APIRef("WebRTC")}} -**`RTCSessionDescription`** インターフェイスは、接続 (または接続する予定のもの) の一端と、その構成方法を記述します。それぞれの **`RTCSessionDescription`** は、どのオファー/アンサー交渉プロセスを使用するかを表す記述の {{domxref("RTCSessionDescription.type", "type")}} と、セッションの {{Glossary("SDP")}} 記述子から成ります。 +**`RTCSessionDescription`** インターフェイスは、接続 (または接続する予定のもの) の一端と、その構成方法を記述します。それぞれの `RTCSessionDescription` は、どのオファー/アンサー交渉プロセスを使用するかを表す記述の {{domxref("RTCSessionDescription.type", "type")}} と、セッションの {{Glossary("SDP")}} 記述子から成ります。 -The process of negotiating a connection between two peers involves exchanging `RTCSessionDescription` objects back and forth, with each description suggesting one combination of connection configuration options that the sender of the description supports. Once the two peers agree upon a configuration for the connection, negotiation is complete. +2 つのピア間で接続を交渉するプロセスでは、 `RTCSessionDescription` オブジェクトをやり取りします。それぞれの説明は、説明の送り手が対応している接続構成オプションの組み合わせを提案します。 2 つのピア間で接続の構成が合意されると、交渉は完全に完了します。 ## プロパティ -_`RTCSessionDescription` が継承するプロパティは存在しません。_ +_`RTCSessionDescription` は何もプロパティを継承していません。_ - {{domxref("RTCSessionDescription.type")}} {{ReadOnlyInline}} - - : これは `RTCSdpType` の列挙型であり、ディスクリプションの種類を表します。 - - - + - : 列挙型であり、ディスクリプションの種類を表します。 - {{domxref("RTCSessionDescription.sdp")}} {{ReadOnlyInline}} - - : これは、セッションを説明するための {{Glossary("SDP")}} 形式の {{domxref("DOMString")}} です。 - -## 定数 - -### RTCSdpType - -This enum defines strings that describe the current state of the session description, as used in the {{domxref("RTCSessionDescription.type", "type")}} property. The session description's type will be specified using one of these values. - -| 値 | 説明 | -| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `answer` | The SDP contained in the {{domxref("RTCSessionDescription.sdp", "sdp")}} property is the definitive choice in the exchange. In other words, this session description describes the agreed-upon configuration, and is being sent to finalize negotiation. | -| `offer` | The session description object describes the initial proposal in an offer/answer exchange. The session negotiation process begins with an offer being sent from the caller to the callee. | -| `pranswer` | The session description object describes a provisional answer; that is, it's a response to a previous offer or provisional answer. | -| `rollback` | This special type with an empty session description is used to roll back to the previous stable state. | + - : 文字列で、セッションを説明するための {{Glossary("SDP")}} が入ります。 -## メソッド +## インスタンスメソッド -_`RTCSessionDescription` が継承するメソッドは存在しません。_ +_`RTCSessionDescription` は何もメソッドを継承していません。_ - {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} {{deprecated_inline}} - - : 新しい `RTCSessionDescription` を返します。この引数は `RTCSessionDescriptionInit` ディクショナリであり (任意の) 2 つの引数を含みます。これらの引数の 1 つまたは全て与えられなかった場合、関連するプロパティは null に設定されます。 + - : 新しい `RTCSessionDescription` を返します。この引数は `RTCSessionDescriptionInit` 辞書であり (任意の) 2 つの引数を含みます。 - {{domxref("RTCSessionDescription.toJSON()")}} - - : このオブジェクトの {{Glossary("JSON")}} による表現を生成して返します。生成された JSON は、{{domxref("RTCSessionDescription.type", "type")}} と {{domxref("RTCSessionDescription.sdp", "sdp")}}を含みます。 + - : このオブジェクトの {{Glossary("JSON")}} による表現を生成して返します。生成された JSON は、{{domxref("RTCSessionDescription.type", "type")}} と {{domxref("RTCSessionDescription.sdp", "sdp")}} を含みます。 ## 例 ```js -signalingChannel.onmessage = function (evt) { +signalingChannel.onmessage = (evt) => { if (!pc) start(false); - var message = JSON.parse(evt.data); - if (message.sdp) + const message = JSON.parse(evt.data); + if (message.sdp) { pc.setRemoteDescription( new RTCSessionDescription(message), - function () { + () => { // オファーを受け取った場合、このオファーに対して応答する。 - if (pc.remoteDescription.type == "offer") + if (pc.remoteDescription.type === "offer") { pc.createAnswer(localDescCreated, logError); + } }, logError, ); - else + } else { pc.addIceCandidate( new RTCIceCandidate(message.candidate), - function () {}, + () => {}, logError, ); + } }; ``` -## 仕様策定状況 +## 仕様書 {{Specifications}} -## ブラウザーの対応 +## ブラウザーの互換性 {{Compat}} ## 関連情報 -- [WebRTC](/ja/docs/Web/Guide/API/WebRTC) +- [WebRTC](/ja/docs/Web/API/WebRTC_API) - {{domxref("RTCPeerConnection.setLocalDescription()")}} 及び {{domxref("RTCPeerConnection.setRemoteDescription()")}} diff --git a/files/ja/web/api/shadowroot/innerhtml/index.md b/files/ja/web/api/shadowroot/innerhtml/index.md index 1432b649493d0c..0ed51ecf1427a1 100644 --- a/files/ja/web/api/shadowroot/innerhtml/index.md +++ b/files/ja/web/api/shadowroot/innerhtml/index.md @@ -1,22 +1,18 @@ --- -title: ShadowRoot.innerHTML +title: "ShadowRoot: innerHTML プロパティ" +short-title: innerHTML slug: Web/API/ShadowRoot/innerHTML +l10n: + sourceCommit: f2f9346c0c0e9f6676f2df9f1850933e274401de --- {{APIRef("Shadow DOM")}} **`innerHTML`** は {{domxref("ShadowRoot")}} インターフェイスのプロパティで、 `ShadowRoot` の内部の DOM ツリーに対する参照を設定したり返したりします。 -## 構文 +## 値 -```js -var domString = shadowRoot.innerHTML; -shadowRoot.innerHTML = domString; -``` - -### 値 - -{{domxref("DOMString")}} です。 +文字列です。 ## 例 diff --git a/files/ja/web/api/speechrecognitionalternative/transcript/index.md b/files/ja/web/api/speechrecognitionalternative/transcript/index.md index 7355bf2c22d100..a5838c4e3b5767 100644 --- a/files/ja/web/api/speechrecognitionalternative/transcript/index.md +++ b/files/ja/web/api/speechrecognitionalternative/transcript/index.md @@ -1,80 +1,50 @@ --- -title: SpeechRecognitionAlternative.transcript +title: "SpeechRecognitionAlternative: transcript プロパティ" +short-title: transcript slug: Web/API/SpeechRecognitionAlternative/transcript +l10n: + sourceCommit: f2f9346c0c0e9f6676f2df9f1850933e274401de --- -{{APIRef("Web Speech API")}}{{ SeeCompatTable() }} +{{APIRef("Web Speech API")}} -{{domxref("SpeechRecognitionResult")}} インターフェースの **`transcript`** 読み取り専用プロパティは、認識したワードの記録を含む文字列を返します。 +**`transcript`** は {{domxref("SpeechRecognitionResult")}} インターフェイスの読み取り専用プロパティで、認識した語の記録を含む文字列を返します。 -連続認識において、連続した {{domxref("SpeechRecognitionResult")}} の連結がセッションの適切な記録を生成するように、必要に応じて先頭または末尾の空白が含まれます。 +連続認識において、連続した {{domxref("SpeechRecognitionResult")}} の連結がセッションの適切な記録を生成するように、必要に応じて先頭または末尾にホワイトスペースが含まれます。 -## 構文 +## 値 -``` -var myTranscript = speechRecognitionAlternativeInstance.transcript; -``` - -### 戻り値 - -{{domxref("DOMString")}}。 +文字列です。 ## 例 -このコードは、[Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) から抜き出しています。 +このコードは、 [Speech color changer](https://github.com/mdn/dom-examples/blob/main/web-speech-api/speech-color-changer/script.js) から抜き出しています。 ```js -recognition.onresult = function (event) { +recognition.onresult = (event) => { // The SpeechRecognitionEvent results property returns a SpeechRecognitionResultList object // The SpeechRecognitionResultList object contains SpeechRecognitionResult objects. // It has a getter so it can be accessed like an array // The first [0] returns the SpeechRecognitionResult at position 0. - // Each SpeechRecognitionResult object contains SpeechRecognitionAlternative objects that contain individual results. + // Each SpeechRecognitionResult object contains SpeechRecognitionAlternative objects + // that contain individual results. // These also have getters so they can be accessed like arrays. // The second [0] returns the SpeechRecognitionAlternative at position 0. // We then return the transcript property of the SpeechRecognitionAlternative object - var color = event.results[0][0].transcript; - diagnostic.textContent = "Result received: " + color + "."; + const color = event.results[0][0].transcript; + diagnostic.textContent = `Result received: ${color}.`; bg.style.backgroundColor = color; }; ``` -## 仕様 +## 仕様書 {{Specifications}} -## ブラウザー実装状況 +## ブラウザーの互換性 {{Compat}} -- \[1] Chrome では、SpeechRecognitionare インターフェースにプレフィックスが必要です。そのため、インターフェース名に `webkitSpeechRecognition` のようなプレフィックスが必要です; また、認識を動作させるには、Web サーバ上から提供する必要があります。 -- \[2] - - about:config - - の `media.webspeech.recognition.enable` フラグで有効にできますが、現在の音声認識はデスクトップ版の Firefox では機能しません - 必要な内部権限が整理されればすぐに適切に公開されます。 - -### Firefox OS 許可 - -アプリで音声認識を使用するには、[manifest](/ja/docs/Web/Apps/Build/Manifest) で次の許可が必要です: - -```json -"permissions": { - "audio-capture" : { - "description" : "Audio capture" - }, - "speech-recognition" : { - "description" : "Speech recognition" - } -} -``` - -特権アプリも必要なため、次のものも含める必要があります。 - -```json - "type": "privileged" -``` - -## 関連項目 +## 関連情報 -- [Web Speech API](/ja/docs/Web/API/Web_Speech_API) +- [ウェブ音声 API](/ja/docs/Web/API/Web_Speech_API) diff --git a/files/ja/web/api/web_audio_api/web_audio_spatialization_basics/index.md b/files/ja/web/api/web_audio_api/web_audio_spatialization_basics/index.md new file mode 100644 index 00000000000000..1a733dbe00a356 --- /dev/null +++ b/files/ja/web/api/web_audio_api/web_audio_spatialization_basics/index.md @@ -0,0 +1,552 @@ +--- +title: ウェブオーディオの空間化の基本 +slug: Web/API/Web_Audio_API/Web_audio_spatialization_basics +l10n: + sourceCommit: 10b342385644e822d123694ad3bc8c2ca9abb2dc +--- + +{{DefaultAPISidebar("Web Audio API")}} + +ウェブオーディオ API には、豊富なサウンド処理（他にも）オプションがありますが、例えば、 3D ゲーム内で音源の周りを移動する際のパンニングのように、リスナーが音源の周りを移動する際の音の違いをエミュレートする機能も含まれています。 +これを公式には**空間化**と呼び、この記事ではそのようなシステムの実装方法の基本に応じた説明をします。 + +## 空間化の基本 + +ウェブオーディオでは、複雑な 3D 空間化は {{domxref("PannerNode")}} を使って作成されます。平たく言えば、音声を 3D 空間に現れるようにするための、たくさんのクールな数学です。 +音はあなたの上を飛んだり、あなたの後ろに忍び寄ったり、あなたの前を移動したりします。 +そういうことです。 + +WebXR やゲームには実に有益です。 +3D 空間では、リアルな音声を実現する唯一の方法です。 [three.js](https://threejs.org/) や [A-frame](https://aframe.io/) のようなライブラリーは、音を扱うときにその可能性を利用します。 +完全な 3D 空間内で音を移動させる必要はなく、 2D 平面だけに限定することもできるので、もし 2D ゲームを計画していたとしても、このノードは探していたノードになるでしょう。 + +> **メモ:** 単純な左右のステレオパンニング効果を作成する、一般的な用途に対処するために設計された {{domxref("StereoPannerNode")}} もあります。 +> これは使用するのがはるかに簡単ですが、明らかに汎用性には遠く及びません。 +> 単純なステレオパンニング効果が欲しいだけなら、 [StereoPannerNode の例](https://mdn.github.io/webaudio-examples/stereo-panner-node/) （[ソースコードを参照](https://github.com/mdn/webaudio-examples/tree/main/stereo-panner-node)）で必要なものはすべて得られるでしょう。 + +## 3D のラジカセのデモ + +3D 空間化のデモを行うために、基本的な[ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API)ガイドで作成したラジカセデモを変更したものを作成しました。 +[3D 空間化デモライブ版](https://mdn.github.io/webaudio-examples/spatialization/)をご覧ください（[ソースコード](https://github.com/mdn/webaudio-examples/tree/main/spatialization)もご覧ください）。 + +![回転するラジカセと、それを左右や内外に移動させたり回転させたりするコントローラーを備えた単純な UI。](web-audio-spatialization.png) + +このデモでは、指定されたコントローラーでラジカセを移動したり回転させたりすることができます。 +ラジカセを移動させると、それに応じて音が変化し、部屋の左右に移されるとパンしたり、ユーザーから遠ざかると小さくなったり、スピーカーがユーザーから離れるように回転したりします。 +これは `PannerNode` オブジェクトインスタンスの様々なプロパティをその動きに関連して設定することで、空間化をエミュレートしています。 + +> **メモ:** ヘッドフォンを使用するか、コンピューターに接続するサラウンドサウンドシステムがあれば、はるかに良い経験ができます。 + +## 音声リスナーの作成 + +それでは始めましょう！ {{domxref("BaseAudioContext")}}（{{domxref("AudioContext")}} が拡張されたインターフェイス）は [`listener`](/ja/docs/Web/API/BaseAudioContext/listener) プロパティを持っており、これが {{domxref("AudioListener")}} オブジェクトを返します。 +これはシーンのリスナー（通常はユーザー）を表します。 +空間のどこにいて、どの方向を向いているかを定義します。 +それらは静的なままです。 `pannerNode` はリスナーの位置との相対的な音の位置を計算することができます。 + +コンテキストとリスナーを作成し、リスナーの位置を、部屋を覗き込んでいる人を想定して設定しましょう。 + +```js +const AudioContext = window.AudioContext || window.webkitAudioContext; +const audioCtx = new AudioContext(); +const listener = audioCtx.listener; + +const posX = window.innerWidth / 2; +const posY = window.innerHeight / 2; +const posZ = 300; + +listener.positionX.value = posX; +listener.positionY.value = posY; +listener.positionZ.value = posZ - 5; +``` + +`positionX` を使用してリスナーを左右に、 `positionY` を使用して上下に、 `positionZ` を使用して部屋の内外に移動させることができます。ここでは、ビューポートの中央、ラジカセの少し前にリスナーを設定しています。また、リスナーが向いている方向を設定することもできます。これが既定値ですが、うまく動作します。 + +```js +listener.forwardX.value = 0; +listener.forwardY.value = 0; +listener.forwardZ.value = -1; +listener.upX.value = 0; +listener.upY.value = 1; +listener.upZ.value = 0; +``` + +forward プロパティは、リスナーの前方（例えば、彼らが向いている方向）の 3D 座標位置を表し、 up プロパティは、リスナーの頭のてっぺんの 3D 座標位置を表します。 +この 2 つを組み合わせることで、うまく方向を設定することができます。 + +## パナーノードの作成 + +{{domxref("PannerNode")}} を作成しましょう。これにはたくさんのプロパティがあります。それぞれを見ていきましょう。 + +始めに、 [`panningModel`](/ja/docs/Web/API/PannerNode/panningModel) を設定します。 +これは 3D 空間で音声を位置指定するために使用する空間指定アルゴリズムです。これを設定するには次のようにします。 + +`equalpower` — 既定で一般的なパンニングの方法 + +`HRTF` — これは 'Head-related transfer function' の略で、音の位置を把握する際に人間の頭を考慮しているようです。 + +なかなか賢い。 `HRTF` モデルを使用してみましょう。 + +```js +const panningModel = "HRTF"; +``` + +[`coneInnerAngle`](/ja/docs/Web/API/PannerNode/coneInnerAngle) と [`coneOuterAngle`](/ja/docs/Web/API/PannerNode/coneOuterAngle) プロパティを指定します。 +既定ではどちらも 360 度です。 +私たちのラジカセのスピーカーは、より小さな円錐を持つことになり、それを定義することができます。 +内側のコーンはゲイン（音量）が常に最大でエミュレートされる場所で、外側のコーンはゲイン（音量）が下がり始める場所です。 +ゲインは [`coneOuterGain`](/ja/docs/Web/API/PannerNode/coneOuterGain) の値で縮小します。 +後でこれらの引数に使用する値を格納する定数を作成しましょう。 + +```js +const innerCone = 60; +const outerCone = 90; +const outerGain = 0.3; +``` + +次の引数は [`distanceModel`](/ja/docs/Web/API/PannerNode/distanceModel) - これは `linear`、`inverse`、`exponential` のいずれかにのみ設定することができます。これらは異なるアルゴリズムで、音声ソースがリスナーから遠ざかるにつれて音量を縮小するために使用します。単純なので `linear` を使用します。 + +```js +const distanceModel = "linear"; +``` + +ソースとリスナーの間に最大距離 ([`maxDistance`](/ja/docs/Web/API/PannerNode/maxDistance)) を設定することができます。ソースがこの点からさらに移動されても音量は縮小しません。 +これは有益なことができます。距離をエミュレートしたいが、音量が落ちてしまうことがあり、それは実際には望むことではないからです。 +既定では 10,000 （単位なしの相対値）です。このままでも構いません。 + +```js +const maxDistance = 10000; +``` + +参照距離 ([`refDistance`](/ja/docs/Web/API/PannerNode/refDistance)) もあり、これは距離モデルで使用します。 +これも既定値 `1` のままでよいでしょう。 + +```js +const refDistance = 1; +``` + +次にロールオフ係数　([`rolloffFactor`](/ja/docs/Web/API/PannerNode/rolloffFactor))　があります。パナーがリスナーから離れるにつれて音量がどのくらいすばやく縮小するかです。 +既定値は 1 です。動きを誇張するために、もう少し大きくしてみましょう。 + +```js +const rollOff = 10; +``` + +これで、ラジカセの位置と方向を設定し始めることができます。 +これは、リスナーで行った方法とよく似ています。 +これらはインターフェイスのコントロールを使用するときに変更する引数でもあります。 + +```js +const positionX = posX; +const positionY = posY; +const positionZ = posZ; + +const orientationX = 0.0; +const orientationY = 0.0; +const orientationZ = -1.0; +``` + +Z 方向がマイナス値であることに注意してください。これでラジカセがこちらを向くように設定します。 +正の値を設定すると、音はこちら側を向いて設定されます。 + +パナーノードを作成するために、関連するコンストラクターを使用し、上で設定した引数をすべて渡してみましょう。 + +```js +const panner = new PannerNode(audioCtx, { + panningModel, + distanceModel, + positionX, + positionY, + positionZ, + orientationX, + orientationY, + orientationZ, + refDistance, + maxDistance, + rolloffFactor: rollOff, + coneInnerAngle: innerCone, + coneOuterAngle: outerCone, + coneOuterGain: outerGain, +}); +``` + +## ラジカセの移動 + +これで、ラジカセを「部屋」の中で移動させることができます。そのために一連のコントロールを設定しました。 +左右、上下、前後に移動させたり、回転させたりすることができます。 +音の方向は正面のラジカセのスピーカーから決まりますので、ラジカセを回転させると、音の方向を変えることができます。 + +インターフェイスのためにいくつかのことを設定する必要があります。 +最初に、移動させたい要素の参照を取得し、次に実際に移動させるために [CSS 座標変換](/ja/docs/Web/CSS/CSS_transforms)を設定するときに変更する値の参照を格納します。 +最後に、ラジカセがどの方向にも移動しすぎないように、境界を設定します。 + +```js +const moveControls = document + .querySelector("#move-controls") + .querySelectorAll("button"); +const boombox = document.querySelector(".boombox-body"); + +// CSS 座標変換の値 +const transform = { + xAxis: 0, + yAxis: 0, + zAxis: 0.8, + rotateX: 0, + rotateY: 0, +}; + +// 境界を設定 +const topBound = -posY; +const bottomBound = posY; +const rightBound = posX; +const leftBound = -posX; +const innerBound = 0.1; +const outerBound = 1.5; +``` + +移動したい方向を引数として受け取り、 CSS 座標変換を変更し、パナーノードプロパティの位置と方向の値を更新し、音を適切に変更する関数を作成してみましょう。 + +始めるには、左、右、上、下の値を見てみましょう。 +これらの軸に沿ってラジカセを移動させ、適切な位置を更新します。 + +```js +function moveBoombox(direction) { + switch (direction) { + case "left": + if (transform.xAxis > leftBound) { + transform.xAxis -= 5; + panner.positionX.value -= 0.1; + } + break; + case "up": + if (transform.yAxis > topBound) { + transform.yAxis -= 5; + panner.positionY.value -= 0.3; + } + break; + case "right": + if (transform.xAxis < rightBound) { + transform.xAxis += 5; + panner.positionX.value += 0.1; + } + break; + case "down": + if (transform.yAxis < bottomBound) { + transform.yAxis += 5; + panner.positionY.value += 0.3; + } + break; + } +} +``` + +移動される値も同じようなものです。 + +```js +case 'back': + if (transform.zAxis > innerBound) { + transform.zAxis -= 0.01; + panner.positionZ.value += 40; + } + break; +case 'forward': + if (transform.zAxis < outerBound) { + transform.zAxis += 0.01; + panner.positionZ.value -= 40; + } + break; +``` + +しかし、回転値は、音を「回転」移動させる必要があるため、少し複雑です。 +2　つの軸の値を更新する必要があるだけでなく（例えば、オブジェクトを x 軸の周りに回転させる場合、そのオブジェクトの y 座標と z 座標を更新します）、このためにさらにいくつかの計算をする必要があります。 +回転は円であり、その円を描画するために [`Math.sin`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/sin) と [`Math.cos`](/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/cos) が必要です。 + +回転率を設定しましょう。これは後で `Math.sin` と `Math.cos` で使用するラジアン範囲の値に変換して、ラジカセを回転させるときの新しい座標を求めるときに使用します。 + +```js +// 回転定数の設定 +const rotationRate = 60; // 数字が大きいほど音の回転が遅い + +const q = Math.PI / rotationRate; // 回転の増加（ラジアン単位） +``` + +これを使用して回転度を計算することもできます。これは CSS 座標変換を作成する際に役立ちます（CSS 座標変換には x 軸と y 軸の両方が必要であることに注意してください）。 + +```js +// CSS の角度を取得 +const degreesX = (q * 180) / Math.PI; +const degreesY = (q * 180) / Math.PI; +``` + +例えば、左回転を見てみましょう。左回転のために、パンナーの座標の x 方向と z 方向を変えて、 y 軸の周りを移動する必要があります。 + +```js +case 'rotate-left': + transform.rotateY -= degreesY; + + // 'left' は y 軸を中心とした回転で、負の角度を加える + z = panner.orientationZ.value*Math.cos(q) - panner.orientationX.value*Math.sin(q); + x = panner.orientationZ.value*Math.sin(q) + panner.orientationX.value*Math.cos(q); + y = panner.orientationY.value; + + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +``` + +これは少しわかりにくいですが、 sin と cos を使用して、ラジカセの回転に必要な座標の円運動を作業しているのです。 + +これはすべての軸に対してできます。更新する正しい位置指定と、正の値か負の値かを選ぶだけです。 + +```js +case 'rotate-right': + transform.rotateY += degreesY; + // 'right' は y 軸を中心とした回転で、正の角度を加える + z = panner.orientationZ.value*Math.cos(-q) - panner.orientationX.value*Math.sin(-q); + x = panner.orientationZ.value*Math.sin(-q) + panner.orientationX.value*Math.cos(-q); + y = panner.orientationY.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +case 'rotate-up': + transform.rotateX += degreesX; + // 'up' は x 軸を中心とした回転で、負の角度を加える + z = panner.orientationZ.value*Math.cos(-q) - panner.orientationY.value*Math.sin(-q); + y = panner.orientationZ.value*Math.sin(-q) + panner.orientationY.value*Math.cos(-q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +case 'rotate-down': + transform.rotateX -= degreesX; + // 'down' は x 軸を中心とした回転で、正の角度を加える + z = panner.orientationZ.value*Math.cos(q) - panner.orientationY.value*Math.sin(q); + y = panner.orientationZ.value*Math.sin(q) + panner.orientationY.value*Math.cos(q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; +``` + +最後にもうひとつ、 CSS を更新し、マウスイベント用に最後に移動されたときの参照を保持する必要があります。 +これが最後の `moveBoombox` 関数です。 + +```js +function moveBoombox(direction, prevMove) { + switch (direction) { + case "left": + if (transform.xAxis > leftBound) { + transform.xAxis -= 5; + panner.positionX.value -= 0.1; + } + break; + case "up": + if (transform.yAxis > topBound) { + transform.yAxis -= 5; + panner.positionY.value -= 0.3; + } + break; + case "right": + if (transform.xAxis < rightBound) { + transform.xAxis += 5; + panner.positionX.value += 0.1; + } + break; + case "down": + if (transform.yAxis < bottomBound) { + transform.yAxis += 5; + panner.positionY.value += 0.3; + } + break; + case "back": + if (transform.zAxis > innerBound) { + transform.zAxis -= 0.01; + panner.positionZ.value += 40; + } + break; + case "forward": + if (transform.zAxis < outerBound) { + transform.zAxis += 0.01; + panner.positionZ.value -= 40; + } + break; + case "rotate-left": + transform.rotateY -= degreesY; + + // 'left' は y 軸を中心とした回転で、負の角度を加える + z = + panner.orientationZ.value * Math.cos(q) - + panner.orientationX.value * Math.sin(q); + x = + panner.orientationZ.value * Math.sin(q) + + panner.orientationX.value * Math.cos(q); + y = panner.orientationY.value; + + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + case "rotate-right": + transform.rotateY += degreesY; + // 'right' は y 軸を中心とした回転で、正の角度を加える + z = + panner.orientationZ.value * Math.cos(-q) - + panner.orientationX.value * Math.sin(-q); + x = + panner.orientationZ.value * Math.sin(-q) + + panner.orientationX.value * Math.cos(-q); + y = panner.orientationY.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + case "rotate-up": + transform.rotateX += degreesX; + // 'up' は x 軸を中心とした回転で、負の角度を加える + z = + panner.orientationZ.value * Math.cos(-q) - + panner.orientationY.value * Math.sin(-q); + y = + panner.orientationZ.value * Math.sin(-q) + + panner.orientationY.value * Math.cos(-q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + case "rotate-down": + transform.rotateX -= degreesX; + // 'down' は x 軸を中心とした回転で、正の角度を加える + z = + panner.orientationZ.value * Math.cos(q) - + panner.orientationY.value * Math.sin(q); + y = + panner.orientationZ.value * Math.sin(q) + + panner.orientationY.value * Math.cos(q); + x = panner.orientationX.value; + panner.orientationX.value = x; + panner.orientationY.value = y; + panner.orientationZ.value = z; + break; + } + + boombox.style.transform = + `translateX(${transform.xAxis}px) ` + + `translateY(${transform.yAxis}px) ` + + `scale(${transform.zAxis}) ` + + `rotateY(${transform.rotateY}deg) ` + + `rotateX(${transform.rotateX}deg)`; + + const move = prevMove || {}; + move.frameId = requestAnimationFrame(() => moveBoombox(direction, move)); + return move; +} +``` + +## コントロールを接続 + +制御するボタンの接続は比較的単純です。これで、コントロールのマウスイベントを待ち受けてこの関数を実行し、マウスを離したときにこの関数を停止させることができます。 + +```js +// 各コントロールについて、ラジカセを移動させ、位置値を変更します。 +moveControls.forEach((el) => { + let moving; + el.addEventListener( + "mousedown", + () => { + const direction = this.dataset.control; + if (moving && moving.frameId) { + cancelAnimationFrame(moving.frameId); + } + moving = moveBoombox(direction); + }, + false, + ); + + window.addEventListener( + "mouseup", + () => { + if (moving && moving.frameId) { + cancelAnimationFrame(moving.frameId); + } + }, + false, + ); +}); +``` + +## グラフを接続 + +HTML には、パンナーノードを影響させたい audio 要素を格納します。 + +```html + +``` + +その要素からソースを取得し、 {{domxref('AudioContext.createMediaElementSource')}} を使用してウェブオーディオ API にパイプする必要があります。 + +```js +// audio 要素を取得 +const audioElement = document.querySelector("audio"); + +// 音声コンテキストに渡す +const track = audioContext.createMediaElementSource(audioElement); +``` + +次に、音声グラフを接続させなければなりません。入力（トラック）、変更ノード（パンナー）、出力先（この場合はスピーカー）を接続します。 + +```js +track.connect(panner).connect(audioCtx.destination); +``` + +現在の状態に応じて、クリックすると音声を再生または一時停止する再生ボタンを作成しましょう。 + +```html + +``` + +```js +// 再生ボタンを選択 +const playButton = document.querySelector("button"); + +playButton.addEventListener( + "click", + () => { + // コンテキストが停止状態（autoplay ポリシーによる）かどうかをチェック + if (audioContext.state === "suspended") { + audioContext.resume(); + } + + // 状態によってトラックを再生または停止させる + if (playButton.dataset.playing === "false") { + audioElement.play(); + playButton.dataset.playing = "true"; + } else if (playButton.dataset.playing === "true") { + audioElement.pause(); + playButton.dataset.playing = "false"; + } + }, + false, +); +``` + +音声や音声グラフの再生・制御についてより詳しく見ていくには、[ウェブオーディオ API の使用](/ja/docs/Web/API/Web_Audio_API/Using_Web_Audio_API)をご覧ください。 + +## まとめ + +この記事で、ウェブオーディオの空間設定がどのように動作するのか、また {{domxref("PannerNode")}} プロパティがそれぞれ何をするのか（かなりいくつかあります）について、ご理解いただけたかと思います。 +値の操作が難しい場合もあり、使用する用途によっては正しい値を取得するのに時間がかかることもあります。 + +> **メモ:** さまざまなブラウザー間で、音声の空間化には若干の違いがあります。 +> パナーノードは、ボンネットの中でとても複雑な計算をします。 +> ここには[たくさんのテスト](https://wpt.fyi/results/webaudio/the-audio-api/the-pannernode-interface?label=stable&aligned=true)があるので、異なるプラットフォーム間でこのノードの内部動作の状態を追跡することができます。 + +また、[最終的なデモはここで確認](https://mdn.github.io/webaudio-examples/spatialization/)でき、[最終的なソースコードはここ](https://github.com/mdn/webaudio-examples/tree/main/spatialization)で確認できます。 +[Codepen のデモ](https://codepen.io/Rumyra/pen/MqayoK?editors=0100)もあります。 + +もしあなたが 3D ゲームや WebXR で作業しているのであれば、このような機能を作成するために 3D ライブラリーを利用するのはよい考えです。 +私たちは、これがどのように動作するのかの考え方を提供するために、この記事で自分自身で展開しましたが、他の人が先に行った成果を利用することで多くの時間を節約することができます。 diff --git a/files/ja/web/api/webrtc_api/index.md b/files/ja/web/api/webrtc_api/index.md index 092e0c9a58f673..1ba4ed1e75ec7b 100644 --- a/files/ja/web/api/webrtc_api/index.md +++ b/files/ja/web/api/webrtc_api/index.md @@ -1,6 +1,8 @@ --- title: WebRTC API slug: Web/API/WebRTC_API +l10n: + sourceCommit: 904cdf09c7e328b7a15a6a4db6bc6bd31f969cce --- {{DefaultAPISidebar("WebRTC")}} @@ -9,17 +11,9 @@ slug: Web/API/WebRTC_API WebRTC は、相互に関連したいくつかの API とプロトコルで構成されており、これらが連携してこれを実現しています。ここで紹介するドキュメントでは、WebRTC の基礎知識、データ接続とメディア接続、両方の設定方法と、使用方法などを理解するのに役立ちます。 -## 相互運用性 - -WebRTC の実装はまだ進化しており、ブラウザーごとに[コーデック](/ja/docs/Web/Media/Formats/WebRTC_codecs)や WebRTC 機能の対応レベルが異なるため、コードを書き始める前に Google が提供する [Adapter.js ライブラリー](https://github.com/webrtcHacks/adapter) を利用することを強く検討する必要があります。 - -Adapter.js はシムやポリフィルを使用して、サポートしている環境によって異なる WebRTC 実装の違いを滑らかにします。また、接頭辞やその他の名前の違いも Adapter.js が処理することで、WebRTC の開発プロセス全体がより簡単になり、より広範な互換性のある結果が得られるようになります。このライブラリーは [NPM パッケージ](https://www.npmjs.com/package/webrtc-adapter)としても提供されています。 - -Adapter.js の詳細については、[WebRTC adapter.js を使用した互換性の向上](/ja/docs/Web/API/WebRTC_API/adapter.js)を参照してください。 - ## WebRTC の概念と使い方 -WebRTC は複数の目的に対応しています。[メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Streams_API) と一緒に使用することで、音声・ビデオ会議、ファイル交換、画面共有、ID 管理、{{Glossary("DTMF")}} (タッチトーンダイヤル信号) の送信サポートを含む旧来の電話システムとのインターフェイスなど、強力なマルチメディア機能をウェブに提供します。ピアー間の接続は、特別なドライバーやプラグインを必要とせずに行うことができ、多くの場合、中間サーバーを介さずに行うことができます。 +WebRTC は複数の目的に対応しています。[メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Capture_and_Streams_API) と一緒に使用することで、音声・ビデオ会議、ファイル交換、画面共有、ID 管理、{{Glossary("DTMF")}} (タッチトーンダイヤル信号) の送信サポートを含む旧来の電話システムとのインターフェイスなど、強力なマルチメディア機能をウェブに提供します。ピアー間の接続は、特別なドライバーやプラグインを必要とせずに行うことができ、多くの場合、中間サーバーを介さずに行うことができます。 2 つのピアー間の接続は {{DOMxRef("RTCPeerConnection")}} インターフェイスで表現されます。接続が確立され、`RTCPeerConnection` を使用して開かれると、メディアストリーム ({{DOMxRef("MediaStream")}}) やデータチャンネル ({{DOMxRef("RTCDataChannel")}}) を接続に追加することができます。 @@ -27,7 +21,9 @@ WebRTC は複数の目的に対応しています。[メディアキャプチャ また、2 つのピアー間の接続を使用して、{{DOMxRef("RTCDataChannel")}} インターフェイスを使用して任意のバイナリーデータを交換することもできます。これは、バックチャンネル情報、メタデータ交換、ゲームステータスパケット、ファイル転送、あるいはデータ転送のためのプライマリーチャンネルとして使用することができます。 -**_より多くの詳細と関連するガイドやチュートリアルへのリンクが必要ですね…。_** +### 相互運用性 + +WebRTC は現行のブラウザーでは概ね対応していますが、一部非互換性も残っています。 [adapter.js](https://github.com/webrtcHacks/adapter) ライブラリーは、これらの非互換性からアプリを保護するための補助的なものです。 ## WebRTC リファレンス @@ -48,7 +44,7 @@ WebRTC は、様々なタスクを達成するために連携して動作する - {{DOMxRef("RTCSessionDescription")}} - : セッションの引数を表します。各 `RTCSessionDescription` は、オファー/アンサーネゴシエーションプロセスの、どの部分を記述するかを示す記述型 ({{DOMxRef("RTCSessionDescription.type", "type")}}) と、セッションの {{Glossary("SDP")}} 記述子で構成されます。 - {{DOMxRef("RTCStatsReport")}} - - : 接続または接続上の個々のトラックの統計情報の詳細を提供します。{{DOMxRef("RTCPeerConnection.getStats()")}} を呼び出すと報告を取得できます。 WebRTC 統計情報の使用に関する詳細は、 [WebRTC 統計 API](/ja/docs/Web/API/WebRTC_Statistics_API) を参照してください。 + - : 接続または接続上の個々のトラックの統計情報の詳細を提供します。{{DOMxRef("RTCPeerConnection.getStats()")}} を呼び出すと報告を取得できます。 - {{DOMxRef("RTCIceCandidate")}} - : {{DOMxRef("RTCPeerConnection")}} を確立するための {{Glossary("ICE")}}(インタラクティブ接続確立) サーバーの候補を表します。 - {{DOMxRef("RTCIceTransport")}} @@ -64,13 +60,6 @@ WebRTC は、様々なタスクを達成するために連携して動作する - {{DOMxRef("RTCSctpTransport")}} - : Stream Control Transmission Protocol (**{{Glossary("SCTP")}}**) トランスポートを説明する情報を提供し、 {{DOMxRef("RTCPeerConnection")}} のすべての[`RTCPeerConnection`](/ja/docs/Web/API/RTCPeerConnection) のデータチャネルの SCTP パケットが送受信される Datagram Transport Layer Security (**{{Glossary("DTLS")}}**) トランスポートにアクセスする方法も提供します。 -#### 辞書 - -- {{DOMxRef("RTCIceServer")}} - - : ({{Glossary("STUN")}} や {{Glossary("TURN")}} サーバーのような) 単一の {{Glossary("ICE")}} サーバーを定義します。 -- {{DOMxRef("RTCRtpContributingSource")}} - - : ソース貢献されているパケットが再生された直近の時刻を含む、特定の貢献ソース (contributing source; CSRC) に関する情報が含まれています。 - #### イベント - {{domxref("RTCDataChannel.bufferedamountlow_event", "bufferedamountlow")}} @@ -115,6 +104,8 @@ WebRTC は、様々なタスクを達成するために連携して動作する - : `RTCIceTransport` の状態が変化した。 - {{domxref("RTCSctpTransport.statechange_event", "statechange")}} - : `RTCSctpTransport` の状態が変化した。 +- {{DOMxRef("DedicatedWorkerGlobalScope.rtctransform_event", "rtctransform")}} + - : エンコードされた動画や音声のフレームは、ワーカーで変換ストリームを使用して処理する準備ができています。 #### 型 @@ -136,7 +127,7 @@ WebRTC は、様々なタスクを達成するために連携して動作する ### 電話回線 -これらのインターフェイスとイベントは、公衆交換電話網 (PTSN) との相互作用に関連するものです。これらは主に、トーンダイヤルの音、またはその音を表すパケットをネットワーク経由でリモートピアーに送信するために使用されます。 +これらのインターフェイスとイベントは、公衆交換電話網 (PSTN) との相互作用に関連するものです。これらは主に、トーンダイヤルの音、またはその音を表すパケットをネットワーク経由でリモートピアーに送信するために使用されます。 #### インターフェイス @@ -150,6 +141,33 @@ WebRTC は、様々なタスクを達成するために連携して動作する - {{domxref("RTCDTMFSender.tonechange_event", "tonechange")}} - : 新しい {{Glossary("DTMF")}} トーンが接続上で再生され始めたか、 `RTCDTMFSender` の {{domxref("RTCDTMFSender.toneBuffer", "toneBuffer")}} にある最後のトーンが送信されてバッファが空になったか、どちらかです。このイベントの型は {{domxref("RTCDTMFToneChangeEvent")}} です。 +### エンコードされた変換 + +これらのインターフェイスとイベントは、ワーカーで実行する変換ストリームを使用して、入出力されるエンコード方式の動画と音声フレームを処理するために使用します。 + +#### インターフェイス + +- {{DOMxRef("RTCRtpScriptTransform")}} + - : ワーカーで実行する変換ストリームを RTC パイプラインに挿入するインターフェイスです。 +- {{DOMxRef("RTCRtpScriptTransformer")}} + - : メインスレッドからオプションを渡す `RTCRtpScriptTransform` に対応するワーカーサイドのもので、 {{DOMxRef("TransformStream")}} を通してエンコードされたフレームをパイプするために使用することができる読み取り可能なストリームと書き込み可能なストリームも一緒に渡します。 +- {{DOMxRef("RTCEncodedVideoFrame")}} + - : RTC パイプラインで変換されるエンコードされた動画フレームを表します。 +- {{DOMxRef("RTCEncodedAudioFrame")}} + - : RTC パイプラインで変換されるエンコードされた音声フレームを表します。 + +#### プロパティ + +- {{DOMxRef("RTCRtpReceiver.transform")}} + - : エンコードされた映像および音声フレームが受信パイプラインに変換ストリームを挿入するために使用するプロパティです。 +- {{DOMxRef("RTCRtpSender.transform")}} + - : エンコードされた映像および音声フレームの送信パイプラインに変換ストリームを挿入するために使用するプロパティです。 + +#### イベント + +- {{DOMxRef("DedicatedWorkerGlobalScope.rtctransform_event", "rtctransform")}} + - : RTC 変換がワーカーで実行する準備ができているか、エンコードされた動画や音声フレームを処理する準備ができています。 + ## ガイド - [WebRTC プロトコル入門](/ja/docs/Web/API/WebRTC_API/Protocols) @@ -168,15 +186,17 @@ WebRTC は、様々なタスクを達成するために連携して動作する - : このガイドでは、ピアー接続と関連する {{DOMxRef("RTCDataChannel")}} を使用して、2 つのピアー間で任意のデータを交換する方法について説明します。 - [WebRTC での DTMF の使用](/ja/docs/Web/API/WebRTC_API/Using_DTMF) - : {{DOMxRef("RTCDTMFSender")}} インターフェイスを用いた DTMF トーン送信サポートを含む、旧式の電話システムとのゲートウェイとやりとりを行うための WebRTC 対応について、このガイドでは、その方法を説明します。 +- [WebRTC エンコード変換](/ja/docs/Web/API/WebRTC_API/Using_Encoded_Transforms) + - : このガイドでは、ワーカーで実行する {{DOMxRef("TransformStream")}} を使用して、ウェブアプリケーションが入出力する WebRTCのエンコードされた映像および音声フレームを変更する方法を示します。 ## チュートリアル -- [Improving compatibility using WebRTC adapter.js](/ja/docs/Web/API/WebRTC_API/adapter.js) - - : WebRTC 組織は、異なるブラウザーの WebRTC 実装における互換性の問題を回避するため [adapter.js](https://github.com/webrtc/adapter/) を提供しています。このアダプタは JavaScript のはシム ({{Glossary("Shim")}}) で、あなたのコードを仕様に合わせて記述することで、WebRTC をサポートしているすべてのブラウザーで「ただ動く (just work) 」ようにしてくれます。 -- [WebRTC で静止画を撮る](/ja/docs/Web/API/WebRTC_API/Taking_still_photos) - - : この記事では、WebRTC に対応したパソコンや携帯電話でWebRTCを使ってカメラにアクセスして写真を撮る方法を紹介しています。 +- [WebRTC adapter.js を使用した互換性の向上](#相互運用性) + - : WebRTC 組織は、異なるブラウザーの WebRTC 実装における互換性の問題を回避するため [adapter.js](https://github.com/webrtc/adapter/) を提供しています。このアダプターは JavaScript のはシム ({{Glossary("Shim")}}) で、あなたのコードを仕様に合わせて記述することで、WebRTC に対応しているすべてのブラウザーで「ただ動く (just work) 」ようにしてくれます。 - [シンプルな RTCDataChannel のサンプル](/ja/docs/Web/API/WebRTC_API/Simple_RTCDataChannel_sample) - : {{DOMxRef("RTCDataChannel")}} インターフェイスは、2つのピアー間で任意のデータを送受信するためのチャネルを開くことができる機能です。このAPIは意図的に [WebSocket API](/ja/docs/Web/API/WebSocket_API) に似せているので、それぞれに同じプログラミングモデルを使用することができます。 +- [Peer.js によるインターネット接続電話の構築](/ja/docs/Web/API/WebRTC_API/Build_a_phone_with_peerjs) + - : このチュートリアルは、 Peer.js を使用して電話を構築する方法を段階を追ってガイドします。 ## 仕様書 @@ -208,9 +228,8 @@ WebRTC は、様々なタスクを達成するために連携して動作する - {{DOMxRef("MediaStreamTrack")}} - {{DOMxRef("MessageEvent")}} - {{DOMxRef("MediaStream")}} -- [メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Streams_API) +- [メディアキャプチャとストリーム API](/ja/docs/Web/API/Media_Capture_and_Streams_API) - [Firefox multistream and renegotiation for Jitsi Videobridge](https://hacks.mozilla.org/2015/06/firefox-multistream-and-renegotiation-for-jitsi-videobridge/) - [Peering Through the WebRTC Fog with SocketPeer](https://hacks.mozilla.org/2015/04/peering-through-the-webrtc-fog-with-socketpeer/) - [Inside the Party Bus: Building a Web App with Multiple Live Video Streams + Interactive Graphics](https://hacks.mozilla.org/2014/04/inside-the-party-bus-building-a-web-app-with-multiple-live-video-streams-interactive-graphics/) - [ウェブメディア技術](/ja/docs/Web/Media) -- [WebRTC 統計 API](/ja/docs/Web/API/WebRTC_Statistics_API) diff --git a/files/ja/web/api/window/localstorage/index.md b/files/ja/web/api/window/localstorage/index.md index f1c9627872d1a3..37ca39a886e3b6 100644 --- a/files/ja/web/api/window/localstorage/index.md +++ b/files/ja/web/api/window/localstorage/index.md @@ -10,7 +10,7 @@ l10n: **`localStorage`** は {{domxref("window")}} プロパティの読み取り専用プロパティで、この {{DOMxRef("Document")}} の {{glossary("origin")}} における {{DOMxRef("Storage")}} オブジェクトにアクセスできます。格納されたデータは、ブラウザーのセッションを跨いで保存されます。 -`localStorage` は {{DOMxRef("Window.sessionStorage", "sessionStorage")}} によく似ていまが、 `localStorage` のデータには期限がないのに対し、 `sessionStorage` のデータはページセッションが終了したとき、すなわちページが閉じられたときにクリアされます。（「プライベートブラウジング」や「プライバシーモード」のセッションに読み込まれた文書の `localStorage` のデータは、最後の「プライベート」タブが閉じられたときにクリアされます。） +`localStorage` は {{DOMxRef("Window.sessionStorage", "sessionStorage")}} によく似ていますが、 `localStorage` のデータには期限がないのに対し、 `sessionStorage` のデータはページセッションが終了したとき、すなわちページが閉じられたときにクリアされます。（「プライベートブラウジング」や「プライバシーモード」のセッションに読み込まれた文書の `localStorage` のデータは、最後の「プライベート」タブが閉じられたときにクリアされます。） ## 値 diff --git a/files/ja/web/svg/attribute/preserveaspectratio/index.md b/files/ja/web/svg/attribute/preserveaspectratio/index.md new file mode 100644 index 00000000000000..1c23d8fef89cde --- /dev/null +++ b/files/ja/web/svg/attribute/preserveaspectratio/index.md @@ -0,0 +1,665 @@ +--- +title: preserveAspectRatio +slug: Web/SVG/Attribute/preserveAspectRatio +l10n: + sourceCommit: 904cdf09c7e328b7a15a6a4db6bc6bd31f969cce +--- + +{{SVGRef}} + +**`preserveAspectRatio`** 属性は、指定されたアスペクト比を提供するビューボックスを持つ要素が、異なるアスペクト比を持つビューポートにどのように収まるべきかを示します。 + +SVG 画像のアスペクト比は {{SVGAttr('viewBox')}} 属性によって定義されるので、この属性が設定されていない場合、 **`preserveAspectRatio`** 属性は何の効果も持ちません（_後述する {{SVGElement('image')}} 要素は例外です_）。 + +## 例 + +### meet (width > height) + +この例では、要素の `width` が `height` よりも大きい場合に `meet` を使用することを示しています。 3 つの配置値 `xMidYMid`、`xMinYMid`、`xMaxYMid` で 3 つのバリエーションを表示します。 + +```css hidden +html, +body, +svg { + height: 100%; +} + +/* それぞれの iframe の本文に flex 要素を配置し、様々な画面サイズに対応できるようにした */ +body { + display: flex; +} +``` + +```html + + + + + +``` + +```html + + xMidYMid meet + + + + +``` + +```html + + xMinYMid meet + + + + +``` + +```html + + xMaxYMid meet + + + + + +``` + +```css +path { + fill: yellow; + stroke: black; + stroke-width: 8px; + stroke-linecap: round; + stroke-linejoin: round; + pointer-events: none; +} + +rect:hover, +rect:active { + outline: 1px solid red; +} +``` + +{{EmbedLiveSample('meet width height', '100%', 200)}} + +### slice (width > height) + +この例では、要素の `width` が `height` よりも大きい場合に `slice` を使用することを示しています。 3 種類の配置値 `xMidYMin`、`xMidYMid`、`xMidYMax` で 3 つのバリエーションを表示します。 + +```css hidden +html, +body, +svg { + height: 100%; +} + +/* それぞれの iframe の本文に flex 要素を配置し、様々な画面サイズに対応できるようにした */ +body { + display: flex; +} +``` + +```html + + + + + +``` + +```html + + xMidYMin slice + + + + +``` + +```html + + xMidYMid slice + + + + +``` + +```html + + xMidYMax slice + + + + + +``` + +```css +path { + fill: yellow; + stroke: black; + stroke-width: 8px; + stroke-linecap: round; + stroke-linejoin: round; + pointer-events: none; +} + +rect:hover, +rect:active { + outline: 1px solid red; +} +``` + +{{EmbedLiveSample('slice width height', '100%', 200)}} + +### meet (height > width) + +この例では、要素の `height` が `width` よりも大きい場合に `meet` を使用することを示しています。 3 種類の配置値 `xMidYMin`、`xMidYMid`、`xMidYMax` で 3 つのバリエーションを表示します。 + +```css hidden +html, +body, +svg { + height: 100%; +} + +/* それぞれの iframe の本文に flex 要素を配置し、様々な画面サイズに対応できるようにした */ +body { + display: flex; +} +``` + +```html + + + + + +``` + +```html + + xMidYMin meet + + + + +``` + +```html + + xMidYMid meet + + + + +``` + +```html + + xMidYMax meet + + + + + +``` + +```css +path { + fill: yellow; + stroke: black; + stroke-width: 8px; + stroke-linecap: round; + stroke-linejoin: round; + pointer-events: none; +} + +rect:hover, +rect:active { + outline: 1px solid red; +} +``` + +{{EmbedLiveSample('meet height width', '100%', 200)}} + +### slice (height > width) + +この例では、要素の `height` が `width` よりも大きい場合に `slice` を使用することを示しています。 3 種類の配置値 `xMinYMid`、`xMidYMid`、`xMaxYMid` で 3 つのバリエーションを表示します。 + +```css hidden +html, +body, +svg { + height: 100%; +} + +/* それぞれの iframe の本文に flex 要素を配置し、様々な画面サイズに対応できるようにした */ +body { + display: flex; +} +``` + +```html + + + + + +``` + +```html + + xMinYMid slice + + + + +``` + +```html + + xMidYMid slice + + + + +``` + +```html + + xMaxYMid slice + + + + + +``` + +```css +path { + fill: yellow; + stroke: black; + stroke-width: 8px; + stroke-linecap: round; + stroke-linejoin: round; + pointer-events: none; +} + +rect:hover, +rect:active { + outline: 1px solid red; +} +``` + +{{EmbedLiveSample('slice height width', '100%', 200)}} + +### none + +この例では配置値を `none` に設定した要素を表示させています。 + +```css hidden +html, +body, +svg { + height: 100%; +} + +/* それぞれの iframe の本文に flex 要素を配置し、様々な画面サイズに対応できるようにした */ +body { + display: flex; +} +``` + +```html + + + + + +``` + +```html + + + none + + + + + +``` + +```css +path { + fill: yellow; + stroke: black; + stroke-width: 8px; + stroke-linecap: round; + stroke-linejoin: round; + pointer-events: none; +} + +rect:hover, +rect:active { + outline: 1px solid red; +} +``` + +{{EmbedLiveSample('none ', '100%', 200)}} + +## 構文 + +```plain +preserveAspectRatio=" []" +``` + +その値は、 1 つまたは 2 つのキーワードで構成されます。必要な配置値と、下記で記述されているオプションの "meet または slice" の参照です。 + +- 配置値 + + - : 配置値は、均等な変倍を強制するかどうかを示し、もしそうなら、{{ SVGAttr("viewBox") }}の縦横比がビューポートの縦横比と一致しない場合に使用する配置方法を示します。配置値は以下のいずれかのキーワードでなければなりません。 + + - **none** + 均等な変倍を強制しません。指定された要素のグラフィックコンテンツを、要素の外接ボックスがビューポートの長方形に正確に一致するように、必要に応じて不均一に変倍します。 _もし `` が `none` ならば、オプションの `` の値は無視されることに注意してください_。 + - **xMinYMin** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 Y 値に配置します。 + - **xMidYMin** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の X の中央値をビューポートの X の中央値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 Y 値に配置します。 + - **xMaxYMin** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 Y 値に配置します。 + - **xMinYMid** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の Y の中央値をビューポートの Y の中央値に配置します。 + - **xMidYMid** (the default) - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の X の中央値をビューポートの X の中央値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の Y の中央値をビューポートの Y の中央値に配置します。 + - **xMaxYMid** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の Y の中央値をビューポートの Y の中央値に配置します。 + - **xMinYMax** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `` をビューポートの最小 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 Y 値に配置します。 + - **xMidYMax** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の X の中央値をビューポートの X の中央値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 Y 値に配置します。 + - **xMaxYMax** - 均等な変倍を強制します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 X 値に配置します。 + 要素の {{ SVGAttr("viewBox") }} の `+` をビューポートの最大 Y 値に配置します。 + +- meet または slice の参照 + + - : meetまたはslice参照はオプションで、指定された場合は以下のキーワードのいずれかでなければなりません： + + - **meet** (_the default_) - 次のようにグラフィックを変倍します。 + + - アスペクト比を維持されます。 + - {{ SVGAttr("viewBox") }} 全体がビューポート内に表示されます。 + - {{ SVGAttr("viewBox") }} は、他にも条件を満たしつつ、可能な限り拡大します。 + + この場合、グラフィックのアスペクト比がビューポートと一致しないと、ビューポートの一部が {{ SVGAttr("viewBox") }} の枠からはみ出してしまいます（つまり、{{ SVGAttr("viewBox") }} が描画する領域はビューポートよりも小さくなります）。 + + - **slice** - 次のようにグラフィックを変倍します。 + + - アスペクト比を維持されます。 + - ビューポート全体が {{ SVGAttr("viewBox") }} に応じたものになります。 + - {{SVGAttr("viewBox") }} は、他にも条件を満たしつつ、可能な限り縮小します。 + + この場合、 {{ SVGAttr("viewBox") }} のアスペクト比がビューポートと一致しないと、{{ SVGAttr("viewBox") }} の一部がビューポートの境界からはみ出してしまいます（つまり、{{ SVGAttr("viewBox") }} が描画する領域はビューポートよりも大きくなります）。 + +## 要素 + +この属性は以下の SVG 要素で使用することができます。 + +- {{SVGElement("svg")}} +- {{SVGElement("symbol")}} +- {{SVGElement("image")}} +- {{SVGElement("feImage")}} +- {{SVGElement("marker")}} +- {{SVGElement("pattern")}} +- {{SVGElement("view")}} + +### feImage + +{{SVGElement('feImage')}} の場合、 `preserveAspectRatio` は参照している画像が `` 要素で定義した長方形に収まるように定義します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### image + +{{SVGElement('image')}} の場合、 `preserveAspectRatio` は参照している画像が `` 要素で定義した長方形に収まるように定義します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### marker + +{{SVGElement('marker')}} の場合、 `preserveAspectRatio` は、要素のビューポートに合わせて一様に変倍する必要があるかどうかを示します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### pattern + +{{SVGElement('pattern')}} の場合、 `preserveAspectRatio` は、要素のビューポートに合わせて一様に変倍する必要があるかどうかを示します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### svg + +{{SVGElement('svg')}} の場合、 `preserveAspectRatio` は、要素のビューポートに合わせて一様に変倍する必要があるかどうかを示します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### symbol + +{{SVGElement('symbol')}} の場合、 `preserveAspectRatio` は、要素のビューポートに合わせて一様に変倍する必要があるかどうかを示します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +### view + +{{SVGElement('view')}} の場合、 `preserveAspectRatio` は、要素のビューポートに合わせて一様に変倍する必要があるかどうかを示します。 + + + + + + + + + + + + + + + + +
値<align> <meetOrSlice>?
既定値xMidYMid meet
アニメーション可
+ +## 仕様書 + +{{Specifications}} diff --git a/files/zh-cn/glossary/first_contentful_paint/index.md b/files/zh-cn/glossary/first_contentful_paint/index.md new file mode 100644 index 00000000000000..82307f356e877a --- /dev/null +++ b/files/zh-cn/glossary/first_contentful_paint/index.md @@ -0,0 +1,20 @@ +--- +title: 首次内容绘制 +slug: Glossary/First_contentful_paint +l10n: + sourceCommit: 835d6632d59993861a0458510402787f8a2c3cb3 +--- + +{{GlossarySidebar}} + +**首次内容绘制**（FCP）是指浏览器渲染 DOM 中的第一部分内容，向用户提供页面正在加载的第一次反馈的时间。在首次内容绘制完成时，问题“它正在发生吗？”的答案为“是”。 + +*首次内容绘制*时间戳是指浏览器首次渲染任何文本、图像（包括背景图像）、视频、已绘制的画布或非空 SVG 的时间。这不包括任何 iframe 的内容，但包括待加载 web 字体的文本。这是用户可以开始查看页面内容的时间。 + +## 参见 + +- [首次绘制](/zh-CN/docs/Glossary/First_paint) +- [`PerformancePaintTiming`](/zh-CN/docs/Web/API/PerformancePaintTiming) +- [最大内容绘制](/zh-CN/docs/Glossary/Largest_contentful_paint) +- [首次有效绘制](/zh-CN/docs/Glossary/First_meaningful_paint) +- [首次内容绘制](https://web.dev/articles/fcp)，web.dev diff --git a/files/zh-cn/glossary/first_meaningful_paint/index.md b/files/zh-cn/glossary/first_meaningful_paint/index.md new file mode 100644 index 00000000000000..2d888cc51bd848 --- /dev/null +++ b/files/zh-cn/glossary/first_meaningful_paint/index.md @@ -0,0 +1,19 @@ +--- +title: 首次有效绘制 +slug: Glossary/First_meaningful_paint +l10n: + sourceCommit: ada5fa5ef15eadd44b549ecf906423b4a2092f34 +--- + +{{GlossarySidebar}} + +**首次有效绘制**（FMP）是在发生最大的首屏布局更改并加载 web 字体后进行的绘制。在首次有效绘制后，问题“这是否有用？”的答案变成了“是”。 + +FMP 对页面加载中的微小差异非常敏感。这可能导致不一致（双峰分布）的结果。该指标的定义依赖于特定于浏览器的实现细节，这意味着它无法标准化，并且尚未在所有的 web 浏览器中实现。 + +> **警告：** 首次有效绘制（FMP）已在 Lighthouse 6.0 中弃用。在未来，请考虑使用 [LargestContentfulPaint API](https://wicg.github.io/largest-contentful-paint/)。 + +## 参见 + +- [首次内容绘制](/zh-CN/docs/Glossary/First_contentful_paint) +- [最大内容绘制](https://wicg.github.io/largest-contentful-paint/) diff --git a/files/zh-cn/glossary/largest_contentful_paint/index.md b/files/zh-cn/glossary/largest_contentful_paint/index.md new file mode 100644 index 00000000000000..78e02005a2a58f --- /dev/null +++ b/files/zh-cn/glossary/largest_contentful_paint/index.md @@ -0,0 +1,24 @@ +--- +title: 最大内容绘制 +slug: Glossary/Largest_contentful_paint +l10n: + sourceCommit: ada5fa5ef15eadd44b549ecf906423b4a2092f34 +--- + +{{GlossarySidebar}} + +**最大内容绘制**（LCP）性能指标提供了在视口内可见的最大图像或文本块的渲染时间（从页面开始加载时开始记录）。 + +确定 LCP 时会考虑以下元素： + +- {{HTMLElement("img")}} 元素。 +- SVG 中的 [``](/zh-CN/docs/Web/SVG/Element/image) 元素。 +- {{HTMLElement("video")}} 元素的封面图像。 +- 具有 {{cssxref("background-image")}} 的元素。 +- 文本节点（例如 {{HTMLElement("p")}}）分组。 + +## 参见 + +- [`LargestContentfulPaint`](/zh-CN/docs/Web/API/LargestContentfulPaint) +- [首次内容绘制](/zh-CN/docs/Glossary/First_contentful_paint) +- [首次绘制](/zh-CN/docs/Glossary/First_paint) diff --git a/files/zh-cn/web/api/abortsignal/abort_static/index.md b/files/zh-cn/web/api/abortsignal/abort_static/index.md index d1e0c24602b150..a12ae282cb7434 100644 --- a/files/zh-cn/web/api/abortsignal/abort_static/index.md +++ b/files/zh-cn/web/api/abortsignal/abort_static/index.md @@ -1,5 +1,5 @@ --- -title: AbortSignal.abort() +title: AbortSignal：abort() 静态方法 slug: Web/API/AbortSignal/abort_static --- @@ -17,7 +17,7 @@ return controller.signal; 例如，将它传递给一个 fetch 方法，以运行它的中止逻辑（也就是说，可能其代码的执行顺序是即使预期的 fetch 操作还没有启动，也应该运行中止逻辑）。 -> **备注：** 该方法在目的上类似于 {{JSxRef("Promise.reject")}}。 +> **备注：** 该方法的作用类似于 {{JSxRef("Promise.reject")}}。 ## 语法 @@ -29,7 +29,7 @@ AbortSignal.abort(reason) ### 参数 - `reason` - - : 操作被中止的原因，可以是任意的 JavaScript 值。如果没有指定原因，则默认设置为"AbortError"{{domxref("DOMException")}}。 + - : 操作被中止的原因，可以是任意的 JavaScript 值。如果没有指定原因，则默认设置为“AbortError” {{domxref("DOMException")}}。 ### 返回值 diff --git a/files/zh-cn/web/api/fetch/index.md b/files/zh-cn/web/api/fetch/index.md index 7aec3661274056..4171c75f3078e0 100644 --- a/files/zh-cn/web/api/fetch/index.md +++ b/files/zh-cn/web/api/fetch/index.md @@ -1,19 +1,21 @@ --- -title: fetch() +title: 全局函数 fetch() slug: Web/API/fetch +l10n: + sourceCommit: 272cd2b471705d5071dd63764ba13b4c46a260d7 --- -{{APIRef("Fetch")}} +{{APIRef("Fetch API")}}{{AvailableInWorkers}} -全局的 **`fetch()`** 方法用于发起获取资源的请求。它返回一个 promise，这个 promise 会在请求响应后被 resolve，并传回 {{domxref("Response")}} 对象。 +全局 **`fetch()`** 方法用于发起获取资源的请求，它会返回一个会在请求响应后兑现的 promise。 -{{domxref("Window")}} 和 {{domxref("WorkerGlobalScope")}} 都实现了 WorkerOrGlobalScope。——这意味着基本在任何场景下只要你想获取资源，都可以使用 位于 WorkerOrGlobalScope 中的 `fetch()` 方法。 +该 promise 会兑现一个表示请求响应的 {{domxref("Response")}} 对象。 -当遇到网络错误时，{{domxref("fetch()")}} 返回的 promise 会被 reject，并传回 {{jsxref("TypeError")}}，虽然这也可能因为权限或其他问题导致。成功的 fetch() 检查不仅要包括 promise 被 resolve，还要包括 {{domxref("Response.ok")}} 属性为 true。HTTP 404 状态并不被认为是网络错误。 +当遇到网络错误（因为权限或其他类似的问题）时，`fetch()` 返回的 promise 才会被拒绝。`fetch()` 的 promise *不会*因为 HTTP 错误而被拒绝（比如 `404`、`504`，等）。因此，`then()` 处理器必须检查 {{domxref("Response.ok")}} 和/或 {{domxref("Response.status")}} 属性。 -`fetch()` 方法由 [Content Security Policy](/zh-CN/docs/Security/CSP/CSP_policy_directives) 的 `connect-src`指令控制，而不是它请求的资源。 +`fetch()` 方法由 [Content Security Policy](/zh-CN/docs/Security/CSP/CSP_policy_directives) 的 `connect-src` 指令控制，而不是它请求的资源。 -> **备注：** {{domxref("fetch()")}} 方法的参数与 {{domxref("Request.Request","Request()")}} 构造器是一样的。 +> **备注：** `fetch()` 方法的参数与 {{domxref("Request.Request","Request()")}} 构造器是一样的。 ## 语法 @@ -23,27 +25,84 @@ Promise fetch(input[, init]); ### 参数 -- _?input_ +- `resource` - - : 定义要获取的资源。这可能是： + - : 定义你想要获取的资源。这可能是： - - 一个 {{domxref("USVString")}} 字符串，包含要获取资源的 URL。一些浏览器会接受 `blob:` 和 `data:` 作为 schemes. + - 一个字符串或任何其他具有 {{Glossary("stringifier")}} 的对象，包括 {{domxref("URL")}} 对象——提供你想要获取的资源的 URL。 - 一个 {{domxref("Request")}} 对象。 -- _init_ {{optional_inline}} +- `options` {{optional_inline}} - - : 一个配置项对象，包括所有对请求的设置。可选的参数有： + - : 一个包含要应用于请求的自定义设置的对象。可能的选项有： - - `method`: 请求使用的方法，如 `GET`、`POST`。 - - `headers`: 请求的头信息，形式为 {{domxref("Headers")}} 的对象或包含 {{domxref("ByteString")}} 值的对象字面量。 - - `body`: 请求的 body 信息：可能是一个 {{domxref("Blob")}}、{{domxref("BufferSource")}}、{{domxref("FormData")}}、{{domxref("URLSearchParams")}} 或者 {{domxref("USVString")}} 对象。注意 GET 或 HEAD 方法的请求不能包含 body 信息。 - - `mode`: 请求的模式，如 `cors`、`no-cors` 或者 `same-origin`。 - - `credentials`: 请求的 credentials，如 `omit`、`same-origin` 或者 `include`。为了在当前域名内自动发送 cookie，必须提供这个选项，从 Chrome 50 开始，这个属性也可以接受 {{domxref("FederatedCredential")}} 实例或是一个 {{domxref("PasswordCredential")}} 实例。 - - `cache`: 请求的 cache 模式：`default`、 `no-store`、 `reload` 、 `no-cache`、 `force-cache` 或者 `only-if-cached`。 - - `redirect`: 可用的 redirect 模式：`follow` (自动重定向), `error` (如果产生重定向将自动终止并且抛出一个错误），或者 `manual` (手动处理重定向)。在 Chrome 中默认使用 `follow`（Chrome 47 之前的默认值是 `manual`）。 - - `referrer`: 一个 {{domxref("USVString")}} 可以是 `no-referrer`、`client` 或一个 URL。默认是 `client`。 - - `referrerPolicy`: 指定了 HTTP 头部 referer 字段的值。可能为以下值之一：`no-referrer`、 `no-referrer-when-downgrade`、`origin`、`origin-when-cross-origin`、 `unsafe-url`。 - - `integrity`: 包括请求的 [subresource integrity](/zh-CN/docs/Web/Security/Subresource_Integrity) 值（例如： `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`）。 + - `body` + + - : 你想要添加到请求中的任意消息主体：可以是一个 {{domxref("Blob")}}、{{jsxref("ArrayBuffer")}}、{{jsxref("TypedArray")}}、{{jsxref("DataView")}}、{{domxref("FormData")}}、{{domxref("URLSearchParams")}}、字符串对象或者字符串字面量，或者 {{domxref("ReadableStream")}} 对象。注意 `GET` 或 `HEAD` 方法的请求不能包含消息主体。 + + - `browsingTopics` {{experimental_inline}} + + - : 布尔值，表示当前用户选择的主题是否应该在关联请求的 {{httpheader("Sec-Browsing-Topics")}} 标头中发送。有关更多详细信息，请参阅[使用 Topics API](/zh-CN/docs/Web/API/Topics_API/Using)。 + + - `cache` + + - : 字符串，表示请求如何与浏览器的 [HTTP 缓存](/zh-CN/docs/Web/HTTP/Caching)进行交互。可能的值有 `default`、`no-store`、`reload`、`no-cache`、`force-cache` 和 `only-if-cached`，这些取值在 {{domxref("Request")}} 对象的 {{domxref("Request/cache", "cache")}} 属性的文档中有记录。 + + - `credentials` + + - : 控制浏览器如何处理凭据（[cookie](/zh-CN/docs/Web/HTTP/Cookies)、[HTTP authentication](/zh-CN/docs/Web/HTTP/Authentication) 条目和 TLS 客户端证书）。必须是以下字符串之一： + + - `omit`：告诉浏览器在请求中排除凭据，并忽略响应中发送的任何凭据（例如，任何 {{HTTPHeader("Set-Cookie")}} 标头）。 + - `same-origin`：告诉浏览器在请求同源 URL 时包含凭据，并使用来自同源 URL 响应中返回的凭据。**这是默认值。** + - `include`：告诉浏览器在同源和跨源请求中都包含凭据，并始终使用响应中返回的凭据。 + + > **备注：** 凭据可以包含在简单和“最终”的跨源请求中，但不应包含在 [CORS 预检请求](/zh-CN/docs/Web/HTTP/CORS#预检请求)中。 + + - `headers` + + - : 任意你想要附加到请求的标头，可以是 {{domxref("Headers")}} 对象或者带有{{jsxref("String", "字符串")}}值的对象字面量。注意[有些标头是被禁止的](/zh-CN/docs/Glossary/Forbidden_header_name)。 + + > **备注：** 请求中可能会有 [`Authorization`](/zh-CN/docs/Web/HTTP/Headers/Authorization) HTTP 标头，但是如果请求跨源重定向的话就会被删除。 + + - `integrity` + + - : 包含请求的[子资源完整性](/zh-CN/docs/Web/Security/Subresource_Integrity)值（比如 `sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=`）。 + + - `keepalive` + - : `keepalive` 选项可以允许请求持续保持连接，甚至页面已经关闭的情况。使用 `keepalive` 标志的 Fetch 是 {{domxref("Navigator.sendBeacon()")}} API 的一种替代方案。 + - `method` + + - : 请求的方法，比如 `"GET"`、`"POST"`，默认值是 `"GET"`。注意 {{HTTPMethod("HEAD")}} 或者 {{HTTPMethod("GET")}} 的 Fetch 请求不会设置 {{httpheader("Origin")}} 标头（此行为已在 Firefox 65 中修正——参见 [Firefox bug 1508661](https://bugzil.la/1508661)）。不区分大小写的情况下能匹配上 [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-overview) 中的任意字符串都会自动被转成大小。如果你想使用自定义的方法（比如 `PATCH`），你应该将它变为大写。 + + - `mode` + - : 你想要使用的模式，比如 `cors`、`no-cors` 或 `same-origin`。 + - `priority` + - : 指定相对于其他同类型的请求的 fetch 请求的优先级。必须是以下字符串之一： + - `high` + - : 相对于其他同类型的请求而言，这是一个高优先级的 fetch 请求。 + - `low` + - : 相对于其他同类型的请求而言，这是一个低优先级的 fetch 请求。 + - `auto` + - : 自动确定相对于同类型的其他请求的 fetch 请求的优先级（默认）。 + - `redirect` + + - : 如何处理重定向（`redirect`）响应： + + - `follow` + - : 自动跟随重定向。除非另有说明，否则重定向模式设置为 `follow`。 + - `error` + - : 如果发生重定向，则中止并显示错误。 + - `manual` + - : 调用者打算在另一个上下文中处理响应。详细信息请参阅 [WHATWG fetch 规范](https://fetch.spec.whatwg.org/#concept-request-redirect-mode)。 + + - `referrer` + + - : 一个指定请求的引用者的字符串。这可以是同源 URL、`about:client` 或空字符串。 + + - `referrerPolicy` + - : 指定请求所使用的 [referrer policy](https://w3c.github.io/webappsec-referrer-policy/#referrer-policies)。可能是以下其中之一 `no-referrer`、`no-referrer-when-downgrade`、`same-origin`、`origin`、`strict-origin`、`origin-when-cross-origin`、`strict-origin-when-cross-origin` 或者 `unsafe-url`。 + - `signal` + - : 一个 {{domxref("AbortSignal")}} 对象实例；允许你通过 {{domxref("AbortController")}} 与 fetch 请求进行通信，并在需要时中止请求。 ### 返回值 diff --git a/files/zh-cn/web/html/element/tr/index.md b/files/zh-cn/web/html/element/tr/index.md index b83ec922b2e664..77980e711e0aea 100644 --- a/files/zh-cn/web/html/element/tr/index.md +++ b/files/zh-cn/web/html/element/tr/index.md @@ -1,105 +1,412 @@ --- -title: +title: ：表格行元素 slug: Web/HTML/Element/tr +l10n: + sourceCommit: fffabdeeb9a069e40a070dadeedc93298b2aca7e --- -**HTML `` 元素**定义表格中的行。同一行可同时出现{{HTMLElement("td")}} 和{{HTMLElement("th")}} 元素。 +{{HTMLSidebar}} - - +[HTML](/zh-CN/docs/Web/HTML) **``** 元素定义了表格中的一行单元格。然后可以使用 {{HTMLElement("td")}}（数据单元格）和 {{HTMLElement("th")}}（标题单元格）元素的组合来建立该行的单元格。 + +{{EmbedInteractiveExample("pages/tabbed/tr.html","tabbed-taller")}} + +## 属性 + +此元素包含[全局属性](/zh-CN/docs/Web/HTML/Global_attributes)。 + +### 已废弃的属性 + +以下属性已被弃用，不应再使用。下文记录了这些属性，仅供更新现有代码时参考。 + +- `align` {{deprecated_inline}} + + - : 指定每行单元格的水平对齐方式。可能的{{Glossary("enumerated", "枚举")}}值包括 `left`、`center`、`right`、`justify` 和 `char`。如果支持，`char` 值将根据 [`char`](#char) 属性中定义的字符和 [`charoff`](#charoff) 属性定义的偏移量对文本内容进行对齐。请使用 {{cssxref("text-align")}} CSS 属性代替，因为该属性已被弃用。 + +- `bgcolor` {{deprecated_inline}} + + - : 定义每行单元格的背景颜色。值是 HTML 颜色；可以是以“`#`”为前缀的 [6 位十六进制 RGB 代码](/zh-CN/docs/Web/CSS/hex-color)，也可以是[颜色关键字](/zh-CN/docs/Web/CSS/named-color)。不支持其他 CSS {{cssxref("color_value", "<color>")}} 值。请使用 {{cssxref("background-color")}} CSS 属性代替，因为该属性已被弃用。 + +- `char` {{deprecated_inline}} + + - : 指定内容与每行单元格中一个字符的对齐方式。当尝试对齐数字或货币值时，典型值包括句号（`.`）。如果 [`align`](#align) 未设置为 `char`，该属性将被忽略。 + +- `charoff` {{deprecated_inline}} + + - : 指定由 [`char`](#char) 属性指定的对齐字符偏移行单元格内容的字符数。 + +- `valign` {{deprecated_inline}} + + - : 指定每行单元格的垂直对齐方式。可能的{{Glossary("enumerated", "枚举")}}值包括 `baseline`、`bottom`、`middle` 和 `top`。请使用 {{cssxref("vertical-align")}} CSS 属性代替，因为该属性已被弃用。 + +## 使用说明 + +- `` 可以作为其 {{HTMLElement("table")}} 父元素的直接子元素，但前提是 `
` 没有 {{HTMLElement("tbody")}} 子元素，并且只能位于任何 {{HTMLElement("caption")}}、{{HTMLElement("colgroup")}} 和 {{HTMLElement("thead")}} 元素之后。否则，父元素必须是 {{HTMLElement("thead")}}、{{HTMLElement("tbody")}} 或 {{HTMLElement("tfoot")}} 元素。 +- CSS 伪类 {{cssxref(":nth-of-type")}}、{{cssxref(":first-of-type")}} 和 {{cssxref(":last-of-type")}} 通常用于选择所需的行集及其数据和标题单元格（{{HTMLElement("td")}} 和 {{HTMLElement("th")}} 元素）。 + +## 示例 + +参见 {{HTMLElement("table")}} 以获取介绍通用标准和最佳实践的完整表格示例。 + +### 基本行设置 + +本例演示了一个有四行三列的表格，其中第一列包含行数据单元格的标题。 + +#### HTML + +四个 `` 元素用于创建四个表格行。每行包含三个单元格——一个标题单元格（{{HTMLElement("th")}}）和两个数据单元格（{{HTMLElement("td")}}）——形成三列。在每个标题单元格上设置的 [`scope`](/zh-CN/docs/Web/HTML/Element/th#scope) 属性指定了它们与哪些单元格相关，在本示例中就是与 `row`（行）中的所有数据单元格相关。 + +```html +
- - + + + - - + + + - - + + + - - + + + + +
Content categoriesNoneAAlfaAL fah
Permitted contentZero or more {{HTMLElement("td")}} or {{HTMLElement("th")}} elements, or a mix of themBBravoBRAH voh
Tag omissionStart tag is mandatory. End tag may be omitted if the {{HTMLElement("tr")}} element is immediately followed by a {{HTMLElement("tr")}} element, or if the parent table group ({{HTMLElement("thead")}}, {{HTMLElement("tbody")}} or {{HTMLElement("tfoot")}}) element doesn't have any more contentCCharlieCHAR lee
Permitted parents{{HTMLElement("table")}}, {{HTMLElement("thead")}}, {{HTMLElement("tbody")}} or {{HTMLElement("tfoot")}} elementDDeltaDELL tah
+``` + +#### CSS + +CSS {{cssxref(":nth-of-type")}} 伪类用于选择每一个“奇数”行，并将这些行的 {{cssxref("background-color")}} 设置为稍暗的色调，从而产生所谓的“斑马条纹”效果。这种交替的背景使表格中的数据行更容易解析和阅读——想象一下有许多行和列，并试图在某一行中找到一些数据的情景。此外，行标题单元格（{{HTMLElement("th")}} 元素）用 {{cssxref("background-color")}} 突出显示，以区别于数据单元格（{{HTMLElement("td")}} 元素）。 + +```css +tr:nth-of-type(odd) { + background-color: #eee; +} + +tr th[scope="row"] { + background-color: #d6ecd4; +} +``` + +```css hidden +table { + border-collapse: collapse; + border: 2px solid rgb(140 140 140); + font-family: sans-serif; + font-size: 0.8rem; + letter-spacing: 1px; +} + +th, +td { + border: 1px solid rgb(160 160 160); + padding: 8px 10px; +} +``` + +#### 结果 + +{{EmbedLiveSample("基本行设置", 650, 140)}} + +### 标题行 + +本示例扩展了[上一示例](#基本行设置)中的基本表格，在表格的第一行添加了标题行。 + +#### HTML + +我们添加了额外的表格行（``）作为第一行，其中的列标题单元格（{{HTMLElement("th")}}）为每列提供了一个标题。我们将这一行放在 {{HTMLElement("thead")}} 分组元素中，以表示这是表格的表头。[`scope`](/zh-CN/docs/Web/HTML/Element/th#scope) 属性被添加到该页眉行中的每个表头单元格（``）中，以明确指定每个表头单元格与其所在列中的所有单元格相关，即使这些单元格位于 {{HTMLElement("tbody")}} 中。 + +```html + + + + + + + + + + + + + + + - - + + + - - + + + -
符号代码发音
AAlfaAL fah
BBravoBRAH voh
Permitted ARIA rolesAnyCCharlieCHAR lee
DOM interface{{domxref("HTMLTableRowElement")}}DDeltaDELL tah
+``` -## Attributes +#### CSS -表格标签支持 [全局特性](/zh-CN/docs/HTML/Global_attributes)。还有一些过期的特性，你应该避免使用它们，但是可以了解它们，会在你阅读旧代码的时候有所帮助。 +CSS 与[上一示例](#基本行设置)几乎没有变化，只是增加了一些样式来突出显示“标题行”，从而使各列的标题从其他单元格中脱颖而出。 -- `align` {{Deprecated_inline}} +```css +tr:nth-of-type(odd) { + background-color: #eee; +} - - : 该枚举属性指定每个单元格中内容的水平对齐方式，可使用的属性值如下： +tr th[scope="col"] { + background-color: #505050; + color: #fff; +} - - `left`, 内容在单元格中左对齐 - - `center`, 内容在单元格中居中 - - `right`, 内容在单元格中右对齐 - - `justify`, 增加文本内容之间的空白以伸展这行文本，使得该单元格中的多行文本具有相同的长度。 - - `char`, aligning the textual content on a special character with a minimal offset, defined by the [`char`](/zh-CN/docs/Web/HTML/Element/tr#char) and [`charoff`](/zh-CN/docs/Web/HTML/Element/tr#charoff) attributes. If this attribute is not set, the parent node's value is inherited. +tr th[scope="row"] { + background-color: #d6ecd4; +} +``` - > **备注：** Do not use this attribute as it is obsolete (not supported) in the latest standard. - > - > - To achieve the same effect as the `left`, `center`, `right` or `justify` values, use the CSS {{cssxref("text-align")}} property on it. - > - To achieve the same effect as the `char` value, in CSS3, you can use the value of the [`char`](/zh-CN/docs/Web/HTML/Element/tr#char) as the value of the {{cssxref("text-align")}} property. +```css hidden +table { + border-collapse: collapse; + border: 2px solid rgb(140 140 140); + font-family: sans-serif; + font-size: 0.8rem; + letter-spacing: 1px; +} -- `bgcolor` {{Deprecated_inline}} +th, +td { + border: 1px solid rgb(160 160 160); + padding: 8px 10px; +} +``` - - : This attribute defines the background color of each cell of the row. It can be either an [hexadecimal `#RRGGBB` or `#RGB` value]() or a [color keyword](/zh-CN/docs/Web/CSS/color_value#Color_keywords). +#### 结果 - > **备注：** the {{HTMLElement("tr")}} element should be styled using [CSS](/zh-CN/docs/CSS). To give a similar effect to the **bgcolor** attribute, use the [CSS](/zh-CN/docs/CSS) property {{cssxref("background-color")}}. +{{EmbedLiveSample("标题行", 650, 170)}} -- `char` {{Deprecated_inline}} +### 行排序 - - : This attribute is used to set the character to align the cells in a column on. Typical values for this include a period (.) when attempting to align numbers or monetary values. If [`align`](/zh-CN/docs/Web/HTML/Element/tr#align) is not set to `char`, this attribute is ignored. +目前还没有对 {{HTMLElement("table")}} 的行（`` 元素）进行排序的原生方法。但是可以使用 {{jsxref("Array.prototype.sort()")}}, {{domxref("Node.removeChild")}} 和 {{domxref("Node.appendChild")}} 在 JavaScript 中实现自定 `sort()` 函数，对 {{domxref("HTMLCollection")}} 的 `` 元素进行排序。 - > **备注：** Do not use this attribute as it is obsolete (and not supported) in the latest standard. To achieve the same effect as the [`char`](/zh-CN/docs/Web/HTML/Element/tr#char), in CSS3, you can use the character set using the [`char`](/zh-CN/docs/Web/HTML/Element/tr#char) attribute as the value of the {{cssxref("text-align")}} property. +#### HTML -- `charoff` {{Deprecated_inline}} +在这个基本表格中使用了 {{HTMLElement("tbody")}} 元素来标记表格的主体部分，并包含三行（{{HTMLElement("tr")}} 元素）数据（{{HTMLElement("td")}} 元素），创建了一列按降序排列的数字。 - - : This attribute is used to indicate the number of characters to offset the column data from the alignment characters specified by the **char** attribute. +```html + + + + + + + + + + + + +
3
2
1
+``` - > **备注：** Do not use this attribute as it is obsolete (and not supported) in the latest standard. +#### JavaScript -- `valign` {{Deprecated_inline}} +在下面的 JavaScript 代码中，创建的 `sort()` 函数被附加到 {{HTMLElement("tbody")}} 元素上，这样它就能按照数值递增的顺序对表格单元格进行排序，并相应地更新显示内容。 - - : This attribute specifies the vertical alignment of the text within each row of cells of the table header. Possible values for this attribute are: +```js +HTMLTableSectionElement.prototype.sort = function (cb) { + Array.from(this.rows) + .sort(cb) + .forEach((e) => this.appendChild(this.removeChild(e))); +}; - - `baseline`, which will put the text as close to the bottom of the cell as it is possible, but align it on the [baseline](https://en.wikipedia.org/wiki/Baseline_%28typography%29) of the characters instead of the bottom of them. If characters are all of the size, this has the same effect as `bottom`. - - `bottom`, which will put the text as close to the bottom of the cell as it is possible; - - `middle`, which will center the text in the cell; - - and `top`, which will put the text as close to the top of the cell as it is possible. +document + .querySelector("table") + .tBodies[0].sort((a, b) => a.textContent.localeCompare(b.textContent)); +``` - > **备注：** Do not use this attribute as it is obsolete (and not supported) in the latest standard: instead set the CSS {{cssxref("vertical-align")}} property on it. +```css hidden +table { + border-collapse: collapse; + border: 2px solid rgb(140 140 140); + font-family: sans-serif; + font-size: 0.8rem; + letter-spacing: 1px; +} -## Examples +td { + border: 1px solid rgb(160 160 160); + padding: 4px 8px; +} +``` -See {{HTMLElement("table")}} for examples on ``. +#### 结果 -## Specifications +{{EmbedLiveSample('行排序', '650', '80')}} -{{Specifications}} +### 点击表头单元格以进行排序 -## Browser compatibility +本示例扩展了[上一示例](#行排序)中的基本表格，使排序具有交互性，并可独立于多列。 -{{Compat}} +#### HTML -## See also +在表格主体（{{HTMLElement("tbody")}} 元素）中的每一行（`` 元素）上添加一个额外的数据单元格（{{HTMLElement("td")}} 元素），以创建第二列，按字母升序排列。使用 {{HTMLElement("thead")}} 元素，在主体部分之前添加标题部分，以引入包含表头单元格的标题行（{{HTMLElement("th")}} 元素）。在下面的 JavaScript 代码中使用这些标题单元格，使其可以点击，然后在每次点击激活时执行相应的排序。 -- Other table-related HTML Elements: {{HTMLElement("caption")}}, {{HTMLElement("col")}}, {{HTMLElement("colgroup")}}, {{HTMLElement("table")}}, {{HTMLElement("tbody")}}, {{HTMLElement("td")}}, {{HTMLElement("tfoot")}}, {{HTMLElement("th")}}, {{HTMLElement("thead")}}; -- CSS properties and pseudo-classes that may be specially useful to style the `` element: +```html + + + + + + + + + + + + + + + + + + + + + +
数字字母
3A
2B
1C
+``` - - the {{cssxref(":nth-child")}} pseudo-class to set the alignment on the cells of the column; - - the {{cssxref("text-align")}} property to align all cells content on the same character, like '.'.< +#### JavaScript -{{HTMLSidebar}} +{{domxref("HTMLDocument", "文档")}}中的每个 {{HTMLElement("table")}} 的每个表头（{{HTMLElement("th")}}元素）都添加了一个点击事件处理程序；它会根据行中包含的数据单元格（{{HTMLElement("td")}} 元素）的内容对 {{HTMLElement("tbody")}} 的所有行（`` 元素）进行排序。 + +> **备注：** 此解决方案假设 {{HTMLElement("td")}} 元素由原始文本填充，没有后代元素。 + +```js +const allTables = document.querySelectorAll("table"); + +for (const table of allTables) { + const tBody = table.tBodies[0]; + const rows = Array.from(tBody.rows); + const headerCells = table.tHead.rows[0].cells; + + for (const th of headerCells) { + const cellIndex = th.cellIndex; + + th.addEventListener("click", () => { + rows.sort((tr1, tr2) => { + const tr1Text = tr1.cells[cellIndex].textContent; + const tr2Text = tr2.cells[cellIndex].textContent; + return tr1Text.localeCompare(tr2Text); + }); + + tBody.append(...rows); + }); + } +} +``` + +```css hidden +table { + border-collapse: collapse; + border: 2px solid rgb(140 140 140); + font-family: sans-serif; + font-size: 0.8rem; + letter-spacing: 1px; +} + +th, +td { + border: 1px solid rgb(160 160 160); + padding: 4px 8px; +} + +th { + background-color: #505050; + color: #fff; + cursor: pointer; +} +``` + +#### 结果 + +{{EmbedLiveSample('点击表头单元格以进行排序', '650', '100')}} + +> **备注：** 为了保证可用性和无障碍性，每个可排序列的标题单元格都必须可识别为排序按钮，并且每个标题单元格都必须以可视方式定义列当前是按升序还是降序排序，并使用 [`aria-sort`](/zh-CN/docs/Web/Accessibility/ARIA/Attributes/aria-sort) 属性。更多信息请参阅 [ARIA 创作实践指南](https://www.w3.org/WAI/ARIA/apg/)的[可排序表格示例](https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/)。 + +## 技术概要 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ 内容分类 + 无
允许的内容 + 允许使用零个或多个 {{HTMLElement("td")}} 和/或 {{HTMLElement("th")}} 元素；也允许使用{{Glossary("script-supporting element", "脚本支持元素")}}（{{HTMLElement("script")}} 和 {{HTMLElement("template")}}）。 +
标签省略 + 开始标记是必需的。如果 {{HTMLElement("tr")}} 元素后面紧跟着一个 {{HTMLElement("tr")}} 元素，或者该行是其父表组（{{HTMLElement("thead")}}、{{HTMLElement("tbody")}} 或 {{HTMLElement("tfoot")}}）元素中的最后一个元素，则可以省略结束标记。 +
允许的父元素 + {{HTMLElement("table")}}（仅当表格没有 {{HTMLElement("tbody")}} 子元素时，即便如此，也只能在任何 {{HTMLElement("caption")}}、{{HTMLElement("colgroup")}} 和 {{HTMLElement("thead")}} 元素之后）；否则，父元素必须是 {{HTMLElement("thead")}}、{{HTMLElement("tbody")}} 或 {{HTMLElement("tfoot")}} 元素。 +
隐含的 ARIA 角色 + row +
允许的 ARIA 角色任意
DOM 接口{{DOMxRef("HTMLTableRowElement")}}
+ +## 规范 + +{{Specifications}} + +## 浏览器兼容性 + +{{Compat}} + +## 参见 + +- [学习：HTML 表格](/zh-CN/docs/Learn/HTML/Tables) +- {{HTMLElement("caption")}}、{{HTMLElement("col")}}、{{HTMLElement("colgroup")}}、{{HTMLElement("table")}}、{{HTMLElement("tbody")}}、{{HTMLElement("td")}}、{{HTMLElement("tfoot")}}、{{HTMLElement("th")}}、{{HTMLElement("thead")}}：其他与表格相关的元素 +- {{cssxref("background-color")}}：用于设置单元格背景颜色的 CSS 属性 +- {{cssxref("border")}}：用于控制行单元格边框的 CSS 属性 +- {{cssxref("text-align")}}：使每行单元格内容水平对齐的 CSS 属性 +- {{cssxref("vertical-align")}}：使每行单元格内容垂直对齐的 CSS 属性 +- {{cssxref(":nth-of-type")}}、{{cssxref(":first-of-type")}}、{{cssxref(":last-of-type")}}：选择特定单元格的伪类 diff --git a/files/zh-cn/web/javascript/reference/statements/const/index.md b/files/zh-cn/web/javascript/reference/statements/const/index.md index 1874f032d2a842..8278a03b60ee6f 100644 --- a/files/zh-cn/web/javascript/reference/statements/const/index.md +++ b/files/zh-cn/web/javascript/reference/statements/const/index.md @@ -1,116 +1,139 @@ --- title: const slug: Web/JavaScript/Reference/Statements/const +l10n: + sourceCommit: 4f86aad2b0b66c0d2041354ec81400c574ab56ca --- {{jsSidebar("Statements")}} -常量是块级范围的，非常类似用 [let](/zh-CN/docs/Web/JavaScript/Reference/Statements/let) 语句定义的变量。但常量的值是无法（通过重新赋值）改变的，也不能被重新声明。 +**`const`** 声明用于声明块作用域的局部变量。常量的值不能通过使用[赋值运算符](/zh-CN/docs/Web/JavaScript/Reference/Operators/Assignment)重新赋值来更改，但是如果常量是一个[对象](/zh-CN/docs/Web/JavaScript/Data_structures#objects)，它的属性可以被添加、更新或删除。 {{EmbedInteractiveExample("pages/js/statement-const.html")}} ## 语法 -```plain -const name1 = value1 [, name2 = value2 [, ... [, nameN = valueN]]]; +```js-nolint +const name1 = value1; +const name1 = value1, name2 = value2; +const name1 = value1, name2 = value2, /* …, */ nameN = valueN; ``` - `nameN` - - : 常量名称，可以是任意合法的{{Glossary("identifier","标识符")}}。 + - : 要声明的变量的名称。每个变量名称必须是合法的 JavaScript [标识符](/zh-CN/docs/Web/JavaScript/Reference/Lexical_grammar#标识符)或[解构绑定模式](/zh-CN/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)。 - `valueN` - - : 常量值，可以是任意合法的表达式。 + - : 变量的初始值。它可以是任何合法的表达式。 ## 描述 -此声明创建一个常量，其作用域可以是全局或本地声明的块。与[`var`](/zh-CN/docs/Web/JavaScript/Reference/Statements/var)变量不同，全局常量不会变为 window 对象的属性。需要一个常数的初始化器；也就是说，你必须在声明的同一语句中指定它的值（这是有道理的，因为以后不能更改）。 +`const` 声明与 {{jsxref("Statements/let", "let")}} 非常相似： -**`const` 声明**创建一个值的只读引用。但这并不意味着它所持有的值是不可变的，只是变量标识符不能重新分配。例如，在引用内容是对象的情况下，这意味着可以改变对象的内容（例如，其参数）。 +- `const` 声明的作用域既可以是块级作用域，也可以是函数作用域。 +- `const` 声明只有在声明的位置之后才能访问（参见[暂时性死区](/zh-CN/docs/Web/JavaScript/Reference/Statements/let#暂时性死区)）。因此，`const` 声明通常被视为[非提升](/zh-CN/docs/Glossary/Hoisting)的声明方式。 +- 当在脚本的顶层声明时，`const` 声明不会在 {{jsxref("globalThis")}} 上创建属性。 +- 在同一作用域中，`const` 声明不能被任何其他声明[重新声明](/zh-CN/docs/Web/JavaScript/Reference/Statements/let#重新声明)。 +- `const` 是[*声明*而不是*语句*](/zh-CN/docs/Web/JavaScript/Reference/Statements#语句和声明的区别)。这意味着你不能将单独的 `const` 声明用作块的主体（这是合理的，因为无法访问变量）。 -关于“[暂存死区](/zh-CN/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone_and_errors_with_let)”的所有讨论都适用于[`let`](/zh-CN/docs/Web/JavaScript/Reference/Statements/let)和`const`。 + ```js-nolint example-bad + if (true) const a = 1; // SyntaxError: Lexical declaration cannot appear in a single-statement context + ``` -一个常量不能和它所在作用域内的其他变量或函数拥有相同的名称。 +一个常量需要一个初始值。你必须在声明同时指定它的值。（这是合理的，因为它在声明后不能被改变。） + +```js-nolint example-bad +const FOO; // SyntaxError: Missing initializer in const declaration +``` + +`const` 声明创建了一个对值的不可变引用。它并*不*意味着它所持有的值是不可变的，只是变量标识符不能被重新赋值。例如，在内容是对象的情况下，这意味着对象的内容（例如属性）是可以被修改的。你应该将 `const` 声明理解为“创建一个*身份*保持不变”的标识符（变量），而不是“保持*值*不变的标识符”——换言之，是“创建不可变的{{Glossary("binding", "绑定")}}”，而不是“不可变的值”。 + +许多代码风格指南（包括 [MDN 的指南](/zh-CN/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#变量声明)建议当变量在其作用域中不会重新赋值时使用 `const` 而不是 {{jsxref("Statements/let", "let")}}。这样可以清晰地表达变量的类型（或值，如果是原始类型的情况下）永远不会改变的意图。对非原始值可能改变的情况下其他人可能更喜欢使用 `let`。 + +紧跟在 `const` 关键字后面的列表被称为[_绑定_](/zh-CN/docs/Glossary/Binding)_列表_，用逗号分隔，其中逗号*不是*[逗号运算符](/zh-CN/docs/Web/JavaScript/Reference/Operators/Comma_operator)，`=` 符号*不是*[赋值运算符](/zh-CN/docs/Web/JavaScript/Reference/Operators/Assignment)。后面变量的初始值可以引用处在列表前面的变量。 ## 示例 ### const 基本用法 -常量在声明的时候可以使用大小写，但通常情况下全部用大写字母。 +常量在声明的时候可以使用大小写，但通常情况下全部用大写字母，特别是对于原始值，因为它们确实是不可变的。 ```js -// 定义常量 MY_FAV 并赋值 7 +// 定义常量 MY_FAV 并赋值为 7 const MY_FAV = 7; -// 报错 - Uncaught TypeError: Assignment to constant variable. -MY_FAV = 20; - -// MY_FAV is 7 -console.log("my favorite number is: " + MY_FAV); - -// 尝试重新声明会报错 -// Uncaught SyntaxError: Identifier 'MY_FAV' has already been declared -const MY_FAV = 20; +console.log(`我最喜欢的数字是：${MY_FAV}`); +``` -// MY_FAV 保留给上面的常量，这个操作会失败 -var MY_FAV = 20; +```js-nolint example-bad +// 对常量变量重新赋值会引发错误 +MY_FAV = 20; // TypeError: Assignment to constant variable -// 也会报错 -let MY_FAV = 20; +// 重新声明常量会引发错误 +const MY_FAV = 20; // SyntaxError: Identifier 'MY_FAV' has already been declared +var MY_FAV = 20; // SyntaxError: Identifier 'MY_FAV' has already been declared +let MY_FAV = 20; // SyntaxError: Identifier 'MY_FAV' has already been declared ``` -### 块作用域 +### 块级作用域 -注意块作用域的性质很重要 +请务必注意块作用域的特性。 -```js -if (MY_FAV === 7) { - // 没问题，并且创建了一个块作用域变量 MY_FAV - // (works equally well with let to declare a block scoped non const variable) - let MY_FAV = 20; +```js-nolint +const MY_FAV = 7; - // MY_FAV 现在为 20 - console.log("my favorite number is " + MY_FAV); +if (MY_FAV === 7) { + // 没有问题，因为它在新的块级作用域中 + const MY_FAV = 20; + console.log(MY_FAV); // 20 - // 这被提升到全局上下文并引发错误 - var MY_FAV = 20; + // var 声明的范围不限于块，因此会引发错误 + var MY_FAV = 20; // SyntaxError: Identifier 'MY_FAV' has already been declared } -// MY_FAV 依旧为 7 -console.log("my favorite number is " + MY_FAV); +console.log(MY_FAV); // 7 ``` -### 常量要求一个初始值 +### 定义对象和数组常量 -```js -// 报错 -// Uncaught SyntaxError: Missing initializer in const declaration +`const` 也适用于对象和数组。尝试覆盖该对象会引发错误“Assignment to constant variable”。 -const FOO; +```js example-bad +const MY_OBJECT = { key: "值" }; +MY_OBJECT = { OTHER_KEY: "值" }; ``` -### 常量可以定义成对象和数组 - -常量可以定义成对象和数组 +然而，对象的键不受保护，因此以下语句可以正常执行。 ```js -const MY_OBJECT = { key: "value" }; +MY_OBJECT.key = "其他值"; +``` -// 重写对象和上面一样会失败 -// Uncaught TypeError: Assignment to constant variable. -MY_OBJECT = { OTHER_KEY: "value" }; +你可能需要使用 {{jsxref("Object.freeze()")}} 来使对象不可变。 -// 对象属性并不在保护的范围内 -// 下面这个声明会成功执行 -MY_OBJECT.key = "otherValue"; // Use Object.freeze() to make object immutable +这对数据同样适用。尝试覆盖该数组会引发错误“Assignment to constant variable”。 -// 也可以用来定义数组 +```js example-bad const MY_ARRAY = []; -// 可以向数组填充数据 -MY_ARRAY.push("A"); // ["A"] -// 但是，将一个新数组赋给变量会引发错误 -// Uncaught TypeError: Assignment to constant variable. MY_ARRAY = ["B"]; ``` +同样地，数组的元素不受保护，因此以下语句可以正常执行。 + +```js +MY_ARRAY.push("A"); // ["A"] +``` + +### 带解构赋值的声明 + +每个 `=` 后面的左侧也可以是绑定模式。这允许一次创建多个变量。 + +```js +const result = /(a+)(b+)(c+)/.exec("aaabcc"); +const [, a, b, c] = result; +console.log(a, b, c); // "aaa" "b" "cc" +``` + +有关更多信息，请参阅[解构赋值](/zh-CN/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)。 + ## 规范 {{Specifications}}