docs(cndocs): sync latest upstream docs (#1028)

Author: sunnylqm

cndocs/accessibility.md

@@ -4,7 +4,7 @@ title: 无障碍功能
 description: 使用 React Native 面向 Android 和 iOS 的无障碍 API，构建可被辅助技术访问的移动应用。
 ---
 
-import ExperimentalAPIWarning from './_experimental-api-warning.mdx';
+import ExperimentalAPIWarning from './\_experimental-api-warning.mdx';
 
 Android 和 iOS 都提供了与辅助技术集成的能力，例如系统自带的读屏器 VoiceOver（iOS）和 TalkBack（Android）。React Native 提供了配套 API，帮助你的应用更好地服务所有用户。
 
@@ -191,13 +191,13 @@ large content viewer 显示时使用的标题文本。
 
 `accessibilityState` 是对象，包含：
 
-| Name     | Description                                                                                                                           | Type               | Required |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------- |
-| disabled | 元素是否禁用。                                                                                                                         | boolean            | No       |
-| selected | 可选元素当前是否选中。                                                                                                                 | boolean            | No       |
-| checked  | 可勾选元素状态。可为布尔值，或字符串 `"mixed"`（混合状态）。                                                                           | boolean or 'mixed' | No       |
-| busy     | 元素当前是否忙碌。                                                                                                                     | boolean            | No       |
-| expanded | 可展开元素当前是展开还是折叠。                                                                                                         | boolean            | No       |
+| Name     | Description                                                  | Type               | Required |
+| -------- | ------------------------------------------------------------ | ------------------ | -------- |
+| disabled | 元素是否禁用。                                               | boolean            | No       |
+| selected | 可选元素当前是否选中。                                       | boolean            | No       |
+| checked  | 可勾选元素状态。可为布尔值，或字符串 `"mixed"`（混合状态）。 | boolean or 'mixed' | No       |
+| busy     | 元素当前是否忙碌。                                           | boolean            | No       |
+| expanded | 可展开元素当前是展开还是折叠。                               | boolean            | No       |
 
 使用时，将 `accessibilityState` 设为符合上述结构的对象。
 
@@ -207,12 +207,12 @@ large content viewer 显示时使用的标题文本。
 
 `accessibilityValue` 是对象，包含：
 
-| Name | Description                                                                                    | Type    | Required                  |
-| ---- | ---------------------------------------------------------------------------------------------- | ------- | ------------------------- |
-| min  | 范围最小值。                                                                                     | integer | Required if `now` is set. |
-| max  | 范围最大值。                                                                                     | integer | Required if `now` is set. |
-| now  | 当前值。                                                                                         | integer | No                        |
-| text | 值的文本描述。若设置该字段，会覆盖 `min`、`now`、`max`。                                           | string  | No                        |
+| Name | Description                                              | Type    | Required                  |
+| ---- | -------------------------------------------------------- | ------- | ------------------------- |
+| min  | 范围最小值。                                             | integer | Required if `now` is set. |
+| max  | 范围最大值。                                             | integer | Required if `now` is set. |
+| now  | 当前值。                                                 | integer | No                        |
+| text | 值的文本描述。若设置该字段，会覆盖 `min`、`now`、`max`。 | string  | No                        |
 
 ### `accessibilityViewIsModal` <div className="label ios">iOS</div>
 
@@ -520,13 +520,13 @@ large content viewer 显示时使用的标题文本。
 - `'magicTap'` - iOS only - VoiceOver 焦点在组件上/内部时，用户双指双击。
 - `'escape'` - iOS only - VoiceOver 焦点在组件上/内部时，用户执行双指擦拭手势（左、右、左）。
 - `'activate'` - 激活动作。应与普通（非辅助技术）操作保持一致；读屏用户双击组件时触发。
-- `'increment'` - 增加可调整组件值。iOS 上，当角色为 `'adjustable'` 且用户上滑时触发；Android 上，当用户聚焦后按音量加键触发。
-- `'decrement'` - 减少可调整组件值。iOS 上，当角色为 `'adjustable'` 且用户下滑时触发；Android 上，当用户聚焦后按音量减键触发。
+- `'increment'` - 增加可调整组件值。iOS 上，当组件角色为 `'adjustable'` 且用户聚焦后向上轻扫时，VoiceOver 会生成此动作。Android 上，在 TalkBack 8.1 及更早版本中，用户聚焦组件并按下音量加键时会生成此动作；在 TalkBack 9.1 及更高版本中，它已被“调整阅读控件”手势（在聚焦的控件上向上轻扫）取代。
+- `'decrement'` - 减少可调整组件值。iOS 上，当组件角色为 `'adjustable'` 且用户聚焦后向下轻扫时，VoiceOver 会生成此动作。Android 上，在 TalkBack 8.2 及更早版本中，用户聚焦组件并按下音量减键时会生成此动作；在 TalkBack 9.2 及更高版本中，它已被“调整阅读控件”手势（在聚焦的控件上向下轻扫）取代。
 - `'longpress'` - Android only - 用户聚焦后双击并按住触发；应与普通长按行为一致。
 - `'expand'` - Android only - 展开组件，TalkBack 会播报“已展开”提示。
 - `'collapse'` - Android only - 折叠组件，TalkBack 会播报“已折叠”提示。
 
-`label` 对标准动作通常不会被辅助技术使用；对自定义动作，`label` 应是本地化字符串，用于向用户描述该动作。
+`label` 字段对标准动作是可选的，辅助技术会用它来描述某个动作的具体结果。例如，TalkBack 会使用该字段将默认的“双击即可激活”播报替换为类似“双击打开聊天”的自定义描述。对于自定义动作，`label` 是一个本地化字符串，用于向用户描述该动作。
 
 处理动作请求时，实现 `onAccessibilityAction`，其参数事件中包含动作名。示例：
 

cndocs/linking.md

@@ -91,15 +91,15 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import con
 <TabItem value="swift">
 
 ```swift title="AppDelegate.swift"
-override func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
   return RCTLinkingManager.application(app, open: url, options: options)
 }
 ```
 
 如果你的 app 用了 [Universal Links](https://developer.apple.com/ios/universal-links/)，需要正确的把下述代码添加进去：
 
 ```swift title="AppDelegate.swift"
-override func application(
+func application(
   _ application: UIApplication,
   continue userActivity: NSUserActivity,
   restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {

cnwebsite/package.json

@@ -52,11 +52,12 @@
     "@docusaurus/plugin-google-gtag": "3.10.1",
     "@docusaurus/plugin-pwa": "3.10.1",
     "@docusaurus/preset-classic": "3.10.1",
+    "@docusaurus/theme-mermaid": "3.10.1",
+    "docusaurus-plugin-copy-page-button": "^0.6.2",
     "docusaurus-plugin-sass": "^0.2.6",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
-    "react-github-btn": "^1.4.0",
-    "@docusaurus/theme-mermaid": "3.10.1"
+    "react-github-btn": "^1.4.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.10.1",

cnwebsite/src/css/customTheme.scss

@@ -103,9 +103,14 @@
 
 body {
   font-family: var(--ifm-font-family-base);
+  scrollbar-gutter: stable;
 }
 
 html[data-theme="light"] {
+  body {
+    scrollbar-color: var(--subtle) var(--ifm-background-color);
+  }
+
   --ifm-link-color: #357da1;
 }
 

cnwebsite/src/theme/DocItem/Layout/index.tsx

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
+import CopyPageButton from 'docusaurus-plugin-copy-page-button/react';
+import DocItemPaginator from '@theme/DocItem/Paginator';
+import DocVersionBanner from '@theme/DocVersionBanner';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import DocItemFooter from '@theme/DocItem/Footer';
+import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile';
+import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop';
+import DocItemContent from '@theme/DocItem/Content';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import ContentVisibility from '@theme/ContentVisibility';
+import type {Props} from '@theme/DocItem/Layout';
+
+import styles from './styles.module.css';
+
+function DocItemCopyPageButton({className}: {className?: string}) {
+  return (
+    <div className={clsx(styles.copyPageAction, className)}>
+      <CopyPageButton
+        customStyles={{
+          container: {className: styles.copyPageButtonContainer},
+          button: {
+            className: styles.copyPageButton,
+            style: {marginBottom: 0},
+          },
+          dropdown: {className: styles.copyPageDropdown},
+        }}
+      />
+    </div>
+  );
+}
+
+/**
+ * Decide if the toc should be rendered, on mobile or desktop viewports
+ */
+function useDocTOC() {
+  const {frontMatter, toc} = useDoc();
+  const windowSize = useWindowSize();
+
+  const hidden = frontMatter.hide_table_of_contents;
+  const canRender = !hidden && toc.length > 0;
+
+  const mobile = canRender ? <DocItemTOCMobile /> : undefined;
+
+  const desktop =
+    canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? (
+      <DocItemTOCDesktop />
+    ) : undefined;
+
+  return {
+    canRender,
+    hidden,
+    mobile,
+    desktop,
+  };
+}
+
+export default function DocItemLayout({children}: Props): ReactNode {
+  const docTOC = useDocTOC();
+  const {metadata} = useDoc();
+  return (
+    <div className="row">
+      <div className={clsx('col', !docTOC.hidden && styles.docItemCol)}>
+        <ContentVisibility metadata={metadata} />
+        <DocVersionBanner />
+        <div className={styles.docItemContainer}>
+          <article>
+            <DocBreadcrumbs />
+            <div className={styles.docHeaderContainer}>
+              <DocVersionBadge />
+              <DocItemCopyPageButton
+                className={clsx(
+                  styles.copyPageArticleAction,
+                  docTOC.canRender && styles.copyPageArticleActionWithToc
+                )}
+              />
+            </div>
+            {docTOC.mobile}
+            <DocItemContent>{children}</DocItemContent>
+            <DocItemFooter />
+          </article>
+          <DocItemPaginator />
+        </div>
+      </div>
+      {docTOC.desktop && (
+        <div className="col col--3">
+          <DocItemCopyPageButton className={styles.copyPageAsideAction} />
+          {docTOC.desktop}
+        </div>
+      )}
+    </div>
+  );
+}

cnwebsite/src/theme/DocItem/Layout/styles.module.css

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
+  margin-top: 0;
+}
+
+.docHeaderContainer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.copyPageAsideAction {
+  margin-bottom: 1rem;
+}
+
+div[class^="copyPageArticleAction"] {
+  margin-bottom: 0;
+}
+
+button[class^="copyPageButton"] {
+  border-radius: var(--ifm-global-radius);
+  border-color: var(--ifm-color-gray-500);
+
+  &:hover {
+    background-color: var(--ifm-menu-color-background-hover) !important;
+    border-color: var(--ifm-color-gray-400) !important;
+  }
+
+  svg {
+    opacity: 0.75;
+  }
+}
+
+div[class^="copyPageDropdown"] {
+  border-color: var(--ifm-table-border-color) !important;
+
+  button[class^="dropdownItem"] {
+    border-bottom-color: var(--ifm-table-border-color) !important;
+
+    &:hover {
+      background-color: var(--ifm-menu-color-background-hover);
+    }
+  }
+
+  div[class^="itemDescription"] {
+    font-weight: 300;
+    font-size: 12px;
+  }
+}
+
+[data-theme="dark"] {
+  button[class^="copyPageButton"] {
+    &:hover {
+      background-color: var(--dark) !important;
+      border-color: var(--ifm-color-gray-800) !important;
+    }
+  }
+
+  button[class^="dropdownItem"] {
+    &:hover {
+      background-color: var(--dark);
+    }
+  }
+
+  div[class^="copyPageDropdown"] {
+    background-color: var(--ifm-navbar-background-color);
+  }
+}
+
+@media (min-width: 997px) {
+  .docItemCol {
+    max-width: 75% !important;
+  }
+
+  .copyPageArticleActionWithToc {
+    display: none;
+  }
+}