diff --git a/cndocs/scrollview.md b/cndocs/scrollview.md
index a8632c9b19d..72ce43c3a16 100644
--- a/cndocs/scrollview.md
+++ b/cndocs/scrollview.md
@@ -70,7 +70,7 @@ export default App;
### `StickyHeaderComponent`
-一个 React 组件,用于渲染粘性头部,应与`stickyHeaderIndices`一起使用。如果你的粘性头部使用了自定义变换(例如,当你希望列表具有可动画隐藏的头部时),你可能需要设置此组件。如果未提供组件,则将使用默认的 [`ScrollViewStickyHeader`](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Components/ScrollView/ScrollViewStickyHeader.js) 组件。
+一个 React 组件,用于渲染粘性头部,应与 `stickyHeaderIndices` 一起使用。如果你的粘性头部使用了自定义变换(例如,当你希望列表具有可动画隐藏的头部时),你可能需要设置此组件。如果未提供组件,则将使用默认的 [`ScrollViewStickyHeader`](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Components/ScrollView/ScrollViewStickyHeader.js) 组件。
| 类型 |
| ------------------ |
@@ -130,7 +130,7 @@ export default App;
### `bounces`
iOS
-当值为 true 时,如果内容范围比滚动视图本身大,在到达内容末尾的时候,可以弹性地拉动一截。如果为 false,尾部的所有弹性都会被禁用,即使`alwaysBounce`属性为 true。默认值为 true。
+当值为 true 时,如果内容范围比滚动视图本身大,在到达内容末尾的时候,可以弹性地拉动一截。如果为 false,尾部的所有弹性都会被禁用,即使 `alwaysBounce*` 系列属性为 `true`。默认值为 true。
| 类型 | 默认值 |
| ---- | ------ |
@@ -170,7 +170,7 @@ export default App;
### `contentContainerStyle`
-这些样式会应用到一个内层的内容容器上,所有的子视图都会包裹在内容容器内。示例:
+应用于内容容器的样式,该容器包裹所有子视图。示例:
```
return (
@@ -185,6 +185,13 @@ const styles = StyleSheet.create({
});
```
+**与 `contentInsetAdjustmentBehavior` 的交互(iOS)**
+
+通常,`contentContainerStyle` 用于让条目与屏幕边缘或滚动指示器保持间距。当设置了 [`contentInsetAdjustmentBehavior`](#contentinsetadjustmentbehavior-ios) 时(推荐如此),`padding` 的应用方式与普通 `` 略有不同:
+
+- **像素值:** 如果某个边缘适用安全区域内边距,则取 `padding` 与内边距中**较大的那个**。没有内边距的边缘(例如表头下方的滚动视图顶部)会保留完整的 `padding`。
+- **百分比值:** 在垂直于可滚动轴的方向上,`padding` 会被直接使用,取代安全区域内边距;在沿可滚动轴的方向上,安全区域内边距仍然生效,而 `padding` 会在其基础上叠加。
+
| 类型 |
| ------------------------------ |
| [View Style](view-style-props) |
@@ -203,7 +210,12 @@ const styles = StyleSheet.create({
### `contentInsetAdjustmentBehavior` iOS
-本属性用于指定安全区域内边距如何修改滚动视图的内容区域。
+安全区域内边距如何修改滚动视图的内容区域。
+
+- **在沿可滚动轴的方向上**,内边距会变为内容内边距,因此内容会滚动到系统 UI(例如状态栏或主屏幕指示条)下方。
+- **在垂直于可滚动轴的方向上**,除 `'never'` 之外的每个值都会用内边距为内容容器留出空间,因此内容会布局在系统 UI 之外,例如 iPhone Duo 上的侧边栏或横屏时的摄像头挖孔。容器的背景和滚动指示器仍会延伸到屏幕边缘。
+
+在每个边缘上,来自 [`contentContainerStyle`](#contentcontainerstyle) 的 padding 都会计入内边距,因此内容会位于两者中较大的那个位置。
| 类型 | 默认值 |
| -------------------------------------------------------------- | --------- |
@@ -280,9 +292,9 @@ const styles = StyleSheet.create({
如果值大于 `0`,则会根据当前的滚动方向和位置设置淡出边缘,指示是否有更多内容可显示。
-| 类型 | 默认值 |
-| ------ | ------ |
-| number | `0` |
+| 类型 | 默认值 |
+| -------------------------------------------------- | ------ |
+| number
object: `{start: number, end: number}` | `0` |
---
@@ -435,7 +447,7 @@ _仅 iOS 可用的值_
### `onScroll`
-在滚动的过程中,每帧最多调用一次此回调函数。调用的频率可以用`scrollEventThrottle`属性来控制。事件的构型如下(所有值都是数字):
+在滚动的过程中,每帧最多调用一次此回调函数。调用的频率可以用`scrollEventThrottle`属性来控制。事件的构型如下(未标明类型的值均为数字):
```js
{
@@ -444,7 +456,11 @@ _仅 iOS 可用的值_
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
- zoomScale
+ velocity: {x, y},
+ responderIgnoreScroll: boolean,
+ zoomScale,
+ // iOS only
+ targetContentOffset: {x, y}
}
}
```
@@ -485,7 +501,7 @@ _仅 iOS 可用的值_
---
-### `overScrollMode`
+### `overScrollMode` Android
覆盖默认的 overScroll 模式
@@ -543,11 +559,15 @@ _仅 iOS 可用的值_
### `removeClippedSubviews`
-(实验特性):当此属性为 true 时,屏幕之外的子视图(子视图的`overflow`样式需要设为`hidden`)会被移除。这个可以提升大列表的滚动性能。
+:::warning
+使用此属性在某些情况下可能导致缺陷(内容缺失)——请自行承担风险。
+:::
-| 类型 | 默认值 |
-| ---- | ------- |
-| bool | `false` |
+当为 `true` 时,屏幕之外的子视图会从其原生父视图(native backing superview)中移除。这可以提升大列表的滚动性能。在 Android 上默认值为 `true`。
+
+| 类型 |
+| ------- |
+| boolean |
---
@@ -593,6 +613,16 @@ _仅 iOS 可用的值_
---
+### `scrollsChildToFocus` Android
+
+当为 `true` 时,ScrollView 会自动滚动,使获得焦点的子视图进入视野。设为 `false` 可禁用此行为,在焦点变化时手动控制滚动位置。
+
+| 类型 | 默认值 |
+| ---- | ------ |
+| bool | `true` |
+
+---
+
### `scrollToOverflowEnabled` iOS
当值为 true 时,滚动视图可以被编程地滚动超过其内容大小。
@@ -633,7 +663,7 @@ _仅 iOS 可用的值_
---
-### `snapToAlignment` iOS
+### `snapToAlignment`
当设置了 `snapToInterval` 时,`snapToAlignment` 会定义停驻点与滚动视图之间的关系。
@@ -689,16 +719,6 @@ _仅 iOS 可用的值_
---
-### `StickyHeaderComponent`
-
-一个 React 组件,用于渲染粘性头部,应与 `stickyHeaderIndices` 一起使用。如果粘性头部使用自定义变换,例如,当您希望列表具有可动画化和可隐藏的头部时,可能需要设置此组件。如果未提供组件,将使用默认的 [`ScrollViewStickyHeader`](https://github.com/react/react-native/blob/main/packages/react-native/Libraries/Components/ScrollView/ScrollViewStickyHeader.js) 组件。
-
-| 类型 |
-| ------------------ |
-| component, element |
-
----
-
### `stickyHeaderHiddenOnScroll`
当设置为 `true` 时,粘性头部将在向下滚动列表时隐藏,当向上滚动时,它将固定在列表顶部。
@@ -751,12 +771,16 @@ scrollTo(
);
```
-滚动到指定的 x, y 偏移处。第三个参数为是否启用平滑滚动动画。
+滚动到指定的 x, y 偏移处,可以立即滚动,也可以使用平滑动画。
-示例:
+**示例:**
`scrollTo({x: 0, y: 0, animated: true})`
+:::note
+这个略显奇怪的函数签名是历史原因造成的:该函数还接受分开的参数作为选项对象的替代。由于存在歧义(y 在 x 之前),这种做法已被废弃,不应再使用。
+:::
+
---
### `scrollToEnd()`