[zh-Hans] translate API docs: utils and components (15)

packages/react-simplikit/src/components/ImpressionArea/zh-Hans/ImpressionArea.md

@@ -0,0 +1,100 @@
+# ImpressionArea
+
+`ImpressionArea` 是一个测量特定 DOM 元素在屏幕上可见时长、并在元素进入或离开视口时执行回调的组件。该组件使用 `useImpressionRef` Hook 来跟踪元素的可见性。
+
+## 接口
+
+```ts
+function ImpressionArea<T extends ElementType>(
+  as: T = 'div',
+  rootMargin?: string,
+  areaThreshold?: number,
+  timeThreshold?: number,
+  onImpressionStart?: () => void,
+  onImpressionEnd?: () => void,
+  ref?: Ref<Element<T>>,
+  children?: React.ReactNode,
+  className?: string
+): JSX.Element;
+```
+
+### 参数
+
+<Interface
+  name="as"
+  type="T"
+  description="要渲染的 HTML 标签。默认值为 <code>div</code>。"
+/>
+
+<Interface
+  name="rootMargin"
+  type="string"
+  description="用于调整检测区域的边距。"
+/>
+
+<Interface
+  name="areaThreshold"
+  type="number"
+  description="元素必须可见的最小比例（0 到 1）。"
+/>
+
+<Interface
+  name="timeThreshold"
+  type="number"
+  description="元素必须可见的最短时间（毫秒）。"
+/>
+
+<Interface
+  name="onImpressionStart"
+  type="() => void"
+  description="元素进入视野时执行的回调函数。"
+/>
+
+<Interface
+  name="onImpressionEnd"
+  type="() => void"
+  description="元素离开视野时执行的回调函数。"
+/>
+
+<Interface
+  name="ref"
+  type="Ref<Element<T>>"
+  description="对元素的引用。"
+/>
+
+<Interface
+  name="children"
+  type="React.ReactNode"
+  description="渲染在组件内部的子元素。"
+/>
+
+<Interface
+  name="className"
+  type="string"
+  description="用于附加样式的 class 名。"
+/>
+
+### 返回值
+
+<Interface
+  name=""
+  type="JSX.Element"
+  description="一个跟踪其子元素可见性的 React 组件。"
+/>
+
+## 示例
+
+```tsx
+function App() {
+  return (
+    <ImpressionArea
+      onImpressionStart={() => console.log('Element entered view')}
+      onImpressionEnd={() => console.log('Element exited view')}
+      timeThreshold={1000}
+      areaThreshold={0.5}
+    >
+      <div>Track me!</div>
+    </ImpressionArea>
+  );
+}
+```

packages/react-simplikit/src/components/Separated/zh-Hans/Separated.md

@@ -0,0 +1,53 @@
+# Separated
+
+`Separated` 是一个在各个子元素之间插入指定组件的组件。适合用于在列表中添加分隔符、间距或其他重复出现的元素。
+
+## 接口
+
+```ts
+function Separated(children: React.ReactNode, by: React.ReactNode): JSX.Element;
+```
+
+### 参数
+
+<Interface
+  required
+  name="children"
+  type="React.ReactNode"
+  description="要渲染的子元素。只有有效的 React 元素（<code>React.isValidElement</code>）才会被渲染。"
+/>
+
+<Interface
+  required
+  name="by"
+  type="React.ReactNode"
+  description="要插入到子元素之间的组件。"
+/>
+
+### 返回值
+
+<Interface
+  name=""
+  type="JSX.Element"
+  description="一个用指定分隔组件分隔子元素的 React 组件。"
+/>
+
+## 示例
+
+```tsx
+function App() {
+  return (
+    <Separated by={<Border type="padding24" />}>
+      {['hello', 'react', 'world'].map(item => (
+        <div key={item}>{item}</div>
+      ))}
+    </Separated>
+  );
+  // Expected output:
+  // <div>hello</div>
+  // <Border type="padding24" />
+  // <div>react</div>
+  // <Border type="padding24" />
+  // <div>world</div>
+}
+```

packages/react-simplikit/src/components/SwitchCase/zh-Hans/SwitchCase.md

@@ -0,0 +1,63 @@
+# SwitchCase
+
+`SwitchCase` 是一个让你根据给定值以声明式方式渲染组件的组件，类似 `switch-case` 语句。当你需要根据特定状态条件渲染不同组件时很有用。
+
+## 接口
+
+```ts
+function SwitchCase<Case>(
+  value: Case,
+  caseBy: Partial<{ [P in StringifiedValue<Case>]: () => ReactElement | null }>,
+  defaultComponent?: () => ReactElement | null
+): ReactElement | null;
+```
+
+### 参数
+
+<Interface
+  required
+  name="value"
+  type="Case"
+  description="要比较的值。将渲染 <code>caseBy</code> 中与之匹配的 key 所对应的组件。"
+/>
+
+<Interface
+  required
+  name="caseBy"
+  type="Partial<{ [P in StringifiedValue<Case>]: () => ReactElement | null }>"
+  description="一个将值映射到待渲染组件的对象。key 表示可能的取值，value 是返回对应组件的函数。"
+/>
+
+<Interface
+  name="defaultComponent"
+  type="() => ReactElement | null"
+  description="当 <code>value</code> 不匹配 <code>caseBy</code> 中的任何 key 时渲染的组件。"
+/>
+
+### 返回值
+
+<Interface
+  name=""
+  type="ReactElement | null"
+  description="一个根据 case 条件渲染的 React 组件。"
+/>
+
+## 示例
+
+```tsx
+function App() {
+  return (
+    <SwitchCase
+      value={status}
+      // Renders TypeA, TypeB, or TypeC based on the status value.
+      caseBy={{
+        a: () => <TypeA />,
+        b: () => <TypeB />,
+        c: () => <TypeC />,
+      }}
+      // Renders Default when the status value does not match any case.
+      defaultComponent={() => <Default />}
+    />
+  );
+}
+```

