From 405a749a6462d43bde473860583515018af23153 Mon Sep 17 00:00:00 2001 From: roboin <50550561+Robot-Inventor@users.noreply.github.com> Date: Sat, 31 Aug 2024 01:07:53 +0900 Subject: [PATCH 01/95] [ja] Fix typo --- .../html_features_for_accessibility/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/ja/learn/common_questions/design_and_accessibility/html_features_for_accessibility/index.md b/files/ja/learn/common_questions/design_and_accessibility/html_features_for_accessibility/index.md index d2eb9a11857aaf..5058e4da400dff 100644 --- a/files/ja/learn/common_questions/design_and_accessibility/html_features_for_accessibility/index.md +++ b/files/ja/learn/common_questions/design_and_accessibility/html_features_for_accessibility/index.md @@ -57,7 +57,7 @@ l10n: ## 画像の alt 属性 -すべての画像には [`alt`](/ja/docs/Web/HTML/Element/img#alt) 属性を設定すべきです。画像が純粋に装飾であり、文書のコンテンツやコンテキストに何の意味も与えない場合、 `alt` 属性は空ですが存在する必要があります。オプションとして、 [`role="presentation"`](/ja/docs/Web/Accessibility/ARIA/Roles/presentation_role) を追加することもできます。それ以外の画像ニはすべて `alt` 属性を設定し、他のコンテンツは読めても画像が見えないユーザーに役立つ方法で[画像を説明する代替テキスト](/ja/docs/Web/API/HTMLImageElement/alt#usage_notes)を提供すべきです。画像を読み込むことができない人に、画像をどのように説明するかを考えてみてください。それが `alt` 属性の値として記載すべき情報です。 +すべての画像には [`alt`](/ja/docs/Web/HTML/Element/img#alt) 属性を設定すべきです。画像が純粋に装飾であり、文書のコンテンツやコンテキストに何の意味も与えない場合、 `alt` 属性は空ですが存在する必要があります。オプションとして、 [`role="presentation"`](/ja/docs/Web/Accessibility/ARIA/Roles/presentation_role) を追加することもできます。それ以外の画像にはすべて `alt` 属性を設定し、他のコンテンツは読めても画像が見えないユーザーに役立つ方法で[画像を説明する代替テキスト](/ja/docs/Web/API/HTMLImageElement/alt#usage_notes)を提供すべきです。画像を読み込むことができない人に、画像をどのように説明するかを考えてみてください。それが `alt` 属性の値として記載すべき情報です。 ```html From e7c1d2c099bb4e7f1c2eaee7526f1fb25ea4e0bf Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 27 Aug 2024 23:19:37 +0900 Subject: [PATCH 02/95] =?UTF-8?q?2024/08/27=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../index.md | 20 ++++-- .../web/uri/fragment/text_fragments/index.md | 33 +++------ files/ja/web/uri/schemes/data/index.md | 68 ++++++++++--------- files/ja/web/uri/schemes/resource/index.md | 27 ++++---- 4 files changed, 70 insertions(+), 78 deletions(-) diff --git a/files/ja/web/uri/authority/choosing_between_www_and_non-www_urls/index.md b/files/ja/web/uri/authority/choosing_between_www_and_non-www_urls/index.md index 087e2d07c431ae..218a1bbda4c7f4 100644 --- a/files/ja/web/uri/authority/choosing_between_www_and_non-www_urls/index.md +++ b/files/ja/web/uri/authority/choosing_between_www_and_non-www_urls/index.md @@ -1,12 +1,13 @@ --- title: www 付きと www なしの URL の選択 slug: Web/URI/Authority/Choosing_between_www_and_non-www_URLs -original_slug: Web/HTTP/Basics_of_HTTP/Choosing_between_www_and_non-www_URLs +l10n: + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 --- -{{HTTPSidebar}} +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} -ウェブサイトの管理者の間で繰り返される質問が、www URL と非 www URL のどちらを選択するかです。このページでは、何が最良かについてアドバイスを提供します。 +ウェブサイトの管理者の間で繰り返される質問が、 'www' (`www.example.com`) のついた URL と非 'www' (`example.com`) URL のどちらを選択するかです。このページでは、何が最良かについてアドバイスを提供します。 ## ドメイン名とは何か @@ -17,7 +18,7 @@ HTTP の URL では、先頭の `http://` または `https://` に続く部分 ## では、自身のウェブサイトでどちらかを選択しなければならないのか - **はい**、ひとつを選択して維持しなければなりません。基準となる場所に応じてどちらを選択するかはあなた次第ですが、どちらかを選択したら、それを維持してください。それにより、ユーザーや検索エンジンから見てウェブサイトが首尾一貫したものになります。これは、常に選択したドメインにリンクする (ウェブサイト内で相対 URL を使用すれば、難しくはないでしょう)、および常に同じドメインへのリンクを (電子メールやソーシャルネットワークなどで) 共有することを含みます。 -- **いいえ**、二つ持つことができます。どちらが公式なドメインであるかについて、一貫性を持って矛盾しないことが重要です。**この公式なドメインは*正規名*と呼ばれます。** すべての絶対パスリンクで正規名を使用するべきです。しかし、それでも他のドメインを機能させることができます。HTTP ではどちらのドメインが正規のものであるかをユーザーや検索エンジンに対して明らかにするとともに、非正規のドメインが機能して想定したページを提供できるようにするための技術が 2 つあります。 +- **いいえ**、2 つ持つことができます。どちらが公式なドメインであるかについて、一貫性を持って矛盾しないことが重要です。**この公式なドメインは*正規名*と呼ばれます。** すべての絶対パスリンクで正規名を使用するべきです。しかし、それでも他のドメインを機能させることができます。HTTP ではどちらのドメインが正規のものであるかをユーザーや検索エンジンに対して明らかにするとともに、非正規のドメインが機能して想定したページを提供できるようにするための技術が 2 つあります。 従って、正規なドメインとしてひとつ選択してください! 以下の 2 つの技術によって、非正規のドメインも機能させることができます。 @@ -37,13 +38,15 @@ HTTP の URL では、先頭の `http://` または `https://` に続く部分 [HTML5 boilerplate project](https://github.com/h5bp/html5-boilerplate) に、[あるドメインから別のドメインへリダイレクトするように Apache を設定する方法](https://github.com/h5bp/html5-boilerplate/blob/7a22a33d4041c479d0962499e853501073811887/.htaccess#L219-L258) の例があります。 -### \ を使用する +### `` を使用する ページの正規のアドレスは何かを示す、専用の HTML {{HTMLElement("link")}} 要素をページに追加できます。これは人間向けのページリーダーには影響がありませんが、検索エンジンのクローラーに対してページが実際はどこにあるかを示します。この方法では検索エンジンが同じページで何度もインデックスを作成したり、重複したコンテンツやスパムであると判断されたり、検索エンジンの結果ページでページが排除されたりランクが下がったりすることがなくなります。 このようなタグを追加するときは両方のドメインで同じコンテンツを提供して、どの URL が正規であるかを検索エンジンに示します。先ほどの例では `http://www.example.org/whaddup` が `http://example.org/whaddup` と同じコンテンツを提供していますが、head に {{htmlelement("link")}} 要素を追加します: -`` +```html + +``` リダイレクトの場合と異なり、ブラウザーの履歴では非 www URL と www URL が独立した項目であるとみなします。 @@ -53,7 +56,10 @@ HTTP の URL では、先頭の `http://` または `https://` に続く部分 ## 状況を判断する -これは[自転車置き場](http://bikeshed.com/)問題と考えられる、とても主観的な話題です。もっと深く読んでみたいと思ったら、この件に関する[多くの](https://www.netlify.com/blog/2017/02/28/to-www-or-not-www/)[記事](https://www.wpbeginner.com/beginners-guide/www-vs-non-www-which-is-better-for-wordpress-seo/)をご覧ください。 +これは非常に主観的なトピックであり、[自転車置き場](https://bikeshed.com/)問題として考えることもできます。より深くお読みになりたい場合は、以下のリソースをご参照ください。 + +- [Options for bare domains](https://www.netlify.com/blog/2020/03/26/how-to-set-up-netlify-dns-custom-domains-cname-and-a-records/#options-for-bare-domains) (netlify.com, 2020) +- [WWW vs non-WWW – Which Is Better for WordPress SEO?](https://www.wpbeginner.com/beginners-guide/www-vs-non-www-which-is-better-for-wordpress-seo/) (wpbeginner.com, 2023) ## 関連情報 diff --git a/files/ja/web/uri/fragment/text_fragments/index.md b/files/ja/web/uri/fragment/text_fragments/index.md index 46fe5a2de863e7..9688f720bb40d6 100644 --- a/files/ja/web/uri/fragment/text_fragments/index.md +++ b/files/ja/web/uri/fragment/text_fragments/index.md @@ -3,9 +3,11 @@ title: テキストフラグメント slug: Web/URI/Fragment/Text_fragments original_slug: Web/Text_fragments l10n: - sourceCommit: c9cc38c3c3c342e2e952c1acd57f55e104c5bb06 + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 --- +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} + **テキストフラグメント**は、URL フラグメントの特定の構文を使用することにより、作成者が ID で注釈を付けなくても、ウェブ文書内のテキストの特定の部分に直接リンクできるようにするものです。対応しているブラウザーは、リンクされたテキストに注意を引く方法を自由に選べます。例えば、色の強調表示やページ上のコンテンツへのスクロールなどです。これは、ウェブコンテンツの作成者が、使用可能な ID が存在しなくても、制御下にない他のコンテンツに深くリンクすることができるため有益なものです。さらに、ユーザーが互いに交換するための、より効果的なコンテンツ共有リンクを生成するために使用することもできます。 ## 概念と使用方法 @@ -33,7 +35,7 @@ ID が変更または削除された場合、文書フラグメントは無視 テキストフラグメントは文書フラグメントと似た様式であり、URL の後にハッシュ記号 (`#`) を付けます。しかし、構文は多少異なります。 -``` +```url https://example.com#:~:text=[prefix-,]textStart[,textEnd][,-suffix] ``` @@ -93,7 +95,7 @@ https://example.com#:~:text=[prefix-,]textStart[,textEnd][,-suffix] ### 複数のテキストフラグメントが付いた URL -アンパサンド(`&`)文字で区切ることで、同じ URL で強調表示する複数のテキストフラグメントを指定することができます。 +アンパサンド (`&`) 文字で区切ることで、同じ URL で強調表示する複数のテキストフラグメントを指定することができます。 - [https://developer.mozilla.org/ja/docs/Web/HTML/Element/a#:~:text=リンクされた&text=扱う](/ja/docs/Web/HTML/Element/a#:~:text=リンクされた&text=扱う) は、テキスト文字列 `Causes` および `linked` のうち最初に出現するものにスクロールし強調表示します。 - [https://developer.mozilla.org/ja/docs/Web/HTML/Element/a#:~:text=リンク先%20URL,-の&text=非推奨の-,属性,属性](/ja/docs/Web/HTML/Element/a#:~:text=リンク先%20URL,-の&text=非推奨の-,属性,属性) は、2 つのテキストにスクロールし強調表示します。 @@ -125,27 +127,8 @@ https://example.com#:~:text=[prefix-,]textStart[,textEnd][,-suffix] ```js document.fragmentDirective; -``` - -以下のような構造を持つ {{domxref("FragmentDirective")}} オブジェクトインスタンスが返されるはずです。 - -```js -items: [ - { - prefix: "", - textStart: "Module Workers", - textEnd: "", - suffix: "support", - type: "text", - }, - { - prefix: "feedback on", - textStart: "usability", - textEnd: "", - suffix: "", - type: "text", - }, -]; +// 対応していれば、空の FragmentDirective オブジェクトを返す +// それ以外の場合は undefined ``` この機能は、現在は主に機能検出を目的としていますが、将来的には、翻訳ヒントなど他の情報を記載するために展開することができます。 @@ -174,4 +157,4 @@ items: [ ## 関連情報 -- [Boldly link where no one has linked before: Text Fragments](https://web.dev/text-fragments/) +- [Boldly link where no one has linked before: Text Fragments](https://web.dev/articles/text-fragments) diff --git a/files/ja/web/uri/schemes/data/index.md b/files/ja/web/uri/schemes/data/index.md index 69d930a1876e81..6eb7b9a7ce87da 100644 --- a/files/ja/web/uri/schemes/data/index.md +++ b/files/ja/web/uri/schemes/data/index.md @@ -1,42 +1,45 @@ --- title: データ URL slug: Web/URI/Schemes/data -original_slug: Web/HTTP/Basics_of_HTTP/Data_URLs +l10n: + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 --- -{{HTTPSidebar}} +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} -**データ URL** は `data:` スキームが先頭についた URL で、小さなファイルをインラインで文書に埋め込むことができます。以前、 WHATWG で取り下げられるまでは "data URIs" と呼ばれていました。 +**データ URL** は `data:` スキームが先頭についた URL で、小さなファイルをインラインで文書に埋め込むことができます。以前、 WHATWG で取り下げられるまでは「データ URI」と呼ばれていました。 > [!NOTE] -> 最近のブラウザーでは、データ URL はナビゲーションを担当する設定オブジェクトの起源を継承するのではなく、一意の不透明な起点として扱われます。 +> 最近のブラウザーでは、データ URL はナビゲーションを担当する設定オブジェクトのオリジンを継承するのではなく、一意の不透明なオリジンとして扱われます。 ## 構文 データ URL は接頭辞 (`data:`)、データの種類を示す [MIME タイプ](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types)、テキストではないデータである場合のオプションである `base64` トークン、データ自体の 4 つの部品で構成されます。 -``` +```plain data:[][;base64], ``` `mediatype` は [MIME タイプ](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types)で, 例えば `'image/jpeg'` で JPEG 画像を表します。省略時の既定値は `text/plain;charset=US-ASCII` です。 -データが文字ならば、そのまま埋め込めます (埋め込む文書タイプに応じて、適切な実体参照やエスケープを行なってください)。それ以外では `base64` を指定し、 base64 エンコードしたバイナリデータを埋め込みます。 MIME タイプについての詳しい情報は[こちら](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types)や[こちら](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)にあります。 +データに [RFC 3986 で予約文字として定義されている文字](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2)が含まれている場合、または空白文字、改行文字、その他の出力されない文字が含まれている場合は、それらの文字は{{Glossary("Percent-encoding", "パーセントエンコード")}}でエンコードする必要があります。 + +データが文字ならば、そのまま埋め込めます (埋め込む文書タイプに応じて、適切な実体参照やエスケープを行なってください)。それ以外では `base64` を指定し、 base64 エンコードしたバイナリーデータを埋め込みます。 MIME タイプについての詳しい情報は[こちら](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types)や[こちら](/ja/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)にあります。 例: -- `data:,Hello%2C%20World!` - - : 平易な text/plain データです。引用符や空白には[パーセントエンコーディング](/ja/docs/Glossary/percent-encoding) (URL エンコーディング) を使用します。また、 CSV データ (MIME タイプは "text/csv") もスプレッドシートの行を区切るための改行文字を保存するためにパーセントエンコーディングが必要です。 +- `data:,Hello%2C%20World%21` + - : text/plain データで `Hello, World!` です。なお、カンマは{{Glossary("Percent-encoding", "パーセントエンコード")}}で `%2C`となり、スペースは `%20` となります。 - `data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==` - : 同じ内容の base64 エンコード版 -- `data:text/html,%3Ch1%3EHello%2C%20World!%3C%2Fh1%3E` - - : `

Hello, World!

` という HTML 文書 -- `data:text/html,` - - : JavaScript のアラートを実行する HTML 文書。終了タグが必要ですので注意してください。 +- `data:text/html,%3Ch1%3EHello%2C%20World%21%3C%2Fh1%3E` + - : HTML 文書で `

Hello, World!

