[zh-cn]: create docs for Fence (#24648)

Co-authored-by: A1lo <[email protected]>

files/zh-cn/web/api/fence/getnestedconfigs/index.md

@@ -0,0 +1,53 @@
+---
+title: Fence：getNestedConfigs() 方法
+slug: Web/API/Fence/getNestedConfigs
+l10n:
+  sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+{{domxref("Fence")}} 接口的 **`getNestedConfigs()`** 方法返回加载到当前 `<fencedframe>` 内部嵌入的 `<fencedframe>` 中的 {{domxref("FencedFrameConfig")}} 配置。
+
+## 语法
+
+```js-nolint
+getNestedConfigs()
+```
+
+### 参数
+
+无。
+
+### 返回值
+
+`getNestedConfigs()` 有两个可能的返回值：
+
+- 如果当前 `<fencedframe>` 的配置是通过支持嵌套配置的 API（例如[受保护的受众](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience)）创建的，则为一个包含 20 个 {{domxref("FencedFrameConfig")}} 对象的数组。在这 20 个配置中，前 N 个配置是通过 API 注册的，其余的是将导航到 `about:blank` 的填充配置，以便隐藏配置的数量并防止任何信息泄露。
+- 如果当前 `<fencedframe>` 的配置是通过不支持嵌套配置的 API（例如[共享存储](/zh-CN/docs/Web/API/Shared_Storage_API)）创建的，则为 `null`。
+
+## 示例
+
+```js
+// 在 <fencedframe> 内部运行
+
+// 获取嵌入围栏框架的配置
+const configs = window.fence.getNestedConfigs();
+
+// 将新的围栏框架配置设置为与检索到的某个配置相同
+const frame = document.createElement("fencedframe");
+frame.config = configs[0];
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- developers.google.cn 上的[围栏框架](https://developers.google.cn/privacy-sandbox/private-advertising/fenced-frame)
+- developers.google.cn 上的[隐私沙盒](https://developers.google.cn/privacy-sandbox)

files/zh-cn/web/api/fence/index.md

@@ -0,0 +1,49 @@
+---
+title: Fence
+slug: Web/API/Fence
+l10n:
+  sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+{{domxref("Fenced Frame API", "围栏框架 API", "", "nocode")}} 的 **`Fence`** 接口包含与 {{htmlelement("fencedframe")}} 功能相关的几个函数。
+
+`Fence` 对象可以通过 {{domxref("Window.fence")}} 属性访问，但它们仅对嵌入在 {{htmlelement("fencedframe")}}（通过 {{domxref("FencedFrameConfig")}} 加载）或 {{htmlelement("iframe")}}（通过不透明 URN 加载）中的文档可用。
+
+> [!NOTE]
+> 参见 [`<fencedframe>` 的工作原理](/zh-CN/docs/Web/API/Fenced_frame_API#fencedframe_的工作原理)了解有关 `FencedFrameConfig` 和不透明 URN 的一些描述。
+
+{{InheritanceDiagram}}
+
+## 实例方法
+
+- {{domxref("Fence.getNestedConfigs", "getNestedConfigs()")}} {{Experimental_Inline}}
+  - : 返回加载到当前 `<fencedframe>` 内部嵌入的 `<fencedframe>` 中的 {{domxref("FencedFrameConfig")}} 配置。
+- {{domxref("Fence.reportEvent", "reportEvent()")}} {{Experimental_Inline}}
+  - : 通过[信标](/zh-CN/docs/Web/API/Beacon_API)触发报告数据的提交，将数据发送到通过[受保护的受众 API](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience) 的 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} 方法注册的一个或多个特定 URL，以收集广告的竞价结果。
+- {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} {{Experimental_Inline}}
+  - : 指定在 `<fencedframe>` 内部发生导航时将发送的事件数据。这些数据将通过自动信标发送到通过[受保护的受众 API](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience) 的 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} 方法注册的一个或多个特定 URL，以收集广告竞价结果的报告数据。
+
+## 示例
+
+```js
+window.fence.reportEvent({
+  eventType: "click",
+  eventData: JSON.stringify({ clickX: "123", clickY: "456" }),
+  destination: ["buyer", "seller"],
+});
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- developers.google.cn 上的[围栏框架](https://developers.google.cn/privacy-sandbox/private-advertising/fenced-frame)
+- developers.google.cn 上的[隐私沙盒](https://developers.google.cn/privacy-sandbox)

files/zh-cn/web/api/fence/reportevent/index.md

@@ -0,0 +1,63 @@
+---
+title: Fence：reportEvent() 方法
+slug: Web/API/Fence/reportEvent
+l10n:
+  sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+{{domxref("Fence")}} 接口的 **`reportEvent()`** 方法通过[信标](/zh-CN/docs/Web/API/Beacon_API)触发报告数据的提交，将数据发送到通过[受保护的受众 API](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience) 的 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} 方法注册的一个或多个特定 URL，以收集广告竞价结果。
+
+> **备注：** {{domxref("Fence.setReportEventDataForAutomaticBeacons", "setReportEventDataForAutomaticBeacons()")}} 提供类似的报告数据提交功能，除非提交是通过导航而不是显式的方法调用触发的。
+
+## 语法
+
+```js-nolint
+reportEvent(event)
+```
+
+### 参数
+
+- `event`
+  - : 表示要发送的数据的对象或字符串。
+    - 对象值定义一个你想要发送的特定报告事件。必需属性如下：
+      - `eventType`
+        - : 表示正在报告的事件类型的字符串——例如，你可能想要了解广告被点击的次数。这个字符串可以是任何相关的事件名称（例如 [`click`](/zh-CN/docs/Web/API/Element/click_event)）。这需要与[受保护的受众 API](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience) worklet 中关联的 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} 调用指定的事件类型相匹配。
+      - `eventData`
+        - : 表示要发送的数据的字符串。
+      - `destination`
+        - : 包含一个或多个枚举值的数组，这些值代表目标类型。这些是将接收数据到其注册 URL（即通过 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}）的涉及方。可能的值包括：
+          - `"buyer"`：广告竞价中的出价方。
+          - `"seller"`：运行广告竞价的顶级卖方。
+          - `"component-seller"`：多级竞价中组成竞价的卖方。
+          - `"direct-seller"`：直接运行买家投标竞价的卖方。如果广告是单级竞价，则使用的值为 `"seller"`。如果广告是多级竞价，则使用的值为 `"component-seller"`。
+          - `"shared-storage-select-url"`：[共享存储 API](https://developers.google.cn/privacy-sandbox/private-advertising/shared-storage) 存储位置，如在 {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} 方法调用中所定义。
+    - 字符串值表示一个 `eventType`，例如 `"click"`（参见前面 `eventType` 的定义）。当将 `eventType` 字符串作为 `reportEvent()` 的值传递时，它会触发所有基于该事件类型（例如通过 {{domxref("PrivateAggregation.contributeToHistogramOnEvent()")}}）做出的隐私聚合贡献的发送。
+
+### 返回值
+
+无（`undefined`）。
+
+## 示例
+
+```js
+window.fence.reportEvent({
+  eventType: "click",
+  eventData: JSON.stringify({ clickX: "123", clickY: "456" }),
+  destination: ["buyer", "seller"],
+});
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- developers.google.cn 上的[围栏框架](https://developers.google.cn/privacy-sandbox/private-advertising/fenced-frame)
+- developers.google.cn 上的[隐私沙盒](https://developers.google.cn/privacy-sandbox)

files/zh-cn/web/api/fence/setreporteventdataforautomaticbeacons/index.md

@@ -0,0 +1,65 @@
+---
+title: Fence：setReportEventDataForAutomaticBeacons() 方法
+slug: Web/API/Fence/setReportEventDataForAutomaticBeacons
+l10n:
+  sourceCommit: f430d277573ba0b06b1ac33ae8017fd90f170bef
+---
+
+{{SeeCompatTable}}{{APIRef("Fenced Frame API")}}
+
+{{domxref("Fence")}} 接口的 **`setReportEventDataForAutomaticBeacons()`** 方法指定在 `<fencedframe>` 内部发生导航时将发送的事件数据。这些数据将通过自动[信标](/zh-CN/docs/Web/API/Beacon_API)发送到通过[受保护的受众 API](https://developers.google.cn/privacy-sandbox/private-advertising/protected-audience) 的 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}} 方法注册的一个或多个特定 URL，以收集广告竞价结果的报告数据。
+
+> **备注：** {{domxref("Fence.reportEvent", "reportEvent()")}} 提供类似的报告数据提交功能，除非提交是通过显式方法调用而不是导航触发的。
+
+## 语法
+
+```js-nolint
+setReportEventDataForAutomaticBeacons(event)
+```
+
+### 参数
+
+- `event`
+  - : 表示要发送数据的对象。可能的属性如下：
+    - `eventType`
+      - : 一个字符串，表示正在报告的事件类型。可用值包括：
+        - `reserved.top_navigation_start`：当顶级导航开始时触发的事件。
+        - `reserved.top_navigation_commit`：当顶级导航完成时触发的事件。
+    - `eventData`
+      - : 表示要发送的数据的字符串。
+    - `destination`
+      - : 包含一个或多个枚举值的数组，这些值代表目标类型。这些是将接收数据到其注册 URL（即通过 {{domxref("InterestGroupReportingScriptRunnerGlobalScope.registerAdBeacon", "registerAdBeacon()")}}）的涉及方。可能的值包括：
+        - `"buyer"`：广告竞价中的出价方。
+        - `"seller"`：运行广告竞价的顶级卖方。
+        - `"component-seller"`：多级竞价中组成竞价的卖方。
+        - `"direct-seller"`：直接运行买家投标竞价的卖方。如果广告是单级竞价，则使用的值为 `"seller"`。如果广告是多级竞价，则使用的值为 `"component-seller"`。
+        - `"shared-storage-select-url"`：[共享存储 API](https://developers.google.cn/privacy-sandbox/private-advertising/shared-storage) 存储位置，如在 {{domxref("WindowSharedStorage.selectURL", "Window.sharedStorage.selectURL()")}} 方法调用中所定义。
+    - `once` {{optional_inline}}
+      - : 一个布尔值。如果设置为 `true`，则仅会为下一个事件发送自动信标，并且在再次调用 `setReportEventDataForAutomaticBeacons()` 之前，不会为后续事件发送信标。例如，当与 `click` 处理程序一起使用时，这可用于仅为特定的顶级导航发送信标数据，而不是为每次顶级导航都发送。此属性的默认值为 `false`。
+
+### 返回值
+
+无（`undefined`）。
+
+## 示例
+
+```js
+window.fence.setReportEventDataForAutomaticBeacons({
+  eventType: "reserved.top_navigation_start",
+  eventData: "示例字符串",
+  destination: ["seller", "buyer"],
+});
+```
+
+## 规范
+
+{{Specifications}}
+
+## 浏览器兼容性
+
+{{Compat}}
+
+## 参见
+
+- developers.google.cn 上的[围栏框架](https://developers.google.cn/privacy-sandbox/private-advertising/fenced-frame)
+- developers.google.cn 上的[隐私沙盒](https://developers.google.cn/privacy-sandbox)