packages/react-simplikit/src/utils/buildContext/zh-Hans/buildContext.md

@@ -0,0 +1,73 @@
+# buildContext
+
+`buildContext` 是一个减少定义 React Context 时重复代码的辅助函数。
+
+## 接口
+
+```ts
+function buildContext<ContextValuesType extends object>(
+  contextName: string,
+  defaultContextValues?: ContextValuesType
+): [
+  Provider: (props: ProviderProps<ContextValuesType>) => JSX.Element,
+  useContext: () => ContextValuesType,
+];
+```
+
+### 参数
+
+<Interface
+  required
+  name="contextName"
+  type="string"
+  description="Context 的名称。"
+/>
+
+<Interface
+  name="defaultContextValues"
+  type="ContextValuesType"
+  description="传递给 Context 的默认值。"
+/>
+
+### 返回值
+
+<Interface
+  name=""
+  type="[Provider: (props: ProviderProps<ContextValuesType>) => JSX.Element, useContext: () => ContextValuesType]"
+  description="具有以下形式的元组："
+  :nested="[
+    {
+      name: 'Provider',
+      type: '(props: ProviderProps<ContextValuesType>) => JSX.Element',
+      required: false,
+      description: '提供 Context 的组件。',
+    },
+    {
+      name: 'useContext',
+      type: '() => ContextValuesType',
+      required: false,
+      description: '使用 Context 的 Hook。',
+    },
+  ]"
+/>
+
+## 示例
+
+```tsx
+const [Provider, useContext] = buildContext<{ title: string }>('TestContext', {
+  title: 'Default title',
+});
+
+function Inner() {
+  const { title } = useContext();
+  return <div>{title}</div>;
+}
+
+function Page() {
+  return (
+    <Provider title="Hello">
+      <Inner />
+    </Provider>
+  );
+}
+```

packages/react-simplikit/src/utils/disableBodyScrollLock/zh-Hans/disableBodyScrollLock.md

@@ -0,0 +1,30 @@
+# disableBodyScrollLock
+
+`disableBodyScrollLock` 是一个解除 body 滚动锁定的工具函数。它会恢复被 `enableBodyScrollLock` 锁定的滚动，并回到保存的滚动位置。
+
+在 SSR 环境中调用是安全的（在服务端为空操作）。
+未锁定时调用同样安全（空操作）。
+
+## 接口
+
+```ts
+function disableBodyScrollLock(): void;
+```
+
+### 参数
+
+此函数不接受任何参数。
+
+### 返回值
+
+此函数不返回任何值。
+
+## 示例
+
+```tsx
+// When modal opens
+enableBodyScrollLock();
+
+// When modal closes
+disableBodyScrollLock();
+```

packages/react-simplikit/src/utils/enableBodyScrollLock/zh-Hans/enableBodyScrollLock.md

@@ -0,0 +1,30 @@
+# enableBodyScrollLock
+
+`enableBodyScrollLock` 是一个锁定 body 滚动的工具函数。它通过应用固定定位来阻止 body 滚动，在打开模态框、抽屉或其他覆盖层组件时很有用。
+
+在 SSR 环境中调用是安全的（在服务端为空操作）。
+在解除锁定之前，重复调用不会产生额外效果。
+
+## 接口
+
+```ts
+function enableBodyScrollLock(): void;
+```
+
+### 参数
+
+此函数不接受任何参数。
+
+### 返回值
+
+此函数不返回任何值。
+
+## 示例
+
+```tsx
+// When modal opens
+enableBodyScrollLock();
+
+// When modal closes
+disableBodyScrollLock();
+```

packages/react-simplikit/src/utils/getKeyboardHeight/zh-Hans/getKeyboardHeight.md

@@ -0,0 +1,38 @@
+# getKeyboardHeight
+
+`getKeyboardHeight` 是一个返回当前屏幕键盘高度（以像素为单位）的工具函数。
+
+该函数使用 Visual Viewport API 计算键盘高度，并假定运行在支持 Visual Viewport 的现代环境中（Safari / WKWebView 14+、Chrome / Android WebView 80+）。
+
+键盘高度的计算方式为：
+`window.innerHeight - visualViewport.height - visualViewport.offsetTop`
+
+减去 `offsetTop` 是为了正确处理 iOS 的行为：键盘出现时，视觉视口可能发生垂直位移。
+
+## 接口
+
+```ts
+function getKeyboardHeight(): number;
+```
+
+### 参数
+
+此函数不接受任何参数。
+
+### 返回值
+
+<Interface
+  name=""
+  type="number"
+  description="键盘高度（像素）。键盘不可见时返回 0。"
+/>
+
+## 示例
+
+```tsx
+const height = getKeyboardHeight();
+
+if (height > 0) {
+  footer.style.paddingBottom = `${height}px`;
+}
+```