docs(zh-Hans): translate 15 API reference pages (utils + components)

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

@@ -0,0 +1,100 @@
+# ImpressionArea
+
+`ImpressionArea` 是一个组件，用于测量特定 DOM 元素在屏幕上的可见时间，并在元素进入或离开视口时执行回调。该组件使用 `useImpressionRef` 钩子来跟踪元素的可见性。
+
+## Interface
+
+```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;
+```
+
+### Parameters
+
+<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="用于样式设置的其他类名。"
+/>
+
+### Return Value
+
+<Interface
+  name=""
+  type="JSX.Element"
+  description="一个跟踪其子元素可见性的 React 组件。"
+/>
+
+## Example
+
+```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>
+  );
+  // 预期输出：
+  // <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> 中与匹配的键相关联的组件。"
+/>
+
+<Interface
+  required
+  name="caseBy"
+  type="Partial<{ [P in StringifiedValue<Case>]: () => ReactElement | null }>"
+  description="将值映射到要渲染的组件的对象。键表示可能的值，值是返回相应组件的函数。"
+/>
+
+<Interface
+  name="defaultComponent"
+  type="() => ReactElement | null"
+  description="当 <code>value</code> 与 <code>caseBy</code> 中的任何键都不匹配时渲染的组件。"
+/>
+
+### 返回值
+
+<Interface
+  name=""
+  type="ReactElement | null"
+  description="根据不同情况条件性渲染的 React 组件。"
+/>
+
+## 示例
+
+```tsx
+function App() {
+  return (
+    <SwitchCase
+      value={status}
+      // 根据 status 的值渲染 TypeA、TypeB 或 TypeC。
+      caseBy={{
+        a: () => <TypeA />,
+        b: () => <TypeB />,
+        c: () => <TypeC />,
+      }}
+      // 当 status 的值与任何情况都不匹配时渲染 Default。
+      defaultComponent={() => <Default />}
+    />
+  );
+}
+```

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

@@ -0,0 +1,71 @@
+# 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',
+      description: '提供 Context 的组件。',
+    },
+    {
+      name: 'useContext',
+      type: '() => ContextValuesType',
+      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,27 @@
+# disableBodyScrollLock
+
+`disableBodyScrollLock` 是一个用于解锁 body 滚动的工具函数。它会恢复被 `enableBodyScrollLock` 锁定的滚动，并回到保存的滚动位置。在 SSR 环境中调用是安全的（在服务器上不会执行）。即使滚动未被锁定，调用它也是安全的。
+
+## 接口
+
+```ts
+function disableBodyScrollLock(): void;
+```
+
+### 参数
+
+此函数不接受任何参数。
+
+### 返回值
+
+<Interface name="" type="void" description="" />
+
+## 示例
+
+```tsx
+// 模态框打开时
+enableBodyScrollLock();
+
+// 模态框关闭时
+disableBodyScrollLock();
+```

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

@@ -0,0 +1,27 @@
+# enableBodyScrollLock
+
+`enableBodyScrollLock` 是一个锁定 body 滚动的工具函数。它通过应用固定定位来阻止 body 滚动。在打开模态框、抽屉或其他覆盖层组件时非常有用。可以安全地在 SSR 环境中调用（在服务器上不会生效）。多次调用也不会产生额外效果，直到解锁为止。
+
+## 接口
+
+```ts
+function enableBodyScrollLock(): void;
+```
+
+### 参数
+
+此函数不接受任何参数。
+
+### 返回值
+
+<Interface name="" type="void" description="" />
+
+## 示例
+
+```tsx
+// 模态框打开时
+enableBodyScrollLock();
+
+// 模态框关闭时
+disableBodyScrollLock();
+```

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

@@ -0,0 +1,31 @@
+# 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`;
+}
+```