` +- `data:text/html,%3Cscript%3Ealert%28%27hi%27%29%3B%3C%2Fscript%3E` + - : HTML 文書で `` であり、JavaScript のアラートを実行する HTML 文書。終了タグが必要ですので注意してください。 ## データの base64 形式へのエンコード -Base64 はバイナリからテキストへのエンコード方法の集まりで、バイナリデータを 64 進数表現に変換することで ASCII 文字列形式にするものです。 ASCII 文字のみから成るため、 Base64 の文字列は一般に URL でも安全ですので、データ URL のデータのエンコードに利用することができます。 +Base64 は、バイナリーからテキストへエンコードする方式の総称で、バイナリーデータを {{Glossary("ASCII")}} 文字列形式へ、64 進表現に変換することで表します。URL 構文で許可されている文字（「URL セーフ」）のみで構成されているため、データ URL にバイナリーデータを安全にエンコードすることができます。Base64 は、URL で特別な意味を持つ可能性のある文字 `+` と `/` を使用することができます。データ URL には URL パス区間やクエリー引数がないため、このコンテキストではこのエンコード方式は安全です。 ### Javascript でのエンコード @@ -60,16 +63,16 @@ base64 a.txt>b.txt ### Microsoft Windows でのエンコード -Windows では、 [Convert.ToBase64String](https://docs.microsoft.com/ja-jp/dotnet/api/system.convert.tobase64string?view=net-5.0) を PowerShell で使用することで Base64 エンコードを行うことができます。 +Windows では、 [Convert.ToBase64String](https://learn.microsoft.com/ja-jp/dotnet/api/system.convert.tobase64string?view=net-5.0) を PowerShell で使用することで Base64 エンコードを行うことができます。 -``` +```plain [convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("hello")) # outputs to console: aGVsbG8= ``` 他にも、 GNU/Linux シェル ([WSL](https://ja.wikipedia.org/wiki/Windows_Subsystem_for_Linux) など) が `base64` ユーティリティを提供しています。 -``` +```bash bash$ echo -n hello | base64 # outputs to console: aGVsbG8= ``` @@ -78,44 +81,43 @@ bash$ echo -n hello | base64 この章では `data` の URL を作ったり使ったりするときに、よく起こる問題について述べます。 -``` -data:text/html,lots of text...

bottom?arg=val +```html +data:text/html,lots of text…

bottom?arg=val

``` これは次の内容の HTML リソースを表します。 -``` -lots of text...

bottom?arg=val +```html +lots of text… +

bottom?arg=val

``` - 構文 - : `data` URL の書式は非常に単純ですが、"データ" 部分の前にカンマを置くのを忘れがちです。忘れるとデータが正しく base64 形式にエンコードされません。 - HTML におけるフォーマット - - : `data` はファイル内でファイルを提供しますが、外側の文書に比べて幅がとても広くなる可能性があります。 URL としては、 `data` はホワイトスペース (改行、タブ、空白) で体裁を整えることができるはずですが、 [base64 エンコードをすると起こる問題](http://bugzilla.mozilla.org/show_bug.cgi?id=73026#c12) があります。 + - : `data` はファイル内でファイルを提供しますが、外側の文書に比べて幅がとても広くなる可能性があります。 URL としては、 `data` はホワイトスペース (改行、タブ、空白) で体裁を整えることができるはずですが、 [base64 エンコードをすると起こる問題](https://bugzil.la/73026#c12) があります。 - 長さの制限 - : ブラウザーは特定の最大長のデータに対応する必要はありません。たとえば、 Opera 11 ブラウザーでは URL が 65535 文字に制限されており、 `data` URL は 65529 文字に制限されています (65529 文字は、 MIME タイプを指定せずにプレーンの `data:` を使用した場合、ソースではなくエンコードされたデータの長さです)。Firefox 97 以降 では、最大 32MB の `data` URL がサポートされます (97 より前のバージョンでは、制限は約 256MB でした)。 Chromium は 512MB 以上の URL 、Webkit (Safari) は 2048MB 以上の URL をサポートしています。 - エラー処理の欠如 - : メディア内の不正な引数や、 `'base64'` の定義内の打ち間違いは無視され、何もエラーは出ません。 -- クエリ文字列のサポートの欠如、など - - : データ URL のデータ部分は不透明 (opaque) なので、データ URL と一緒にクエリ文字列 (`?parameter-data` という構文で表されるページ固有のパラメータ) を使うと、データ URL が表現するデータに単にクエリ文字列が含まれたものになります。 +- クエリー文字列のサポートの欠如、など + - : データ URL のデータ部分は不透明 (opaque) なので、データ URL と一緒にクエリー文字列 (`?parameter-data` という構文で表されるページ固有のパラメーター) を使うと、データ URL が表現するデータに単にクエリー文字列が含まれたものになります。 - セキュリティの課題 - : 多数のセキュリティ問題 (フィッシングなど) がデータ URL に関連付けられており、ブラウザーの最上位でそれらに移動しています。このような問題を軽減するために、Firefox 59+ (リリース版、Nightly/Beta は 58 以降) では `data:` URL へのトップレベルのナビゲーションがブロックされており、他のブラウザーがすぐに対応することを期待しています。詳細については、[Firefox 58 におけるデータ URL へのトップレベルナビゲーションのブロック](https://blog.mozilla.org/security/2017/11/27/blocking-top-level-navigations-data-urls-firefox-58/)を参照してください。 ## 仕様書 -| 仕様書 | 題名 | -| --------------- | --------------------- | -| {{RFC("2397")}} | The "data" URL scheme | +{{Specifications}} ## ブラウザーの互換性 -{{Compat}} +{{compat}} ## 関連情報 -- [Base64](/ja/docs/Glossary/Base64) -- [パーセントエンコーディング](/ja/docs/Glossary/percent-encoding) -- {{domxref("WindowBase64.atob","atob()")}} -- {{domxref("WindowBase64.btoa","btoa()")}} -- [CSS `url()`](/ja/docs/Web/CSS/uri) -- [URI](/ja/docs/Glossary/URI) +- {{Glossary("Base64")}} +- {{Glossary("Percent-encoding", "パーセントエンコーディング")}} +- {{domxref("WorkerGlobalScope.atob()", "atob()")}} +- {{domxref("WorkerGlobalScope.btoa()", "btoa()")}} +- CSS の {{CSSXref("url", "url()")}} +- {{Glossary("URI")}} diff --git a/files/ja/web/uri/schemes/resource/index.md b/files/ja/web/uri/schemes/resource/index.md index 421ffdaf992bd7..8b8d5b3c9fb5f9 100644 --- a/files/ja/web/uri/schemes/resource/index.md +++ b/files/ja/web/uri/schemes/resource/index.md @@ -1,34 +1,35 @@ --- title: リソース URL slug: Web/URI/Schemes/resource -original_slug: Web/HTTP/Basics_of_HTTP/Resource_URLs +l10n: + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 --- -{{HTTPSidebar}}{{non-standard_header}} +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}}{{non-standard_header}} `resource:` というスキームのプレフィックスが付いたリソース URL は、Firefox と Firefox のブラウザー拡張機能によってリソースを内部的に読み込むために使用されますが、情報の一部はブラウザーが接続するサイトでも利用できます。 ## 構文 -リソース URL は、接頭辞 (`resource:`) とロードするリソースを指す URL の 2 つの部分で構成されます。 +リソース URL は、接頭辞 (`resource:`) と読み込むするリソースを指す URL の 2 つの部分で構成されます。 -``` -resource:// +```url +resource:// ``` 例 -``` +```url resource://gre/res/svg.css ``` リソース URL ('->') に矢印がある場合は、最初のファイルが次のファイルにロードされたことを意味します。 -``` +```url resource:// -> ``` -より一般的な詳細については、[ウェブ上のリソースの識別](/ja/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web)を参照してください。 +より一般的な詳細については、[ウェブ上のリソースの識別](/ja/docs/Web/URI)を参照してください。 この記事では、組み込みのリソースを指すために Firefox が内部的に使用するリソース URI に焦点を当てます。 @@ -36,11 +37,11 @@ resource:// -> `resource:` URL によって共有される情報の一部はウェブサイトで利用できるため、ウェブページは内部スクリプトを実行し、デフォルトの設定を含む Firefox の内部リソースを調べることができます。 -たとえば、[Browserleaks のスクリプト](https://www.browserleaks.com/firefox)は、サイトで実行されている簡単なスクリプトでクエリが実行されたときに Firefox が表示する内容を強調表示します (コードは にあります)。 +たとえば、[Browserleaks のスクリプト](https://browserleaks.com/resource-urls)は、サイトで実行されている簡単なスクリプトでクエリーが実行されたときに Firefox が表示する内容を強調表示します（コードは にあります）。 ファイル firefox.js は、プリファレンス名と値を pref() 関数に渡します。 例えば、 -``` +```url http://searchfox.org/mozilla-central/rev/48ea452803907f2575d81021e8678634e8067fc2/browser/app/profile/firefox.js#575 ``` @@ -59,7 +60,7 @@ http://searchfox.org/mozilla-central/rev/48ea452803907f2575d81021e8678634e8067fc > [!NOTE] > ウェブと拡張機能の開発者がリソース URL をもう使用しようとしないことをお勧めします。彼らの使い方はうまくいきませんでした。そしてほとんどの使用法はこれ以上動作しません。 -## 仕様 +## 仕様書 resource: はどの仕様書にも定義されていません。 @@ -69,6 +70,6 @@ resource: は Firefox のみ対応 ## 関連情報 -- [ウェブ上のリソースの識別](/ja/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web) -- [URL とは何か](/ja/docs/Learn/Common_questions/What_is_a_URL) +- [ウェブ上のリソースの識別](/ja/docs/Web/URI) +- [URL とは何か](/ja/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL) - [IANA list of URI schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) (`resource:` is [covered here](https://www.iana.org/assignments/uri-schemes/prov/resource)) From b5d00bbfb50f96eaf84491d98b2bf966cb9a94ec Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 21:21:31 +0900 Subject: [PATCH 03/95] =?UTF-8?q?2024/08/27=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/uri/authority/index.md | 46 +++++++++++++++++++++++++++++ files/ja/web/uri/fragment/index.md | 38 ++++++++++++++++++++++++ 2 files changed, 84 insertions(+) create mode 100644 files/ja/web/uri/authority/index.md create mode 100644 files/ja/web/uri/fragment/index.md diff --git a/files/ja/web/uri/authority/index.md b/files/ja/web/uri/authority/index.md new file mode 100644 index 00000000000000..7788b2155fb6bb --- /dev/null +++ b/files/ja/web/uri/authority/index.md @@ -0,0 +1,46 @@ +--- +title: URI オーソリティ +slug: Web/URI/Authority +l10n: + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 +--- + +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} + +**オーソリティ**は URI の部分で、[スキーム](/ja/docs/Web/URI/Schemes)の後でパスより前に来る部分です。 最大 3 つの部分、すなわちユーザー情報、ホスト、ポート番号を持つことがあります。 + +## 構文 + +```url +host +host:port +user@host +user@host:port +``` + +- host + - : 通常、_host_ はリソースをホストするサーバーのドメイン名または IP アドレスです。ドメイン名は、DNS（ドメインネームシステム）を使用して IP アドレスに解決されます。 +- port {{optional_inline}} + - : _port_ は、サーバーがリクエストを待ち受けするポート番号を示す数字です。これはオプションであり、HTTP の場合は既定で 80、HTTPS の場合は 443 です。他にも、自分自身で既定値を定義したり、必須にしたりするスキームがあります。 +- user {{optional_inline}} + + - : ユーザーはオプションであり、認証目的で使用します。ウェブの URI では一般的に使用されません。 + + > [!WARNING] + > HTTP の URL にユーザー情報を直接記載することは、機密情報が公開される可能性があるため推奨されません。代わりに、HTTP 認証やセッション Cookie などの他の方法を使用することができます。フィッシングサイトでは、ユーザーをだますために、あたかもドメイン名であるかのように「ユーザー」部分が表示される、誤解を招く URL を表示することがあります。これは[セマンティック URL 攻撃](https://en.wikipedia.org/wiki/Semantic_URL_attack)という名前で知られています。 + +## 例 + +- `https://developer.mozilla.org` + - : ホストは `developer.mozilla.org` です。ポート番号は指定されていませんが、`https:` 経由でアクセスされた場合は既定で 443 になります。 +- `http://localhost:8080` + - : ホストは `localhost`、ポートは `8080` です。 `localhost` は特別なホスト名で、ブラウザーがローカルアドレス `127.0.0.1` に解決します。 +- `postgresql://postgres:admin123@db:5432` + - : ホストは `db`、ポートは `5432` です。また、ユーザー `postgres` とパスワード `admin123` を指定します。これは、PostgreSQL データベースに接続する際に使用することができます。 +- `https://cnn.example.com&story=breaking_news@10.0.0.1` + - : 信頼できるウェブサイトを指しているように見える、誤解を招く URL。しかし、ホスト名は `10.0.0.1` であり、`cnn.example.com&story=breaking_news` の部分は「ユーザー」です。 + +## 関連情報 + +- [URI](/ja/docs/Web/URI) +- [www 付きと www なしの URL の選択](/ja/docs/Web/URI/Authority/Choosing_between_www_and_non-www_URLs) diff --git a/files/ja/web/uri/fragment/index.md b/files/ja/web/uri/fragment/index.md new file mode 100644 index 00000000000000..08f1f6bfa30423 --- /dev/null +++ b/files/ja/web/uri/fragment/index.md @@ -0,0 +1,38 @@ +--- +title: URI フラグメント +slug: Web/URI/Fragment +l10n: + sourceCommit: 6b730e3cfdf0f51940b44efa71bd59c84ce76e71 +--- + +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} + +**フラグメント**は URI の最後の部分で、`#` の文字で始まる部分です。文書内のセクションや動画内の位置など、リソースの特定の部分を識別するために使用されます。フラグメントは、URI がリクエストされた際にサーバーに送信されることはありませんが、リソースが取得された後にクライアント（ブラウザーなど）によって処理されます。 + +## 構文 + +```url +#fragment +``` + +- fragment + + - : 任意の文字の並び。フラグメントの正確な形式は、リソース自体によって定義されます。例えば、以下のような一般的な例があります。 + + - HTML 文書内の場合は、要素の [`id`](/ja/docs/Web/HTML/Global_attributes/id) 属性となり、ブラウザーはその要素までスクロールします。 + - [テキストフラグメント](/ja/docs/Web/URI/Fragment/Text_fragments)の形にすることができます。`#:~:text=...` という形で形成され、ブラウザーが指定したテキストを強調表示します。 + - [メディアフラグメント](https://www.w3.org/TR/media-frags/)の形にすることができます。`#t=...` という形で形成され、その時点から動画または音声の再生を開始できます。 + +## 例 + +- `#構文` + - : ブラウザーに、文書内で `id="構文"` のついた要素（このページの場合は[構文](#構文)の見出し）にスクロールします。 +- `#:~:text=fragment` + - : ブラウザーは、文書内の [`fragment`](#:~:text=fragment) というテキストを強調表示します。 +- `#t=10,20` + - : 動画または音声は 10 秒目から再生されます。 + +## 関連情報 + +- [URI](/ja/docs/Web/URI) +- [テキストフラグメント](/ja/docs/Web/URI/Fragment/Text_fragments) From 72691ac9ca35419dae302c06b5d5e54fc8c1778c Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 21:34:41 +0900 Subject: [PATCH 04/95] =?UTF-8?q?2024/08/27=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=96=B0=E8=A6=8F=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/uri/schemes/index.md | 52 +++++++ files/ja/web/uri/schemes/javascript/index.md | 142 +++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 files/ja/web/uri/schemes/index.md create mode 100644 files/ja/web/uri/schemes/javascript/index.md diff --git a/files/ja/web/uri/schemes/index.md b/files/ja/web/uri/schemes/index.md new file mode 100644 index 00000000000000..614a5f54a4e38b --- /dev/null +++ b/files/ja/web/uri/schemes/index.md @@ -0,0 +1,52 @@ +--- +title: URI スキーム +slug: Web/URI/Schemes +l10n: + sourceCommit: 1a48b6abdd27e168c78edcf04a7a9f6a8e0fdc15 +--- + +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} + +URI スキームは、URI の最初の部分で、`:` 文字の前の部分です。これは、ブラウザーがリソースを取得する際に使用するプロトコルを示します。スキームは、URI の残りの部分の構造や解釈に影響を与える可能性があります。 + +## 構文 + +```url +protocol: +``` + +- protocol + - : 使用するプロトコルを識別する文字の列。英数字と、`+`、`-`、`.` の文字のみで構成する必要があります。一般的なスキームは下記です。 + - [`blob`](/ja/docs/Web/API/URL/createObjectURL_static) + - : 大規模なバイナリーオブジェクト (Binary Large Object)。メモリーに存在する大規模オブジェクトへのポインター + - [`data`](/ja/docs/Web/URI/Schemes/data) + - : URL に直接埋め込まれたデータ + - `file` + - : ホスト依存のファイル名 + - `ftp` + - : {{Glossary("FTP","File Transfer Protocol")}} + - `http` / `https` + - : Hyper text transfer protocol (Secure) ({{glossary("HTTP")}}/{{glossary("HTTPS")}}) + - [`javascript`](/ja/docs/Web/URI/Schemes/javascript) + - : URL に埋め込まれた JavaScript コード + - `mailto` + - : 電子メールアドレス + - [`resource`](/ja/docs/Web/URI/Schemes/resource) {{Non-standard_inline}} + - : Firefox および Firefox のブラウザー拡張機能でリソースを内部的に読み込む + - `ssh` + - : Secure shell + - `tel` + - : 電話 + - `urn` + - : Uniform Resource Names + - `view-source` + - : このリソースのソースコード + - `ws` / `wss` + - : [WebSocket 接続 (Secure)](/ja/docs/Web/API/WebSockets_API) + +## 関連情報 + +- [URI](/ja/docs/Web/URI) +- [Data URL](/ja/docs/Web/URI/Schemes/data) +- [リソース URL](/ja/docs/Web/URI/Schemes/resource) +- [IANA list of URI schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) diff --git a/files/ja/web/uri/schemes/javascript/index.md b/files/ja/web/uri/schemes/javascript/index.md new file mode 100644 index 00000000000000..dd3c335dac79f1 --- /dev/null +++ b/files/ja/web/uri/schemes/javascript/index.md @@ -0,0 +1,142 @@ +--- +title: "javascript: URL" +slug: Web/URI/Schemes/javascript +l10n: + sourceCommit: 1a48b6abdd27e168c78edcf04a7a9f6a8e0fdc15 +--- + +{{QuickLinksWithSubpages("/ja/docs/Web/URI")}} + +> [!WARNING] +> ウェブ上で `javascript:` URL を使用することは推奨されていません。これは、[`eval()`](/ja/docs/Web/JavaScript/Reference/Global_Objects/eval)を使用することによる影響と同様に、任意のコードが実行される可能性があるためです。また、通常のリンク動作とは異なるため、{{glossary("accessibility", "アクセシビリティ")}}が縮小する可能性があります。 + +**JavaScript URL**、つまり `javascript:` スキームを接頭辞とする URL は、ブラウザーがナビゲートしようとした際に JavaScript を実行する擬似的なナビゲーション対象として使用されます。 URL が文字列として評価された場合、HTML として扱われ、ブラウザーによってレンダリングされます。 + +## 構文 + +JavaScript URL は `javascript:` スキームで始め、JavaScript コードが続きます。 コードはスクリプトとして解釈されます。 + +```url +javascript: +``` + +例えば、`` 要素の `href` 属性を `javascript:` URL に設定すると、"Hello, world!" というコンテンツを持つ新しいページに移動します。 + +```html example-bad +クリックしてね + +``` + +なお、`javascript:` URL は履歴項目を作成しないため、前回ページに戻るには再読み込みする以外の方法はありません。 + +### `javascript:` URL をフォーム処理として使用 + +この例では、`
` 要素の `action` 属性を `javascript:` URL に設定し、送信するとメッセージが表示されるようにします。 + +```html example-bad + + + +
+``` + +これを行う代わりに、フォームを送信する `submit` イベントを待ち受けし、JavaScript で処理することを検討してください。 + +```html example-good +
+ + +
+ +``` + +### `javascript:` URL を iframe のソースとして使用 + +この例では、` + +``` + +その代わりに、`srcdoc` 属性を設定することを検討してください。 + +```html example-good + + +``` + +### `javascript:` URL を window.location で使用 + +この例では、`window.location` プロパティを `javascript:` URL に設定し、"Hello, world!" というコンテンツを含む新しいページに移動します。 + +```js example-bad +window.location = "javascript:'Hello world!'"; +``` + +これを行う代わりに、[DOM API](/ja/docs/Web/API/HTML_DOM_API) を使用してページコンテンツを変更することを検討してください。例えば次のようにします。 + +```js example-good +document.body.textContent = "Hello, world!"; +``` + +## 仕様書 + +{{Specifications}} + +## 関連情報 + +- [URI](/ja/docs/Web/URI) +- [コンテンツセキュリティポリシー (CSP)](/ja/docs/Web/HTTP/CSP) +- [IANA list of URI schemes](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) From f9d1c7b4cd46255f29ee1b6b5f548d4c5c34f664 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 22:28:50 +0900 Subject: [PATCH 05/95] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E7=BF=BB=E8=A8=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/navigatoruadata/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/files/ja/web/api/navigatoruadata/index.md b/files/ja/web/api/navigatoruadata/index.md index 907dd3bfc7582d..235844b3929bc9 100644 --- a/files/ja/web/api/navigatoruadata/index.md +++ b/files/ja/web/api/navigatoruadata/index.md @@ -2,14 +2,14 @@ title: NavigatorUAData slug: Web/API/NavigatorUAData l10n: - sourceCommit: bbecba9e7d688493adbdc37fc70e02d87adfe371 + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} -**`NavigatorUAData`** は{{domxref('User-Agent Client Hints API', 'ユーザーエージェントクライアントヒント API', "", 1)}} のインターフェイスで、ユーザーのブラウザーとオペレーティングシステムに関する情報を返します。 +**`NavigatorUAData`** は{{domxref("User-Agent Client Hints API", "ユーザーエージェントクライアントヒント API", "", "nocode")}} のインターフェイスで、ユーザーのブラウザーとオペレーティングシステムに関する情報を返します。 -このオブジェクトのインスタンスは {{domxref("Navigator.userAgentData")}} を呼び出すことによって返されます。そのため、このインターフェイスにはコンストラクターはありません。 +このオブジェクトのインスタンスは {{domxref("Navigator.userAgentData")}} または {{domxref("WorkerNavigator.userAgentData")}} を呼び出すことによって返されます。そのため、このインターフェイスにはコンストラクターはありません。 > [!NOTE] > 「高エントロピー」と「低エントロピー」という用語は、これらの値がブラウザーについて明らかにする情報の量を参照しています。プロパティとして返される値は、低エントロピーであり、ユーザーを特定する可能性が低いと判断されます。 {{domxref("NavigatorUAData.getHighEntropyValues()")}} によって返される値は、より多くの情報を明らかにする可能性があります。そのため、これらの値は {{jsxref("Promise")}} によって取得され、ブラウザーがユーザーの許可を要求したり、他のチェックを行ったりするための時間を確保することができます。 @@ -68,4 +68,4 @@ navigator.userAgentData ## 関連情報 -- [Improving user privacy and developer experience with User-Agent Client Hints](https://web.dev/user-agent-client-hints/) +- [Improving user privacy and developer experience with User-Agent Client Hints](https://developer.chrome.com/docs/privacy-security/user-agent-client-hints) From 12d015b23985ca3443c1d264a2be0f2f2af75d96 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 22:35:44 +0900 Subject: [PATCH 06/95] =?UTF-8?q?2023/11/09=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/navigatoruadata/mobile/index.md | 7 ++++--- files/ja/web/api/navigatoruadata/platform/index.md | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/files/ja/web/api/navigatoruadata/mobile/index.md b/files/ja/web/api/navigatoruadata/mobile/index.md index 51655d1db4310d..7c0c530379ef74 100644 --- a/files/ja/web/api/navigatoruadata/mobile/index.md +++ b/files/ja/web/api/navigatoruadata/mobile/index.md @@ -1,11 +1,12 @@ --- -title: NavigatorUAData.mobile +title: "NavigatorUAData: mobile プロパティ" +short-title: mobile slug: Web/API/NavigatorUAData/mobile l10n: - sourceCommit: 4b4638246aad5d39b9a2e5c572b179b4c39c0a84 + sourceCommit: ea68d8f5b27af9c11247dc7d8115c0cfa6bffd1b --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} **`mobile`** は {{domxref("NavigatorUAData")}} インターフェイスの読み取り専用プロパティで、この端末がモバイル端末であるかどうかを示す値を返します。 diff --git a/files/ja/web/api/navigatoruadata/platform/index.md b/files/ja/web/api/navigatoruadata/platform/index.md index 663ec455a80177..dc5bf66b6b9473 100644 --- a/files/ja/web/api/navigatoruadata/platform/index.md +++ b/files/ja/web/api/navigatoruadata/platform/index.md @@ -1,11 +1,12 @@ --- -title: NavigatorUAData.platform +title: "NavigatorUAData: platform プロパティ" +short-title: platform slug: Web/API/NavigatorUAData/platform l10n: - sourceCommit: 4b4638246aad5d39b9a2e5c572b179b4c39c0a84 + sourceCommit: ea68d8f5b27af9c11247dc7d8115c0cfa6bffd1b --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} **`platform`** は {{domxref("NavigatorUAData")}} インターフェイスの読み取り専用プロパティで、プラットフォームのブランド情報を返します。 From 696d07498c1afb4d42765423a89cec1601327934 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 22:44:44 +0900 Subject: [PATCH 07/95] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../gethighentropyvalues/index.md | 30 ++++++++++++------- .../web/api/navigatoruadata/tojson/index.md | 9 +++--- 2 files changed, 24 insertions(+), 15 deletions(-) diff --git a/files/ja/web/api/navigatoruadata/gethighentropyvalues/index.md b/files/ja/web/api/navigatoruadata/gethighentropyvalues/index.md index 5c7e07f4bee0b2..7b90d7b754ca9a 100644 --- a/files/ja/web/api/navigatoruadata/gethighentropyvalues/index.md +++ b/files/ja/web/api/navigatoruadata/gethighentropyvalues/index.md @@ -1,18 +1,19 @@ --- -title: NavigatorUAData.getHighEntropyValues() +title: "NavigatorUAData: getHighEntropyValues() メソッド" +short-title: getHighEntropyValues() slug: Web/API/NavigatorUAData/getHighEntropyValues l10n: - sourceCommit: b7556b71e1fc3e89057671b372871e9f33d3f0b8 + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} **`getHighEntropyValues()`** は {{domxref("NavigatorUAData")}} インターフェイスのメソッドで、ユーザーエージェントが返す _高エントロピー_ 値を格納した辞書オブジェクトで解決される {{jsxref("Promise")}} を返し案す。 > [!NOTE] > 「高エントロピー」「低エントロピー」という用語は、これらの値がブラウザーについて明らかにする情報の量を示します。 > プロパティとして返される値は、低エントロピーであり、ユーザーを特定する可能性は低いと判断されます。 -> {{domxref("NavigatorUAData.getHighEntropyValues()")}} が返す値は、より多くの情報を明らかにする可能性があります。 +> `getHighEntropyValues()` が返す値は、より多くの情報を明らかにする可能性があります。 > そのため、これらの値は {{jsxref("Promise")}} によって取得され、ブラウザーがユーザーの許可を求めたり、他のチェックを行ったりする時間を確保することができます。 ## 構文 @@ -29,10 +30,12 @@ getHighEntropyValues(hints) - `"architecture"` - `"bitness"` + - `"formFactor"` + - `"fullVersionList"` - `"model"` - `"platformVersion"` - `"uaFullVersion"` {{Deprecated_Inline}} - - `"fullVersionList"` + - `"wow64"` ### 返値 @@ -53,20 +56,25 @@ getHighEntropyValues(hints) - `bitness` - : アーキテクチャのビット数を格納した文字列。例えば `"32"` または `"64"` です。 なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダーでサーバーが明示的にリクエストした場合、 {{HTTPHeader("Sec-CH-UA-Bitness")}} ヘッダーでサーバーに送ることができます。 +- `formFactor` + - : 端末のフォームファクターを格納する文字列。例えば、`"Tablet"` または「VR」など。 + サーバーが {{HTTPHeader("Accept-CH")}} ヘッダーで明示的にリクエストした場合、この情報は {{HTTPHeader("Sec-CH-UA-Form-Factor")}} ヘッダーでサーバーに送信される可能性があることに注意してください。 +- `fullVersionList` + - : `"brand"` と `"version"` というプロパティを持つオブジェクトの配列で、それぞれブラウザー名とフルバージョンを表します。 + 例えば、 `{"brand": "Google Chrome", "version": "103.0.5060.134"}, {"brand": "Chromium", "version": "103.0.5060.134"}` です。 + サイトが修正されたブラウザーのリストに依存しないように、オブジェクトには意図的に不正な情報が含まれている場合があることにご注意ください。サーバーが {{HTTPHeader("Accept-CH")}} ヘッダーで明示的にリクエストした場合、この情報は {{HTTPHeader("Sec-CH-UA-Full-Version-List")}} ヘッダーでサーバーに送信される場合があります。 - `model` - : モバイル端末のモデルを格納した文字列。例えば `"Pixel 2XL"` です。機器がモバイル端末でない場合、または機器のモデルが不明な場合は `model` は `""` になります。 - なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダでサーバーが明示的にリクエストすれば、 {{HTTPHeader("Sec-CH-UA-Model")}} でサーバーに送信することができます。 + なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダーでサーバーが明示的にリクエストすれば、 {{HTTPHeader("Sec-CH-UA-Model")}} でサーバーに送信することができます。 - `platformVersion` - : プラットフォームのバージョンを格納した文字列。プラットフォーム名自体は、常に低エントロピーのヒント `platform` として利用することができます。例えば `"10.0"` です。 なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダーでサーバーが明示的にリクエストすれば、 {{HTTPHeader("Sec-CH-UA-Platform-Version")}} ヘッダーでサーバーに送ることができます。 - `uaFullVersion` {{Deprecated_Inline}} - : 完全なブラウザーバージョンを格納した文字列。例えば `"103.0.5060.134"` です。`fullVersionList` に取って代わられ、非推奨です。 なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダーでサーバーが明示的にリクエストした場合、 {{HTTPHeader("Sec-CH-UA-Full-Version")}} ヘッダーでサーバーに送ることができます。 -- `fullVersionList` - - : オブジェクトの配列であり、プロパティ `"brand"` と `"version"` はそれぞれブラウザー名とフルバージョンを表す。 - 例えば、 `{"brand": "Google Chrome", "version": "103.0.5060.134"}, {"brand": "Chromium", "version": "103.0.5060.134"}` です。 - オブジェクトによっては、サイトが固定されたブラウザーのリストに依存しないようにするため、意図的に無効な情報を格納している場合があることに注意してください。 - なお、この情報は、 {{HTTPHeader("Accept-CH")}} ヘッダーでサーバーが明示的にリクエストした場合、 {{HTTPHeader("Sec-CH-UA-Full-Version-List")}} ヘッダーでサーバーに送ることができます。 +- `wow64` + - : 64 ビット版の Windows 上でユーザーエージェントのバイナリーが 32 ビットモードで実行されているかどうかを示す論理値。 + この情報は、サーバーが {{HTTPHeader("Sec-CH-UA-WoW64")}} ヘッダーで明示的にリクエストした場合、{{HTTPHeader("Accept-CH")}} ヘッダーでサーバーに送信される可能性があります。 ### 例外 diff --git a/files/ja/web/api/navigatoruadata/tojson/index.md b/files/ja/web/api/navigatoruadata/tojson/index.md index 3bf7c499ed78c0..f90e9eaa7de27c 100644 --- a/files/ja/web/api/navigatoruadata/tojson/index.md +++ b/files/ja/web/api/navigatoruadata/tojson/index.md @@ -1,13 +1,14 @@ --- -title: NavigatorUAData.toJSON() +title: "NavigatorUAData: toJSON() メソッド" +short-title: toJSON() slug: Web/API/NavigatorUAData/toJSON l10n: - sourceCommit: b7556b71e1fc3e89057671b372871e9f33d3f0b8 + sourceCommit: cfb7587e3e3122630ad6cbd94d834ecadbe0a746 --- -{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}} +{{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}} -**`toJSON()`** は {{domxref("NavigatorUAData")}} インターフェイスのメソッドで、インターフェースは、 `NavigatorUAData` オブジェクトの低エントロピーのプロパティの JSON 表現を返す _シリアライザー_ です。 +**`toJSON()`** は {{domxref("NavigatorUAData")}} インターフェイスのメソッドで、インターフェイスは、 `NavigatorUAData` オブジェクトの低エントロピーのプロパティの JSON 表現を返す _シリアライザー_ です。 > [!NOTE] > 高エントロピーと低エントロピーという用語は、これらの値がブラウザーについて明らかにする情報の量を参照します。このメソッドで返される低エントロピーの値は、ユーザーを特定できるような情報を明らかにしない値です。高エントロピーの値は {{domxref("NavigatorUAData.getHighEntropyValues()")}} メソッドによってのみ返すことができます。 From 38c24031e837392176726c8fc6a7c569e7b06ea8 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 23:02:48 +0900 Subject: [PATCH 08/95] =?UTF-8?q?2024/04/02=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../web/api/network_information_api/index.md | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/files/ja/web/api/network_information_api/index.md b/files/ja/web/api/network_information_api/index.md index f455ccb98620ab..078f4916d6debb 100644 --- a/files/ja/web/api/network_information_api/index.md +++ b/files/ja/web/api/network_information_api/index.md @@ -2,22 +2,27 @@ title: ネットワーク情報 API slug: Web/API/Network_Information_API l10n: - sourceCommit: 4b4638246aad5d39b9a2e5c572b179b4c39c0a84 + sourceCommit: 895129fb017e0bb86c61f688d99ac4c5c75f4934 --- -{{DefaultAPISidebar("Network Information API")}}{{SeeCompatTable}} +{{DefaultAPISidebar("Network Information API")}} {{AvailableInWorkers}} -ネットワーク情報 API はシステムのネットワーク接続に関する情報を、一般的な接続の種類 ('wifi' や 'cellular' など) の観点から提供します。 +**ネットワーク情報 API** はシステムのネットワーク接続に関する情報を、一般的な接続の種類 ('wifi' や 'cellular' など) の観点から提供します。 これは、ユーザーの接続に基づき、高解像度コンテンツや低解像度コンテンツを選択するために使用することができます。 -API は単一の {{domxref("NetworkInformation")}} オブジェクトで構成されます。これは {{domxref("Navigator.connection")}} プロパティから返されるインスタンスです。 - -{{AvailableInWorkers}} +API は単一の {{domxref("NetworkInformation")}} オブジェクトで構成されます。これは {{domxref("Navigator.connection")}} または {{domxref("WorkerNavigator.connection")}} プロパティから返されるインスタンスです。 ## インターフェイス - {{domxref("NetworkInformation")}} - - : 端末がネットワーク通信に使用している接続方法の情報を提供します。また、接続の種類が変更された場合に、スクリプトへ通知する手段も提供します。 `NetworkInformation` インターフェイスはインスタンス化できません。代わりに、 {{domxref("Navigator")}} インターフェイスを通してアクセスします。 + - : 端末がネットワーク通信に使用している接続方法の情報を提供します。また、接続の種類が変更された場合に、スクリプトへ通知する手段も提供します。 `NetworkInformation` インターフェイスはインスタンス化できません。代わりに、 {{domxref("Navigator")}} または {{domxref("WorkerNavigator")}} インターフェイスを通してアクセスします。 + +### 他のインターフェイスの拡張 + +- {{domxref("Navigator.connection")}} {{ReadOnlyInline}} + - : 端末のネットワーク接続に関する情報を格納する {{domxref("NetworkInformation")}} オブジェクトを返します。 +- {{domxref("WorkerNavigator.connection")}} {{ReadOnlyInline}} + - : 端末のネットワーク接続に関する情報を格納する {{domxref("NetworkInformation")}} オブジェクトを提供します。 ## 例 @@ -40,7 +45,7 @@ navigator.connection.addEventListener("change", updateConnectionStatus); ### 大きなリソースを事前読み込み -接続オブジェクトは、大きな帯域幅やメモリが使われるリソースを事前読み込みするかどうか決める場合に便利です。以下の例は、ページの読み込み直後に呼び出され、動画の事前読み込みが望ましくない場合の接続の種類を確かめます。携帯電話回線接続が見つかると、 `preloadVideo` フラグは `false` に設定されます。コードをわかりやすくするために、この例ではひとつの接続の種類だけをテストしました。実際に使う場合には、 switch 文その他のやり方で、 {{domxref("NetworkInformation.type")}} の可能な値すべてを確かめることになるでしょう。 `type` の値にかかわらず、 {{domxref("NetworkInformation.effectiveType")}} プロパティを用いて接続速度を見積もることができます。 +接続オブジェクトは、大きな帯域幅やメモリーが使われるリソースを事前読み込みするかどうか決める場合に便利です。以下の例は、ページの読み込み直後に呼び出され、動画の事前読み込みが望ましくない場合の接続の種類を確かめます。携帯電話回線接続が見つかると、 `preloadVideo` フラグは `false` に設定されます。コードをわかりやすくするために、この例ではひとつの接続の種類だけをテストしました。実際に使う場合には、 switch 文その他のやり方で、 {{domxref("NetworkInformation.type")}} の可能な値すべてを確かめることになるでしょう。 `type` の値にかかわらず、 {{domxref("NetworkInformation.effectiveType")}} プロパティを用いて接続速度を見積もることができます。 ```js let preloadVideo = true; From 251b4e4cc333ad5188631e6b58382946622a7a43 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 23:23:01 +0900 Subject: [PATCH 09/95] =?UTF-8?q?2023/04/07=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/node/selectstart_event/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/files/ja/web/api/node/selectstart_event/index.md b/files/ja/web/api/node/selectstart_event/index.md index cbb634c6b9520b..d1a53672bea1ab 100644 --- a/files/ja/web/api/node/selectstart_event/index.md +++ b/files/ja/web/api/node/selectstart_event/index.md @@ -1,5 +1,6 @@ --- title: "Node: selectstart イベント" +short-title: selectstart slug: Web/API/Node/selectstart_event l10n: sourceCommit: 312081aabba3885b35a81107b3c2fc53428896c5 @@ -7,7 +8,7 @@ l10n: {{APIRef}} -**`selectstart`** は[選択 API](/ja/docs/Web/API/Selection) のイベントで、新しい選択範囲をユーザが指定した際に発行されます。 +**`selectstart`** は[選択 API](/ja/docs/Web/API/Selection) のイベントで、新しい選択範囲をユーザーが指定した際に発行されます。 イベントがキャンセルされた場合、選択範囲は変更されません。 From 929a5d93a5db09b144763eafe396bb98be990e77 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Mon, 2 Sep 2024 00:58:37 +0900 Subject: [PATCH 10/95] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20(#23294)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/26 時点の英語版に基づき更新 * Update index.md * Update index.md --- files/ja/web/api/notification/index.md | 40 ++++---- .../api/notification/notification/index.md | 91 ++++++++++++------- 2 files changed, 78 insertions(+), 53 deletions(-) diff --git a/files/ja/web/api/notification/index.md b/files/ja/web/api/notification/index.md index f8c8f706f6b591..c85cc70acba1a3 100644 --- a/files/ja/web/api/notification/index.md +++ b/files/ja/web/api/notification/index.md @@ -2,12 +2,12 @@ title: Notification slug: Web/API/Notification l10n: - sourceCommit: 571287e7fe2a51f8790c1dc717e5fb55ca60339d + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- -{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}} +{{APIRef("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}} -`Notification` は[通知 API](/ja/docs/Web/API/Notifications_API) のインターフェイスで、ユーザーへのデスクトップ通知の設定と表示に使われます。 +`Notification` は{{domxref("Notifications API", "通知 API", "", "nocode")}} のインターフェイスで、ユーザーへのデスクトップ通知の設定と表示に使われます。 これらの通知の表示方法や機能はプラットフォームによって異なりますが、一般にユーザーに対して非同期に情報を提供する方法を提供します。 @@ -20,9 +20,9 @@ l10n: ## 静的プロパティ -これらのプロパティは `Notification` オブジェクト自身のみで利用することができます。 +_親インターフェイスである {{domxref("EventTarget")}} から継承したプロパティもあります。_ -- {{domxref("Notification.permission")}} {{ReadOnlyInline}} +- {{domxref("Notification.permission_static", "Notification.permission")}} {{ReadOnlyInline}} - : 文字列で、通知の表示についての現在の権限を表します。取りうる値は次の通りです。 @@ -30,37 +30,37 @@ l10n: - `granted` —通知が表示されることをユーザーが受け入れた。 - `default` — ユーザーの選択が不明であるため、ブラウザーは値が denied であるかのように動作します。 -- {{domxref("Notification.maxActions")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("Notification.maxActions_static", "Notification.maxActions")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : 端末とユーザーエージェントが対応しているアクションの最大数。 ## インスタンスプロパティ -これらのプロパティは `Notification` オブジェクトのインスタンスでのみ使用可能です。 +_親インターフェイスである {{domxref("EventTarget")}} から継承したプロパティもあります。_ - {{domxref("Notification.actions")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : コンストラクターの `options` 引数で指定された、通知のアクションの配列です。 -- {{domxref("Notification.badge")}} {{ReadOnlyInline}} {{Experimental_Inline}} - - : 通知自体を表示する空間が充分にない場合に通知を表す画像の URL です。 +- {{domxref("Notification.badge")}} {{ReadOnlyInline}} + - : Android の通知バーなど、通知そのものを表示する空間が十分でない場合に通知を表す画像の URL を含む文字列。Android 端末では、バッジは最大4xの解像度、約 96 × 96 ピクセルの端末に対応する必要があり、画像は自動的にマスクされます。 - {{domxref("Notification.body")}} {{ReadOnlyInline}} - : コンストラクターの `options` 引数で指定された、通知の本文の文字列です。 - {{domxref("Notification.data")}} {{ReadOnlyInline}} - : 通知のデータの構造化されたクローンを返します。 - {{domxref("Notification.dir")}} {{ReadOnlyInline}} - : コンストラクターの `options` 引数で指定された、通知の書字方向です。 -- {{domxref("Notification.lang")}} {{ReadOnlyInline}} - - : コンストラクターの `options` 引数で指定された、通知の言語コードです。 -- {{domxref("Notification.tag")}} {{ReadOnlyInline}} - - : コンストラクターの `options` 引数で指定された、通知の ID です。 - {{domxref("Notification.icon")}} {{ReadOnlyInline}} - : コンストラクターの `options` 引数で指定された、通知のアイコンの画像 URL です。 - {{domxref("Notification.image")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : コンストラクターの `options` 引数で指定された、通知の一部として表示される画像の URL です。 +- {{domxref("Notification.lang")}} {{ReadOnlyInline}} + - : コンストラクターの `options` 引数で指定された、通知の言語コードです。 - {{domxref("Notification.renotify")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : 古い通知が新しい通知に置き換えられた後、ユーザーに通知するかどうかを指定します。 -- {{domxref("Notification.requireInteraction")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("Notification.requireInteraction")}} {{ReadOnlyInline}} - : 論理値で、ユーザーがクリックするか閉じるかするまで、通知が自動的に閉じずに残るべきであることを示します。 -- {{domxref("Notification.silent")}} {{ReadOnlyInline}} {{Experimental_Inline}} +- {{domxref("Notification.silent")}} {{ReadOnlyInline}} - : 静かに通知をするかどうかを明示します。つまり、端末の設定に関係なく、通知の際に無音やバイブレーションさせない状態を設定できます。 +- {{domxref("Notification.tag")}} {{ReadOnlyInline}} + - : コンストラクターの `options` 引数で指定された、通知の ID です。 - {{domxref("Notification.timestamp")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : 通知が生成されたとき、または適用されるとき (過去、現在、未来) の時刻を示します。 - {{domxref("Notification.title")}} {{ReadOnlyInline}} @@ -70,20 +70,22 @@ l10n: ## 静的メソッド -これらのメソッドは `Notification` オブジェクト自体に対してのみ使用できます。 +_親インターフェイスである {{domxref("EventTarget")}} から継承したメソッドもあります。_ -- {{domxref("Notification.requestPermission()")}} +- {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} - : ユーザーに通知を表示する許可をリクエストします。 ## インスタンスメソッド -これらのメソッドは `Notification` オブジェクトのインスタンス、または [`prototype`](/ja/docs/Web/JavaScript/Inheritance_and_the_prototype_chain) からのみ使用できます。 `Notification` オブジェクトは {{domxref("EventTarget")}} インターフェイスも継承しています。 +_親インターフェイスである {{domxref("EventTarget")}} から継承したメソッドもあります。_ - {{domxref("Notification.close()")}} - - : プログラムで通知を閉じます。 + - : プログラムで通知インスタンスを閉じます。 ## イベント +_親インターフェイスである {{domxref("EventTarget")}} から継承したイベントもあります。_ + - {{domxref("Notification.click_event", "click")}} - : ユーザーが通知をクリックするたびに発生します。 - {{domxref("Notification.close_event", "close")}} diff --git a/files/ja/web/api/notification/notification/index.md b/files/ja/web/api/notification/notification/index.md index 24114352283092..e902c42e131857 100644 --- a/files/ja/web/api/notification/notification/index.md +++ b/files/ja/web/api/notification/notification/index.md @@ -1,14 +1,17 @@ --- -title: Notification() +title: "Notification: Notification() コンストラクター" +short-title: Notification() slug: Web/API/Notification/Notification l10n: - sourceCommit: 2b8f5d9a29f00aea5d2edfa78d1fb90c51752858 + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- -{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}} +{{APIRef("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}} **`Notification()`** コンストラクターは、ユーザー通知を表す新しい {{domxref("Notification")}} オブジェクトのインスタンスを生成します。 +> **メモ:** {{domxref("ServiceWorkerGlobalScope")}} 内で `Notification()` コンストラクターを使用して通知を作成しようとすると、`TypeError` が発生します。代わりに {{domxref("ServiceWorkerRegistration.showNotification()")}} を使用してください。 + ## 構文 ```js-nolint @@ -24,48 +27,74 @@ new Notification(title, options) - : 通知に適用するカスタム設定を含むオプションオブジェクトです。使用できるオプションは以下のとおりです。 - - `dir` + - `dir` {{optional_inline}} - : 通知を表示する方向です。既定値は `auto` で、ブラウザーの言語設定の振る舞いが適用されますが、 `ltr` と `rtl` の値で振る舞いを上書きできます (ただし、ほとんどのブラウザーがこれらの設定を無視しているようですが)。 - - `lang` - - : {{RFC(5646, "言語を識別するタグ（BCP 47 とも）")}}を表す文字列を使って指定される通知の言語です。簡単なリファレンスとして [ISO 2 letter language codes](https://www.sitepoint.com/iso-2-letter-language-codes/) ページを参照してください。 - - `badge` + - `lang` {{optional_inline}} + - : {{RFC(5646, "言語を識別するタグ（BCP 47 とも）")}}を表す文字列を使って指定される通知の言語です。 + 簡単なリファレンスとして [ISO 2 letter language codes](https://www.sitepoint.com/iso-2-letter-language-codes/) ページを参照してください。 + 既定値は空文字列です。 + - `badge` {{optional_inline}} - : 文字列で、通知自体を表示する充分な空間がない場合に通知の表現に使用される画像の URL を指定します。 - - `body` + - `body` {{optional_inline}} - : 文字列で、タイトルの下側に表示される通知の本文を表します。 - - `tag` + 既定値は空文字列です。 + - `tag` {{optional_inline}} - : 通知のための識別タグを表す 文字列です。 - - `icon` + - `icon` {{optional_inline}} - : 通知の一部として表示されるアイコンのURLを含む文字列です。 - - `image` + - `image` {{optional_inline}} - : 文字列で、通知に表示される画像の URL を指定します。 - - `data` + - `data` {{optional_inline}} - : 通知に関連付ける任意のデータです。これはどのデータ型でも可能です。 - - `vibrate` - - : 通知が発生したときに端末のバイブレーションハードウェアに通知する[バイブレーションパターン](/ja/docs/Web/API/Vibration_API#vibration_patterns)です。 - - `renotify` - - : 古い通知が新しい通知に置き換えられた後、ユーザーに通知するかどうかを指定する論理値です。既定値は `false` で、通知しないことを意味します。 - - `requireInteraction` - - : 通知が自動的に閉じるのではなく、ユーザーがクリックするか解除するまでアクティブな状態を維持すべきであることを示します。既定値は `false` です。 - - `actions` + 既定値は `null` です。 + - `vibrate` {{optional_inline}} + - : 通知が発生したときに端末のバイブレーションハードウェアに通知する[バイブレーションパターン](/ja/docs/Web/API/Vibration_API#バイブレーションパターン)です。指定された場合、`silent` は `true` にできません。 + - `timestamp` {{optional_inline}} + - : 数値で、通知が作成された時点または適用される時点（過去、現在、未来）を表します。 + - `renotify` {{optional_inline}} + - : 古い通知が新しい通知に置き換えられた後、ユーザーに通知するかどうかを指定する論理値です。既定値は `false` で、通知しないことを意味します。`true` の場合、`tag` も設定する必要があります。 + - `requireInteraction` {{optional_inline}} + - : 通知が自動的に閉じるのではなく、ユーザーがクリックするか解除するまでアクティブな状態を維持すべきであることを示します。 + 既定値は `false` です。 + - `actions` {{optional_inline}} - : 通知で表示するアクションの配列です。配列内のそれぞれの要素は、以下のメンバーを持つオブジェクトです。 - - `action`: 通知上に表示されるユーザーアクションを特定する文字列。 - - `title`: ユーザーに表示するアクションテキストを含む文字列。 - - `icon`: アクションとともに表示されるアイコンの URL を含む文字列。 + - `action` + - : 通知上に表示されるユーザーアクションを特定する文字列。 + - `title` + - : ユーザーに表示するアクションテキストを含む文字列。 + - `icon` {{optional_inline}} + - : アクションとともに表示されるアイコンの URL を含む文字列。 適切なレスポンスは `event.action` を使用して {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "notificationclick")}} イベント内で構築されます。 - - `silent` - - : 通知をサイレントにするかどうかを指定する論理値です。端末の設定にかかわらず、音やバイブレーションを発しないようにします。既定値は `false` で、サイレントではないことを意味します。 + - `silent` {{optional_inline}} + - : 通知をサイレントにするかどうかを指定する論理値です。端末の設定にかかわらず、音やバイブレーションを発しないようにします。 + 既定値は `null` です。`true` の場合、 `vibrate` が存在してはいけません。 + +### 返値 + +{{domxref("Notification")}} オブジェクトのインスタンスです。 + +### 例外 + +- {{jsxref("TypeError")}} + - : 以下の場合に例外が発生します。 + - コンストラクターが {{domxref("ServiceWorkerGlobalScope")}} の中で呼び出された場合。 + - `actions` オプションが設定されており、空であった場合。 + - `silent` オプションが `true` で、`vibrate` オプションが指定されていた場合。 + - `renotify` オプションが `true` だが、`tag` オプションが空の場合。 +- `DataCloneError` {{domxref("DOMException")}} + - : 何らかの理由で `data` オプションのシリアライズに失敗した場合に発生します。 ## 例 -[`Emogotchi demo`](https://chrisdavidmills.github.io/emogotchi/)（[ソースコードを見る](https://github.com/chrisdavidmills/emogotchi)）では、私たちが通知を発生させたいときに、 `spawnNotification()` 関数を実行しています。関数は必要な本文、アイコン、タイトルを指定する引数を受け取り、必要な `options` オブジェクトを生成して、 `Notification()` コンストラクターを用いて通知を発生させます。 +この例は、その権限がすでに付与されている場合にのみ通知を表示させるという最も基本的なものです。より完全な例については、{{domxref("Notification")}} ページをご覧ください。 ```js -function spawnNotification(body, icon, title) { - const notification = new Notification(title, { body, icon }); +if (Notification.permission === "granted") { + const notification = new Notification("Hi there!"); } ``` @@ -81,13 +110,7 @@ function spawnNotification(body, icon, title) { Chrome 49 以降では、 incognito モードでは通知が動作しません。 -Android 版 Chrome は `Notification` コンストラクターを呼び出すと {{jsxref("TypeError")}} を発生させます。サービスワーカーからの通知の作成にのみ対応しています。詳しくは [Chromium issue tracker](https://bugs.chromium.org/p/chromium/issues/detail?id=481856) をご覧ください。 - -### Internet Explorer の注意事項 - -バージョン 38.14352 以降の MS Edge は通知 API に対応しています。 [Wikipedia - MS Edge](https://en.wikipedia.org/wiki/Microsoft_Edge#Release_history) - -IE 11 以前では対応していません。 +Android 版 Chrome は `Notification` コンストラクターを呼び出すと {{jsxref("TypeError")}} を発生させます。サービスワーカーからの通知の作成にのみ対応しています。詳しくは [Chromium issue tracker](https://crbug.com/481856) をご覧ください。 ## 関連情報 From 093791efe9f672f09247c23459bd5a7ae2d27ddb Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Wed, 28 Aug 2024 23:55:44 +0900 Subject: [PATCH 11/95] =?UTF-8?q?2024/03/06=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../web/api/notification/maxactions_static/index.md | 12 ++++++++---- .../web/api/notification/permission_static/index.md | 11 +++++++---- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/files/ja/web/api/notification/maxactions_static/index.md b/files/ja/web/api/notification/maxactions_static/index.md index 7d08cd3f84fe4b..a78b8714b8bc9c 100644 --- a/files/ja/web/api/notification/maxactions_static/index.md +++ b/files/ja/web/api/notification/maxactions_static/index.md @@ -1,15 +1,18 @@ --- -title: Notification.maxActions +title: "Notification: maxActions 静的プロパティ" +short-title: maxActions slug: Web/API/Notification/maxActions_static +l10n: + sourceCommit: e4c0939929e1b3e1fa3fd3da82b827fca3ed4c79 --- -{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{SecureContext_Header}}{{SeeCompatTable}} +{{APIRef("Web Notifications")}}{{SecureContext_Header}}{{SeeCompatTable}} {{AvailableInWorkers}} **`maxActions`** は {{domxref("Notification")}} インターフェイスの属性で、端末とユーザーエージェントが対応するアクションの最大数を返します。実質的には、これはユーザーエージェントが尊重する {{domxref("Notification.actions")}} 配列の最大数です。 ## 値 -整数で、ユーザ－エージェントと端末がユーザーに提示することができるできる通知アクションの最大数を示します。 +整数で、ユーザーエージェントと端末がユーザーに提示することができるできる通知アクションの最大数を示します。 ## 例 @@ -18,7 +21,7 @@ slug: Web/API/Notification/maxActions_static ```js const maxActions = Notification.maxActions; console.log( - `This device can display at most ${maxActions} actions on each notification.`, + `この端末はそれぞれの通知を ${maxActions} アクションずつ表示することができます。`, ); ``` @@ -33,3 +36,4 @@ console.log( ## 関連情報 - [通知 API の使用](/ja/docs/Web/API/Notifications_API/Using_the_Notifications_API) +- {{domxref("Notification.actions")}} diff --git a/files/ja/web/api/notification/permission_static/index.md b/files/ja/web/api/notification/permission_static/index.md index 5d14ca7214dee8..7b0a93daa14d47 100644 --- a/files/ja/web/api/notification/permission_static/index.md +++ b/files/ja/web/api/notification/permission_static/index.md @@ -1,9 +1,12 @@ --- -title: Notification.permission +title: "Notification: permission 静的プロパティ" +short-title: permission slug: Web/API/Notification/permission_static +l10n: + sourceCommit: e4c0939929e1b3e1fa3fd3da82b827fca3ed4c79 --- -{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}} +{{APIRef("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}} `permission` は {{domxref("Notification")}} インターフェイスの読み取り専用プロパティで、ユーザーが現在のオリジンに対してウェブ通知を表示することを許可したかどうか、現在の許可状態を表します。 @@ -60,5 +63,5 @@ function notifyMe() { - [通知 API](/ja/docs/Web/API/Notifications_API) - [通知 API の使用](/ja/docs/Web/API/Notifications_API/Using_the_Notifications_API) -- [許可 API](/ja/docs/Web/API/Permissions_API) -- [許可 API の使用](/ja/docs/Web/API/Permissions_API/Using_the_Permissions_API) +- [権限 API](/ja/docs/Web/API/Permissions_API) +- [権限 API の使用](/ja/docs/Web/API/Permissions_API/Using_the_Permissions_API) From 6751def36742b20aa119ebf0442de843cf34b0f4 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 2 Sep 2024 09:13:20 +0800 Subject: [PATCH 12/95] zh-CN: create Glossary/CardDAV (#23349) --- files/zh-cn/glossary/carddav/index.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 files/zh-cn/glossary/carddav/index.md diff --git a/files/zh-cn/glossary/carddav/index.md b/files/zh-cn/glossary/carddav/index.md new file mode 100644 index 00000000000000..8c6cf530003aa1 --- /dev/null +++ b/files/zh-cn/glossary/carddav/index.md @@ -0,0 +1,15 @@ +--- +title: CardDAV +slug: Glossary/CardDAV +l10n: + sourceCommit: ada5fa5ef15eadd44b549ecf906423b4a2092f34 +--- + +{{GlossarySidebar}} + +**CardDAV**（{{Glossary("WebDAV")}} 的 vCard 拓展）是由 {{Glossary("IETF")}} 标准化，用于远程访问或共享{{glossary("server", "服务器")}}上的联系人信息的{{glossary("protocol", "协议")}}。 + +## 参见 + +- 维基百科上的 [CardDAV](https://zh.wikipedia.org/wiki/CardDAV) +- [RFC 6352：基于 Web 的分布式编写和版本控制（WebDAV）的 vCard 拓展](https://datatracker.ietf.org/doc/html/rfc6352) From 3f77773cef6c619029fb3a149822deafe480ea69 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 2 Sep 2024 09:37:16 +0800 Subject: [PATCH 13/95] zh-CN: create Glossary/Credential (#23339) --- files/zh-cn/glossary/credential/index.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 files/zh-cn/glossary/credential/index.md diff --git a/files/zh-cn/glossary/credential/index.md b/files/zh-cn/glossary/credential/index.md new file mode 100644 index 00000000000000..1ec7b755b467b7 --- /dev/null +++ b/files/zh-cn/glossary/credential/index.md @@ -0,0 +1,23 @@ +--- +title: 凭证 +slug: Glossary/Credential +l10n: + sourceCommit: 66afe9b59c609043c91e51487cfcecaecbbadb3d +--- + +{{GlossarySidebar}} + +**凭证**是一种使系统能够做出{{glossary("authentication", "认证")}}决策的对象：例如，决定是否将用户登录到帐户中。 + +在 Web 安全中，凭证的类型包括： + +- 密码 +- 生物识别数据 +- 从一次性短信代码中输入的令牌 +- 用于在公钥系统中进行认证断言的密钥，例如 [Web 认证](/zh-CN/docs/Web/API/Web_Authentication_API) + +[凭证管理 API](/zh-CN/docs/Web/API/Credential_Management_API) 让开发者能够创建、存储和检索各种类型的凭证。 + +## 参见 + +- {{rfc("4949", "互联网安全术语")}} From c226fe7875bfaee00c4b0aad4ff09c027a405113 Mon Sep 17 00:00:00 2001 From: 720 <71604450+T34-active@users.noreply.github.com> Date: Mon, 2 Sep 2024 15:27:50 +0800 Subject: [PATCH 14/95] [zh-cn]: update the translation of `Window.top` property (#23255) Co-authored-by: A1lo --- files/zh-cn/web/api/window/top/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/files/zh-cn/web/api/window/top/index.md b/files/zh-cn/web/api/window/top/index.md index d25072eedcdc31..6801c57c113f3d 100644 --- a/files/zh-cn/web/api/window/top/index.md +++ b/files/zh-cn/web/api/window/top/index.md @@ -1,23 +1,23 @@ --- -title: Window.top +title: Window：top 属性 slug: Web/API/Window/top +l10n: + sourceCommit: cc070123f72376faec06e36622c4fc723a75325f --- {{APIRef}} -返回窗口层级最顶层窗口的引用。 +返回对窗口层次结构中最顶层窗口的引用。 -## 语法 +## 值 -```plain -var topWindow = window.top; -``` +对最顶层窗口的引用。 ## 备注 -[`window.parent`](/zh-CN/DOM/window.parent) 返回当前窗口的直接父对象，而 {{domxref("window.top")}} 返回最顶层的窗口对象。 +{{domxref("window.parent")}} 属性返回当前窗口的直接父窗口，而 `window.top` 返回窗口对象层次结构中的最顶层窗口。 -当你在处理父窗口的子框架（subframe），而你想获取顶层框架时，这个属性相当有用。 +此属性在处理位于父窗口或多个父窗口的子框架中的窗口时特别有用，可以用来获取顶级框架集。 ## 规范 From e530604d2e28f4a27b4a8cfc23315a8dde822046 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 2 Sep 2024 15:28:39 +0800 Subject: [PATCH 15/95] zh-CN: create Glossary/RDF (#23325) Co-authored-by: A1lo --- files/zh-cn/glossary/rdf/index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 files/zh-cn/glossary/rdf/index.md diff --git a/files/zh-cn/glossary/rdf/index.md b/files/zh-cn/glossary/rdf/index.md new file mode 100644 index 00000000000000..175d4bb05351d4 --- /dev/null +++ b/files/zh-cn/glossary/rdf/index.md @@ -0,0 +1,14 @@ +--- +title: RDF +slug: Glossary/RDF +l10n: + sourceCommit: ada5fa5ef15eadd44b549ecf906423b4a2092f34 +--- + +{{GlossarySidebar}} + +**RDF**（资源描述框架）是 W3C 开发的一种用于在万维网（例如网页）上表示信息的语言。RDF 提供了一种对资源信息进行编码的标准方式，以便在应用程序之间以完全自动化的方式交换这些信息。 + +## 参见 + +- 维基百科上的[资源描述框架](https://zh.wikipedia.org/wiki/資源描述框架) From ce208f4c45081bc0b8c75b5b0d4a12dd61a53144 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Mon, 2 Sep 2024 15:30:47 +0800 Subject: [PATCH 16/95] zh-CN: create Glossary/ICANN (#23340) --- files/zh-cn/glossary/icann/index.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 files/zh-cn/glossary/icann/index.md diff --git a/files/zh-cn/glossary/icann/index.md b/files/zh-cn/glossary/icann/index.md new file mode 100644 index 00000000000000..dab0dd116abd42 --- /dev/null +++ b/files/zh-cn/glossary/icann/index.md @@ -0,0 +1,15 @@ +--- +title: ICANN +slug: Glossary/ICANN +l10n: + sourceCommit: ada5fa5ef15eadd44b549ecf906423b4a2092f34 +--- + +{{GlossarySidebar}} + +**ICANN**（互联网名称与数字地址分配机构）是负责维护{{glossary("DNS", "域名系统")}}和 {{glossary("IP address", "IP 地址")}}的记录的国际非营利组织。 + +## 参见 + +- [官网](https://www.icann.org/) +- 维基百科上的 [ICANN](https://zh.wikipedia.org/wiki/互联网名称与数字地址分配机构) From fd01f7fca650da4237e507deba66de4b5a41d456 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Sep 2024 11:31:34 +0000 Subject: [PATCH 17/95] build(deps): bump lint-staged from 15.2.9 to 15.2.10 (#23360) --- package.json | 2 +- yarn.lock | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/package.json b/package.json index b79f4667626215..e4ca526859b517 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,7 @@ "fdir": "^6.3.0", "front-matter": "^4.0.2", "husky": "9.1.5", - "lint-staged": "15.2.9", + "lint-staged": "15.2.10", "markdown-it": "^14.1.0", "markdownlint-cli2": "0.13.0", "markdownlint-rule-search-replace": "1.2.0", diff --git a/yarn.lock b/yarn.lock index 5023b205142872..0163dc95b2571f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -530,10 +530,10 @@ linkify-it@^5.0.0: dependencies: uc.micro "^2.0.0" -lint-staged@15.2.9: - version "15.2.9" - resolved "https://registry.yarnpkg.com/lint-staged/-/lint-staged-15.2.9.tgz#bf70d40b6b192df6ad756fb89822211615e0f4da" - integrity sha512-BZAt8Lk3sEnxw7tfxM7jeZlPRuT4M68O0/CwZhhaw6eeWu0Lz5eERE3m386InivXB64fp/mDID452h48tvKlRQ== +lint-staged@15.2.10: + version "15.2.10" + resolved "https://registry.yarnpkg.com/lint-staged/-/lint-staged-15.2.10.tgz#92ac222f802ba911897dcf23671da5bb80643cd2" + integrity sha512-5dY5t743e1byO19P9I4b3x8HJwalIznL5E1FWYnU6OWw33KxNBSLAc6Cy7F2PsFEO8FKnLwjwm5hx7aMF0jzZg== dependencies: chalk "~5.3.0" commander "~12.1.0" @@ -541,7 +541,7 @@ lint-staged@15.2.9: execa "~8.0.1" lilconfig "~3.1.2" listr2 "~8.2.4" - micromatch "~4.0.7" + micromatch "~4.0.8" pidtree "~0.6.0" string-argv "~0.3.2" yaml "~2.5.0" @@ -880,10 +880,10 @@ micromatch@4.0.5: braces "^3.0.2" picomatch "^2.3.1" -micromatch@^4.0.4, micromatch@~4.0.7: - version "4.0.7" - resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.7.tgz#33e8190d9fe474a9895525f5618eee136d46c2e5" - integrity sha512-LPP/3KorzCwBxfeUuZmaR6bG2kdeHSbe0P2tY3FLRU4vYrjYz5hI4QZwV0njUx3jeuKe67YukQ1LSPZBKDqO/Q== +micromatch@^4.0.4, micromatch@~4.0.8: + version "4.0.8" + resolved "https://registry.yarnpkg.com/micromatch/-/micromatch-4.0.8.tgz#d66fa18f3a47076789320b9b1af32bd86d9fa202" + integrity sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA== dependencies: braces "^3.0.3" picomatch "^2.3.1" From 83048b452d9b8b912ad746104caffb0504d04171 Mon Sep 17 00:00:00 2001 From: familyboat <84062528+familyboat@users.noreply.github.com> Date: Mon, 2 Sep 2024 20:12:02 +0800 Subject: [PATCH 18/95] zh-cn: update the translation of the Web/Tutorials index page (#23306) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: A1lo --- files/zh-cn/web/tutorials/index.md | 237 ++++++++++++++++------------- 1 file changed, 128 insertions(+), 109 deletions(-) diff --git a/files/zh-cn/web/tutorials/index.md b/files/zh-cn/web/tutorials/index.md index 6d76265f93899a..52aa78b5dc12ed 100644 --- a/files/zh-cn/web/tutorials/index.md +++ b/files/zh-cn/web/tutorials/index.md @@ -1,126 +1,145 @@ --- title: 教程 slug: Web/Tutorials +l10n: + sourceCommit: b8a0743ca8b1e1b1b1a95cc93a4413c020f11262 --- -本页面上的链接通向各式各样的入门指导和培训教材。不管你是仅仅开始入门、学过些基础或者是个网站开发老手，你都能在这里找到有用的资源加以绝佳的练习。 +本页面涵盖着各式各样的教程和练习资料的链接。不管你是才入门，还是了解基础，抑或是 Web 开发老手，在这都能找到实用的最佳练习资源。 -这些资源都来自卓有远见的公司和乐于接受开放标准网站开发人员。这是网站开发的绝佳练习而且使用一种开放内容授权，比如[知识共享许可协议](https://www.mozilla.org/foundation/licensing/website-content.html)来提供并允许进行翻译。 +这些资源由卓有远见的公司和 Web 开发者创建（他们采用开放标准和最佳实践来开发 Web），并且这些资源通过知识共享（Creative Commons）等开放内容许可来提供且允许进行翻译 -## 对于学习 Web 的新手 +## 面向学习 Web 的纯新手 -[开始学习 Web](/zh-CN/docs/Learn/Getting_started_with_the_web) +- [Web 入门](/zh-CN/docs/Learn/Getting_started_with_the_web) + - : *Web 入门*是一套简明的，介绍 Web 开发实践的系列文章。你会安装构建简单网页和发布简单代码所需的工具。 -一系列介绍帮助你开始学习 Web 开发。你需要准备工具去创建一个简单的网页并发布你自己简单的代码。 +## HTML 教程 -## HTML 入门 +### 初级 -### 初级课程 - -- [HTML 简介](/zh-CN/docs/Learn/HTML/Introduction_to_HTML) - - : HTML 是什么，干什么，以及其简要历史，还有一个 HTML 文档的结构是什么样子的。其后的文章会更深入 HTML 的每一个部分。 -- [网页的基本构架](http://reference.sitepoint.com/html/page-structure) _（由出版社提供）_ - - : 学习 HTML 元素是如何组装在一起从而构成一个更大的图块的。 +- [介绍 HTML](/zh-CN/docs/Learn/HTML/Introduction_to_HTML) + - : 本模块分为几个阶段：熟悉重要的概念和语法、在文本中应用 HTML、创建超链接、使用 HTML 构建网页。 - [MDN 的 HTML 元素参考](/zh-CN/docs/Web/HTML/Element) - - : 一个 HTML 元素综合性性参考，还有不同浏览器对它们的支持。 -- [HTML 挑战](http://wikiversity.org/wiki/Web_Design/HTML_Challenges)_（来自维基大学）_ - - : 参与这些挑战来巩固你的 HTML 技能。（例如，“我到底是应该使用一个 \

元素还是用 \ 呢？”）专注于有意义的小点滴。 - -### 高级课程 - -- [编写出能够快速加载 HTML 页面的小贴士](/zh-CN/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages) - - : 优化网页，以减少你的 Web 服务器上的负载和网络连接和为游客提供一个响应迅速的网站。 -- [HTML5 入门](http://www.html5rocks.com/tutorials/)_（HTML5 Rocks）_ - - : 通过指南来指导使用 HTML5 特征来写代码。 -- [HTML5 语法](http://www.alistapart.com/articles/semanticsinhtml5/) _(分开的列表)_ - - : 学习那些可扩展和向后和向前兼容的有意义的标签语法。 -- [Canvas 入门](/zh-CN/docs/Canvas_tutorial) - - : 学习如何使用脚本和 canvas 标签来画图。 -- [HTML5 博士](http://html5doctor.com/) - - : HTML5 应用前线上的文章。 -- [HTML5 声音标签的乐趣](http://www.elated.com/articles/html5-audio/)_（兴趣勃勃啊）_ - - : 学习如何使用 HTML audio 标签简简单单地来把声音文件放到你的网页里去。在这里包含了很多代码范例。 - -## Javascript 入门 - -### 初级课程 - -- [Codecademy](http://www.codecademy.com/) *（*来自 Codecademy 网站*）* - - : Codecademy 是学习如何编写 JavaScript 最容易的方式。它互动、有趣，你能够和你的朋友们一起来学习。 -- [开始使用 JavaScript](/zh-CN/docs/Learn/Getting_started_with_the_web/JavaScript_basics) - - : JavaScript 是什么以及它如何帮助你？ -- [JavaScript 最佳实践](http://dev.opera.com/articles/view/javascript-best-practices/) _（来自 WebPlatform.org 网站）_ - - : 学习一些明显或者不是很明显的编写 JavaScript 最佳实践。 -- [CodeAvengers](http://codeavengers.com/)_（来自 CodeAvengers.com 网站）_ - - : Code Avengers（代码复仇者联盟）是一个有趣且高效的学习使用 HTML, CSS, and JavaScript 编写网络 apps 和游戏代码的好地方。 - -### 中级课程 - -- [JavaScript 再深入](/zh-CN/docs/Web/JavaScript/Language_overview) - - : 针对于中等水平的开发者的关于 Javascript 编程语言的一个回顾。 -- [Eloquent JavaScript](http://eloquentjavascript.net/contents.html) - - : 一本中级和高级 JavaScript 使用方法的全面指南。（译者注：简体中文版《JavaScript 编程精解》已由机械工业出版社华章公司出版发行） -- [必要的 JavaScript 设计模式](http://www.addyosmani.com/resources/essentialjsdesignpatterns/book/) _(Addy Osmani)_ - - : 介绍基本的 JavaScript 设计模式。 -- [JavaScript 编程语言](http://www.yuiblog.com/blog/2007/01/24/video-crockford-tjpl/) _(YUI Blog)_ - - : Douglas Crockford 探讨了如今这个语言的情况，还有如何来实现。 + - : 完整的 HTML 元素参考以及不同浏览器的兼容性信息。 +- [用 HTML 创建简单的网页](https://www.theblogstarter.com/html-for-beginners/) + - : 一篇面向初学者的 HTML 指南——解释常见的标签，其中包含 HTML 标签。同时包含一篇带代码示例的分步指南——创建基础的网页。 +- [HTML 挑战](https://wikiversity.org/wiki/Web_Design/HTML_Challenges) + - : 这些挑战会打磨你的 HTML 技巧（例如，应该使用 \

元素还是 \ 元素？）——专注有意义的标记。 -### 高级课程 +### 中级 -- [JavaScript 指南](/zh-CN/docs/Web/JavaScript/Guide) - - : 一个为所有的学习者从初级到高级的全面、定期更新的 JavaScript 指南。 -- [学习高级别的 JavaScript](http://ejohn.org/apps/learn/) _(John Resig)_ - - : John Resig 的高级 JavaScript 指南。 -- [介绍 JavaScript DOM](http://www.elated.com/articles/javascript-dom-intro/) (Elated) - - : DOM 是什么，以及为什么有用？这篇文章将向你介绍 Javascript 这一强大功能。 -- [一个麻烦的 API : DOM 理论](http://yuiblog.com/blog/2006/10/20/video-crockford-domtheory/) (YUI Blog) - - : Douglas Crockford 解释文件对象模型。 -- [Javascript 进阶](http://yuiblog.com/blog/2006/11/27/video-crockford-advjs/) (YUI Blog) - - : Douglas Crockford 审视代码的模式，以便程序员在创建应用的时候可以选择。 -- [JavaScript 花园](http://bonsaiden.github.com/JavaScript-Garden/) - - : 关于 Javascript 最古怪部分的资料。 -- [非阻塞 JavaScript 加载](http://yuiblog.com/blog/2008/07/22/non-blocking-scripts/) (YUI Blog) - - : 提高含 Javascript 页面加载性能的一些提示。 - -## CSS 入门 - -### 初级课程 - -- [CSS 入门](/zh-CN/docs/Learn/Getting_started_with_the_web/CSS_basics) - - : 这个教程向你介绍层叠样式表（CSS），通过具体的实例引导你熟悉基本的 CSS 功能，你可以试着在自己电脑上练习这些实例。 -- [CSS 类选择器](http://en.wikiversity.org/wiki/Web_Design/CSS_Classes) (来自维基大学) - - : 在 CSS 里类是什么？ -- [外部 CSS](http://en.wikiversity.org/wiki/Web_Design/External_CSS) (来自维基大学) - - : 从外部样式表使用 CSS。 -- [添加一点样式](https://www.w3.org/MarkUp/Guide/Style) (W3C) - - : 入门介绍使用 CSS 样式化网页。 -- [常见 CSS 问题](/zh-CN/docs/Learn/CSS/Howto/CSS_FAQ) - - : 初学者一些常见问题和解答。 -- [代码复仇者](http://codeavengers.com/) (CodeAvengers.com) - - : 代码复仇者用有趣、高效的方式学习使用 HTML，CSS，JavaScript 开发 Web 应用和游戏。 - -### 中级课程 +- [多媒体和嵌入](/zh-CN/docs/Learn/HTML/Multimedia_and_embedding) + - : 本模块探索了在网页中如何使用 HTML 嵌入多媒体，包含：不同的嵌入图像的方法，以及嵌入视频、音频，甚至完整的其它网页的方式。 +- [HTML 表格](/zh-CN/docs/Learn/HTML/Tables) + - : 在网页中以一种{{glossary("Accessibility", "易懂的")}}的方式展示表格数据是个挑战。本模块涵盖的内容是：基本的表格标记，以及复杂一点的特性（诸如标题和摘要）。 + +### 高级 + +- [HTML 表单](/zh-CN/docs/Learn/Forms) + - : 表单是 Web 中非常重要的一部分——其提供了网站交互所需的很多功能，例如，注册、登录、发送反馈、购买产品，等等。在本模块中你会学习如何创建客户端表单。 +- [让 HTML 页面加载快的技巧](/zh-CN/docs/Learn/HTML/Howto/Author_fast-loading_HTML_pages) + - : 网页优化能为用户提供一个响应更好的站点，能减少 Web 服务器和互联网连接的加载时间。 + +## CSS 教程 + +### 初级 + +- [CSS 基础](/zh-CN/docs/Learn/Getting_started_with_the_web/CSS_basics) + - : CSS（层叠样式表）用于为网页添加样式。*CSS 基础*将带你了解入门所需的内容。本文回答了如下问题：如何把文本变成黑色或者红色？怎么将内容显示到屏幕上的特定位置？怎么用背景图像或者颜色装饰网页？ +- [CSS 第一步](/zh-CN/docs/Learn/CSS/First_steps) + - : CSS（层叠样式表）用于为网页添加样式，对网页进行布局——例如，修改内容的字体、颜色、大小和间距，将内容分成多列，或添加动画和其它装饰特性。在前往掌握 CSS 基础知识（CSS 的运作方式，CSS 语法是什么样子，在 HTML 中如何使用 CSS 添加样式）的道路上，本模块是一个很好的开始。 +- [CSS 构建块](/zh-CN/docs/Learn/CSS/Building_blocks) + + - : 本模块承接 [CSS 入门](/zh-CN/docs/Learn/CSS/First_steps)——这时你已经熟悉 CSS 语言及其语法、有了基本的使用经验，是时候再深入一些。在本模块中，你会学习层叠和继承、可用的选择器类型、单位、大小、为背景和边框添加样式、调试，以及其它内容。 + + 本文的目的是，在了解诸如[为文本添加样式](/zh-CN/docs/Learn/CSS/Styling_text)和 [CSS 布局](/zh-CN/docs/Learn/CSS/CSS_layout)等特定领域的知识之前，提供一个能让你编写合格 CSS 的工具集并帮助你理解基本的理论。 + +- [选择器](/zh-CN/docs/Learn/CSS/Building_blocks/Selectors) + + - : 用 CSS 定位 HTML 元素，其中包含带状态的元素。 +- [优先级](/zh-CN/docs/Web/CSS/Specificity) + + - : 通过[优先级测验](https://estelle.github.io/CSS/selectors/exercises/specificity.html)了解浏览器算法在遇到存在冲突的 CSS 声明时会决定将哪个声明应用到元素上。 + +- [层叠与继承](/zh-CN/docs/Learn/CSS/Building_blocks/Cascade_and_inheritance) + + - : 层叠、优先级和继承决定了 CSS 会如何应用于 HTML 中，以及如何解决样式声明冲突。 + +- [为文本添加样式](/zh-CN/docs/Learn/CSS/Styling_text) + - : 本文介绍了为文本添加样式的基础知识，包括：设置字体、加粗、斜体、行间距、字间距、阴影和其它文本特性。在本模块中，还会学习的内容有：在页面中应用自定义字体、为列表和链接添加样式。 +- [CSS 常见问题](/zh-CN/docs/Learn/CSS/Howto/CSS_FAQ) + - : 面向初学者的常见问题和回答。 + +### 中级 + +- [CSS 布局](/zh-CN/docs/Learn/CSS/CSS_layout) + - : 看到这儿，你已经学习过 CSS 基础知识、如何为文本添加样式、如何为放置内容的盒子添加样式并操纵它。现在，是时候学习参照视口或另一个盒子时如何将盒子放置在正确的位置。必要的前置知识已经具备，此时你可以深入 CSS 布局，学习不同的显示设置、传统的布局方式（使用浮动和定位）、新发明的布局工具（如弹性盒）。 - [CSS 参考](/zh-CN/docs/Web/CSS/Reference) - - : CSS 完整参考，包含 Firefox 和另外浏览器支持的详细信息。 -- [CSS 挑战](http://en.wikiversity.org/wiki/Web_Design/CSS_challenges) (维基大学) - - : 让你的 CSS 技巧更灵活，看你是否需要更多的练习。 -- [中级 CSS 概念](http://www.html.net/tutorials/css/) (HTML.net) - - : 分组，伪类等等。 -- [CSS 定位 101](http://www.alistapart.com/articles/css-positioning-101/) (A List Apart) - - : 使用符合标准的定位，无表布局。 -- [CSS 渐进增强](http://www.alistapart.com/articles/progressiveenhancementwithcss/) (A List Apart) - - : 把 CSS 渐进增强结合到你的网页。 -- [流体网格](http://www.alistapart.com/articles/fluidgrids/) (A List Apart) - - : 设计根据浏览器窗口自适应布局，同时使用一个字体网格。 - -### 高级课程 - -- [应用 CSS 转换](/zh-CN/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) - - : 使用 CSS 旋转、倾斜、缩放和变换。 + - : 完整的 CSS 参考，以及火狐和其它浏览器的兼容性信息。 +- [流式网格](https://alistapart.com/article/fluidgrids/) + - : 设计一种能随着浏览器窗口大小变化而流畅地调整大小的布局，且仍使用排版网格。 +- [CSS 挑战](https://en.wikiversity.org/wiki/Web_Design/CSS_challenges) + - : 展示你的 CSS 技巧，看看哪些地方还需要加强练习。 + +### 高级 + +- [使用 CSS 变换](/zh-CN/docs/Web/CSS/CSS_transforms/Using_CSS_transforms) + - : 用 CSS 实现旋转、倾斜、缩放和平移。 - [CSS 过渡](/zh-CN/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) - - : CSS 过渡是 CSS3 草案规范的一部分，提供了渐变动画来改变 CSS 属性，而不是突变生效。 -- [应用网页字体快速指南 - 使用 @font-face](http://www.html5rocks.com/tutorials/webfonts/quick/) (HTML5 Rocks) - - : 来自 CSS3 的 @font-face 功能，允许你以可访问的，可操作的，易扩展的方式使用 web 上的自定义字体。 -- [开始写 CSS](http://davidwalsh.name/starting-css) (David Walsh) - - : 介绍工具和方法来写更简洁，易维护和可扩展的 CSS。 + - : CSS 过渡提供一种以动画的形式来改变 CSS 属性的方式，而非让改变立即生效。 +- [Canvas 教程](/zh-CN/docs/Web/API/Canvas_API/Tutorial) + - : 学习如何使用画布元素和脚本绘制图形。 + +## JavaScript 教程 + +### 初级 + +- [JavaScript 第一步](/zh-CN/docs/Learn/JavaScript/First_steps) + - : 在第一个 JavaScript 模块中，你会了解一些基础知识，例如，JavaScript 是什么、JavaScript 是什么样、JavaScript 能做什么。然后你会体验初次编写 JavaScript。紧接着，你会详细地学习一些关键的 JavaScript 特性，例如，变量、字符串、数字和数组。 +- [创建 JavaScript 代码块](/zh-CN/docs/Learn/JavaScript/Building_blocks) + - : 在本模块中，你会继续学习关键的 JavaScript 基础特性，注意力会转向常见的代码块类型，例如，条件语句、循环、函数和事件。这些概念在课程中早已见过，但只是一扫而过——这里会明确地讨论这些概念。 +- [开始学习 JavaScript](/zh-CN/docs/Learn/Getting_started_with_the_web/JavaScript_basics) + - : JavaScript 是什么、JavaScript 如何帮助你？ +- [Codecademy](https://www.codecademy.com/) + - : 在 Codecademy 学习如何编写 JavaScript 很容易。Codecademy 提供了交互界面，你可以和你的朋友一起学。 +- [freeCodeCamp](https://www.freecodecamp.org/learn) + - : freeCodeCamp 教授大量的语言和 Web 开发框架。还有对应的[论坛](https://forum.freecodecamp.org/)、[互联网电台](https://coderadio.freecodecamp.org)和[博客](https://www.freecodecamp.org/news)。 + +### 中级 + +- [介绍 JavaScript 对象](/zh-CN/docs/Learn/JavaScript/Objects) + - : 在 JavaScript 中，对象普遍存在，从核心 JavaScript 特性（如字符串和数组）到构建于 JavaScript 之上的浏览器 API。你甚至可以自己创建对象，将相关的函数和变量高效地封装起来。如果你想深入了解 JavaScript 并编写更高效的代码，那么理解 JavaScript 的面向对象的特性非常重要。本模块会讲解这方面的知识。你会学习对象理论和语法的细节，学习如何创建对象，学习 JSON 数据是什么以及如何使用 JSON。 +- [客户端 Web API](/zh-CN/docs/Learn/JavaScript/Client-side_web_APIs) + - : 为网站或应用编写客户端 JavaScript 代码时，如果不使用 API——操纵浏览器和站点的运行环境所处的操作系统的各个方面的接口或甚至是来自其它网站或服务的数据，你将寸步难行。在本模块中，你会学习 API 是什么、如何使用一些在开发工作中最常见的 API。 +- [JavaScript 编程精解](https://eloquentjavascript.net/) + - : 中高级 JavaScript 方法论的综合指南。 +- [大话 JavaScript](https://exploringjs.com/es5/) + - : 面向想又快又好地学习 JavaScript 的程序员，也面向想提升技能或寻找特定主题的 JavaScript 程序员。 +- [基本的 JavaScript 设计模式](https://addyosmani.com/resources/essentialjsdesignpatterns/book/) + - : 介绍基本的 JavaScript 设计模式。 +- [JavaScript.info——现代 JavaScript 教程](https://zh.javascript.info/) + - : 卷一：语言。卷二：在浏览器中如何使用 JavaScript。 + +### 高级 + +- [JavaScript 指南](/zh-CN/docs/Web/JavaScript/Guide) + - : 一份全面且经常更新的 JavaScript 指南，面向从初级到高级的学习者。 +- [你不了解 JS](https://github.com/getify/You-Dont-Know-JS) + - : 深入 JavaScript 语言核心机制的系列书籍。 +- [JavaScript 花园](https://github.com/BonsaiDen/JavaScript-Garden) + - : JavaScript 中最古怪部分的文档。 +- [探索 ES6](https://exploringjs.com/es6/) + - : 和 ECMAScript 2015 相关的靠谱且有深度的信息。 +- [JavaScript 模式](https://github.com/chuanxshi/javascript-patterns) + - : JavaScript 模式和反模式合集：涵盖函数模式、jQuery 模式、jQuery 插件模式、设计模式、通用模式、字面量和构造函数模式、对象创建模式、代码复用模式、DOM。 +- [浏览器的工作方式](https://web.dev/articles/howbrowserswork) + - : 一篇详细的研究文章：内容涵盖不同的现代浏览器、引擎、页面渲染等等。 +- [JavaScript 视频](https://github.com/bolshchikov/js-must-watch) + - : 必看的 JavaScript 视频合集。 + +### 扩展开发 + +- [Web 扩展](/zh-CN/docs/Mozilla/Add-ons/WebExtensions) + - : Web 扩展是一种用于开发浏览器附加组件的跨浏览器系统。很大程度上，该系统与谷歌 Chrome 和 Opera 支持的[扩展 API](https://developer.chrome.com/docs/extensions/reference/) 是兼容的。为这些浏览器编写的扩展在大多数情况下[仅需一点改动](https://extensionworkshop.com/documentation/develop/porting-a-google-chrome-extension/)就能在火狐或[微软 Edge](https://docs.microsoft.com/archive/microsoft-edge/legacy/developer/) 上运行。这些 API 与[多进程版本的火狐](https://wiki.mozilla.org/Firefox/multiprocess)也完全兼容。 From 77aecfd04e286494e0b18a258e51430f14a80d53 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 29 Aug 2024 22:44:29 +0900 Subject: [PATCH 19/95] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- files/ja/web/api/notificationevent/index.md | 39 ++++++++++++--------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/files/ja/web/api/notificationevent/index.md b/files/ja/web/api/notificationevent/index.md index 7b8bb924b7ffcd..0d9779d6f69f45 100644 --- a/files/ja/web/api/notificationevent/index.md +++ b/files/ja/web/api/notificationevent/index.md @@ -1,40 +1,43 @@ --- title: NotificationEvent slug: Web/API/NotificationEvent +l10n: + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- -{{APIRef("Web Notifications")}} +{{APIRef("Web Notifications")}}{{AvailableInWorkers("service")}} -{{domxref("ServiceWorkerGlobalScope.onnotificationclick", "onnotificationclick")}} ハンドラーに渡される引数である `NotificationEvent` インターフェイスは、 {{domxref("ServiceWorker")}} の {{domxref("ServiceWorkerGlobalScope")}} で配信される通知クリックイベントを表します。 +**`NotificationEvent`** は{{domxref("Notifications API", "通知 API", "", "nocode")}}のインターフェイスで、サービスワーカー ({{domxref("ServiceWorker")}}) の {{domxref("ServiceWorkerGlobalScope")}} で配信される通知イベントを表します。 このインターフェイスは {{domxref("ExtendableEvent")}} インターフェイスを継承しています。 +> **メモ:** {{domxref("ServiceWorkerGlobalScope")}} オブジェクトで発行される持続的な通知イベントのみが、`NotificationEvent`インターフェイスを実装します。{{domxref("Notification")}} オブジェクトで発行される非持続的な通知イベントは、`Event`インターフェイスを実装します。 + +{{InheritanceDiagram}} + ## コンストラクター - {{domxref("NotificationEvent.NotificationEvent","NotificationEvent()")}} - : 新しい `NotificationEvent` オブジェクトを作成します。 -## プロパティ +## インスタンスプロパティ -_祖先である {{domxref("Event")}} からプロパティを継承しています。_ +_親インターフェイスである {{domxref("ExtendableEvent")}} から継承したプロパティもあります。_ -- {{domxref("NotificationEvent.notification")}} {{readonlyInline}} +- {{domxref("NotificationEvent.notification")}} {{ReadOnlyInline}} - : イベントを発生させるためにクリックされた通知を表す {{domxref("Notification")}} オブジェクトを返します。 -- {{domxref("NotificationEvent.action")}} {{readonlyinline}} +- {{domxref("NotificationEvent.action")}} {{ReadOnlyInline}} - : ユーザーがクリックした通知ボタンの文字列 ID を返します。ユーザーがアクションボタン以外の場所で通知をクリックした場合、または通知にボタンがない場合、この値は空の文字列を返します。 -## メソッド +## インスタンスメソッド -_親の {{domxref("ExtendableEvent")}} からメソッドを継承しています。_ - -- {{domxref("ExtendableEvent.waitUntil", "ExtendableEvent.waitUntil()")}} - - : イベントの存続期間を延長します。作業が進行中であることをブラウザーに伝えます。 +_親インターフェイスである {{domxref("ExtendableEvent")}} から継承したメソッドもあります。_ ## 例 ```js -self.addEventListener("notificationclick", function (event) { - console.log("On notification click: ", event.notification.tag); +self.addEventListener("notificationclick", (event) => { + console.log(`On notification click: ${event.notification.tag}`); event.notification.close(); // これは、現在のページが既に開いているかどうかを確認し、 @@ -44,10 +47,9 @@ self.addEventListener("notificationclick", function (event) { .matchAll({ type: "window", }) - .then(function (clientList) { - for (var i = 0; i < clientList.length; i++) { - var client = clientList[i]; - if (client.url == "/" && "focus" in client) return client.focus(); + .then((clientList) => { + for (const client of clientList) { + if (client.url === "/" && "focus" in client) return client.focus(); } if (clients.openWindow) return clients.openWindow("/"); }), @@ -59,6 +61,9 @@ self.addEventListener("notificationclick", function (event) { {{Specifications}} +> [!NOTE] +> このインターフェイスは[通知 API](/ja/docs/Web/API/Notifications_API) で定義されていますが、{{domxref("ServiceWorkerGlobalScope")}} を通してアクセスします。 + ## ブラウザーの互換性 {{Compat}} From 835bcfff5b919583af5ac026c86d8cff61c2c0fd Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Thu, 29 Aug 2024 22:50:40 +0900 Subject: [PATCH 20/95] =?UTF-8?q?2024/04/12=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../web/api/notificationevent/action/index.md | 4 +-- .../notificationevent/notification/index.md | 30 +++++++++--------- .../notificationevent/index.md | 31 +++++++++++++------ 3 files changed, 39 insertions(+), 26 deletions(-) diff --git a/files/ja/web/api/notificationevent/action/index.md b/files/ja/web/api/notificationevent/action/index.md index c35f70a71e65e4..2bed4db1ce953e 100644 --- a/files/ja/web/api/notificationevent/action/index.md +++ b/files/ja/web/api/notificationevent/action/index.md @@ -3,10 +3,10 @@ title: "NotificationEvent: action プロパティ" short-title: action slug: Web/API/NotificationEvent/action l10n: - sourceCommit: 212e53bbdaf88af59a57ec1f335bde5e828b68c5 + sourceCommit: 28848ba41c082db2a8c55e85c804bd06363afb57 --- -{{APIRef("Web Notifications")}} +{{APIRef("Web Notifications")}}{{AvailableInWorkers("service")}} **`action`** は {{domxref("NotificationEvent")}} インターフェイスの読み取り専用プロパティで、ユーザーがクリックした通知ボタンの文字列 ID を返します。ユーザーがアクションボタン以外の場所で通知をクリックした場合、または通知にボタンがない場合、この値は空の文字列を返します。通知 ID は、アクション配列属性を介した通知の作成中に設定され、通知が置き換えられない限り変更することはできません。 diff --git a/files/ja/web/api/notificationevent/notification/index.md b/files/ja/web/api/notificationevent/notification/index.md index 671446e111e3d2..ba7a928f3abc6b 100644 --- a/files/ja/web/api/notificationevent/notification/index.md +++ b/files/ja/web/api/notificationevent/notification/index.md @@ -1,11 +1,14 @@ --- -title: NotificationEvent.notification +title: "NotificationEvent: notification プロパティ" +short-title: notification slug: Web/API/NotificationEvent/notification +l10n: + sourceCommit: 28848ba41c082db2a8c55e85c804bd06363afb57 --- -{{APIRef("Web Notifications")}} +{{APIRef("Web Notifications")}}{{AvailableInWorkers("service")}} -`notification` は {{domxref("NotificationEvent")}} インターフェイスの読取専用プロパティで、クリックされてイベントを発行した {{domxref("Notification")}} のインスタンスを返します。 {{domxref("Notification")}} は `tag` や `data` 属性など、 Notification のインスタンス化時に設定された多くのプロパティへの読み取り専用アクセスを提供しており、あとで `notificationclick` イベントで使用するための情報を保存することができます。 +**`notification`** は {{domxref("NotificationEvent")}} インターフェイスの読み取り専用プロパティで、クリックされてイベントを発行した {{domxref("Notification")}} のインスタンスを返します。 {{domxref("Notification")}} は `tag` や `data` 属性など、 Notification のインスタンス化時に設定された多くのプロパティへの読み取り専用アクセスを提供しており、あとで `notificationclick` イベントで使用するための情報を保存することができます。 ## 返値 @@ -14,26 +17,25 @@ slug: Web/API/NotificationEvent/notification ## 例 ```js -self.addEventListener("notificationclick", function (event) { +self.addEventListener("notificationclick", (event) => { console.log("On notification click"); - // Data can be attached to the notification so that you - // can process it in the notificationclick handler. - console.log("Notification Tag:", event.notification.tag); - console.log("Notification Data:", event.notification.data); + // 通知にデータを添付することで、notificationclick ハンドラーで + // 処理することができる + console.log(`通知タグ: ${event.notification.tag}`); + console.log(`通知データ: ${event.notification.data}`); event.notification.close(); - // This looks to see if the current is already open and - // focuses if it is + // これは、すでに開いているかどうかを調べて、開いている場合は + // フォーカスする event.waitUntil( clients .matchAll({ type: "window", }) - .then(function (clientList) { - for (var i = 0; i < clientList.length; i++) { - var client = clientList[i]; - if (client.url == "/" && "focus" in client) return client.focus(); + .then((clientList) => { + for (const client of clientList) { + if (client.url === "/" && "focus" in client) return client.focus(); } if (clients.openWindow) return clients.openWindow("/"); }), diff --git a/files/ja/web/api/notificationevent/notificationevent/index.md b/files/ja/web/api/notificationevent/notificationevent/index.md index 229447893068f1..c9ce1aced63d80 100644 --- a/files/ja/web/api/notificationevent/notificationevent/index.md +++ b/files/ja/web/api/notificationevent/notificationevent/index.md @@ -1,31 +1,42 @@ --- -title: NotificationEvent.NotificationEvent() +title: "NotificationEvent: NotificationEvent() コンストラクター" +short-title: NotificationEvent() slug: Web/API/NotificationEvent/NotificationEvent +l10n: + sourceCommit: 28848ba41c082db2a8c55e85c804bd06363afb57 --- -{{APIRef("Web Notifications")}} +{{APIRef("Web Notifications")}}{{AvailableInWorkers("service")}} **`NotificationEvent()`** コンストラクターは、新しい {{domxref("NotificationEvent")}} オブジェクトを生成します。 ## 構文 -``` -var myNotificationEvent = new NotificationEvent(type, NotificationEventInit); +```js-nolint +new NotificationEvent(type, options) ``` ### 引数 - `type` - - : TBD -- `NotificationEventInit` {{optional_inline}} - - : イベントが配信される通知として使用される {{domxref("Notification")}} オブジェクトを含む辞書オブジェクト。この仕様書の後の草稿では、このパラメータはオプションではありません。 + - : イベントの名前の文字列。 + 大文字と小文字が区別され、ブラウザーでは `notificationclick` または `notificationclose` に設定します。 +- `options` + - : オブジェクトで、_{{domxref("ExtendableEvent/ExtendableEvent", "ExtendableEvent()")}} で定義されているプロパティに加え_、以下のプロパティを持つことができます。 + - `notification` + - : イベントが配信される際に通知として使用する {{domxref("Notification")}} オブジェクト。 + - `action` {{optional_inline}} + - : 通知に関連付けられたアクション。既定では `""` です。 + +### 返値 + +新しい {{domxref("NotificationEvent()")}} オブジェクトです。 ## 例 ```js -var n = new Notification("Hello"); -var init = { notification: n }; -var myNotificationEvent = new NotificationEvent(type, init); +const n = new Notification("Hello"); +const myNotificationEvent = new NotificationEvent(type, { notification: n }); ``` ## 仕様書 From 933dc7719230fa2d4d5f2aa3836e693e85558c25 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Mon, 2 Sep 2024 23:30:29 +0900 Subject: [PATCH 21/95] =?UTF-8?q?2024/07/26=20=E6=99=82=E7=82=B9=E3=81=AE?= =?UTF-8?q?=E8=8B=B1=E8=AA=9E=E7=89=88=E3=81=AB=E5=9F=BA=E3=81=A5=E3=81=8D?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20(#23304)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2024/07/26 時点の英語版に基づき更新 * Update index.md * Update screen_shot_2019-12-11_at_9.59.14_am.png --- files/ja/web/api/notifications_api/index.md | 40 ++-- .../screen_shot_2019-12-11_at_9.59.14_am.png | Bin 0 -> 9000 bytes .../using_the_notifications_api/index.md | 183 +++++++----------- 3 files changed, 95 insertions(+), 128 deletions(-) create mode 100644 files/ja/web/api/notifications_api/screen_shot_2019-12-11_at_9.59.14_am.png diff --git a/files/ja/web/api/notifications_api/index.md b/files/ja/web/api/notifications_api/index.md index adcf4a871fdcb6..3b8cd40713ca8c 100644 --- a/files/ja/web/api/notifications_api/index.md +++ b/files/ja/web/api/notifications_api/index.md @@ -1,54 +1,56 @@ --- title: 通知 API slug: Web/API/Notifications_API +l10n: + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- -{{DefaultAPISidebar("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}} +{{DefaultAPISidebar("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}} 通知 API を使えば、ウェブページがエンドユーザーに表示するシステム通知を制御できるようになります。これらのシステムは、最上位の閲覧コンテキストのビューポートの外にあるため、ユーザーがタブを切り替えたり、別のアプリに移動していても表示されます。また、この API は既存の通知システムと互換性を持つように設計されているので、異なるプラットフォームでも動作します。 ## 概要と使い方 -対応済みのプラットフォームでは、システム通知を表示するには、一般的に 2 つのことが必要です。まず、ユーザーが現在のオリジンに対してシステム通知を表示する許可を与える必要があります。これは一般的にアプリやサイトが初期化されたとき、 {{domxref("Notification.requestPermission()")}} を使用して行われます。これは、例えばボタンをクリックするなど、ユーザーの操作に反応して行う必要があります。 +対応済みのプラットフォームでは、システム通知を表示するには、一般的に 2 つのことが必要です。まず、ユーザーが現在のオリジンに対してシステム通知を表示する許可を与える必要があります。これは一般的にアプリやサイトが初期化されたとき、 {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} メソッドを使用して行われます。 +このメソッドは、例えばユーザーのジェスチャーを処理する場合、マウスクリックを処理する場合などでのみ呼び出すべきです。 ```js -btn.addEventListener("click", function () { +btn.addEventListener("click", () => { let promise = Notification.requestPermission(); // wait for permission }); ``` -これはベストプラクティスで、ユーザーが同意していない通知でユーザーに迷惑をかけるべきではありません。しかし、今後ブラウザーはユーザーの操作から起動されていない通知を明示的に拒否するようになるでしょう。例えば、 Firefox はバージョン 72 からすでにこれを行っています。 - これは以下のようにリクエストダイアログを起動します。 -![](screen_shot_2019-12-11_at_9.59.14_am.png) +![オリジンからの通知を許可するかどうかをユーザーに要求するダイアログボックス。通知を許可しない、または許可するオプションがあります。](screen_shot_2019-12-11_at_9.59.14_am.png) ここでは、ユーザーはこのオリジンからの通知を許可するかどうかを選択できます。一度決定がなされると、現在のセッションの間はその設定が保存されます。 -> [!NOTE] -> Firefox 44 からは、通知と[プッシュ通知](/ja/docs/Web/API/Push_API)の許可が統合されました。通知に許可が与えられれば、プッシュ通知も同時に有効になります。 - -つぎに、新しい通知は {{domxref("Notification.Notification","Notification()")}} コンストラクターを使って作られます。このコンストラクターには、必須の title 引数と、オプションを指定する引数として options オブジェクトを与えることができます。オプションには、テキストの方向、本文テキスト、表示アイコン、通知サウンドなどが指定可能です。 +次に、新しい通知は {{domxref("Notification.Notification","Notification()")}} コンストラクターを使って作られます。このコンストラクターには、必須の title 引数と、オプションを指定する引数として options オブジェクトを与えることができます。オプションには、テキストの方向、本文テキスト、表示アイコン、通知サウンドなどが指定可能です。 さらに、通知 API の仕様には、いくつかの[サービスワーカー API](/ja/docs/Web/API/Service_Worker_API) が定義されており、サービスワーカーが通知を発行できるようになっています。 > [!NOTE] > 自分のアプリでの通知の詳しい使い方については、[通知 API の使用](/ja/docs/Web/API/Notifications_API/Using_the_Notifications_API)を参照してください。 -## 通知インターフェイス +## インターフェイス - {{domxref("Notification")}} - : 通知オブジェクトを定義します。 - -### サービスワーカーの追加要素 - -- {{domxref("ServiceWorkerRegistration")}} - - : {{domxref("ServiceWorkerRegistration.showNotification()")}} および {{domxref("ServiceWorkerRegistration.getNotifications()")}} メソッドが含まれており、通知の表示の制御に使用できます。 -- {{domxref("ServiceWorkerGlobalScope")}} - - : {{domxref("ServiceWorkerGlobalScope.notificationclick_event", "onnotificationclick")}} ハンドラーが含まれており、通知がクリックされた時にカスタム関数を実行させることができるようになります。 - {{domxref("NotificationEvent")}} - - : {{domxref("ExtendableEvent")}} を基本とした、特定の型ののイベントオブジェクトです。すでに実行された通知を表現します。 + - : {{domxref("ServiceWorker")}} の {{domxref("ServiceWorkerGlobalScope")}} に配信された通知イベントを表します。 + +### 他インターフェイスへの拡張 + +- {{domxref("ServiceWorkerGlobalScope/notificationclick_event", "notificationclick")}} イベント + - : 表示された通知をユーザーがクリックすると発生します。 +- {{domxref("ServiceWorkerGlobalScope/notificationclose_event", "notificationclose")}} イベント + - : 表示された通知をユーザーが閉じたときに発生します。 +- {{domxref("ServiceWorkerRegistration.getNotifications()")}} + - : 現在のオリジンから現在のサービスワーカー登録を経由して作成された順番で、通知の一覧を返します。 +- {{domxref("ServiceWorkerRegistration.showNotification()")}} + - : リクエストされたタイトルで通知を表示します。 ## 仕様書 diff --git a/files/ja/web/api/notifications_api/screen_shot_2019-12-11_at_9.59.14_am.png b/files/ja/web/api/notifications_api/screen_shot_2019-12-11_at_9.59.14_am.png new file mode 100644 index 0000000000000000000000000000000000000000..17251c2ec673122b8afacef7c37a3b448fd91cae GIT binary patch literal 9000 zcmb7qcQjnx*Z+_pB+_&S2|*G>^wCCd(M63GMs!gVov4X6h#Dojh(22M&eePGj1r6) zjNaz;Jm0l`>-WCv{pVfl-g9?bpMB2WckQ#+Iww?JRi2cDmIMR>kt!<4Xo5iazzw~0 z=hn^0$pde{`P{aYRFMRM5K(t8O$lyzJQq!QDNxBEcUX4w>LL|#^U4Y1qFV?Of@$KfhoypvDo9i zrqGof{pvpryXb?g5zw%EfR6_Xs+&n~!w#NZFLxJzX}c;6F2Jqi8t9uu zhelwrSdi(SvXc7RNCTBgR^9maDhAu#-G}+xc*|@V56}1P^sM#j+V6M2r>D=}9tzKF z*#IBU)XZ{pW3OcG!i<_mTk9R}8teUrB|f_)D6q-5@t`wQN*{3$9PsN)%?=)jY2yM{ z7;N^467rD7{I|VuZRof66dzKX=4Ua7%ggKX!7Tv+P3G_>gM^*obTiy|0uvF4m_r(< z&wnfp$6VnqFvt2?OT)!M&CQ*stJqRR8M4?urgD;BJ1Bbi3U@sLDmzV#tRQzPTP;VD z@_VmWe~C5_ZYxP?$Xs!?T-h8$A70|r!X15ii+RTQn)1Q+M5Z^Us)e|67Uz zjFFxDlSxXY89%tJ^5lco8y7LTq2aa#tJ&rK@iyxHi{~P$jLS zy|N#^6kt=_USHvYt*VoY$$$QR^M_vdtzWNi*;C27iQq;5+z!?GoH28;y|s}DTkUIZ z9PLH(WFM9{O@Mq+`!y~i&F9T)-FTk$8ue$Xqb-N19rJg=$eDeb=s*e(h!LSEBdO&+ zi%Kz3CNp3F)cBu? z^9m>|{+@*zkye_J#r?w|5YMf7`qAL9AAb*D_) z6Iw7`wa?wo9UJ6ROFZyby%*LaK^vzvXyWPo%O2u7aQ&IGc7Hu7oOG^Q$YUfxrl-OO z&dHHJ($}t3$Ml0V&)iuR9#|YkP$5*E&N(+is^dFXbT#XPS|RkC_|?>^-)P4+bUSX~ z03*PV2W`O+E_p846CInTDYbc8&W4>msETRY(akp0^(ql4DQx%03Bm!S3=L%UB8|Wi zJfAeAPqJ3SoUbPjg-^w5?>(VEtNA?eXXKZd_VJNWbu%0M?#lGyukh!MF1?7p`gz## zvZ1{I5+abA&8}k{C}1daJ4IL4__1ClLnS-ALPL$sVnWGsr}9^(D3UcudWnJyN?fbT z+PnHBEhMV;Fm|^4-6Zqqx*lu>3@bVv=;79(cj$Gh{uI?XDrSenLtlCcKaO&SM9-}W zc1;Bw)tl{7Q>vs%J*>5QEffAxCG&k888W%9lM*sW-f)LFbm(v_Tp6>Y{2|`poW*<#C?d|nGh>XPkDvf>H7~EO2R_!E+(gh z-F1(5uQhfVTPcOLbV#q_=s81#Vh3lmxUT&2-d)T7F=i`_tE)wVL zv92%U@hr@Y*80v-uASk?nu9sDTT??(mA9f{Cl3nO5j1jAG36J{I1NOvQ*^+; zbB?}0peq_S@TGp%!#27nu1$+af3bVMY#s@gd(X39bxKwHP{ydMnR*wq^K?oXliJXq z1iuZ$(6#JjYrw&Vj79+?j=!@5Cwvu%y3d~F;^~_2+?6rNTs}Rh zN+87CNyz=!%joLI>t@3;@=@eTOo{IE#+LwF&MVs@UCQl)A9?bVv=%0efWk_*n@jCx z``>%kkGA}Da2BowB$%)(2{af2rQY!~_eHXRFA@`W#4l@!fS(hXuzdUHfK78;DMPSo z?97x@N7ata((KofCLZ&2Cgeqof62xnHDwI{fs{P$8mr=H$&S50@?1++rP|8S@{@4K zq^(F0$uM9@r_hyf&uHafFg1jxj9nscy7F&TkN(dz<^EGZNj^Wi7<@_Bj|L%gE%aH3 z9lAqb`oDKY2W7DrEQz&jzT(S9ds(JRB<{A*92mPD=hYb#sy)-ObiVhV>Fi4FBHQt0 z-RkSwmh|pNqyR-!PXhSj1+YRFy~7Q(P=rZ5Z4(^36@$Hh|3NFql9=3bRx%zWudYoN zl2<C5jqfXn?tQ z?}K!mHFT{l=iX)12tB#rl$DlVJ|xV4eb9}aykpx<9xvFdWnZ>UhXusggm91+^<9Xs z`%)>+2|QdW#CdAE6QFBJ8n-UA@~~oWiVT-P&#SNkDHU>3kt0YA7l$msiSy8Mr7H$}{Mtuo;vQNAdM# z=WD>%J4m7BLdWcylYDMi8A7a+`zG$LU}nY2 z{7$02&q5(zin<&NKSCDqfht48!Go--XiR4hkRTLd6}XpD$m`sj6Ze9N?|K-L6bL)0 z@jh`7vX0BO$vBu|=CS*G5WL|PgXLxkbdA-w}>N^ z0af+gH-{LdHmA*czr4M>xSa&Dhy6p`)@_D)n;=E_2R~1+Zu&bseSGi(DJix>>qw{o zeZ9MIXH2g#wH80k(L{@8Zo{hh(!8$8zQauPE;QVgqCEdqIC;$0- zc&sx0HbwQBNHUMFCB~etSl8UejxMQ8&eK6CQ!!ANsYbh*9x+J#FsfdSgz8prjvx9{ zBL8udpg2&$Yl~oipyqarZnyTU)ZX0n36)4j?nQpJC%tvIW#8nd>az`WI&n~GDsg^% zOo%=xMU|BnuJP>7C!%Q8!$Dq%+;OgHzHaoh%*Ez9y==IuTr&rpnO6+&anprozk_dS z+oMtRwoLtee1z$vUJ}(kJskqcZ(l`K{n@|3=ASCu4{^F96?;viqpy;rT2|-*c{RgT zxv@^&nQ)HDKr0-wYAL|fuVk#~3v#sYKoSyNXgprr=Dzk1ZvDmX33ikI;1M+Z(a-tn zQX$CEk~W2*;bKc*?NdBg)US@hJ`piUZFwk^A*BR@Q=-6!k6o`FV5hHIiLBv0BZ*UW zap&AKU=O$!JX2H5ok}M)-bON6?A>B+ElRQms|-i@agz}3h8r%?4yVx4+utlq@r`6n z@TkkTJ4h{&ZRq5bagcb)Ll2@M=SdkpRRNj4VV{4ZY<+NR!r0krq=@XAg03d>q9MsN>Cj z7j{qh1i8CHtuN*D)V#+dEGN!*5E=WN3oyVnv$710=?{Krs%~*fYtVC7fHfT?m-!X^ zq85^iyq}A2=VYGe;kSq5oj~fbwOmCNpEsk@{FKS8X#xFiv;v`DbJ{$CsI8=+eW<6N ztILk&V=~uWxM|8pcLDn&{uRo%_XggPG@?xJq`j1cQ6*DT;+ExQ?LO$22MFanjbXXd zBMJHTbY|RL<2&>BB_T^UALQiF|v%sQn>h$aKTm9_rK;Crr!!WRZ)V{Z@ki+6UrtXN_iEyw}F{A}cND z<#A`*qL`XX8RV2MiA&sz4}FwtHL_Pf=>oX(ARh-Yydv33-a{_m-8exyS z-mE`;BdOK#G}l=u0KD%7P(C?$|I(cGIr2G3gUqQnNO_snf!`G83T% zW|2I2bm8j*`y0U#WNfO28o+RXL0tTj*|_daoM-^q5)4-b4ernJ4Yz{LXmsP0V z;&$aSxS2{x2rdkVE#2%J8Q`~YYjyYwfbThgqXXz(02)2}a=qN7z1-_bgzHJp%7MJM=X%?7^9vI^y+o63G{b!pu%NsM4BEO~qD{5F{O6lXjWr z^Gx)iqJD)%WuII$$C$wtn;L-$&73}on9&tMUJrw}1)PGm6BPXmDiX62+8AwD!0?? z9I5MRrT}Fjct1DN!JQ7sd{qIlFovSxE!+&>@O|u`^8nBK4nH+3{c<8EVM^{lJ!#zN zk3z9X4e9FXT!n&`ZeQ zT9@j7hU9jh)gq@AwW=0|ZX^yX_ILF)OzN{Z#!!z^@G;Ca26?HeaU*t-t zdaZ#?v(R~!1;>ECFXCZ>dhzbBlayfNlP891AOfUSwcgk9&kQbh^bBRh*%P|ElT6Q$ zdT*q>1Ju*zQE#L30=J;_#^Y(bJ)Ezf^dl?}504ZzS{*6JW@i0&f^*-V3WfLF`^m4c z?(~Bp1@}AN1%)rkw@ww4nvta2bbF%GbaOxJbY15ud;Xg6s_>ilSy#K*CS#ey8fXKb ztmrj@4z_1xp#bY~5BAoi#smU84mKJjQxhM2iPoCob+6y3jVBh_^%8bw?ul{$x zdl$QE^MPyBD$n@ihXheFHwz#tg&=mS>D7XFX1E*vaRwZ?y% z={1i(J0po!`da#?3vtA{7+a+XuAsd4?GUW_71E`tPcaE|1W~bl+NP2;G4*dC6s0RW zyc^arMHBYq06u2zEH?SBXcrJkkvNPRClgz|0BcUL!qT~8ksPmTdV;KD(CmN?KD5~{ zeJO{;lL*JSPdxwm^kbOMLSPlaw@fe>9zgiBs8A;8b$gaIi&>vw>MM(G{x(t+r9rlC zOfa~~_^+Wdbt^1XyzAkc7v*bUCB<%XcY=4nk_Wjj0~vd~JCCF7LpZXyp0I;frk@vD z=V}KZ>A8Z!Vg*8B(+_!kQOpWZO=-tJd-m>fh$Ntlf#`hD0bi2SFDU1HpJDi&v0dQF ztx3Ud?&Gu`cU}T zA^bvAer$}YcKGkd+JuxPb{l#Ix)|6q)<;4cz9K-wiAvdaHIz!eTN&h zMhSGh;l#>v%X)7Dx*w+ud=VY$;kIh34L^lF^b0I~`Ir6ri%|4gSefj7r-n||8V&tF zI!=;sZMV0k6B3R#Nea@dC5QJdAI)xXTKfgP1~ktCYToH?#pM+5NvCs1!k$cxn7odJ z`K^)%&_t$Pm(}3-7#qt=d#Fof`h<*K6`li`&cU7MaVV^XbCF-Qo05^Wr$2nD%z`hbRZBlI=9KPyS|K5Z3C|rHjRliT_wmQ- zYZ~2AAo#rc!KeS@LZ%HsS32MH^No}x6`r;%1l_wT1zzfpcj<4Md6FO>aMAF_JC(sv zOPCbAs*@?tQB>w7+>spQ`_PV{#Q80JNpiuyXr_>Q_vZj&4z6VExJ5$IUYd#bQ?Q{c za+c3F##{{llT>?*LX(to!0W^f5(h<(VEKj#pss<1|0#SR(TR+PTit3mT}l%EgOfR+ zN|;~I%~sl9n5#+AwAzk7+4W~_d{I++oNJz#mm0uLy0iT|8XYKc9D?r>XP0SC_1h)nap zW|@{GdBjBwwI_5QTZHR<-_e2Ft`2lm0{aay=V7^Z588MR3OIPN(A(dA%k66Dz8j^5 zDgg1H%=IaMU{aMy8w2#tUOYLr$4J(bT?WSuR|VdkMnCd;f3+%g<+l6YXGYpx5s;H8 zq8KOj`R0dR)yJC?T4j-I6BcH{QmBr)C@Uk2B=cfuPfYGw=!E&pS_*NG3UFb-OmuC1 zC#Qr-O#XBk!^p_prSaGY7Fk(Fu-?tWc1*N0IJlW@4S!*Wtj+8wB{0o0qzskXxYzIl zHan0`-}&k}Phb+|6iKiyCqjP~CS=l^Sg{?q@w z_(z4a$6QOT3Xg#zMAEVcX^0D%2o?l>M#E@jR$q;N6flsSzq`p)R9*I*yVbPL^$DR7 z?W0)oas~1?tHGQUp$L(Y$CNHH?{=R3&h_Vy%b61v_)QgG!-AguXqdN<@ol+!0dp}J z0Y82)8;P(S#Ll~d)kee5*4NV0XL6;5;w{&PLjP z=FL>6dZ`GBLAnsT$H=7F87$EpiBkkj1Pwg4Gu%b#T|I<5+4XtMI~wm&4E4&M&4m0G zxiK!@L>MMob|rhHe}x%f0Mfa0X@Uy29{{BK2aXMs7?l++ILX=qdCo7i_ zF|FtlLRVodHE=9a`UE^T?WBH@N!<;xVEEr6@^4)JpTZ9JQogTBrP#ZYXCE5NC+#;) zV+~RL4BV2mkG)G+*ScJ!goIAlzMgo!(C-fhr_@Q zRt#=meV``KYu1Q+=(w1S1j%R-=+6A#+gNc4U`X_H?vsaaU^`Lw$0mo-9AP (!Ksk$9h@(1VaH@|=ET{yWC#kv~hR;+Vzx&8-<+M#u` zkJW8-eK|C7z5R&`o+cV)Tkvdp&^jE`-85ob8M4f?L&~9*n zWAbtl=keFe9oGhC@k|Ssll9pKT_}Qqar%W$8O76g;WP}qnY3y%rDo!FYXwE5fH6^HzGBy0N1Th6Fy{2=mNHp$55 zC0EGT^UXEJm)oiOrAV?)oU-;+^_oJ(kNRJ(OM8sDOKe4<+r10f;6CnMP6T+$XWlO1 z(zj*Yt=avOOT_KE79pUTTJ7y@Y8gk_VKx)&dMp$uvSCCn!XMMa&teTgVt@HYCKODJhVi5(YAl$ zp~UGjIll{Ko(k(J82q7ReL!mFhWqBXut_mzi^<7@`XIC-XRAQGO7J@~#BjG}J+GRp z!|O#dq(x8snDYa)n6CvueZ zjU1H3h$y>?>%8>zWObatK?CITxu|hOV;UK=e*b!J@A(J73`+rrW!HA{PEn?Ekth=o zxLO-F^rRGhUm`#6o7!?O_2klJ*If-XHbPT|E*)(cLv=Am>ow@`*t}P2+lS=*WnNs} zY!l!_3}IB`#Z>!Z2kZe@eL%qM_ib=F}?*7=((yqGGBy&=E@TlC_ve zi1V1x6o3EqsI`YJOV)H~KEj#fWMykl(2U}YheHlg#Z@}AA8J-hku>?7Qj<*A9HVVZ zV7#ukQY==K>dEN0d*rmATJ_KXKCz!>nCOI>_5h=fBluW^;gyl+i9=B=<~VPSX<^;_ z#@p0?w;A;x8|<5Fr#I&*q|q04n$7Z3%qJn`eR(kiH_%H;{sh+UfJ_P>=P~O$2N$ zXb8)5!cgzH^PgC2ifD;PkkxG*c4r7JD>1o1Ar4}4D z-uG8^mZlY9PR=4~HSBlsItige6_Y`&qtx|bQ}0w3B7AO-UQfPV`h=C~jC?z(nR(*t z<7|RbJn}HUB!LdOG$5VNkbb_eaqqIO*Du)3?ANYIKCP7@52xUwW=SLN=hD|67?wfq=_-J+On#CD;MXCVgp4 z0A`cD_23py^ClsX0*yIqgh5zEzQS$_H8B8T1tXIj|JglP-23S3ol@iA3;&Ttz}ohs zTnvpukU1`fI=d2poIt6!X1qOQz)9|%1mt*cluesq1+vTm%=mL8u59G070idQvqz_` z+?>E5_V#DlG@!P{j!8&~s=n9m`?1g49eb+U6ydO2GXoYeG6unOgh+QXFj4t!bDi)U z{g=0qMPJ6iec6JiHR#E9q zt18YMa^*S7)oKlJn$Pc3n-m3qeK3FCXTHO8+sxqkA|D_FVQu4HNxJhth(|ZU`d9UT fB1UivI1s#~)zdK3GydiV3P@2_Ri;GheZYSKKom0P literal 0 HcmV?d00001 diff --git a/files/ja/web/api/notifications_api/using_the_notifications_api/index.md b/files/ja/web/api/notifications_api/using_the_notifications_api/index.md index 08a18a0b0b49b2..13d3e131fd26fe 100644 --- a/files/ja/web/api/notifications_api/using_the_notifications_api/index.md +++ b/files/ja/web/api/notifications_api/using_the_notifications_api/index.md @@ -1,15 +1,17 @@ --- title: 通知 API の使用 slug: Web/API/Notifications_API/Using_the_Notifications_API +l10n: + sourceCommit: aa8fa82a902746b0bd97839180fc2b5397088140 --- -{{APIRef("Web Notifications")}}{{AvailableInWorkers}}{{securecontext_header}} +{{DefaultAPISidebar("Web Notifications")}}{{securecontext_header}} {{AvailableInWorkers}} [通知 API](/ja/docs/Web/API/Notifications_API) は、ウェブページやアプリからシステムレベルでページ外部に表示される通知を送ることを可能にします。これにより、アプリケーションがアイドルやバックグラウンドの状態であっても、アプリからユーザーに情報を送信することができます。この記事では、アプリで API を使用する方法の基本を見ていきます。 一般的にシステム通知とは、オペレーティングシステムの標準的な通知メカニズムを指します。一般的なデスクトップシステムやモバイル端末が、通知を行う方法の実例を思い出しましょう。 -![](android-notification.png) +![デスクトップ通知: To do list via mdn.github.io HEY! Your task "Go shopping" is now overdue](desktop-notification.png) 当然ながらシステム通知の仕組みはプラットフォームやブラウザーによって異なりますが問題はなく、通知 API はほとんどのシステム通知に対して十分な互換性を持つようになっています。 @@ -21,7 +23,7 @@ slug: Web/API/Notifications_API/Using_the_Notifications_API ## 許可の要求 -アプリが通知を送信できるようになる前に、ユーザーはアプリがそれを行う権限を認めなければなりません。これは API がウェブページの外部にあるものと対話しようとする際の一般的な要件です。ユーザは少なくとも 1 回はアプリケーションが通知を送ることを認めなければならず、これによりどのアプリやサイトが通知を表示してよいかをユーザーが制御することができます。 +アプリが通知を送信できるようになる前に、ユーザーはアプリがそれを行う権限を認めなければなりません。これは API がウェブページの外部にあるものと対話しようとする際の一般的な要件です。ユーザーは少なくとも 1 回はアプリケーションが通知を送ることを認めなければならず、これによりどのアプリやサイトが通知を表示してよいかをユーザーが制御することができます。 過去にプッシュ通知が悪用されることがあったため、ウェブブラウザーや開発者はこの問題を緩和するための対策を実装し始めています。通知を表示することの許可を求めるのは、ユーザーの操作 (ボタンをクリックするなど) の反応として行うべきです。ユーザーが同意していない通知でユーザーに迷惑をかけるべきではないので、これはベストプラクティスであるだけでなく、今後ブラウザーはユーザーの操作によって起動されたものではない通知の許可の要求を明示的に拒否するようになるでしょう。例えば、 Firefox はバージョン72からすでにこれを行っており、 Safari もしばらく前からこれを行っています。 @@ -29,7 +31,7 @@ slug: Web/API/Notifications_API/Using_the_Notifications_API ### 現在の許可状態を確認する -読取専用の {{domxref("Notification.permission")}} プロパティの値を調べると、すでに許可を得ているかを確認できます。このプロパティは、3 種類のいずれかの値を取ります。 +読み取り専用の {{domxref("Notification.permission_static", "Notification.permission")}} プロパティの値を調べると、すでに許可を得ているかを確認できます。このプロパティは、3 種類のいずれかの値を取ります。 - `default` - : ユーザーはまだ許可を求められたことがなく、したがって通知は表示されない。 @@ -40,10 +42,10 @@ slug: Web/API/Notifications_API/Using_the_Notifications_API ### 許可を得る -通知を表示する許可をまだ得ていない場合は、アプリケーションは {{domxref("Notification.requestPermission()")}} メソッドを使用してユーザーに要求する必要があります。もっとも簡単な形では、次のようなものがあります。 +通知を表示する許可をまだ得ていない場合は、アプリケーションは {{domxref("Notification.requestPermission_static", "Notification.requestPermission()")}} メソッドを使用してユーザーに要求する必要があります。もっとも簡単な形では、次のようなものがあります。 ```js -Notification.requestPermission().then(function (result) { +Notification.requestPermission().then((result) => { console.log(result); }); ``` @@ -51,11 +53,15 @@ Notification.requestPermission().then(function (result) { これはメソッドのプロミスベースの版を使用しています。古いバージョンに対応したい場合は、次のように古いコールバック版を使用する必要があります。 ```js -Notification.requestPermission(); +Notification.requestPermission((result) => { + console.log(result); +}); ``` コールバック版はオプションで、ユーザーが表示を許可する要求に答えた時に呼び出されるコールバック関数を受け入れます。 +> **メモ:** `Notification.requestPermission` がプロミスベース版に対応しているかどうかを、確実に機能テストする方法はありません。古いブラウザーの対応が必要な場合は、コールバック版を使用してください。非推奨ではありますが、新しいブラウザーでも動作します。詳しくは、[ブラウザー互換性表](/ja/docs/Web/API/Notification/requestPermission_static#ブラウザーの互換性)を参照してください。 + ### 例 To-do リストのデモでは、 "Enable notifications" ボタンを配置し、押されたときにアプリの通知を要求します。 @@ -68,62 +74,23 @@ To-do リストのデモでは、 "Enable notifications" ボタンを配置し ```js function askNotificationPermission() { - // function to actually ask the permissions - function handlePermission(permission) { - // set the button to shown or hidden, depending on what the user answers - if ( - Notification.permission === "denied" || - Notification.permission === "default" - ) { - notificationBtn.style.display = "block"; - } else { - notificationBtn.style.display = "none"; - } - } - - // Let's check if the browser supports notifications + // Check if the browser supports notifications if (!("Notification" in window)) { console.log("This browser does not support notifications."); - } else { - if (checkNotificationPromise()) { - Notification.requestPermission().then((permission) => { - handlePermission(permission); - }); - } else { - Notification.requestPermission(function (permission) { - handlePermission(permission); - }); - } + return; } + Notification.requestPermission().then((permission) => { + // set the button to shown or hidden, depending on what the user answers + notificationBtn.style.display = permission === "granted" ? "none" : "block"; + }); } ``` -最初に 2 番目のメインブロックを見てみると、まず最初に通知に対応しているかどうかチェックしているのが分かります。もし対応していれば、次に `Notification.requestPermission()` のプロミスベース版に対応しているかどうかチェックします。対応している場合は、プロミスベース版 (Safari 以外で対応) を実行し、対応していない場合は古いコールバックベース版 (Safari で対応) を実行します。 - -コードの重複を避けるために、このスニペットの最初のメインブロックである `handlePermission()` 関数の中に、多少のハウスキーピングコードを格納しています。この内部では、 `Notification.permission` の値を明示的に設定し (古いバージョンの Chrome では自動的に設定できないものがありました)、ユーザーが許可ダイアログで選択した内容に応じてボタンを表示・非表示にしています。すでに許可されている場合は表示したくありませんが、ユーザーが許可を拒否することを選択した場合は、後で変更できるようにしたいと考えています。 - -> [!NOTE] -> バージョン 37 より前の Chrome では、 {{domxref("Notification.requestPermission()")}} を `load` イベントのハンドラー内で呼び出すことを許可していませんでした ([issue 274284](https://bugs.chromium.org/p/chromium/issues/detail?id=274284) をご覧ください)。 - -### requestPermission() プロミスの機能検出 - -前に、ブラウザーがプロミス版の `Notification.requestPermission()` に対応しているかどうかをチェックする必要があると言いました。これは以下のようにして行います。 - -```js -function checkNotificationPromise() { - try { - Notification.requestPermission().then(); - } catch (e) { - return false; - } - - return true; -} -``` +最初に 2 番目のメインブロックを見てみると、まず最初に通知に対応しているかどうかチェックしているのが分かります。もしそうであれば、プロミスベース版の `Notification.requestPermission()` を実行し、そうでない場合は、コンソールにメッセージをログ出力します。 -基本的には、 `.then()` メソッドが `requestPermission()` で利用できるかどうかを確認します。成功した場合は `true` を返します。失敗した場合は、 `false` を `catch() {}` ブロック内で返します。 +`then` に渡されるプロミス解決ハンドラー内で、ユーザーが権限ダイアログで選んだ内容に応じてボタンの表示・非表示を切り替えます。すでにその権限が許可されている場合はボタンを表示させたくありませんが、ユーザーが権限を拒否するよう選んだ場合は、後で考えを変えるチャンスを与えるべきです。 -

通知の作成

+## 通知の作成 通知の作成は簡単です。 {{domxref("Notification")}} コンストラクターを使用するだけです。このコンストラクターは通知内に表示するタイトルと、通知を拡張するためのアイコン ({{domxref("Notification.icon","icon")}}) やテキスト本文 ({{domxref("Notification.body","body")}}) などのオプションを受け取ります。 @@ -131,7 +98,7 @@ function checkNotificationPromise() { ```js const img = "/to-do-notifications/img/icon-128.png"; -const text = 'HEY! Your task "' + title + '" is now overdue.'; +const text = `HEY! Your task "${title}" is now overdue.`; const notification = new Notification("To do list", { body: text, icon: img }); ``` @@ -141,7 +108,7 @@ const notification = new Notification("To do list", { body: text, icon: img }); ```js const n = new Notification("My Great Song"); -document.addEventListener("visibilitychange", function () { +document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") { // The tab has become visible so clear the now-stale Notification. n.close(); @@ -181,86 +148,84 @@ Notifications API の仕様では、{{domxref("Notification")}} のインスタ 以下の基本的な HTML を想定してください。 ```html - + +
+``` + +```css hidden +#demo-logs { + width: 90%; + height: 100px; + background-color: #ddd; + overflow-x: auto; +} ``` 以下の方法で、複数の通知を扱うことが可能です。 ```js -window.addEventListener("load", function () { - const button = document.getElementsByTagName("button")[0]; - - if (window.self !== window.top) { - // Ensure that if our document is in a frame, we get the user - // to first open it in its own tab or window. Otherwise, it - // won't be able to request permission to send notifications. - button.textContent = "View live result of the example code above"; - button.addEventListener("click", () => window.open(location.href)); - return; - } +const demoLogs = document.querySelector("#demo-logs"); + +window.addEventListener("load", () => { + const button = document.querySelector("#notify"); - button.addEventListener("click", function () { - // If the user agreed to get notified - // Let's try to send ten notifications - if (window.Notification && Notification.permission === "granted") { + button.addEventListener("click", () => { + if (Notification?.permission === "granted") { + demoLogs.innerText += `The site has permission to show notifications. Showing notifications.\n`; + // If the user agreed to get notified + // Let's try to send ten notifications let i = 0; // Using an interval cause some browsers (including Firefox) are blocking notifications if there are too much in a certain time. - const interval = window.setInterval(function () { - // Thanks to the tag, we should only see the "Hi! 9" notification - const n = new Notification("Hi! " + i, { tag: "soManyNotification" }); - if (i++ == 9) { - window.clearInterval(interval); + const interval = setInterval(() => { + // Thanks to the tag, we should only see the "Hi no 9 from MDN." notification + const n = new Notification(`Hi no ${i} from MDN.`, { + tag: "soManyNotification", + }); + if (i === 9) { + clearInterval(interval); } + i++; }, 200); - } - - // If the user hasn't told if they want to be notified or not - // Note: because of Chrome, we are not sure the permission property - // is set, therefore it's unsafe to check for the "default" value. - else if (window.Notification && Notification.permission !== "denied") { - Notification.requestPermission(function (status) { + } else if (Notification && Notification.permission !== "denied") { + demoLogs.innerText += "Requesting notification permission.\n"; + // If the user hasn't told if they want to be notified or not + // Note: because of Chrome, we are not sure the permission property + // is set, therefore it's unsafe to check for the "default" value. + Notification.requestPermission().then((status) => { // If the user said okay if (status === "granted") { + demoLogs.innerText += + "User granted the permission. Sending notifications.\n"; let i = 0; // Using an interval cause some browsers (including Firefox) are blocking notifications if there are too much in a certain time. - const interval = window.setInterval(function () { + const interval = setInterval(() => { // Thanks to the tag, we should only see the "Hi! 9" notification - const n = new Notification("Hi! " + i, { + const n = new Notification(`Message no ${i} from MDN.`, { tag: "soManyNotification", }); - if (i++ == 9) { - window.clearInterval(interval); + if (i === 9) { + clearInterval(interval); } + i++; }, 200); - } - - // Otherwise, we can fallback to a regular modal alert - else { - alert("Hi!"); + } else { + // Otherwise, we can fallback to a regular modal alert + demoLogs.innerText += `User denied the permission request.\n`; } }); - } - - // ユーザが通知を拒否している場合 - else { - // 通常型の alert にフォールバックできます - alert("Hi!"); + } else { + // If the user refuses to get notified, we can fallback to a regular modal alert + demoLogs.innerText += `The site does not have permission to show notifications.\n`; } }); }); ``` -結果は以下のとおりです。 - -{{ EmbedLiveSample('Tag_example', '100%', 30) }} - -## 仕様書 - -{{Specifications}} +### 結果 -## ブラウザーの互換性 +{{ EmbedLiveSample('Tag_example', '100%', 150) }} -{{Compat}} +上記の例をテストするには、ウェブサイト `https://live.mdnplay.dev` の[通知設定](https://support.mozilla.org/en-US/kb/firefox-page-info-window#w_permissions)を変更してください。。 ## 関連情報 From df49588520c94545502f8f9e4dec9e2bb4d59c36 Mon Sep 17 00:00:00 2001 From: Agatem Date: Mon, 2 Sep 2024 21:09:02 +0200 Subject: [PATCH 22/95] [ES] Add `CSS shadow parts` (#23337) --- files/es/web/css/css_shadow_parts/index.md | 62 ++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 files/es/web/css/css_shadow_parts/index.md diff --git a/files/es/web/css/css_shadow_parts/index.md b/files/es/web/css/css_shadow_parts/index.md new file mode 100644 index 00000000000000..d990f02892f7c2 --- /dev/null +++ b/files/es/web/css/css_shadow_parts/index.md @@ -0,0 +1,62 @@ +--- +title: Shadow parts de CSS +slug: Web/CSS/CSS_shadow_parts +l10n: + sourceCommit: 835d6632d59993861a0458510402787f8a2c3cb3 +--- + +{{CSSRef}} + +El módulo **shadow parts de CSS** define el pseudoelemento {{CSSXref("::part", "::part()")}} que se puede establecer en un [shadow host](/es/docs/Glossary/Shadow_tree). Al usar este pseudoelemento, puedes habilitar shadow hosts para exponer el elemento seleccionado en el shadow tree al exterior de la página para poder estilarlo. + +Por defecto, los elementos en un shadow tree solo se pueden estilar dentro de sus respectivos shadow roots. El módulo shadow parts de CSS habilita la inclusión de un atributo [`part`](/es/docs/Web/HTML/Global_attributes#part) en los descendientes de {{HTMLElement("template")}} que componen el elemento personalizado, exponiendo el nodo shadow tree para estilarlo usando el pseudoelemento `::part()`. + +## Referencia + +### Selectores + +- {{CSSXref("::part", "::part()")}} + +### Atributos HTML + +- [`part`](/es/docs/Web/HTML/Global_attributes#part) +- [`exportparts`](/es/docs/Web/HTML/Global_attributes#exportparts) + +### Definiciones + +- {{glossary("Shadow tree")}} + +## Guías + +- [Pseudoelementos CSS](/es/docs/Web/CSS/Pseudo-elements) + + - : Lista alfabética de pseudoelementos definidos por todas las especificaciones de CSS y WebVTT + +- [Componentes web](/es/docs/Web/API/Web_components) + + - : Vista general de las diferentes API que habilitan la creación de elementos personalizados reusables o componentes web. + +## Conceptos relacionados + +- Elemento de HTML {{HTMLElement("template")}} +- Elemento de HTML {{HTMLElement("slot")}} +- Propiedad {{domxref("Element.part")}} +- Propiedad {{domxref("Element.shadowRoot")}} +- Método {{domxref("Element.attachShadow()")}} +- Interfaz {{domxref("ShadowRoot")}} +- Modulo [ámbito de CSS](/es/docs/Web/CSS/CSS_scoping) + - {{CSSXref(":host")}} + - {{CSSXref(":host_function", ":host()")}} + - {{CSSXref(":host-context", ":host-context()")}} + - {{CSSXref("::slotted")}} + +## Especificaciones + +{{Specifications}} + +## Véase también + +- [Pseudoelementos de CSS](/es/docs/Web/CSS/CSS_pseudo-elements) module +- [Selectores de CSS](/es/docs/Web/CSS/CSS_selectors) module +- [Uso del shadow DOM](/es/docs/Web/API/Web_components/Using_shadow_DOM) +- [Plantillas: Estilando fuera del ámbito actual](https://web.dev/learn/html/template/#styling_outside_of_the_current_scope) en web.dev (2023) From 37ab3e54f5ad056448c5546de2597fe3fb37fecd Mon Sep 17 00:00:00 2001 From: Agatem Date: Mon, 2 Sep 2024 21:43:07 +0200 Subject: [PATCH 23/95] [ES] Add `::part()` (#23336) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [ES] Add `::part()` * Update files/es/web/css/_doublecolon_part/index.md --------- Co-authored-by: Juan Vásquez --- files/es/web/css/_doublecolon_part/index.md | 114 ++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 files/es/web/css/_doublecolon_part/index.md diff --git a/files/es/web/css/_doublecolon_part/index.md b/files/es/web/css/_doublecolon_part/index.md new file mode 100644 index 00000000000000..1999a72df47513 --- /dev/null +++ b/files/es/web/css/_doublecolon_part/index.md @@ -0,0 +1,114 @@ +--- +title: "::part()" +slug: Web/CSS/::part +l10n: + sourceCommit: 5863b9e6635b304b96ef5f70937329e854957f73 +--- + +{{CSSRef}} + +El [pseudoelemento](/es/docs/Web/CSS/Pseudo-elements) de [CSS](/es/docs/Web/CSS) **`::part`** representa cualquier elemento dentro de un [shadow tree](/es/docs/Web/API/Web_components/Using_shadow_DOM) que tiene un atributo [`part`](/es/docs/Web/HTML/Global_attributes#part) coincidente. + +```css +custom-element::part(foo) { + /* Estilos que se aplican al part `foo` */ +} +``` + +## Sintaxis + +```css +::part(+) { + /* ... */ +} +``` + +## Ejemplos + +### HTML + +```html + + + +``` + +### CSS + +```css +tabbed-custom-element::part(tab) { + color: #0c0dcc; + border-bottom: transparent solid 2px; +} + +tabbed-custom-element::part(tab):hover { + background-color: #0c0d19; + color: #ffffff; + border-color: #0c0d33; +} + +tabbed-custom-element::part(tab):hover:active { + background-color: #0c0d33; + color: #ffffff; +} + +tabbed-custom-element::part(tab):focus { + box-shadow: + 0 0 0 1px #0a84ff inset, + 0 0 0 1px #0a84ff, + 0 0 0 4px rgb(10 132 255 / 30%); +} + +tabbed-custom-element::part(active) { + color: #0060df; + border-color: #0a84ff !important; +} +``` + +### JavaScript + +```js +let template = document.querySelector("#tabbed-custom-element"); +globalThis.customElements.define( + template.id, + class extends HTMLElement { + constructor() { + super().attachShadow({ mode: "open" }).append(template.content); + } + }, +); +``` + +### Resultado + +{{EmbedLiveSample('Ejemplos')}} + +## Especificaciones + +{{Specifications}} + +## Compatibilidad con navegadores + +{{Compat}} + +## Véase también + +- Atributo [`part`](/es/docs/Web/HTML/Global_attributes#part) +- Función pseudoclase {{CSSxRef(":state",":state()")}} +- Atributo [`exportparts`](/es/docs/Web/HTML/Global_attributes#exportparts) +- Módulo [shadow parts de CSS](/es/docs/Web/CSS/CSS_shadow_parts) From 7da4dde3bcb85f5f17cc70bb971097314b7c67fd Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 08:51:27 +0800 Subject: [PATCH 24/95] zh-CN: create Glossary/UAAG (#23322) Co-authored-by: A1lo --- files/zh-cn/glossary/uaag/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 files/zh-cn/glossary/uaag/index.md diff --git a/files/zh-cn/glossary/uaag/index.md b/files/zh-cn/glossary/uaag/index.md new file mode 100644 index 00000000000000..77be928c0982b8 --- /dev/null +++ b/files/zh-cn/glossary/uaag/index.md @@ -0,0 +1,19 @@ +--- +title: UAAG +slug: Glossary/UAAG +l10n: + sourceCommit: 9231a7046973685f4600e1891fa644ecce41ef3b +--- + +{{GlossarySidebar}} + +_用户代理{{glossary("Accessibility", "无障碍")}}指南_（**UAAG**）是由 {{Glossary("W3C")}} 的 {{Glossary("WAI", "Web 无障碍倡议")}}工作组发布的一项推荐标准，解释了如何让残障人士可以无障碍地访问用户代理。用户代理包括浏览器、浏览器扩展、媒体播放器、阅读器和其他渲染网页内容的应用程序。与 Web 内容相比，浏览器更能满足某些无障碍需求，例如文本自定义、偏好设置和用户界面无障碍。 + +## 参见 + +- 维基百科上的 [WAI 中的 UAAG]() +- [用户代理无障碍指南（UAAG）2.0：推荐标准](https://www.w3.org/TR/UAAG20/) +- 术语 + - {{Glossary("Accessibility", "无障碍")}} + - {{Glossary("WAI")}} + - {{Glossary("WCAG")}} From 5b10e4ee671e257d5bb1ba80df9318351e79e0af Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 08:52:55 +0800 Subject: [PATCH 25/95] zh-CN: create Glossary/Real_User_Monitoring (#23324) Co-authored-by: A1lo --- .../glossary/real_user_monitoring/index.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 files/zh-cn/glossary/real_user_monitoring/index.md diff --git a/files/zh-cn/glossary/real_user_monitoring/index.md b/files/zh-cn/glossary/real_user_monitoring/index.md new file mode 100644 index 00000000000000..e9c6136823cb68 --- /dev/null +++ b/files/zh-cn/glossary/real_user_monitoring/index.md @@ -0,0 +1,17 @@ +--- +title: 真实用户监控（RUM） +slug: Glossary/Real_User_Monitoring +l10n: + sourceCommit: 50e5edd07155de2eec2a8b6b2ad95820748cfec7 +--- + +{{GlossarySidebar}} + +**真实用户监控**（Real User Monitoring，RUM）是一种用于从真实的用户设备上测量页面性能的技术。通常，第三方脚本会在每个页面上注入一个脚本，以便测量和报告每个请求的页面加载情况。这种技术监控应用程序的实际用户交互。在 RUM 中，第三方脚本会从真实用户的浏览器中收集性能指标。RUM 有助于确定应用程序的使用情况，包括用户的地理分布以及该分布对终端用户体验的影响。 + +## 参见 + +- [真实用户监控（RUM）与模拟监控](/zh-CN/docs/Web/Performance/Rum-vs-Synthetic) +- 相关术语： + - {{Glossary("Synthetic monitoring", "模拟监控")}} + - {{Glossary("Beacon", "信标")}} From 376565c436e8f4953268ad9133daaf54ce2e4129 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 08:54:31 +0800 Subject: [PATCH 26/95] zh-CN: create Glossary/Raster_image (#23326) Co-authored-by: A1lo --- files/zh-cn/glossary/raster_image/index.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 files/zh-cn/glossary/raster_image/index.md diff --git a/files/zh-cn/glossary/raster_image/index.md b/files/zh-cn/glossary/raster_image/index.md new file mode 100644 index 00000000000000..3aceeccc172b02 --- /dev/null +++ b/files/zh-cn/glossary/raster_image/index.md @@ -0,0 +1,12 @@ +--- +title: 栅格图（位图） +slug: Glossary/Raster_image +l10n: + sourceCommit: 50e5edd07155de2eec2a8b6b2ad95820748cfec7 +--- + +{{GlossarySidebar}} + +**_栅格图_**（_位图_）是由像素网格定义的图像文件。Web 上常见的栅格图格式有 {{Glossary("JPEG")}}、{{Glossary("PNG")}}、{{Glossary("GIF")}} 和 [ICO](https://zh.wikipedia.org/wiki/ICO)。 + +栅格图文件通常包含一组尺寸，但用于网站图标和 [CSS 光标图像](/zh-CN/docs/Web/CSS/cursor)的 ICO 和 CUR 格式可以包含多组尺寸。 From 06e78f2f40bbe708a1283dbfcebc3e98aace509e Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 09:25:52 +0800 Subject: [PATCH 27/95] zh-CN: create Glossary/Digital_signature (#23347) Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- .../zh-cn/glossary/digital_signature/index.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 files/zh-cn/glossary/digital_signature/index.md diff --git a/files/zh-cn/glossary/digital_signature/index.md b/files/zh-cn/glossary/digital_signature/index.md new file mode 100644 index 00000000000000..a977c9e472acb1 --- /dev/null +++ b/files/zh-cn/glossary/digital_signature/index.md @@ -0,0 +1,30 @@ +--- +title: 数字签名 +slug: Glossary/Digital_signature +l10n: + sourceCommit: 50e5e8a9b8a6b7d0dd9877610c9639d8b90f329f +--- + +{{GlossarySidebar}} + +**数字签名**是用于{{glossary("authentication", "认证")}}文档或消息的对象。 + +数字签名通常基于{{glossary("public-key cryptography", "非对称密钥密码")}}。其中，创建一个具有这样的属性的密钥对：如果某个输入使用一个密钥加密，那么只能使用另一个密钥解密，反之亦然。 + +密钥对的创建者将其中一个密钥公开，另一个密钥保密。要签署文档，密钥对的所有者创建文档的{{glossary("hash", "散列值")}}，并使用私钥对其进行加密。 + +文档和签名被发送给验证者，验证者对文档进行散列运算，检索公钥，并解密签名：如果签名与散列值匹配，则签名可以通过验证，验证者可以确信它是由具有私钥访问权限的实体创建的。 + +数字签名系统的安全性取决于： + +- 私钥的所有者保持其安全：如果其他实体可以访问私钥，则它们可以冒充所有者。 +- 验证者使用的公钥是所有者私钥的真实对应物：如果攻击者能够欺骗验证者相信错误的公钥，则它们可以冒充所有者。 + +验证者通常使用{{glossary("digital certificate", "数字证书")}}来检查公钥是否真实。 + +## 参见 + +- 相关术语： + - {{glossary("Digital certificate", "数字证书")}} + - {{glossary("Hash", "散列")}} + - {{glossary("Public-key cryptography", "非对称密钥密码")}} From e4f8abe2e413a9a9d104490950ca95311911a147 Mon Sep 17 00:00:00 2001 From: abing <1786107245@qq.com> Date: Tue, 3 Sep 2024 10:30:27 +0800 Subject: [PATCH 28/95] zh-cn: update "What's in the head? Metadata in HTML" (#23363) --- .../the_head_metadata_in_html/index.md | 47 ++++++++++--------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/files/zh-cn/learn/html/introduction_to_html/the_head_metadata_in_html/index.md b/files/zh-cn/learn/html/introduction_to_html/the_head_metadata_in_html/index.md index 4119bd5a5b4b27..11c37fff85647a 100644 --- a/files/zh-cn/learn/html/introduction_to_html/the_head_metadata_in_html/index.md +++ b/files/zh-cn/learn/html/introduction_to_html/the_head_metadata_in_html/index.md @@ -203,37 +203,40 @@ Twitter 还拥有自己的类型的专有元数据协议（称为 [Twitter Cards ![Firefox 的书签面板，显示了一个书签的例子，旁边显示了一个 favicon。](bookmark-favicon.png) -如今还有很多其他的图标类型可以考虑。例如，你可以在 MDN Web 文档的源代码中找到它： +你可能还需要在不同的场景使用不同的图标。例如，你可以在 MDN Web 文档的源代码中找到它： ```html - - - - - + + +``` + +这是一种使网站在保存到苹果设备主屏幕时显示图标的方法。你甚至可以为不同的设备提供不同的图标，以确保图标在所有设备上都看起来美观。例如： + +```html + - + rel="apple-touch-icon" + sizes="167x167" + href="/apple-touch-icon-167x167.png" /> + - + rel="apple-touch-icon" + sizes="180x180" + href="/apple-touch-icon-180x180.png" /> + + rel="apple-touch-icon" + sizes="152x152" + href="/apple-touch-icon-152x152.png" /> + + + + ``` 这些注释解释了每个图标的用途——这些元素涵盖的东西提供一个高分辨率图标，这些高分辨率图标当网站保存到 iPad 的主屏幕时使用。 -不用担心现在实现所有这些类型的图标——这是一个相当先进的功能，不要求你有这方面的知识来通过课程的进展。这里的主要目的是让你提前了解有这一样东西，以防当你浏览其他网站的源代码时不理解源代码的含义。 +不用担心现在实现所有这些类型的图标——这是一个相当先进的特性，不要求你有这方面的知识来通过课程的进展。这里的主要目的是让你提前了解有这一样东西，以防当你浏览其他网站的源代码时不理解源代码的含义。如果你确实想了解更多关于所有这些值以及如何选择它们，请阅读 {{HTMLElement("link")}} 元素的参考页面。 > [!NOTE] > 如果你的网站使用了内容安全策略（Content Security Policy，CSP）来增加安全性，这个策略会应用在 favicon 图标上。如果你遇到了图标没有被加载的问题，你需要确认 {{HTTPHeader("Content-Security-Policy")}} 响应头的 [`img-src` 指令](/zh-CN/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) 没有阻止访问图标。 From 352b37a056b63de66160434ee0144d71ffb8d8e6 Mon Sep 17 00:00:00 2001 From: A1lo Date: Tue, 3 Sep 2024 10:34:32 +0800 Subject: [PATCH 29/95] zh-cn: update the translation of `IDBObjectStore` (#23256) Co-authored-by: Jason Ren <40999116+jasonren0403@users.noreply.github.com> --- files/zh-cn/web/api/idbobjectstore/index.md | 582 ++++---------------- 1 file changed, 98 insertions(+), 484 deletions(-) diff --git a/files/zh-cn/web/api/idbobjectstore/index.md b/files/zh-cn/web/api/idbobjectstore/index.md index ad646c0369f21f..ce6e26728f5bc5 100644 --- a/files/zh-cn/web/api/idbobjectstore/index.md +++ b/files/zh-cn/web/api/idbobjectstore/index.md @@ -1,475 +1,91 @@ --- title: IDBObjectStore slug: Web/API/IDBObjectStore +l10n: + sourceCommit: 32305cc3cf274fbfdcc73a296bbd400a26f38296 --- -{{APIRef("IndexedDB")}} - -[IndexedDB API](/zh-CN/docs/Web/API/IndexedDB_API) 的 **`IDBObjectStore`** 接口表示数据库中的 一个 [对象库 (object store)](/zh-CN/IndexedDB#gloss_object_store) 。对象库中的记录根据其键值进行排序。这种排序可以实现快速插入，查找和有序检索。 - -{{AvailableInWorkers}} - -注：为了方便理解，可以把“对象存储空间”想象成关系数据库的“表”结构，下文也会把对象存储空间称为表。 - -## 方法预览 - -| `IDBRequest add (in any value, in optional any key) raises (DOMException);` | -| ------------------------------------------------------------------------------------------------------------------- | -| `IDBRequest clear() raises (DOMException);` | -| `IDBRequest count (in optional any key) raises (DOMException);` | -| `IDBIndex createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (DOMException);` | -| `IDBRequest delete (in any key) raises (DOMException);` | -| `void deleteIndex (in any DOMString indexName) raises (DOMException); | -| `IDBRequest get (in any key) raises (DOMException);` | -| `IDBIndex index (in DOMString name) raises (DOMException);` | -| `IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises(DOMException);` | -| `IDBRequest put (in any value, in optional any key) raises (DOMException);` | - -## 属性 - -| Attribute | Type | Description | -| --------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| `indexNames` | `readonly DOMStringList` | 表中对象的[索引](/zh-CN/IndexedDB#gloss_index)名列表。 | -| `keyPath` | `readonly` [`DOMString`](/En/DOM/DOMString) | 表中的[键路径](/zh-CN/IndexedDB#gloss_key_path)，如果该属性为 null，每次操作表时必须提供一个键名。 | -| `name` | `readonly` [`DOMString`](/En/DOM/DOMString) | 表名 | -| `transaction` | `readonly IDBTransaction` | 事务的名称，该表属于此事务。 | -| `autoIncrement` | `readonly boolean` | 表中自增字段的值 | - -## 方法 - -### add() - -返回一个 IDBRequest 对象，并且在新线程中克隆一个值，该值存储在表中。 - -想知道是否成功添加数据，可以在事务的 complete 事件中进行监听，而不是 success，因为事务在 success 事件之后还有可能失败。 - -add 方法只能插入数据。如果以 key 参数作为某记录的关键字，并且该条记录已存在，则其所返回的请求对象会产生 ConstrainError 错误。 - -``` -IDBRequest add (in any value, in optional any key) raises (DOMException); -``` - -#### 参数 - -- value - - : 被存储的值。 -- key - - : 标识某条记录的键，如果不指定，它会被设为 null。 - -##### 返回 - -- [IDBRequest](/zh-CN/IndexedDB/IDBRequest) - - : 一个请求对象，可以在其中绑定事件。 - -##### 异常 - -该方法会抛出 DOMError 类型的 DOMException 异常。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExceptionDescription
ReadOnlyError - The transaction associated with this operation is in read-only - mode. -
TransactionInactiveErrorThis IDBObjectStore's transaction is inactive.
DataError -

Any of the following conditions apply:

-
    -
  • - The object store uses in-line keys or has a key generator, and a key - parameter was provided. -
    • -
  • - The object store uses out-of-line keys and has no key generator, and - no key parameter was provided. -
    • -
  • - The object store uses in-line keys but no key generator, and the - object store's key path does not yield a valid key. -
    • -
  • - The key parameter was provided but does not contain a valid key. -
    • -
-
InvalidStateErrorThe IDBObjectStore has been deleted or removed.
DataCloneError - The data being stored could not be cloned by the internal structured - cloning algorithm. -
- -### clear() - -创建并立即返回一个 [IDBRequest](/zh-CN/IndexedDB/IDBRequest) 对象，并且在一个单独的线程中清除这个对象存储。清除对象存储包括从对象存储中删除所有的记录，并删除对象存储引用的索引中的所有记录。 - -``` -IDBRequest clear () raises (DOMException); -``` - -#### Returns - -- [IDBRequest](/zh-CN/IndexedDB/IDBRequest) - - : 返回一个 request 对象，在其上触发与操作相关的事件。 - -##### Exceptions - -此方法可能会引发 domException，其中 domError 的类型如下： - -| Exception | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -| ReadOnlyError | The transaction associated with this operation is in read-only [mode](/zh-CN/docs/IndexedDB/IDBTransaction#mode_constants). | -| TransactionInactiveError | This IDBObjectStore's transaction is inactive. | - -### count() - -立即返回一个 [IDBRequest](/zh-CN/IndexedDB/IDBRequest) 对象，并在新线程中计算符合条件的对象的数量，该方法的参数可以是键，或键范围（key range）。在 [IDBRequest](/zh-CN/IndexedDB/IDBRequest) 对象中，source 属性就是 IDBObjectStore 对象，result 属性持有计算后的数量值。如果参数非法将会抛出异常。 - -``` -IDBRequest count (in optional any key) raises(DOMException); -``` - -#### 参数 - -- key - - : 计算被该键或键范围（key range）所标识的记录数。 - -##### Returns - -- [IDBRequest](/zh-CN/IndexedDB/IDBRequest) - - : 一个请求对象，可绑定事件。 - -##### 异常 - -该方法会引发如下异常： - -| Exception | Description | -| ------------------------ | --------------------------- | -| TransactionInactiveError | 事务已闲置 | -| DataError | key 参数非法 | -| `InvalidStateError` | IDBObjectStore 对象已被删除 | - -### createIndex() - -创建并返回新的 IDBIndex 对象，该方法只能从 versionchange 事务模式的回调方法中被调用。 - -``` -IDBIndex createIndex (in DOMString name, in DOMString keyPath, in optional boolean unique) raises (DOMException); -``` - -#### Parameters - -- name - - : The name of the index to create. -- keyPath - - : The key path for the index to use. -- optionalParameters - - - : The IDBIndexParameters object whose attributes are optional parameters to the method. It includes the following properties: - - | Attribute | Description | - | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `unique` | If true, the index will not allow duplicate values for a single key. | - | `multiEntry` | If true, the index will add an entry in the index for each array element when the _keypath_ resolves to an Array. If false, it will add one single entry containing the Array. | - -##### Returns - -- [IDBIndex](/zh-CN/IndexedDB/IDBIndex) - - : The newly created index. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `InvalidStateError` | The IDBObjectStore has been deleted or removed or the method was not called from a [`versionchange`](/zh-CN/docs/IndexedDB/IDBTransaction#VERSION_CHANGE) transaction mode callback. | -| `ConstraintError` | An index with the same name (case-sensitive) already exists in the database. | - -### delete() - -Immediately returns an [`IDBRequest`](/zh-CN/IndexedDB/IDBRequest) object, and removes the records specified by the given key or key range from this object store, and any indexes that reference it, in a separate thread. - -``` -IDBRequest delete (in any key) raises (DOMException); -``` - -#### Parameters - -- key - - : The key or key range that identifies the records. - -##### Returns - -- [IDBRequest](/zh-CN/IndexedDB/IDBRequest) - - : A request object on which subsequent events related to this operation are fired. As [per spec](http://www.w3.org/TR/IndexedDB/#object-store-deletion-operation) the result of the Object Store Deletion Operation algorithm is `undefined`, so it's not possible to know if some records were actually deleted by looking at the request result. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -| TransactionInactiveError | This IDBObjectStore's transaction is inactive. | -| ReadOnlyError | The transaction associated with this operation is in read-only [mode](/zh-CN/docs/IndexedDB/IDBTransaction#mode_constants). | -| `DataError` | The key or key range provided contains an invalid key. | - -> [!NOTE] -> If the key that identifies the record is a Number, the key passed to the delete method must be a Number too, and not a String. So for example you might need to do the following: -> -> ```js -> var key_val = "42"; -> var key = Number(key_val); -> objectstore.delete(key); -> ``` - -### deleteIndex() - -Destroys the index with the specified name in the connected database. Note that this method must be called only from a [`VersionChange`](/zh-CN/IndexedDB/IDBTransaction#VERSION_CHANGE) transaction mode callback. Note that this method synchronously modifies the [indexNames](#attr_indexNames) property. - -``` -void deleteIndex (in any DOMString indexName) raises (DOMException); -``` - -#### Parameters - -- indexName - - : The name of the existing index to remove. -- Returns - - : Void - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `InvalidStateError` | The method was not called from a [`versionchange`](/zh-CN/docs/IndexedDB/IDBTransaction#VERSION_CHANGE) transaction mode callback. | -| `NotFoundError` | There is no index with the given name (case-sensitive) in the database. | - -### get() - -Immediately returns an [IDBRequest](/zh-CN/IndexedDB/IDBRequest) object, and retrieves the requested record from the object store in a separate thread. If the operation is successful, then a success event is fired on the returned object, with its [`result`](/zh-CN/IndexedDB/IDBSuccessEvent#attr_result) set to the retrieved value, and [`transaction`](/zh-CN/IndexedDB/IDBTransactionEvent#attr_transaction) set to the transaction in which this object store is opened. - -``` -IDBRequest get (in any key) raises (DOMException); -``` - -> **备注：**This function produces the same result if no record with the given key exists in the database as when a record exists, but with an `undefined` value. To tell these situations apart, call the openCursor() method with the same key. That method provides a cursor if the record exists, and no cursor if it does not. - -#### Parameters - -- key - - : The key or key range identifying the record to retrieve. In the case of a key range, the record returned is the first record associated with the first key in the range. - -##### Returns - -- [`IDBRequest`](/zh-CN/IndexedDB/IDBRequest) - - : A request object on which subsequent events related to this operation are fired. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------------ | ------------------------------------------------------- | -| TransactionInactiveError | This IDBObjectStore's transaction is inactive. | -| DataError | The key or key range provided contains and invalid key. | -| `InvalidStateError` | The IDBObjectStore has been deleted or removed. | - -### index() - -Opens the named index in this object store. - -``` -IDBIndex index (in DOMString name) raises (DOMException); -``` - -#### Parameters - -- name - - : The name of the index to open. - -##### Returns - -- [`IDBIndex`](/zh-CN/IndexedDB/IDBIndex) - - : An object for accessing the index. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------- | ----------------------------------------------------------------------------------------------- | -| `InvalidStateError` | The source object store has been deleted, or the transaction for the object store has finished. | -| `NotFoundError` | There is no index with the given name (case-sensitive) in the database. | - -### openCursor() - -Immediately returns an [IDBRequest](/zh-CN/IndexedDB/IDBRequest) object, and creates a [cursor](/zh-CN/docs/IndexedDB/IDBCursor) over the records in this object store, in a separate thread. If there is even a single record that matches the [key range](/zh-CN/IndexedDB#gloss_key_range), then a success event is fired on the returned object, with its [`result`](/zh-CN/IndexedDB/IDBSuccessEvent#attr_result) set to the [IDBCursor](/zh-CN/IndexedDB/IDBCursor) object for the new cursor. If no records match the key range, then a success event is fired on the returned object, with its [`result`](/zh-CN/IndexedDB/IDBSuccessEvent#attr_result) set to null. - -``` -IDBRequest openCursor (in optional IDBKeyRange range, in optional unsigned short direction) raises(DOMException); -``` - -#### Parameters - -- range - - : The key range to use as the cursor's range. If this parameter is unspecified or null, then the range includes all the records in the object store. -- direction - - : The cursor's [direction](/zh-CN/docs/IndexedDB/IDBCursor). - -##### Returns - -- [`IDBRequest`](/zh-CN/IndexedDB/IDBRequest) - - : A request object on which subsequent events related to this operation are fired. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - -| Exception | Description | -| ------------------------ | ------------------------------------------------------- | -| TransactionInactiveError | This IDBObjectStore's transaction is inactive. | -| DataError | The key or key range provided contains and invalid key. | -| `InvalidStateError` | The IDBObjectStore has been deleted or removed. | -| `TypeError` | The value of the `direction` parameter is invalid. | - -### put() - -Returns an [IDBRequest](/zh-CN/IndexedDB/IDBRequest) object, and, in a separate thread, creates a [structured clone](http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#structured-clone) of the `value`, and stores the cloned value in the object store. If the record is successfully stored, then a success event is fired on the returned request object with the [`result`](/zh-CN/docs/IndexedDB/IDBRequest) set to the key for the stored record, and [`transaction`](/zh-CN/docs/IndexedDB/IDBRequest) set to the transaction in which this object store is opened. - -The put method is an _update or insert_ method. See also the [add()](#add) method. - -``` -IDBRequest put (in any value, in optional any key) raises (DOMException); -``` - -#### Parameters - -- value - - : The value to be stored. -- key - - : The key to use to identify the record. If unspecified, it results to null. - -##### Returns - -- IDBRequest - - : A request object on which subsequent events related to this operation are fired. - -##### Exceptions - -This method may raise a [DOMException](/zh-CN/docs/DOM/DOMException) with a [DOMError](/zh-CN/docs/DOM/DOMError) of the following types: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExceptionDescription
ReadOnlyError - The transaction associated with this operation is in read-only - mode. -
TransactionInactiveErrorThis IDBObjectStore's transaction is inactive.
DataError -

Any of the following conditions apply:

-
    -
  • - The object store uses in-line keys or has a key generator, and a key - parameter was provided. -
    • -
  • - The object store uses out-of-line keys and has no key generator, and - no key parameter was provided. -
    • -
  • - The object store uses in-line keys but no key generator, and the - object store's key path does not yield a valid key. -
    • -
  • - The key parameter was provided but does not contain a valid key. -
    • -
-
InvalidStateErrorThe IDBObjectStore has been deleted or removed.
DataCloneError - The data being stored could not be cloned by the internal structured - cloning algorithm. -
- -## Example - -This example shows a variety of different uses of object stores, from updating the data structure with {{domxref("IDBObjectStore.createIndex")}} inside an `onupgradeneeded`function, to adding a new item to our object store with {{domxref("IDBObjectStore.add")}}. For a full working example, see our [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) app ([view example live](https://mdn.github.io/dom-examples/to-do-notifications/).) +{{APIRef("IndexedDB")}} {{AvailableInWorkers}} + +[IndexedDB API](/zh-CN/docs/Web/API/IndexedDB_API) 的 **`IDBObjectStore`** 接口表示数据库中的对象存储。对象存储中的记录根据其键值进行排序。这种排序可以实现快速插入、查找和有序检索。 + +## 实例属性 + +- {{domxref("IDBObjectStore.indexNames")}} {{ReadOnlyInline}} + - : 对象存储中对象的[索引](/zh-CN/docs/Web/API/IndexedDB_API/Basic_Terminology#索引)名列表。 +- {{domxref("IDBObjectStore.keyPath")}} {{ReadOnlyInline}} + - : 对象存储的[键路径](/zh-CN/docs/Web/API/IndexedDB_API/Basic_Terminology#键路径)。如果该属性为 `null`，应用在每次操作时必须提供键名。 +- {{domxref("IDBObjectStore.name")}} + - : 对象存储的名称。 +- {{domxref("IDBObjectStore.transaction")}} {{ReadOnlyInline}} + - : 对象存储所属的 {{domxref("IDBTransaction")}} 对象。 +- {{domxref("IDBObjectStore.autoIncrement")}} {{ReadOnlyInline}} + - : 对象存储自增标志的值。 + +## 实例方法 + +- {{domxref("IDBObjectStore.add()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并且在单独的线程中创建该值（`value`）的[结构化克隆](https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#structured-clone)，并将克隆后的值存储到对象存储中。其用于将新记录添加到对象存储中。 +- {{domxref("IDBObjectStore.clear()")}} + - : 创建并立即返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中清除当前对象存储。其用于删除对象存储中当前的所有记录。 +- {{domxref("IDBObjectStore.count()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中返回匹配提供的键或 {{domxref("IDBKeyRange")}} 的记录的数量。如果未提供参数，它会返回当前存储的记录总数。 +- {{domxref("IDBObjectStore.createIndex()")}} + - : 在版本升级时创建新索引，返回一个所连接数据库的新 {{domxref("IDBIndex")}} 对象。 +- {{domxref("IDBObjectStore.delete()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中删除由指定键选中的存储对象。其用于删除对象存储中的某个单独的记录。 +- {{domxref("IDBObjectStore.deleteIndex()")}} + - : 在版本升级时销毁所连接数据库的指定索引。 +- {{domxref("IDBObjectStore.get()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中返回由指定键选中的存储对象。其用于从对象存储中检索特定记录。 +- {{domxref("IDBObjectStore.getKey()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中检索并返回与指定参数匹配的对象存储中记录的键。 +- {{domxref("IDBObjectStore.getAll()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中检索并返回与指定参数匹配的对象存储中的所有记录，如果没有提供参数，则返回存储中的所有记录。 +- {{domxref("IDBObjectStore.getAllKeys()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，检索与指定参数匹配的对象存储中所有对象记录的键，如果没有提供参数，则检索存储中的所有对象记录的键。 +- {{domxref("IDBObjectStore.index()")}} + - : 打开当前对象存储的指定索引，然后索引可被用于通过游标来按索引的顺序返回一系列记录。 +- {{domxref("IDBObjectStore.openCursor()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中返回一个新的 {{domxref("IDBCursorWithValue")}} 对象。其用于通过游标按主键迭代对象存储。 +- {{domxref("IDBObjectStore.openKeyCursor()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中返回一个新的 {{domxref("IDBCursor")}} 对象。其用于通过键迭代对象存储。 +- {{domxref("IDBObjectStore.put()")}} + - : 返回一个 {{domxref("IDBRequest")}} 对象，并在单独的线程中创建该值（`value`）的[结构化克隆](https://html.spec.whatwg.org/multipage/common-dom-interfaces.html#structured-clone)，并将克隆后的值存储到对象存储中。其用于在事务模式为 `readwrite` 时更新对象存储中的现有记录。 + +## 示例 + +此示例展示了对象存储的各种不同用法，从在 `onupgradeneeded` 函数中使用 {{domxref("IDBObjectStore.createIndex")}} 更新数据结构，到使用 {{domxref("IDBObjectStore.add")}} 向对象存储中添加新项目。有关完整的可运行示例，请参见我们的[待办事项通知](https://github.com/mdn/dom-examples/tree/main/to-do-notifications)应用程序（[查看在线示例](https://mdn.github.io/dom-examples/to-do-notifications/)）。 ```js -// Let us open our database -var DBOpenRequest = window.indexedDB.open("toDoList", 4); +// 打开数据库 +const DBOpenRequest = window.indexedDB.open("toDoList", 4); -DBOpenRequest.onsuccess = function (event) { - note.innerHTML += "
  • Database initialised.
    • "; +DBOpenRequest.onsuccess = (event) => { + note.appendChild(document.createElement("li")).textContent = + "Database initialized."; - // store the result of opening the database in db. + // 将打开数据库的结果存储到 db 中。 db = DBOpenRequest.result; }; -// This event handles the event whereby a new version of -// the database needs to be created Either one has not -// been created before, or a new version number has been -// submitted via the window.indexedDB.open line above -DBOpenRequest.onupgradeneeded = function (event) { - var db = event.target.result; +// 此事件处理要创建新版本的数据库的事件（要么之前没有创建过，要么通过上面的 +// window.indexedDB.open 行提交了一个新的版本号） +DBOpenRequest.onupgradeneeded = (event) => { + const db = event.target.result; - db.onerror = function (event) { - note.innerHTML += "
  • Error loading database.
    • "; + db.onerror = (event) => { + note.appendChild(document.createElement("li")).textContent = + "加载数据库时出错。"; }; - // Create an objectStore for this database + // 在数据库中创建一个对象存储 - var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" }); + const objectStore = db.createObjectStore("toDoList", { + keyPath: "taskTitle", + }); - // define what data items the objectStore will contain + // 定义对象存储将包含的数据项 objectStore.createIndex("hours", "hours", { unique: false }); objectStore.createIndex("minutes", "minutes", { unique: false }); @@ -479,11 +95,12 @@ DBOpenRequest.onupgradeneeded = function (event) { objectStore.createIndex("notified", "notified", { unique: false }); - note.innerHTML += "
  • Object store created.
    • "; + note.appendChild(document.createElement("li")).textContent = + "已创建对象存储。"; }; -// Create a new item to add in to the object store -var newItem = [ +// 创建一个要添加到对象存储中的新项目 +const newItem = [ { taskTitle: "Walk dog", hours: 19, @@ -495,45 +112,42 @@ var newItem = [ }, ]; -// open a read/write db transaction, ready for adding the data -var transaction = db.transaction(["toDoList"], "readwrite"); +// 创建一个读写事务，准备添加数据 +const transaction = db.transaction(["toDoList"], "readwrite"); -// report on the success of the transaction completing, when everything is done -transaction.oncomplete = function (event) { - note.innerHTML += "
  • Transaction completed.
    • "; +// 当一切完成后，报告事务成功完成 +transaction.oncomplete = (event) => { + note.appendChild(document.createElement("li")).textContent = "事务完成。"; }; -transaction.onerror = function (event) { - note.innerHTML += - "
  • Transaction not opened due to error. Duplicate items not allowed.
    • "; +transaction.onerror = (event) => { + note.appendChild(document.createElement("li")).textContent = + "事务因错误而未能创建。不允许重复的项目。"; }; -// create an object store on the transaction -var objectStore = transaction.objectStore("toDoList"); -// make a request to add our newItem object to the object store -var objectStoreRequest = objectStore.add(newItem[0]); +// 使用事务创建对象存储 +const objectStore = transaction.objectStore("toDoList"); +// 请求将 newItem 对象添加到对象存储中 +const objectStoreRequest = objectStore.add(newItem[0]); -objectStoreRequest.onsuccess = function (event) { - note.innerHTML += "
  • Request successful .
    • "; +objectStoreRequest.onsuccess = (event) => { + note.appendChild(document.createElement("li")).textContent = "请求成功。"; }; ``` -## Specifications +## 规范 {{Specifications}} -## Browser compatibility - -The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out and send us a pull request. +## 浏览器兼容性 {{Compat}} -## See also +## 参见 -- [Using IndexedDB](/zh-CN/docs/Web/API/IndexedDB_API/Using_IndexedDB) -- Starting transactions: {{domxref("IDBDatabase")}} -- Using transactions: {{domxref("IDBTransaction")}} -- Setting a range of keys: {{domxref("IDBKeyRange")}} -- Retrieving and making changes to your data: {{domxref("IDBObjectStore")}} -- Using cursors: {{domxref("IDBCursor")}} -- Reference example: [To-do Notifications](https://github.com/mdn/dom-examples/tree/main/to-do-notifications) ([view example live](https://mdn.github.io/dom-examples/to-do-notifications/).) +- [使用 IndexedDB](/zh-CN/docs/Web/API/IndexedDB_API/Using_IndexedDB) +- 开始事务：{{domxref("IDBDatabase")}} +- 使用事务：{{domxref("IDBTransaction")}} +- 设置键的范围：{{domxref("IDBKeyRange")}} +- 使用游标：{{domxref("IDBCursor")}} +- 参考示例：[待办事项通知](https://github.com/mdn/dom-examples/tree/main/to-do-notifications)（[查看在线示例](https://mdn.github.io/dom-examples/to-do-notifications/)）。 From e3e0ad601cb5e939af70f8f176f40060d84b8af2 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 14:04:01 +0800 Subject: [PATCH 30/95] zh-CN: update "Express Tutorial Part 4: Routes and controllers" (#22385) Co-authored-by: A1lo --- .../express_nodejs/routes/index.md | 460 ++++++++++++++---- 1 file changed, 376 insertions(+), 84 deletions(-) diff --git a/files/zh-cn/learn/server-side/express_nodejs/routes/index.md b/files/zh-cn/learn/server-side/express_nodejs/routes/index.md index 712e4eb4b71cf1..24a7ee42d2f1b4 100644 --- a/files/zh-cn/learn/server-side/express_nodejs/routes/index.md +++ b/files/zh-cn/learn/server-side/express_nodejs/routes/index.md @@ -1,11 +1,13 @@ --- title: Express 教程 4：路由和控制器 slug: Learn/Server-side/Express_Nodejs/routes +l10n: + sourceCommit: 1467f47e1944c151b368e047fe4f9cf7f1f0e0e2 --- {{LearnSidebar}}{{PreviousMenuNext("Learn/Server-side/Express_Nodejs/mongoose", "Learn/Server-side/Express_Nodejs/Displaying_data", "Learn/Server-side/Express_Nodejs")}} -本节将为 [LocalLibrary](/zh-CN/docs/Learn/Server-side/Express_Nodejs/Tutorial_local_library_website) 站点中所需的资源端点（Endpoint）配置路由。先用空的处理函数搭建起路由处理的模块结构（下节会将它们扩充为真实的处理函数）。并详细介绍了 Express 路由模块的创建方法。 +在本教程中，我们将为[本地图书馆](/zh-CN/docs/Learn/Server-side/Express_Nodejs/Tutorial_local_library_website)网站最终需要的所有资源端点设置具有“虚拟”处理器函数的路由（URL 处理代码）。完成后，我们就有了路由处理代码的模块化结构，可以在接下来的文章中使用真正的处理器函数对其进行扩展。此外，我们还将真正了解如何使用 Express 创建模块化路由！ @@ -15,11 +17,10 @@ slug: Learn/Server-side/Express_Nodejs/routes 回顾 Express/Node 入门。完成本教程之前小节（。完成本教程之前小节（包括 Express 教程 3：使用数据库 (Mongoose) - 等）。了解服务器端编程，了解正则表达式。 + >Express 教程 3：使用数据库（Mongoose））。 @@ -31,35 +32,36 @@ slug: Learn/Server-side/Express_Nodejs/routes ## 概览 -[上节](/zh-CN/docs/Learn/Server-side/Express_Nodejs/mongoose) 定义了与数据库交互的 Mongoose 模型，使用一个（独立）脚本创建了一些初始记录。现在可以编写代码来向用户展示这些信息。首先要确定页面中应显示哪些信息，然后定义适当的 URL 来返回这些资源。随后应创建路由（URL 处理器）和视图（模板）来显示这些页面。 +[上节](/zh-CN/docs/Learn/Server-side/Express_Nodejs/mongoose)定义了与数据库交互的 _Mongoose_ 模型，并使用一个（独立）脚本创建了一些初始的图书馆记录。现在可以编写代码来向用户展示这些信息。我们首先要确定页面中应显示哪些信息，然后定义适当的 URL 来返回这些资源。随后要创建路由（URL 处理器）和视图（模板）来显示这些页面。 -下图展示了 HTTP 请求/响应处理的主数据流和需要实现的行为。图中除视图（View）和路由（Route）外，还展示了控制器（Controller），它们是实际的请求处理函数，与路由请求代码是分开的。 +下图展示了 HTTP 请求/响应处理的主数据流和需要实现的行为。图中除视图（View）和路由（Route）外，还展示了控制器（Controller），即将路由请求的代码与实际处理请求的代码分离的函数。 -模型已经创建，现在要创建的主要是： +因为我们已经创建好了模型，我们接下来需要创建的是： -- 路由：把需要支持的请求（以及请求 URL 中包含的任何信息）转发到适当的控制器函数。 -- 控制器：从模型中获取请求的数据，创建一个 HTML 页面显示出数据，并将页面返回给用户，以便在浏览器中查看。 +- “路由”：把需要支持的请求（以及请求 URL 中编码的任何信息）转发到适当的控制器函数。 +- 控制器函数：从模型中获取请求的数据，创建一个显示数据的 HTML 页面，并将页面返回给用户，以便在浏览器中查看。 - 视图（模板）：供控制器用来渲染数据。 -![Express HTTP 请求/响应 路径](mvc_express.png) +![MVC Express 服务器的主要数据流图：“路由”接收发送到 Express 服务器的 HTTP 请求，并将其转发给相应的“控制器”函数。控制器从模型中读取和写入数据。模型连接到数据库，为服务器提供数据访问。控制器使用“视图”（也称为模板）来呈现数据。控制器将 HTML HTTP 响应作为 HTTP 响应发送回客户端。](mvc_express.png) -因此我们需要页面来显示藏书、藏书种类、作者、藏书副本的列表和详细信息，还需要页面来创建、更新和删除记录。这些内容对于本节来说不算少，因此本节将主要集中在路由和控制器设置。本节编写的这些函数都只有框架，后续章节再扩展控制器方法，以使用模型数据。 +因此我们最终需要显示图书、图书种类、作者、图书副本的列表和详细信息的页面，还需要页面来创建、更新和删除记录。这些内容对于本节来说不算少，因此本节将主要集中在路由和控制器设置。本节编写的这些函数都只有框架，而会后续章节再扩展控制器方法以使用模型数据。 -第一段提供了 Express 的 [Router](http://expressjs.com/en/4x/api.html#router) 中间件的“入门”知识。后续设置 LocalLibrary 路由时将用到这些知识。 +第一小节提供了 Express 的 [Router](http://expressjs.com/en/4x/api.html#router) 中间件的“入门”知识。后续设置本地图书馆的路由时我们将用到这些知识。 ## 路由入门 路由是一段 Express 代码，它将 HTTP 动词（`GET`、`POST`、`PUT`、`DELETE` 等）、URL 路径/模式和处理函数三者关联起来。 -创建路由有几种方法。本教程将使 [`express.Router`](http://expressjs.com/en/guide/routing.html#express-router) 中间件，因为使用它可以将站点特定部分的路由处理程序打包，并使用通用路由前缀访问它们。我们会将所有与图书馆有关的路由保存在 `catalog` 模块中，在添加处理帐户或其他功能的路由时，可以分开保存。 +创建路由有多种方法。在本教程中，我们将使用 [`express.Router`](https://expressjs.com/en/guide/routing.html#express-router) 中间件，因为它允许我们将网站特定部分的路由处理器分组在一起并使用共同的路由前缀访问它们。我们将把所有与图书馆相关的路由保存在“catalog”（目录）模块中，如果我们添加了用于处理用户账户或其他功能的路由，可以将它们单独分组。 -> **备注：** [Express 简介 > 创建路由处理程序](/zh-CN/docs/zh-CN/docs/Learn/Server-side/Express_Nodejs/Introduction#%E5%88%9B%E5%BB%BA%E8%B7%AF%E7%94%B1%E5%A4%84%E7%90%86%E5%99%A8%EF%BC%88Route_handler%EF%BC%89) 简要讨论了 Express 应用的路由机制。使用 `Router` 可以保证更好的模块化（下文所述），且用法与直接在 Express 应用对象定义路由非常类似。 +> [!NOTE] +> 我们在 [Express 简介 > 创建路由处理程序](/zh-CN/docs/Learn/Server-side/Express_Nodejs/Introduction#创建路由处理器（route_handler）)中简要讨论了 Express 应用的路由机制。使用 _Router_ 可以保证更好的模块化（下文所述），且用法与直接在 *Express 应用对象*上定义路由非常类似。 -本段以下内容介绍使用 `Router` 定义路由的方法。 +本小节的剩余部分内容将介绍使用 `Router` 定义路由的方法。 ### 定义和使用单独的路由模块 -以下代码举例说明了如何创建路由模块，以及如何在 Express 应用中使用它。 +以下代码举例说明了如何创建路由模块，以及如何在 _Express_ 应用中使用它。 首先，在 **wiki.js** 模块中创建一个维基路由。代码一开始导入 Express 应用对象，用它取得一个 `Router` 对象，然后用 `get()` 方法向其添加两个具体的路由。模块的最后导出该 `Router` 对象。 @@ -83,13 +85,13 @@ module.exports = router; ``` > [!NOTE] -> 上面的路由处理回调直接定义在了路由函数中。LocalLibrary 的回调将定义在单独的控制器模块中。 +> 上面的路由处理回调直接定义在了路由函数中。本地图书馆的回调将定义在单独的控制器模块中。 -要在主应用中使用该路由模块，首先应 `require` 它（**wiki.js**），然后对 Express 应用对象调用 `use()`（指定路径‘/wiki’），即可将其添加到中间件处理路径。 +要在主应用中使用该路由模块，首先应 `require()` 它（**wiki.js**），然后在 Express 应用对象上调用 `use()`（指定 URL 路径“wiki”），即可将其添加到中间件处理路径。 ```js const wiki = require("./wiki.js"); -// ... +// … app.use("/wiki", wiki); ``` @@ -108,17 +110,17 @@ router.get("/about", (req, res) => { 该回调有三个参数（通常命名为：`req`、`res`、`next`），分别是：HTTP 请求对象、HTTP 响应、中间件链中的下一个函数。 > [!NOTE] -> 路由函数就是 [Express 中间件](/zh-CN/docs/Learn/Server-side/Express_Nodejs/Introduction#Using_middleware)，这意味着它们必须（通过响应）结束请求，否则必须调用链中的 `next` 函数。上述示例使用`send()` 完成了请求，所以没有使用 `next` 参数（参数表中将其省略）。 +> 路由函数就是 [Express 中间件](/zh-CN/docs/Learn/Server-side/Express_Nodejs/Introduction#使用中间件（middleware）)，这意味着它们要么（通过响应）结束请求，要么调用链中的 `next` 函数。在上述示例中，我们使用 `send()` 完成了请求，因而没有用上 `next` 参数（参数表中将其省略）。 > -> 上述路由函数只需要一个回调，可以根据需要指定任意数量的回调参数，或一个回调函数数组。每个函数都将加入中间件链，并且将按添加顺序调用（若有回调完成请求则中止当前周期）。 +> 上述路由函数只需要一个回调。我们可以根据需要指定任意数量的回调参数或一个回调函数数组。每个函数都将加入中间件链，并且将按添加顺序调用（若有回调完成请求则中止当前周期）。 -此处的回调对响应对象调用 [`send()`](https://expressjs.com/en/4x/api.html#res.send)，当收到带有路径（'`/about'`）的 GET 请求时将返回字符串“关于此维基”。还有许多其他可以结束请求/响应周期 [响应方法](https://expressjs.com/en/guide/routing.html#response-methods)，例如，可调用 [`res.json()`](https://expressjs.com/en/4x/api.html#res.json) 来发送 JSON 响应，或调用 [`res.sendFile()`](https://expressjs.com/en/4x/api.html#res.sendFile) 来发送文件。构建 LocalLibrary 最常使用的响应方法是 [`render()`](https://expressjs.com/en/4x/api.html#res.render)，它使用模板和数据创建并返回 HTML 文件。后续章节进一步讨论。 +此处的回调对响应对象调用 [`send()`](https://expressjs.com/en/4x/api.html#res.send)，当收到带有路径（`/about`）的 GET 请求时将返回字符串“关于此维基”。还有许多其他可以结束请求/响应周期[响应方法](https://expressjs.com/en/guide/routing.html#response-methods)，例如，可调用 [`res.json()`](https://expressjs.com/en/4x/api.html#res.json) 来发送 JSON 响应，或调用 [`res.sendFile()`](https://expressjs.com/en/4x/api.html#res.sendFile) 来发送文件。构建本地图书馆最常使用的响应方法是 [`render()`](https://expressjs.com/en/4x/api.html#res.render)，它使用模板和数据创建并返回 HTML 文件。我们将在后续章节进一步讨论。 ### HTTP 动词 上面的示例使用 `Router.get()` 方法来响应特定路径的 HTTP GET 请求。 -`Router` 还为所有其他 HTTP 动词提供路由方法，大都用法相同：`post()`, `put()`, `delete()`, `options()`, `trace()`, `copy()`, `lock()`, `mkcol()`, `move()`, `purge()`, `propfind()`, `proppatch()`, `unlock()`, `report()`, `mkactivity()`, `checkout()`, `merge()`, `m-search()`, `notify()`, `subscribe()`, `unsubscribe()`, `patch()`, `search()`, 和 `connect()`。 +`Router` 还为所有其他 HTTP 动词提供路由方法，大都用法相同：`post()`、`put()`、`delete()`、`options()`、`trace()`、`copy()`、`lock()`、`mkcol()`、`move()`、`purge()`、`propfind()`、`proppatch()`、`unlock()`、`report()`、`mkactivity()`、`checkout()`、`merge()`、`m-search()`、`notify()`、`subscribe()`、`unsubscribe()`、`patch()`、`search()` 和 `connect()`。 比如下方代码与上方 `/about` 路由行为一致，但只响应 HTTP POST 请求。 @@ -130,9 +132,9 @@ router.post("/about", (req, res) => { ### 路由路径 -路由路径用于定义可请求的端点。之前示例中路径都是字符串，并且必须精确写为：'/'、'/ about'、'/ book'，等等。 +路由路径用于定义可请求的端点。之前示例中路径都是字符串，并且必须精确写作：“/”、“/about”、“/book”诸如此类。 -路由路径也可以是字符串模式（String Pattern）。可用部分正则表达式语法来定义端点的模式。以下是所涉及的正则表达式（注意，连字符（ `-`）和点（`.`）在字符串路径中解释为字面量，不能做为正则表达式）： +路由路径也可以是字符串模式（string pattern）。字符串模式使用*正则表达式语法*来定义将匹配的端点模式。语法如下所示（注意，连字符（`-`）和点（`.`）在基于字符串的路径中被解释为字面量）： - `?`：问号之前的一个字符只能出现零次或一次。例如，路由路径 `'/ab?cd'` 路径匹配端点 `acd` 或 `abcd`。 - `+`：加号之前的一个字符至少出现一次。例如，路径路径 `'/ab+cd'` 匹配端点 `abcd`、`abbcd`、`abbbcd`，等。 @@ -148,13 +150,13 @@ app.get(/.*fish$/, (req, res) => { ``` > [!NOTE] -> LocalLibrary 的大部分路由都只使用字符串，很少用字符串模式和正则表达式。接下来将讨论“路由参数”。 +> 本地图书馆的大部分路由都只用到字符串，很少用字符串模式和正则表达式。接下来我们将讨论“路由参数”。 ### 路由参数 -路径参数是命名的 URL 段，用于捕获在 URL 中的位置指定的值。命名段以冒号为前缀，然后是名称（例如 `/:your_parameter_name/`。捕获的值保存在 `req.params` 对象中，键即参数名（例如 `req.params.your_parameter_name`）。 +路径参数是*具名 URL 片段*，用于捕获在 URL 中的位置指定的值。具名段以冒号为前缀并紧接着名称（如 `/:your_parameter_name/`）。捕获的值保存在 `req.params` 对象中，其中参数名对应对象的键（例如 `req.params.your_parameter_name`）。 -举例说，一个包含用户和藏书信息的 URL：`http://localhost:3000/users/34/books/8989`，可以这样提取信息（使用 `userId` 和 `bookId` 路径参数）： +比如，我们考虑一个包含用户和图书信息的 URL：`http://localhost:3000/users/34/books/8989`。我们可以这样提取信息（使用 `userId` 和 `bookId` 路径参数）： ```js app.get("/users/:userId/books/:bookId", (req, res) => { @@ -164,19 +166,74 @@ app.get("/users/:userId/books/:bookId", (req, res) => { }); ``` -路由参数名必须由“单词字符”（/`[A-Za-z0-9_]`/）组成。 +路由参数名必须由“单词字符”（A-Z、a-z、0-9 以及 \_）组成。 > [!NOTE] -> URL `/book/create` 会匹配 `/book/:bookId` 这样的路由（将提取值为'`create`' 的 '`bookId`'）。第一个与传入 URL 相匹配的路由会被使用，因此 `/book/create` 的路由处理器必须定义在 `/book/:bookId` 路由之前，才能妥善处理。 +> URL _/book/create_ 会匹配 `/book/:bookId` 这样的路由（因为 `:bookId` 是*任意*字符串的占位符，会匹配 `create`）。第一个与传入 URL 相匹配的路由会被使用，因此 `/book/create` 的路由处理器必须定义在 `/book/:bookId` 路由之前，才能专门处理这个路由。 + +以上就是使用路由所有的预备知识。Express 文档中还能找到更多信息：[基础路由](http://expressjs.com/en/starter/basic-routing.html)和[路由指南](http://expressjs.com/en/guide/routing.html)。以下是本地图书馆路由和控制器的设置过程。 + +### 处理路由函数中的错误 + +前面显示的路由函数都有参数 `req` 和 `res`，分别代表请求和响应。路由函数还可以使用第三个参数 `next`，该参数可用于将错误传递给 Express 中间件链。 -以上就是使用路由所有的预备知识。Express 文档中还能找到更多信息：[基础路由](http://expressjs.com/en/starter/basic-routing.html) 和 [路由指南](http://expressjs.com/en/guide/routing.html)。以下是 LocalLibrary 路由和控制器的设置过程。 +下面的代码展示了它是如何工作的，使用一个数据库查询的示例，该查询采用回调函数并返回错误 `err` 或一些结果。如果返回 `err`，就将 `err` 传入 `next` 方法，（最终错误会传播到我们的全局错误处理代码）。如果成功，将返回所需的数据并将在响应中使用。 + +```js +router.get("/about", (req, res, next) => { + About.find({}).exec((err, queryResults) => { + if (err) { + return next(err); + } + // 成功了，那么就渲染吧 + res.render("about_view", { title: "About", list: queryResults }); + }); +}); +``` -## LocalLibrary 所需路由 +### 处理路由函数中的异常 -以下是站点页面的完整 URL 列表。`` 是模型名称（`book`、`bookinstance`、`genre`、`author`），`` 是一组模型，`` 是每个 Mongoose 模型实例默认的标识字段（`_id`）。 +上一节展示了 Express 期望路由函数返回错误的方式。该框架设计用于异步函数，这些函数采用回调函数（带有错误和结果参数），该函数在操作完成时调用。这是一个问题，因为稍后我们将使用基于 [Promise](/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise) 的 API 进行 Mongoose 数据库查询，并且可能会在路由函数中抛出异常（而不是在回调中返回错误）。 + +为了使框架正确处理异常，这些异常必须被捕获，然后将其作为错误转发，如上一节所示。 + +> [!NOTE] +> 目前处于测试阶段的 Express 5 有望能原生处理 JavaScript 异常。 + +在上一节中的简单示例中，`About.find().exec()` 是返回 Promise 的数据库查询，我们可以在 [`try...catch`](/zh-CN/docs/Web/JavaScript/Reference/Statements/try...catch) 块内编写路由函数，如下所示： + +```js +exports.get("/about", async function (req, res, next) { + try { + const successfulResult = await About.find({}).exec(); + res.render("about_view", { title: "About", list: successfulResult }); + } catch (error) { + return next(error); + } +}); +``` + +每个函数都需要添加大量的样板代码。在本教程中，我们将使用 [express-async-handler](https://www.npmjs.com/package/express-async-handler) 模块。它定义了一个包装器函数，隐藏了 `try...catch` 块和用于转发错误的代码。现在，相同的示例将变得非常简单，因为我们只需要为假设成功的情况编写代码： + +```js +// 导入模块 +const asyncHandler = require("express-async-handler"); + +exports.get( + "/about", + asyncHandler(async (req, res, next) => { + const successfulResult = await About.find({}).exec(); + res.render("about_view", { title: "About", list: successfulResult }); + }), +); +``` + +## 本地图书馆所需的路由 + +以下是站点页面的完整 URL 列表，其中 _object_ 是模型名称（`book`、`bookinstance`、`genre`、`author`），_objects_ 是一组模型，_id_ 是每个 Mongoose 模型实例默认的标识字段（`_id`）。 - `catalog/`：主页。 -- `catalog//`：模型（藏书、藏书副本、藏书种类、作者）的完整列表（例如 `/catalog/books/`、`/catalog/genres/` 等） +- `catalog//`：模型（图书、图书副本、图书种类、作者）的完整列表（例如 `/catalog/books/`、`/catalog/genres/` 等） - `catalog//`_：具有_ `_id` 字段值的特定模型的详细信息页面（例如 `/catalog/book/584493c1f4887f06c0e67d37`）。 - `catalog//create`：添加新模型的表单（例如 `/catalog/book/create`）。 - `catalog///update`：更新具有 `_id` 字段值的特定模型的表单（例如 `/catalog/book/584493c1f4887f06c0e67d37/update`）。 @@ -184,7 +241,7 @@ app.get("/users/:userId/books/:bookId", (req, res) => { 首页和列表页面没有包含任何额外信息。因此它们返回的结果只取决于模型类型和数据库内容，获取信息的查询操作是恒定不变的（类似地，创建对象的代码也没有较大改动）。 -与之相反，其他 URL 是用于处理特定文档/模型实例的，它们会将项目的标识嵌入 URL（上文的 ``）。可以用路径参数来提取嵌入的信息，并传递给路由处理器（后续章节中用于动态获取数据库中的信息）。通过在 URL 中嵌入信息，使得每种类型的所有资源只需要一个路由（例如，所有藏书副本的显示操作只需要一个路由）。 +与之相反，其他 URL 是用于处理特定文档/模型实例的，它们会将项目的标识嵌入 URL（上文的 ``）。可以用路径参数来提取嵌入的信息，并传递给路由处理器（后续章节中用于动态获取数据库中的信息）。通过在 URL 中嵌入信息，使得每种类型的所有资源只需要一个路由（例如，所有图书副本的显示操作只需要一个路由）。 > [!NOTE] > Express 可以通过任何方式构造 URL，可以在 URL 正文中嵌入信息（如上文），或使用 URL `GET` 参数（例如 `/book/?id=6`）。无论哪种方法，URL 都应保持整洁、合理且易读（另请参阅 [W3C 相关建议](https://www.w3.org/Provider/Style/URI)）。 @@ -193,9 +250,9 @@ app.get("/users/:userId/books/:bookId", (req, res) => { ## 创建路由处理器回调函数 -定义路由之前应先使用单独的“控制器”模块创建回调的结构骨架。（文件/模块结构没有限制，但以下结构很适合当前项目的规模）。 +在定义路由之前，我们首先要创建它们将调用的所有虚拟/骨架回调函数。这些回调函数将分别存储在 `Book`、`BookInstance`、`Genre` 和 `Author` 的“控制器”模块中（你可以使用任何文件/模块结构，但我们这样做会更好贴切项目本身）。 -首先在项目根目录新建一个存放控制器的文件夹（**/controllers**），然后为每个模型创建单独的控制器文件（模块）： +首先在项目根目录下为控制器创建一个文件夹（**/controllers**），然后为处理每个模型创建单独的控制器文件/模块： ```plain /express-locallibrary-tutorial // 项目根目录 @@ -206,8 +263,11 @@ app.get("/users/:userId/books/:bookId", (req, res) => { genreController.js ``` -> [!NOTE] -> 上述四个文件可到 GitHub 下载 [dummyControllers.zip](https://github.com/roy-tian/mdn-examples/blob/master/server/express-locallibrary-tutorial/controllers/dummyControllers.zip)。（链接已失效，请移步英文版查看具体代码） +控制器将使用 `express-async-handler` 模块，因此在继续之前，请使用 `npm` 将其安装到程序库中： + +```bash +npm install express-async-handler +``` ### `Author` 控制器 @@ -215,6 +275,7 @@ app.get("/users/:userId/books/:bookId", (req, res) => { ```js const Author = require("../models/author"); +const asyncHandler = require("express-async-handler"); // 显示完整的作者列表 exports.author_list = (req, res) => { @@ -222,64 +283,203 @@ exports.author_list = (req, res) => { }; // 为每位作者显示详细信息的页面 -exports.author_detail = (req, res) => { +exports.author_detail = asyncHandler(async (req, res, next) => { res.send("未实现：作者详细信息：" + req.params.id); }; // 由 GET 显示创建作者的表单 -exports.author_create_get = (req, res) => { - res.send("未实现：作者创建表单的 GET"); +exports.author_create_get = asyncHandler(async (req, res, next) => { + res.send("未实现：创建作者的 GET"); }; // 由 POST 处理作者创建操作 -exports.author_create_post = (req, res) => { +exports.author_create_post = asyncHandler(async (req, res, next) => { res.send("未实现：创建作者的 POST"); }; // 由 GET 显示删除作者的表单 -exports.author_delete_get = (req, res) => { - res.send("未实现：作者删除表单的 GET"); +exports.author_delete_get = asyncHandler(async (req, res, next) => { + res.send("未实现：删除作者的 GET"); }; // 由 POST 处理作者删除操作 -exports.author_delete_post = (req, res) => { +exports.author_delete_post = asyncHandler(async (req, res, next) => { res.send("未实现：删除作者的 POST"); }; // 由 GET 显示更新作者的表单 -exports.author_update_get = (req, res) => { - res.send("未实现：作者更新表单的 GET"); +exports.author_update_get = asyncHandler(async (req, res, next) => { + res.send("未实现：更新作者的 GET"); }; // 由 POST 处理作者更新操作 -exports.author_update_post = (req, res) => { +exports.author_update_post = asyncHandler(async (req, res, next) => { res.send("未实现：更新作者的 POST"); }; ``` -该模块首先导入了用于访问和更新数据的模型，然后为每个需要处理（添加、更新和删除表单，以及相应的 POST 请求，稍后在 [使用表单](/zh-CN/docs/learn/Server-side/Express_Nodejs/forms) 一节中讲解）的 URL 导出一个函数。 +该模块首先需要 `Author` 模型（我们稍后将使用该模型访问和更新数据）和 `asyncHandler` 包装器（我们将使用该封装器捕获路由处理函数中抛出的任何异常）。然后，它为我们希望处理的每个 URL 输出函数。请注意，创建、更新和删除操作使用的是表单，因此还需要额外的方法来处理表单发布请求。我们将在后面的“表单”一文中讨论这些方法。 + +这些函数都使用了上文[处理路由函数中的异常](#处理路由函数中的异常)中描述的封装函数，其参数包括请求、响应和下一步。函数会响应一个字符串，表示相关页面尚未创建。如果控制器函数预计会接收路径参数，则会在消息字符串中输出这些参数（参见上文的 `req.params.id`）。 + +请注意，某些路由函数在实现后可能不包含任何可抛出异常的代码。我们可以在使用时将它们改回“正常”的路由处理器函数。 + +### BookInstance 控制器 + +打开 **/controllers/bookinstanceController.js** 文件，复制以下代码（与 `Author` 控制器模块的模式相同）： + +```js +const BookInstance = require("../models/bookinstance"); +const asyncHandler = require("express-async-handler"); + +// 显示所有的 BookInstances +exports.bookinstance_list = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 列表"); +}); + +// 显示特定 BookInstance 的详情页 +exports.bookinstance_detail = asyncHandler(async (req, res, next) => { + res.send(`未实现：BookInstance 详情页面：${req.params.id}`); +}); + +// 由 GET 显示创建 BookInstance 的表单 +exports.bookinstance_create_get = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 创建 GET"); +}); + +// 由 POST 处理创建 BookInstance +exports.bookinstance_create_post = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 创建 POST"); +}); + +// 由 GET 显示删除 BookInstance 的表单 +exports.bookinstance_delete_get = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 删除 GET"); +}); + +// 由 POST 删除 BookInstance +exports.bookinstance_delete_post = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 删除 POST"); +}); + +// 由 GET 显示更新 BookInstance 的表单 +exports.bookinstance_update_get = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 更新 GET"); +}); + +// 由 POST 处理更新 BookInstance +exports.bookinstance_update_post = asyncHandler(async (req, res, next) => { + res.send("未实现：BookInstance 更新 POST"); +}); +``` + +#### Genre 控制器 + +打开 **/controllers/genreController.js** 文件，复制以下文本（与 `Author` 和 `BookInstance` 文件的模式相同）： + +```js +const genre = require("../models/genre"); +const asyncHandler = require("express-async-handler"); + +// 显示所有的流派。 +exports.genre_list = asyncHandler(async (req, res, next) => { + res.send("未实现：流派列表"); +}); + +// 显示特定流派的详情页。 +exports.genre_detail = asyncHandler(async (req, res, next) => { + res.send(`未实现：流派详情页：${req.params.id}`); +}); + +// 通过 GET 显示创建流派。 +exports.genre_create_get = asyncHandler(async (req, res, next) => { + res.send("未实现：流派创建 GET"); +}); + +// 以 POST 方式处理创建流派。 +exports.genre_create_post = asyncHandler(async (req, res, next) => { + res.send("未实现：流派创建 POST"); +}); -所有函数都遵循 Express 中间件函数的标准形式，三个参数依次为：请求 `req`、响应 `res`、当前方法无法完成请求循环时（这里不存在这种情况）调用的 `next` 函数。上述方法只返回一个字符串，显示相关页面尚未创建。接收路径参数的控制器函数可将参数输出到消息字符串中（代码中出现的 `req.params.id` ）。 +// 通过 GET 显示流派删除表单。 +exports.genre_delete_get = asyncHandler(async (req, res, next) => { + res.send("未实现：流派删除 GET"); +}); -### `BookInstance`、`Genre`、`Book` 控制器 +// 处理 POST 时的流派删除。 +exports.genre_delete_post = asyncHandler(async (req, res, next) => { + res.send("未实现：流派删除 POST"); +}); -这三个控制器与 `Author` 的模式完全相同，只是 `Book` 有一个用于显示站点欢迎页面的 `index()` 函数： +// 通过 GET 显示流派更新表单。 +exports.genre_update_get = asyncHandler(async (req, res, next) => { + res.send("未实现：流派更新 GET"); +}); + +// 处理 POST 上的流派更新。 +exports.genre_update_post = asyncHandler(async (req, res, next) => { + res.send("未实现：流派更新 POST"); +}); +``` + +#### Book 控制器 + +打开 **/controllers/bookController.js** 文件，复制以下代码。该代码与其他控制器模块的模式相同，但增加了一个用于显示网站欢迎页面的 `index()` 函数： ```js -// /controllers/bookController.js +const Book = require("../models/book"); +const asyncHandler = require("express-async-handler"); -const Book = require('../models/book'); +exports.index = asyncHandler(async (req, res, next) => { + res.send("未实现：网站主页"); +}); -exports.index = (req, res) => { res.send('未实现：站点首页'); }; +// 显示所有的图书 +exports.book_list = asyncHandler(async (req, res, next) => { + res.send("未实现：图书列表"); +}); + +// 显示特定图书的详情页面。 +exports.book_detail = asyncHandler(async (req, res, next) => { + res.send(`未实现：图书详情页面：${req.params.id}`); +}); -... +// 通过 GET 显示创建图书。 +exports.book_create_get = asyncHandler(async (req, res, next) => { + res.send("未实现：创建图书 GET"); +}); + +// 以 POST 方式处理创建图书。 +exports.book_create_post = asyncHandler(async (req, res, next) => { + res.send("未实现：Book 创建 POST"); +}); + +// 通过 GET 显示删除图书。 +exports.book_delete_get = asyncHandler(async (req, res, next) => { + res.send("未实现：删除 GET"); +}); + +// 以 POST 方式处理删除图书。 +exports.book_delete_post = asyncHandler(async (req, res, next) => { + res.send("未实现：删除 POST"); +}); + +// 通过 GET 显示更新图书。 +exports.book_update_get = asyncHandler(async (req, res, next) => { + res.send("未实现：更新图书 GET"); +}); + +// 处理 POST 时的更新图书。 +exports.book_update_post = asyncHandler(async (req, res, next) => { + res.send("未实现：更新图书 POST"); +}); ``` -## 创建藏书编目 `catalog` 路由模组 +## 创建 catalog 路由模块 -定义好控制器后，我们来为 LocalLibrary 网站创建完整的 URL 路由。 +定义好控制器后，我们来为[本地图书馆网站](#本地图书馆所需的路由)创建完整的 URL 路由。 -站点骨架中有一个 **./routes** 文件夹，其中包含两个路由文件：index 和 user，在这里新建一个 **catalog.js** 路由文件，如下所示： +站点骨架中有一个 **./routes** 文件夹，其中包含两个路由文件：_index_ 和 _users_，在这里新建一个 **catalog.js** 路由文件，如下所示： ```plain /express-locallibrary-tutorial // 项目根目录 @@ -289,10 +489,7 @@ exports.index = (req, res) => { res.send('未实现：站点首页'); }; catalog.js ``` -> [!NOTE] -> 可到 GitHub 下载完整的 [catalog.js](https://raw.githubusercontent.com/roy-tian/mdn-examples/master/server/express-locallibrary-tutorial/routes/catalog.js)。 - -**/routes/catalog.js** 中有以下代码： +打开 **/routes/catalog.js** 并拷贝如下代码到其中： ```js const express = require("express"); @@ -304,49 +501,143 @@ const author_controller = require("../controllers/authorController"); const genre_controller = require("../controllers/genreController"); const book_instance_controller = require("../controllers/bookinstanceController"); -/// 藏书路由 /// +/// 图书路由 /// -// GET 获取藏书编目主页 +// GET 获取图书编目主页 router.get("/", book_controller.index); -// GET 请求添加新的藏书。注意此项必须位于显示藏书的路由（使用了 id）之前。 +// GET 请求添加新的图书。注意此项必须位于显示图书的路由（使用了 id）之前。 router.get("/book/create", book_controller.book_create_get); -// POST 请求添加新的藏书 +// POST 请求添加新的图书 router.post("/book/create", book_controller.book_create_post); -// GET 请求删除藏书 +// GET 请求删除图书 router.get("/book/:id/delete", book_controller.book_delete_get); -// POST 请求删除藏书 +// POST 请求删除图书 router.post("/book/:id/delete", book_controller.book_delete_post); -// GET 请求更新藏书 +// GET 请求更新图书 router.get("/book/:id/update", book_controller.book_update_get); -// POST 请求更新藏书 +// POST 请求更新图书 router.post("/book/:id/update", book_controller.book_update_post); -// GET 请求藏书 +// GET 请求图书 router.get("/book/:id", book_controller.book_detail); -// GET 请求完整藏书列表 +// GET 请求完整图书列表 router.get("/books", book_controller.book_list); -/// 藏书副本、藏书种类、作者的路由与藏书路由结构基本一致，只是无需获取主页 /// +/// 作者路由 /// + +// 用于创建作者的 GET 请求。注意这必须在 id 的路由之前（比如说显示作者） +router.get("/author/create", author_controller.author_create_get); + +// 创建作者的 POST 请求。 +router.post("/author/create", author_controller.author_create_post); + +// 删除作者的 GET 请求。 +router.get("/author/:id/delete", author_controller.author_delete_get); + +// POST 请求删除作者。 +router.post("/author/:id/delete", author_controller.author_delete_post); + +// 更新作者的 GET 请求。 +router.get("/author/:id/update", author_controller.author_update_get); + +// POST 请求更新作者。 +router.post("/author/:id/update", author_controller.author_update_post); + +// 获取一个作者的 GET 请求。 +router.get("/author/:id", author_controller.author_detail); + +// 获取所有作者列表的 GET 请求。 +router.get("/authors", author_controller.author_list); + +/// 流派路由 /// + +// 用于创建流派的 GET 请求。注意：这必须在显示流派的路由之前（使用 id 的路由）。 +router.get("/genre/create", genre_controller.genre_create_get); + +// POST 请求创建 Genre。 +router.post("/genre/create", genre_controller.genre_create_post); + +// 删除流派的 GET 请求。 +router.get("/genre/:id/delete", genre_controller.genre_delete_get); + +// POST 请求删除 Genre。 +router.post("/genre/:id/delete", genre_controller.genre_delete_post); + +// 更新流派的 GET 请求。 +router.get("/genre/:id/update", genre_controller.genre_update_get); + +// 更新流派的 POST 请求。 +router.post("/genre/:id/update", genre_controller.genre_update_post); + +// 获取一个流派的 GET 请求。 +router.get("/genre/:id", genre_controller.genre_detail); + +// 获取所有流派列表的 GET 请求 +router.get("/genres", genre_controller.genre_list); + +/// BOOKINSTANCE 路由 /// + +// 用于创建 BookInstance 的 GET 请求。注意：这必须在显示 BookInstance 的路由之前（使用 id 的路由）。 +router.get( + "/bookinstance/create", + book_instance_controller.bookinstance_create_get, +); + +// 创建 BookInstance 的 POST 请求。 +router.post( + "/bookinstance/create", + book_instance_controller.bookinstance_create_post, +); + +// 删除 BookInstance 的 GET 请求。 +router.post( + "/bookinstance/:id/delete", + book_instance_controller.bookinstance_delete_get, +); + +// POST 请求删除 BookInstance。 +router.post( + "/bookinstance/:id/delete", + book_instance_controller.bookinstance_delete_post, +); + +// 更新 BookInstance 的 GET 请求。 +router.get( + "/bookinstance/:id/delete", + book_instance_controller.bookinstance_update_get, +); + +// 更新 BookInstance 的 POST 请求。 +router.post( + "/bookinstance/:id/update", + book_instance_controller.bookinstance_update_post, +); + +// 一个 BookInstance 的 GET 请求。 +router.get("/bookinstance/:id", book_instance_controller.bookinstance_detail); + +// GET 请求获取所有 BookInstance 的列表。 +router.get("/bookinstances", book_instance_controller.bookinstance_list); module.exports = router; ``` 该模块导入了 `express` 并创建了一个 `Router` 对象 `router`。所有路由都设置在 `router` 上，最后将其导出。 -对 `router` 对象调用 `.get()` 或`.post()` 函数即可定义路由。这里所有路径都使用字符串定义（而不用字符串模式或正则表达式）。某些特定资源（如藏书）的路由使用路径参数从 URL 中获取对象标识。 +对 `router` 对象调用 `.get()` 或`.post()` 函数即可定义路由。这里所有路径都使用字符串定义（而不用字符串模式或正则表达式）。某些特定资源（如图书）的路由使用路径参数从 URL 中获取对象标识。 处理函数均导入自上文的控制器模块。 -### 更新 index 路由模块 +### 更新索引路由模块 -新路由已经设置完毕，还需要设置一下 `index` 模块。我们将网站的首页重定向（`redirect`）至刚创建的地址 '`/catalog`'。 +我们已经设置了所有新路径，但仍有一条路径指向原始页面。让我们把它重定向到我们在“/catalog”路径下创建的新索引页面。 将 **/routes/index.js** 中的中间件修改一下： @@ -381,9 +672,9 @@ app.use("/catalog", catalogRouter); // 将 catalog 路由添加进中间件链 ``` > [!NOTE] -> 我们将图书编目模块添加到了 `'/catalog'` 路径，该路径是 catalog 模块中所有路径的前缀。例如，访问藏书列表 的 URL 为：`/catalog/books/`。 +> 我们将图书编目模块添加到了 `'/catalog'` 路径，该路径是 catalog 模块中所有路径的前缀。例如，访问图书列表 的 URL 为：`/catalog/books/`。 -大功告成。LocalLibrary 网站所需的所有 URL 的路由和框架函数都已准备完毕。 +大功告成。本地图书馆网站所需的所有 URL 的路由和框架函数都已准备完毕。 ### 测试路由 @@ -392,6 +683,10 @@ app.use("/catalog", catalogRouter); // 将 catalog 路由添加进中间件链 - 默认方法 ```bash + # Windows + SET DEBUG=express-locallibrary-tutorial:* & npm start + + # macOS 或 Linux DEBUG=express-locallibrary-tutorial:* npm start ``` @@ -401,9 +696,6 @@ app.use("/catalog", catalogRouter); // 将 catalog 路由添加进中间件链 DEBUG=express-locallibrary-tutorial:* npm run devstart ``` -> [!NOTE] -> 以上命令只对 bash 有效，要在 Windows 上使用 bash，最简单的方法就是安装 Git。（详情参见[教程 2 相关译注](/zh-CN/docs/Learn/Server-side/Express_Nodejs/skeleton_website#使用应用生成器)） - 接下来浏览上面一些 URL，确保不会收到错误页面（HTTP 404）。可以尝试以下示例： - `http://localhost:3000/` From e682ad25cddbfcbde166995c8550a3d6dcc4b5b8 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 14:04:45 +0800 Subject: [PATCH 31/95] zh-CN: create Glossary/CLS (#23352) Co-authored-by: A1lo --- files/zh-cn/glossary/cls/index.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 files/zh-cn/glossary/cls/index.md diff --git a/files/zh-cn/glossary/cls/index.md b/files/zh-cn/glossary/cls/index.md new file mode 100644 index 00000000000000..f247d9957e76df --- /dev/null +++ b/files/zh-cn/glossary/cls/index.md @@ -0,0 +1,20 @@ +--- +title: 累计布局偏移（CLS） +slug: Glossary/CLS +l10n: + sourceCommit: fcd4f39485d740615c32ccaef63471bc27095fb0 +--- + +{{GlossarySidebar}} + +**累计布局偏移**（CLS）是一种由 Google 设计为[核心 Web 要素](https://web.dev/explore/learn-core-web-vitals)之一的网站的可用性指标。 + +它可以衡量用户遇到意外布局偏移的程度。这里元素的意外偏移指不是由用户操作（如点按按钮或动画的一部分）引起的偏移。 + +布局偏移可能是由于未给定 `width` 和 `height` 属性的 {{htmlelement("img")}} 或 {{htmlelement("video")}} 元素引起的，因此浏览器在加载它们之前不知道它们将占用多少空间。 + +{{domxref("LayoutShift")}} 接口（属于[性能 API](/zh-CN/docs/Web/API/Performance_API)）可用于测量单个布局偏移，然后用于计算网页的 CLS 分数。 + +## 参见 + +- web.dev 上的 [CLS](https://web.dev/articles/cls) From b47cd44b1b8dc8002c02afc9bcc5bfdc43c9df92 Mon Sep 17 00:00:00 2001 From: Hoarfroster Date: Tue, 3 Sep 2024 14:05:17 +0800 Subject: [PATCH 32/95] zh-CN: create Glossary/Physical_properties (#23329) Co-authored-by: A1lo --- .../glossary/physical_properties/index.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 files/zh-cn/glossary/physical_properties/index.md diff --git a/files/zh-cn/glossary/physical_properties/index.md b/files/zh-cn/glossary/physical_properties/index.md new file mode 100644 index 00000000000000..684390a3ab9c65 --- /dev/null +++ b/files/zh-cn/glossary/physical_properties/index.md @@ -0,0 +1,21 @@ +--- +title: 物理属性 +slug: Glossary/Physical_properties +l10n: + sourceCommit: 50e5edd07155de2eec2a8b6b2ad95820748cfec7 +--- + +{{GlossarySidebar}} + +CSS **物理属性**根据物理方向或元素边界定义位置。例如： + +- {{cssxref("top")}}、{{cssxref("right")}}、{{cssxref("bottom")}} 和 {{cssxref("left")}} 等 {{Glossary("inset properties", "inset 属性")}}引用视口的物理尺寸。 +- {{cssxref("margin-top")}}、{{cssxref("border-right")}}、{{cssxref("padding-bottom")}} 和 {{cssxref("border-bottom-left-radius")}} 等特性引用元素的特定边，以及通过该物理方向的样式特性。 + +物理属性与{{glossary("logical properties", "逻辑属性")}}相对：逻辑属性是相对于内容流的，使用相对于块和行向轴的方向关键字。 + +## 参见 + +- [CSS 定位布局](/zh-CN/docs/Web/CSS/CSS_positioned_layout)模块 +- [CSS 盒模型](/zh-CN/docs/Web/CSS/CSS_box_model)模块 +- [CSS 盒子大小设置](/zh-CN/docs/Web/CSS/CSS_box_sizing)模块 From 58c02cde33be2d06738f2c674be4eb9c264efeef Mon Sep 17 00:00:00 2001 From: skyclouds2001 <95597335+skyclouds2001@users.noreply.github.com> Date: Tue, 3 Sep 2024 20:38:36 +0800 Subject: [PATCH 33/95] [zh-cn]: update translation of broadcast channel api - part i (#23358) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: A1lo --- .../web/api/broadcast_channel_api/index.md | 5 ++- .../broadcastchannel/index.md | 10 ++--- files/zh-cn/web/api/broadcastchannel/index.md | 41 ++++++++----------- .../web/api/broadcastchannel/name/index.md | 20 ++++----- 4 files changed, 35 insertions(+), 41 deletions(-) diff --git a/files/zh-cn/web/api/broadcast_channel_api/index.md b/files/zh-cn/web/api/broadcast_channel_api/index.md index 48bac3cb63e15f..2c32d6329bfb01 100644 --- a/files/zh-cn/web/api/broadcast_channel_api/index.md +++ b/files/zh-cn/web/api/broadcast_channel_api/index.md @@ -2,13 +2,16 @@ title: Broadcast Channel API slug: Web/API/Broadcast_Channel_API l10n: - sourceCommit: 50a45d52fd9f45f1ca30b546af5920d0ccda82dc + sourceCommit: be8f7f155a48e11b30c240f8731afb1845f85378 --- {{DefaultAPISidebar("Broadcast Channel API")}} {{AvailableInWorkers}} **Broadcast Channel API** 允许{{glossary("browsing context", "浏览上下文")}}（即 _window_、_tab_、_frame_ 或 _iframe_）与同{{glossary("origin", "源")}}的 worker 之间进行基本通信。 +> [!NOTE] +> 确切地说，允许使用相同的[存储分区](/zh-CN/docs/Web/Privacy/State_Partitioning)的浏览上下文之间进行通信。首先根据顶级网站对存储空间进行分区，例如，如果你在 `a.com` 处打开了一个页面，其中嵌入了 `b.com` 的 iframe，而另一个页面打开的页面是 `b.com`，则 iframe 无法与第二个页面通信，尽管它们在技术上是同源的。但是，如果第一个页面也位于 `b.com` 上，则 iframe 可以与第二个页面通信。 + 通过创建 {{domxref("BroadcastChannel")}} 对象，你可以接收发布到该对象的任何消息。你不必维护对要与之通信的框架或 worker 的引用：他们可以通过构建具有相同名称的 {{domxref("BroadcastChannel")}} 来“订阅”特定频道，并在它们之间进行双向通信。 ![Broadcast Channel API 的原理](broadcastchannel.png) diff --git a/files/zh-cn/web/api/broadcastchannel/broadcastchannel/index.md b/files/zh-cn/web/api/broadcastchannel/broadcastchannel/index.md index cd28a0e11d6709..d173c8ccfeca75 100644 --- a/files/zh-cn/web/api/broadcastchannel/broadcastchannel/index.md +++ b/files/zh-cn/web/api/broadcastchannel/broadcastchannel/index.md @@ -1,14 +1,14 @@ --- title: BroadcastChannel() slug: Web/API/BroadcastChannel/BroadcastChannel +l10n: + sourceCommit: 0a881eea07f0cec6ca4ed85a24af43b367a9f80d --- -{{APIRef("BroadCastChannel API")}} +{{APIRef("BroadCastChannel API")}} {{AvailableInWorkers}} **`BroadcastChannel()`** 构造函数用于创建一个 {{domxref("BroadcastChannel")}} 对象，并与底层的通道相关联。 -{{AvailableInWorkers}} - ## 语法 ```js-nolint @@ -18,7 +18,7 @@ new BroadcastChannel(channelName) ### 参数 - `channelName` - - : 表示通道名称的字符串；对于相同的{{glossary("origin", "来源")}}下的所有{{glossary("browsing context", "浏览上下文")}}，一个名称只对应一个通道。 + - : 表示通道名称的字符串；对于同{{glossary("origin", "源")}}下的所有{{glossary("browsing context", "浏览上下文")}}，一个名称只对应一个通道。 ## 示例 @@ -26,7 +26,7 @@ new BroadcastChannel(channelName) // 创建一个监听“internal_notification”通道的新通道。 const bc = new BroadcastChannel("internal_notification"); -bc.postMessage("New listening connected!"); +bc.postMessage("新的监听连接！"); ``` ## 规范 diff --git a/files/zh-cn/web/api/broadcastchannel/index.md b/files/zh-cn/web/api/broadcastchannel/index.md index 33e286b8e0958a..010c336851420d 100644 --- a/files/zh-cn/web/api/broadcastchannel/index.md +++ b/files/zh-cn/web/api/broadcastchannel/index.md @@ -1,52 +1,45 @@ --- title: BroadcastChannel slug: Web/API/BroadcastChannel +l10n: + sourceCommit: 50a45d52fd9f45f1ca30b546af5920d0ccda82dc --- -{{APIRef("Broadcast Channel API")}} +{{APIRef("Broadcast Channel API")}} {{AvailableInWorkers}} -**`BroadcastChannel`** 接口代理了一个命名频道，可以让指定 {{glossary("origin")}} 下的任意 {{glossary("browsing context")}} 来订阅它。它允许同源的不同浏览器窗口，Tab 页，frame 或者 iframe 下的不同文档之间相互通信。通过触发一个 [`message`](/zh-CN/docs/Web/API/BroadcastChannel/message_event) 事件，消息可以广播到所有监听了该频道的 `BroadcastChannel` 对象。 +**`BroadcastChannel`** 接口表示给定{{glossary("origin", "源")}}的任何{{glossary("browsing context", "浏览上下文")}}都可以订阅的命名频道。它允许同源的不同浏览器窗口、标签页、frame 或者 iframe 下的不同文档之间相互通信。消息通过 {{domxref("BroadcastChannel/message_event", "message")}} 事件进行广播，该事件在侦听该频道的所有 `BroadcastChannel` 对象上触发，发送消息的对象除外。 -{{AvailableInWorkers}} +{{InheritanceDiagram}} ## 构造函数 - {{domxref("BroadcastChannel.BroadcastChannel", "BroadcastChannel()")}} - : 创建一个链接到命名频道的对象。 -## 属性 +## 实例属性 -_该接口会从它的父级 {{domxref("EventTarget")}} 继承属性。_ +_该接口也从它的父接口 {{domxref("EventTarget")}} 继承属性。_ - {{domxref("BroadcastChannel.name")}} - : 频道名称，返回 {{domxref("DOMString")}}。 -### 事件处理程序 +## 实例方法 -- {{domxref("BroadcastChannel.onmessage")}} - - - : 事件处理器，用于定义当该对象上触发了 [`message`](/zh-CN/docs/Web/API/BroadcastChannel/message_event) 事件时要执行的函数。 - -- {{domxref("BroadcastChannel.onmessageerror")}} - - : 事件处理器，用于定义当该对象上触发了类型为 {{domxref("MessageError")}} 的 {{domxref("MessageEvent")}} 事件时要执行的函数。当接收到一条无法反序列化的消息时会触发此事件。 - -## 方法 - -_该接口会从它的父级 {{domxref("EventTarget")}} 继承方法。_ +_该接口也从它的父接口 {{domxref("EventTarget")}} 继承方法。_ - {{domxref("BroadcastChannel.postMessage()")}} - : 向所有监听了相同频道的 `BroadcastChannel` 对象发送一条消息，消息内容可以是任意类型的数据。 - {{domxref("BroadcastChannel.close()")}} - - : 关闭频道对象，告诉它不要再接收新的消息，并允许它最终被垃圾回收。 + - : 关闭频道对象，指示它不会收到任何新消息，并允许它最终被垃圾回收。 ## 事件 -- [`message`](/zh-CN/docs/Web/API/BroadcastChannel/message_event) - - : 当频道收到一条消息时触发。 - 也可以使用 [`onmessage`](/zh-CN/docs/Web/API/BroadcastChannel/onmessage) 属性访问。 -- [`messageerror`](/zh-CN/docs/Web/API/BroadcastChannel/messageerror_event) - - : 当频道收到一条无法反序列化的消息时触发。 - 也可以使用 [`onmessageerror`](/zh-CN/docs/Web/API/BroadcastChannel/onmessageerror) 属性访问。 +_该接口也从它的父接口 {{domxref("EventTarget")}} 继承事件。_ + +- {{domxref("BroadcastChannel/message_event", "message")}} + - : 当频道收到一条消息时触发。也可以使用 `onmessage` 属性访问。 +- {{domxref("BroadcastChannel/messageerror_event", "messageerror")}} + - : 当频道收到一条无法反序列化的消息时触发。也可以使用 `onmessageerror` 属性访问。 ## 规范 @@ -59,4 +52,4 @@ _该接口会从它的父级 {{domxref("EventTarget")}} 继承方法。_ ## 参见 - 一种在不同浏览器上下文之间通信的重量级方案：{{domxref("ServiceWorker")}}。 -- [Broadcast Channel API overview](/zh-CN/docs/Web/API/Broadcast_Channel_API) +- [Broadcast Channel API 概述](/zh-CN/docs/Web/API/Broadcast_Channel_API) diff --git a/files/zh-cn/web/api/broadcastchannel/name/index.md b/files/zh-cn/web/api/broadcastchannel/name/index.md index 1f0d80d6751b32..760cf90c1a3a13 100644 --- a/files/zh-cn/web/api/broadcastchannel/name/index.md +++ b/files/zh-cn/web/api/broadcastchannel/name/index.md @@ -1,27 +1,25 @@ --- -title: BroadcastChannel.name +title: BroadcastChannel：name 属性 slug: Web/API/BroadcastChannel/name +l10n: + sourceCommit: 50a45d52fd9f45f1ca30b546af5920d0ccda82dc --- -{{APIRef("BroadCastChannel API")}} +{{APIRef("BroadCastChannel API")}} {{AvailableInWorkers}} -**`BroadcastChannel.name`** 是类型为 {{domxref("DOMString")}} 的只读属性，是频道的唯一标识。属性 name 是在创建时传入 {{domxref("BroadcastChannel.BroadCastChannel", "BroadcastChannel()")}} 构造函数的，所以是只读的。 +{{domxref("BroadcastChannel")}} 接口的 **`name`** 只读属性返回一个字符串，该字符串使用其名称唯一标识给定频道。此名称在创建时传递给 {{domxref("BroadcastChannel.BroadCastChannel", "BroadcastChannel()")}} 构造函数，因此是只读的。 -{{AvailableInWorkers}} +## 值 -## 语法 - -```plain -var str = channel.name; -``` +一个字符串。 ## 示例 ```js // 连接到指定频道 -var bc = new BroadcastChannel("test_channel"); +const bc = new BroadcastChannel("test_channel"); -// 其他操作 (如：postMessage, …) +// 其他操作（如：postMessage、……） // 在控制台打印频道名称 console.log(bc.name); // "test_channel" From 3d9c6ee7ef8754db558133239111152a2bfc9494 Mon Sep 17 00:00:00 2001 From: Leonid Vinogradov Date: Tue, 3 Sep 2024 23:04:32 +0300 Subject: [PATCH 34/95] [pt-br] improve `Web/API/Element/mouseover_event` (#22434) (#22435) * [pt-br] improve 'Web/API/Element/mouseover_event' (#22434) * [pt-br] translate 'See also' heading * [pt-br] translate 'See also' heading --- .../web/api/element/mouseover_event/index.md | 224 +++++++++++------- 1 file changed, 134 insertions(+), 90 deletions(-) diff --git a/files/pt-br/web/api/element/mouseover_event/index.md b/files/pt-br/web/api/element/mouseover_event/index.md index 716f24a74cfb35..5207c50a982dde 100644 --- a/files/pt-br/web/api/element/mouseover_event/index.md +++ b/files/pt-br/web/api/element/mouseover_event/index.md @@ -1,52 +1,87 @@ --- -title: mouseover +title: "Element: evento mouseover" slug: Web/API/Element/mouseover_event +l10n: + sourceCommit: b4dc8c13ae9041844dc45423aa087002bf9a25e9 --- -O evento `mouseover` é acionado quando um dispositivo ponteiro é movido para o elemento que esteja escutando ou para um de seus filhos. - -## Informações Gerais - -- Especificação - - : [DOM L3](https://www.w3.org/TR/DOM-Level-3-Events/#event-type-mouseover) -- Interface - - : {{domxref("MouseEvent")}} -- Bubbles - - : Sim -- Cancelable - - : Sim -- Alvo - - : Element -- Ação Padrão - - : None - -## Propriedades - -| Property | Type | Description | -| ---------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `target` {{readonlyInline}} | {{domxref("EventTarget")}} | O evento alvo(o mais alto alvo na arvore do DOM). | -| `type` {{readonlyInline}} | {{domxref("DOMString")}} | The type of event. | -| `bubbles` {{readonlyInline}} | Boolean | Whether the event normally bubbles or not | -| `cancelable` {{readonlyInline}} | `Boolean` | Whether the event is cancellable or not | -| `view` {{readonlyInline}} | {{domxref("WindowProxy")}} | {{domxref("document.defaultView")}} (`window` of the document) | -| `detail` {{readonlyInline}} | `long` (`float`) | 0. | -| `currentTarget` {{readonlyInline}} | {{domxref("EventTarget")}} | The node that had the event listener attached. | -| `relatedTarget` {{readonlyInline}} | {{domxref("EventTarget")}} | For `mouseover`, `mouseout`, `mouseenter` and `mouseleave` events: the target of the complementary event (the `mouseleave` target in the case of a `mouseenter` event). `null` otherwise. | -| `screenX` {{readonlyInline}} | long | The X coordinate of the mouse pointer in global (screen) coordinates. | -| `screenY` {{readonlyInline}} | long | The Y coordinate of the mouse pointer in global (screen) coordinates. | -| `clientX` {{readonlyInline}} | long | The X coordinate of the mouse pointer in local (DOM content) coordinates. | -| `clientY` {{readonlyInline}} | long | The Y coordinate of the mouse pointer in local (DOM content) coordinates. | -| `button` {{readonlyInline}} | unsigned short | This is always 0 as no button presses trigger this event (mouse movement does). | -| `buttons` {{readonlyInline}} | unsigned short | The buttons depressed when the mouse event was fired: Left button=1, Right button=2, Middle (wheel) button=4, 4th button (typically, "Browser Back" button)=8, 5th button (typically, "Browser Forward" button)=16. If two or more buttons are depressed, returns the logical sum of the values. E.g., if Left button and Right button are depressed, returns 3 (=1 \| 2). [More info](/pt-BR/docs/Web/API/MouseEvent). | -| `mozPressure` {{readonlyInline}} | float | The amount of pressure applied to a touch or tabdevice when generating the event; this value ranges between 0.0 (minimum pressure) and 1.0 (maximum pressure). | -| `ctrlKey` {{readonlyInline}} | boolean | `true` if the control key was down when the event was fired. `false` otherwise. | -| `shiftKey` {{readonlyInline}} | boolean | `true` if the shift key was down when the event was fired. `false` otherwise. | -| `altKey` {{readonlyInline}} | boolean | `true` if the alt key was down when the event was fired. `false` otherwise. | -| `metaKey` {{readonlyInline}} | boolean | `true` if the meta key was down when the event was fired. `false` otherwise. | - -## Example - -The following example illustrates the difference between `mouseover` and [`mouseenter`](/pt-BR/docs/Web/Events/mouseenter) events. +{{APIRef}} + +O evento `mouseover` é acionado quando um dispositivo ponteiro é movido para o {{domxref("Element", "elemento")}} que esteja escutando ou para um de seus filhos. + +## Sintaxe + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener("mouseover", (event) => {}); + +onmouseover = (event) => {}; +``` + +## Tipo de evento + +A {{domxref("MouseEvent")}}. Inherits from {{domxref("UIEvent")}} and {{domxref("Event")}}. + +{{InheritanceDiagram("MouseEvent")}} + +## Propriedades de evento + +_This interface also inherits properties of its parents, {{domxref("UIEvent")}} and {{domxref("Event")}}._ + +- {{domxref("MouseEvent.altKey")}} {{ReadOnlyInline}} + - : Returns `true` if the alt key was down when the mouse event was fired. +- {{domxref("MouseEvent.button")}} {{ReadOnlyInline}} + - : The button number that was pressed (if applicable) when the mouse event was fired. +- {{domxref("MouseEvent.buttons")}} {{ReadOnlyInline}} + - : The buttons being pressed (if any) when the mouse event was fired. +- {{domxref("MouseEvent.clientX")}} {{ReadOnlyInline}} + - : The X coordinate of the mouse pointer in [viewport coordinates](/pt-BR/docs/Web/CSS/CSSOM_view/Coordinate_systems#viewport). +- {{domxref("MouseEvent.clientY")}} {{ReadOnlyInline}} + - : The Y coordinate of the mouse pointer in [viewport coordinates](/pt-BR/docs/Web/CSS/CSSOM_view/Coordinate_systems#viewport). +- {{domxref("MouseEvent.ctrlKey")}} {{ReadOnlyInline}} + - : Returns `true` if the control key was down when the mouse event was fired. +- {{domxref("MouseEvent.layerX")}} {{Non-standard_inline}} {{ReadOnlyInline}} + - : Returns the horizontal coordinate of the event relative to the current layer. +- {{domxref("MouseEvent.layerY")}} {{Non-standard_inline}} {{ReadOnlyInline}} + - : Returns the vertical coordinate of the event relative to the current layer. +- {{domxref("MouseEvent.metaKey")}} {{ReadOnlyInline}} + - : Returns `true` if the meta key was down when the mouse event was fired. +- {{domxref("MouseEvent.movementX")}} {{ReadOnlyInline}} + - : The X coordinate of the mouse pointer relative to the position of the last {{domxref("Element/mousemove_event", "mousemove")}} event. +- {{domxref("MouseEvent.movementY")}} {{ReadOnlyInline}} + - : The Y coordinate of the mouse pointer relative to the position of the last {{domxref("Element/mousemove_event", "mousemove")}} event. +- {{domxref("MouseEvent.offsetX")}} {{ReadOnlyInline}} + - : The X coordinate of the mouse pointer relative to the position of the padding edge of the target node. +- {{domxref("MouseEvent.offsetY")}} {{ReadOnlyInline}} + - : The Y coordinate of the mouse pointer relative to the position of the padding edge of the target node. +- {{domxref("MouseEvent.pageX")}} {{ReadOnlyInline}} + - : The X coordinate of the mouse pointer relative to the whole document. +- {{domxref("MouseEvent.pageY")}} {{ReadOnlyInline}} + - : The Y coordinate of the mouse pointer relative to the whole document. +- {{domxref("MouseEvent.relatedTarget")}} {{ReadOnlyInline}} + - : The secondary target for the event, if there is one. +- {{domxref("MouseEvent.screenX")}} {{ReadOnlyInline}} + - : The X coordinate of the mouse pointer in [screen coordinates](/pt-BR/docs/Web/CSS/CSSOM_view/Coordinate_systems#screen). +- {{domxref("MouseEvent.screenY")}} {{ReadOnlyInline}} + - : The Y coordinate of the mouse pointer in [screen coordinates](/pt-BR/docs/Web/CSS/CSSOM_view/Coordinate_systems#screen). +- {{domxref("MouseEvent.shiftKey")}} {{ReadOnlyInline}} + - : Returns `true` if the shift key was down when the mouse event was fired. +- {{domxref("MouseEvent.mozInputSource")}} {{non-standard_inline()}} {{ReadOnlyInline}} + - : The type of device that generated the event (one of the `MOZ_SOURCE_*` constants). + This lets you, for example, determine whether a mouse event was generated by an actual mouse or by a touch event (which might affect the degree of accuracy with which you interpret the coordinates associated with the event). +- {{domxref("MouseEvent.webkitForce")}} {{non-standard_inline()}} {{ReadOnlyInline}} + - : The amount of pressure applied when clicking. +- {{domxref("MouseEvent.x")}} {{ReadOnlyInline}} + - : Alias for {{domxref("MouseEvent.clientX")}}. +- {{domxref("MouseEvent.y")}} {{ReadOnlyInline}} + - : Alias for {{domxref("MouseEvent.clientY")}}. + +## Exemplos + +The following example illustrates the difference between `mouseover` and {{domxref("Element/mouseenter_event", "mouseenter")}} events. + +### HTML ```html
      @@ -54,42 +89,50 @@ The following example illustrates the difference between `mouseover` and [`mouse
    • item 2
    • item 3
    +``` - +### JavaScript + +```js +const test = document.getElementById("test"); + +// This handler will be executed only once when the cursor +// moves over the unordered list +test.addEventListener( + "mouseenter", + (event) => { + // highlight the mouseenter target + event.target.style.color = "purple"; + + // reset the color after a short delay + setTimeout(() => { + event.target.style.color = ""; + }, 500); + }, + false, +); + +// This handler will be executed every time the cursor +// is moved over a different list item +test.addEventListener( + "mouseover", + (event) => { + // highlight the mouseover target + event.target.style.color = "orange"; + + // reset the color after a short delay + setTimeout(() => { + event.target.style.color = ""; + }, 500); + }, + false, +); ``` +### Resultado + +{{EmbedLiveSample('Exemplos')}} + ## Especificações {{Specifications}} @@ -98,15 +141,16 @@ The following example illustrates the difference between `mouseover` and [`mouse {{Compat}} -## See also - -- {{Event("mousedown")}} -- {{Event("mouseup")}} -- {{Event("mousemove")}} -- {{Event("click")}} -- {{Event("dblclick")}} -- {{Event("mouseover")}} -- {{Event("mouseout")}} -- {{Event("mouseenter")}} -- {{Event("mouseleave")}} -- {{Event("contextmenu")}} +## Veja também + +- [Introdução a eventos](/pt-BR/docs/Learn/JavaScript/Building_blocks/Events) +- {{domxref("Element/mousedown_event", "mousedown")}} +- {{domxref("Element/mouseup_event", "mouseup")}} +- {{domxref("Element/mousemove_event", "mousemove")}} +- {{domxref("Element/click_event", "click")}} +- {{domxref("Element/dblclick_event", "dblclick")}} +- {{domxref("Element/mouseover_event", "mouseover")}} +- {{domxref("Element/mouseout_event", "mouseout")}} +- {{domxref("Element/mouseenter_event", "mouseenter")}} +- {{domxref("Element/mouseleave_event", "mouseleave")}} +- {{domxref("Element/contextmenu_event", "contextmenu")}} From 42520507829979134e19bcd5a62b6b9b01865086 Mon Sep 17 00:00:00 2001 From: "Juliano S." <77923171+JuSfrei@users.noreply.github.com> Date: Tue, 3 Sep 2024 17:04:43 -0300 Subject: [PATCH 35/95] [pt-BR] fix typo in translation (#23198) fix typo in translation --- files/pt-br/web/api/blob/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/pt-br/web/api/blob/index.md b/files/pt-br/web/api/blob/index.md index f55c8eb4eabcca..0d518bbca2b401 100644 --- a/files/pt-br/web/api/blob/index.md +++ b/files/pt-br/web/api/blob/index.md @@ -17,7 +17,7 @@ As APIs que aceitam objetos `Blob` também são listados na documentação {{dom > O método `slice()` usava inicialmente `length` como segundo argumento para indicar o numero de bytes a copiar no novo `Blob`. Se você especificou valores de maneira que `start + length` excederam o tamanho do `Blob` de origem, o `Blob` retornado contém dados a partir do início do índice até o final do `Blob` de origem. > [!NOTE] -> Esteja ciente que o método `slice()` possui prefixos de fornecedores em alguns navegadores e versões: `blob.mozSlice()` para Firefox 12 e anteriores, e `blob.webkitSlice()` para Safari. Uma versão antiga do método `slice()`, sem prefixos de fornecedor, tem semântica diferente, e portanto é obsoleta. O suporta para `blob.mozSlice()` foi descontinuado a partir do Firefox 30. +> Esteja ciente que o método `slice()` possui prefixos de fornecedores em alguns navegadores e versões: `blob.mozSlice()` para Firefox 12 e anteriores, e `blob.webkitSlice()` para Safari. Uma versão antiga do método `slice()`, sem prefixos de fornecedor, tem semântica diferente, e portanto é obsoleta. O suporte para `blob.mozSlice()` foi descontinuado a partir do Firefox 30. ## Construtor From d28f7355d9bf68fd138cdcc0b2e4404d2459b46c Mon Sep 17 00:00:00 2001 From: MDN Web Docs GitHub Bot <108879845+mdn-bot@users.noreply.github.com> Date: Tue, 3 Sep 2024 22:05:06 +0200 Subject: [PATCH 36/95] [pt-br] sync translated content (#23145) pt-br: sync translated content --- files/pt-br/_redirects.txt | 9 +++++---- files/pt-br/_wikihistory.json | 20 +++++++++---------- .../identifying_resources_on_the_web/index.md | 3 ++- .../web/api/console/timeend_static/index.md | 2 +- .../web/api/console/timestamp_static/index.md | 2 +- 5 files changed, 19 insertions(+), 17 deletions(-) rename files/pt-br/{ => orphaned}/web/http/basics_of_http/identifying_resources_on_the_web/index.md (98%) diff --git a/files/pt-br/_redirects.txt b/files/pt-br/_redirects.txt index 61c3982a9438a8..fe8690bdb4140c 100644 --- a/files/pt-br/_redirects.txt +++ b/files/pt-br/_redirects.txt @@ -538,7 +538,7 @@ /pt-BR/docs/Web/API/BatteryManager/ondischargintimechange /pt-BR/docs/Web/API/BatteryManager/dischargingtimechange_event /pt-BR/docs/Web/API/BatteryManager/onlevelchange /pt-BR/docs/Web/API/BatteryManager/levelchange_event /pt-BR/docs/Web/API/Canvas_API/Tutorial/Compositing/Example /pt-BR/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation -/pt-BR/docs/Web/API/Console.timeEnd /pt-BR/docs/Web/API/console/timeend_static +/pt-BR/docs/Web/API/Console.timeEnd /pt-BR/docs/Web/API/console/timeEnd_static /pt-BR/docs/Web/API/Coordinates /pt-BR/docs/Web/API/GeolocationCoordinates /pt-BR/docs/Web/API/Coordinates/altitude /pt-BR/docs/Web/API/GeolocationCoordinates/altitude /pt-BR/docs/Web/API/DOMString /pt-BR/docs/conflicting/Web/JavaScript/Reference/Global_Objects/String @@ -657,8 +657,8 @@ /pt-BR/docs/Web/API/console/log /pt-BR/docs/Web/API/console/log_static /pt-BR/docs/Web/API/console/table /pt-BR/docs/Web/API/console/table_static /pt-BR/docs/Web/API/console/time /pt-BR/docs/Web/API/console/time_static -/pt-BR/docs/Web/API/console/timeEnd /pt-BR/docs/Web/API/console/timeend_static -/pt-BR/docs/Web/API/console/timeStamp /pt-BR/docs/Web/API/console/timestamp_static +/pt-BR/docs/Web/API/console/timeEnd /pt-BR/docs/Web/API/console/timeEnd_static +/pt-BR/docs/Web/API/console/timeStamp /pt-BR/docs/Web/API/console/timeStamp_static /pt-BR/docs/Web/API/console/warn /pt-BR/docs/Web/API/console/warn_static /pt-BR/docs/Web/API/crypto_property /pt-BR/docs/Web/API/Window/crypto /pt-BR/docs/Web/API/document.getElementById /pt-BR/docs/Web/API/Document/getElementById @@ -815,9 +815,10 @@ /pt-BR/docs/Web/HTML/formatos_midia_suportados /pt-BR/docs/Web/Media/Formats /pt-BR/docs/Web/HTML/microformatos /pt-BR/docs/Web/HTML/microformats /pt-BR/docs/Web/HTTP/Basico_sobre_HTTP /pt-BR/docs/Web/HTTP/Basics_of_HTTP -/pt-BR/docs/Web/HTTP/Basico_sobre_HTTP/Identifying_resources_on_the_Web /pt-BR/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web +/pt-BR/docs/Web/HTTP/Basico_sobre_HTTP/Identifying_resources_on_the_Web /pt-BR/docs/orphaned/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web /pt-BR/docs/Web/HTTP/Basico_sobre_HTTP/MIME_types /pt-BR/docs/Web/HTTP/Basics_of_HTTP/MIME_types /pt-BR/docs/Web/HTTP/Basico_sobre_HTTP/MIME_types/Complete_list_of_MIME_types /pt-BR/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types +/pt-BR/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web /pt-BR/docs/orphaned/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web /pt-BR/docs/Web/HTTP/Cabecalhos_HTTP /pt-BR/docs/Web/HTTP/Headers /pt-BR/docs/Web/HTTP/Compressão /pt-BR/docs/Web/HTTP/Compression /pt-BR/docs/Web/HTTP/Controle_Acesso_CORS /pt-BR/docs/Web/HTTP/CORS diff --git a/files/pt-br/_wikihistory.json b/files/pt-br/_wikihistory.json index 2a02ae522cd680..f6a8bc497c8211 100644 --- a/files/pt-br/_wikihistory.json +++ b/files/pt-br/_wikihistory.json @@ -4221,18 +4221,18 @@ "modified": "2020-10-15T22:16:14.686Z", "contributors": ["elielsonbatista"] }, - "Web/API/console/time_static": { - "modified": "2019-10-03T22:24:48.908Z", - "contributors": ["gcacars"] - }, - "Web/API/console/timeend_static": { + "Web/API/console/timeEnd_static": { "modified": "2019-03-23T23:04:24.266Z", "contributors": ["teoli", "perrucho"] }, - "Web/API/console/timestamp_static": { + "Web/API/console/timeStamp_static": { "modified": "2019-10-03T22:25:43.901Z", "contributors": ["gcacars"] }, + "Web/API/console/time_static": { + "modified": "2019-10-03T22:24:48.908Z", + "contributors": ["gcacars"] + }, "Web/API/console/warn_static": { "modified": "2019-03-18T21:45:25.881Z", "contributors": ["raduq"] @@ -6191,10 +6191,6 @@ "modified": "2019-03-18T20:54:14.334Z", "contributors": ["mauromattos00", "wdot789"] }, - "Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web": { - "modified": "2019-03-23T22:04:02.281Z", - "contributors": ["krisfertig", "rbertoche", "marciioluucas"] - }, "Web/HTTP/Basics_of_HTTP/MIME_types": { "modified": "2019-12-16T17:35:45.160Z", "contributors": ["JpOnline", "hugojunior", "marcusedu"] @@ -11330,6 +11326,10 @@ "modified": "2019-05-05T00:27:21.844Z", "contributors": ["willianpascoal"] }, + "orphaned/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web": { + "modified": "2019-03-23T22:04:02.281Z", + "contributors": ["krisfertig", "rbertoche", "marciioluucas"] + }, "orphaned/Web/HTTP/Feature_Policy/Using_Feature_Policy": { "modified": "2020-07-20T20:48:22.250Z", "contributors": ["FernandoKGA"] diff --git a/files/pt-br/web/http/basics_of_http/identifying_resources_on_the_web/index.md b/files/pt-br/orphaned/web/http/basics_of_http/identifying_resources_on_the_web/index.md similarity index 98% rename from files/pt-br/web/http/basics_of_http/identifying_resources_on_the_web/index.md rename to files/pt-br/orphaned/web/http/basics_of_http/identifying_resources_on_the_web/index.md index da64ffe5da3a98..057374242ce767 100644 --- a/files/pt-br/web/http/basics_of_http/identifying_resources_on_the_web/index.md +++ b/files/pt-br/orphaned/web/http/basics_of_http/identifying_resources_on_the_web/index.md @@ -1,6 +1,7 @@ --- title: Identificando recursos na web -slug: Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web +slug: orphaned/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web +original_slug: Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web --- {{HTTPSidebar}} diff --git a/files/pt-br/web/api/console/timeend_static/index.md b/files/pt-br/web/api/console/timeend_static/index.md index 6b204d690932ca..38e5430407b4cd 100644 --- a/files/pt-br/web/api/console/timeend_static/index.md +++ b/files/pt-br/web/api/console/timeend_static/index.md @@ -1,6 +1,6 @@ --- title: Console.timeEnd() -slug: Web/API/console/timeend_static +slug: Web/API/console/timeEnd_static --- {{APIRef("Console API")}}{{Non-standard_header}} diff --git a/files/pt-br/web/api/console/timestamp_static/index.md b/files/pt-br/web/api/console/timestamp_static/index.md index 2f414bc57cb1f3..940f94b5bff474 100644 --- a/files/pt-br/web/api/console/timestamp_static/index.md +++ b/files/pt-br/web/api/console/timestamp_static/index.md @@ -1,6 +1,6 @@ --- title: Console.timeStamp() -slug: Web/API/console/timestamp_static +slug: Web/API/console/timeStamp_static --- {{ APIRef("Console API") }}{{Non-standard_header}} From 797b7da282ed87f403f9ebab27d9936a8ddd698d Mon Sep 17 00:00:00 2001 From: Raphael Miranda Date: Tue, 3 Sep 2024 17:05:58 -0300 Subject: [PATCH 37/95] pt-BR: "Learn/HTML/Tables": Fixed broken links. (#23057) * pt-BR: "Learn/HTML/Tables": Fixed broken links. * Update index.md --- files/pt-br/learn/html/tables/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/pt-br/learn/html/tables/index.md b/files/pt-br/learn/html/tables/index.md index 5659686b959ef2..5da9e9e85b0145 100644 --- a/files/pt-br/learn/html/tables/index.md +++ b/files/pt-br/learn/html/tables/index.md @@ -18,12 +18,12 @@ Antes de iniciar este módulo, você deverá ter domínio dos básicos de HTML Este módulo contém os seguintes artigos: -- [HTML - o básico sobre tabelas](/pt-BR/docs/Learn/HTML/Tables/Basicos) +- [HTML - o básico sobre tabelas](/pt-BR/docs/Learn/HTML/Tables/Basics) - : Este artigo apresenta as tabelas HTML, cobrindo o essencial, tal como linhas e células, cabeçalhos, como extender células por múltiplas colunas e linhas, e como agrupar todas as células numa coluna para efeitos de estilo. -- [HTML - funcionalidades avançadas de tabelas e acessibilidade](/pt-BR/docs/Learn/HTML/Tables/Avancada) +- [HTML - funcionalidades avançadas de tabelas e acessibilidade](/pt-BR/docs/Learn/HTML/Tables/Advanced) - : No segundo artigo deste módulo, nós vamos ver algumas funcionalidades mais avançadas das tabelas HTML — tais como legendas/resumos e agrupar as suas filas no cabeçalho da tabela (head), seções de corpo (body) e rodapé (footer) — bem como, veremos sobre a acessibilidade das tabelas para os utilizadores deficientes visuais . ## Exercícios -- [Estruturar dados sobre planetas](/pt-BR/docs/Learn/HTML/Tables/Avaliacao_Estruturar_os_dados_dos_planetas) +- [Estruturar dados sobre planetas](/pt-BR/docs/Learn/HTML/Tables/Structuring_planet_data) - : Na nossa avaliação sobre tabelas em HTML, vamos fornecer alguns dados sobre os planetas do nosso sistema solar, para que possa estruturá-los numa tabela HTML. From 7ec97245d1c872c30613846e8fd0cba0958492c4 Mon Sep 17 00:00:00 2001 From: Raphael Miranda Date: Tue, 3 Sep 2024 17:06:58 -0300 Subject: [PATCH 38/95] pt-br: Small fixes in GFM alert. (#23056) pt-br: Small fixes. > extraneous in paragraph. --- .../other_embedding_technologies/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/files/pt-br/learn/html/multimedia_and_embedding/other_embedding_technologies/index.md b/files/pt-br/learn/html/multimedia_and_embedding/other_embedding_technologies/index.md index 334b527e7809c6..a1c4ebe518bbaa 100644 --- a/files/pt-br/learn/html/multimedia_and_embedding/other_embedding_technologies/index.md +++ b/files/pt-br/learn/html/multimedia_and_embedding/other_embedding_technologies/index.md @@ -274,7 +274,7 @@ Acima, mencionamos preocupações de segurança - vamos abordar isso com mais de Fabricantes de navegadores e desenvolvedores da Web descobriram da maneira mais difícil que iframes são um alvo comum (termo oficial: **attack vector** ) para pessoas más na Web (geralmente chamadas de **hackers** ou, mais precisamente, **crackers** ) atacarem se estiverem tentando modificar maliciosamente sua página da web ou induzir as pessoas a fazer algo que não desejam, como revelar informações confidenciais como nomes de usuário e senhas. Por esse motivo, engenheiros de especificações e desenvolvedores de navegadores desenvolveram vários mecanismos de segurança para tornár os `