diff --git a/packages/react-simplikit/src/components/ImpressionArea/zh-Hans/ImpressionArea.md b/packages/react-simplikit/src/components/ImpressionArea/zh-Hans/ImpressionArea.md new file mode 100644 index 00000000..b53eaced --- /dev/null +++ b/packages/react-simplikit/src/components/ImpressionArea/zh-Hans/ImpressionArea.md @@ -0,0 +1,100 @@ +# ImpressionArea + +`ImpressionArea` 是一个组件,用于测量特定 DOM 元素在屏幕上的可见时间,并在元素进入或离开视口时执行回调。该组件使用 `useImpressionRef` 钩子来跟踪元素的可见性。 + +## Interface + +```ts +function ImpressionArea( + as: T = 'div', + rootMargin?: string, + areaThreshold?: number, + timeThreshold?: number, + onImpressionStart?: () => void, + onImpressionEnd?: () => void, + ref?: Ref>, + children?: React.ReactNode, + className?: string +): JSX.Element; +``` + +### Parameters + + + + + + + + + + + + + + + + + + + +### Return Value + + + +## Example + +```tsx +function App() { + return ( + console.log('Element entered view')} + onImpressionEnd={() => console.log('Element exited view')} + timeThreshold={1000} + areaThreshold={0.5} + > +
Track me!
+
+ ); +} +``` diff --git a/packages/react-simplikit/src/components/Separated/zh-Hans/Separated.md b/packages/react-simplikit/src/components/Separated/zh-Hans/Separated.md new file mode 100644 index 00000000..76f0d3b5 --- /dev/null +++ b/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; +``` + +### 参数 + + + + + +### 返回值 + + + +## 示例 + +```tsx +function App() { + return ( + }> + {['hello', 'react', 'world'].map(item => ( +
{item}
+ ))} +
+ ); + // 预期输出: + //
hello
+ // + //
react
+ // + //
world
+} +``` diff --git a/packages/react-simplikit/src/components/SwitchCase/zh-Hans/SwitchCase.md b/packages/react-simplikit/src/components/SwitchCase/zh-Hans/SwitchCase.md new file mode 100644 index 00000000..49b02601 --- /dev/null +++ b/packages/react-simplikit/src/components/SwitchCase/zh-Hans/SwitchCase.md @@ -0,0 +1,63 @@ +# SwitchCase + +`SwitchCase` 是一个可以根据给定值以声明式方式渲染组件的组件。它类似于 `switch-case` 语句。当需要根据特定状态条件性地渲染不同组件时非常有用。 + +## 接口 + +```ts +function SwitchCase( + value: Case, + caseBy: Partial<{ [P in StringifiedValue]: () => ReactElement | null }>, + defaultComponent?: () => ReactElement | null +): ReactElement | null; +``` + +### 参数 + + + + + + + +### 返回值 + + + +## 示例 + +```tsx +function App() { + return ( + , + b: () => , + c: () => , + }} + // 当 status 的值与任何情况都不匹配时渲染 Default。 + defaultComponent={() => } + /> + ); +} +``` diff --git a/packages/react-simplikit/src/utils/buildContext/zh-Hans/buildContext.md b/packages/react-simplikit/src/utils/buildContext/zh-Hans/buildContext.md new file mode 100644 index 00000000..60d2dd7f --- /dev/null +++ b/packages/react-simplikit/src/utils/buildContext/zh-Hans/buildContext.md @@ -0,0 +1,71 @@ +# buildContext + +`buildContext` 是一个辅助函数,用于在定义 React Context 时减少重复代码。 + +## 接口 + +```ts +function buildContext( + contextName: string, + defaultContextValues?: ContextValuesType +): [ + Provider: (props: ProviderProps) => JSX.Element, + useContext: () => ContextValuesType, +]; +``` + +### 参数 + + + + + +### 返回值 + + + +## 示例 + +```tsx +const [Provider, useContext] = buildContext<{ title: string }>('TestContext', { + title: 'Default title', +}); + +function Inner() { + const { title } = useContext(); + return
{title}
; +} + +function Page() { + return ( + + + + ); +} +``` diff --git a/packages/react-simplikit/src/utils/disableBodyScrollLock/zh-Hans/disableBodyScrollLock.md b/packages/react-simplikit/src/utils/disableBodyScrollLock/zh-Hans/disableBodyScrollLock.md new file mode 100644 index 00000000..96204218 --- /dev/null +++ b/packages/react-simplikit/src/utils/disableBodyScrollLock/zh-Hans/disableBodyScrollLock.md @@ -0,0 +1,27 @@ +# disableBodyScrollLock + +`disableBodyScrollLock` 是一个用于解锁 body 滚动的工具函数。它会恢复被 `enableBodyScrollLock` 锁定的滚动,并回到保存的滚动位置。在 SSR 环境中调用是安全的(在服务器上不会执行)。即使滚动未被锁定,调用它也是安全的。 + +## 接口 + +```ts +function disableBodyScrollLock(): void; +``` + +### 参数 + +此函数不接受任何参数。 + +### 返回值 + + + +## 示例 + +```tsx +// 模态框打开时 +enableBodyScrollLock(); + +// 模态框关闭时 +disableBodyScrollLock(); +``` diff --git a/packages/react-simplikit/src/utils/enableBodyScrollLock/zh-Hans/enableBodyScrollLock.md b/packages/react-simplikit/src/utils/enableBodyScrollLock/zh-Hans/enableBodyScrollLock.md new file mode 100644 index 00000000..d041c9dc --- /dev/null +++ b/packages/react-simplikit/src/utils/enableBodyScrollLock/zh-Hans/enableBodyScrollLock.md @@ -0,0 +1,27 @@ +# enableBodyScrollLock + +`enableBodyScrollLock` 是一个锁定 body 滚动的工具函数。它通过应用固定定位来阻止 body 滚动。在打开模态框、抽屉或其他覆盖层组件时非常有用。可以安全地在 SSR 环境中调用(在服务器上不会生效)。多次调用也不会产生额外效果,直到解锁为止。 + +## 接口 + +```ts +function enableBodyScrollLock(): void; +``` + +### 参数 + +此函数不接受任何参数。 + +### 返回值 + + + +## 示例 + +```tsx +// 模态框打开时 +enableBodyScrollLock(); + +// 模态框关闭时 +disableBodyScrollLock(); +``` diff --git a/packages/react-simplikit/src/utils/getKeyboardHeight/zh-Hans/getKeyboardHeight.md b/packages/react-simplikit/src/utils/getKeyboardHeight/zh-Hans/getKeyboardHeight.md new file mode 100644 index 00000000..bfee55e2 --- /dev/null +++ b/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; +``` + +### 参数 + +该函数不接受任何参数。 + +### 返回值 + + + +## 示例 + +```tsx +const height = getKeyboardHeight(); + +if (height > 0) { + footer.style.paddingBottom = `${height}px`; +} +``` diff --git a/packages/react-simplikit/src/utils/getSafeAreaInset/zh-Hans/getSafeAreaInset.md b/packages/react-simplikit/src/utils/getSafeAreaInset/zh-Hans/getSafeAreaInset.md new file mode 100644 index 00000000..d2470156 --- /dev/null +++ b/packages/react-simplikit/src/utils/getSafeAreaInset/zh-Hans/getSafeAreaInset.md @@ -0,0 +1,70 @@ +# getSafeAreaInset + +`getSafeAreaInset` 是一个实用函数,以对象形式返回所有安全区域内边距(单位为像素)。 + +该函数通过创建一个临时 DOM 元素并读取其计算样式,来获取 CSS `env(safe-area-inset-*)` 的值。 + +安全区域内边距用于处理设备特有的 UI 元素: + +- **top**:刘海屏、灵动岛或状态栏 +- **bottom**:Face ID 设备上的主屏幕指示条 +- **left/right**:横屏模式下的圆角 + +典型值(支持 Face ID 的 iPhone,竖屏模式): + +- top:47-59px(刘海屏/灵动岛) +- bottom:34px(主屏幕指示条) +- left/right:0px + +## Interface + +```ts +function getSafeAreaInset(): SafeAreaInset; +``` + +### Parameters + +该函数不接受任何参数。 + +### Return Value + + + +## Example + +```tsx +const { top, bottom, left, right } = getSafeAreaInset(); + +header.style.paddingTop = `${top}px`; +footer.style.paddingBottom = `${bottom}px`; +``` diff --git a/packages/react-simplikit/src/utils/isAndroid/zh-Hans/isAndroid.md b/packages/react-simplikit/src/utils/isAndroid/zh-Hans/isAndroid.md new file mode 100644 index 00000000..c09ee85e --- /dev/null +++ b/packages/react-simplikit/src/utils/isAndroid/zh-Hans/isAndroid.md @@ -0,0 +1,45 @@ +# isAndroid + +`isAndroid` 是一个用于检测当前设备是否在 Android 上运行的实用函数。 + +**注意事项** + +- 所有 Android 浏览器的用户代理中都包含 'Android' 标记。 + +## 接口 + +```ts +function isAndroid(userAgent?: string): boolean; +``` + +### 参数 + + + +### 返回值 + + + +## 示例 + +```tsx +if (isAndroid()) { + // 仅适用于 Android 的代码 + enableAndroidOptimizations(); +} +``` + +```tsx +// 直接传入用户代理的情况 +const isAndroidDevice = isAndroid( + 'Mozilla/5.0 (Linux; Android 12; Pixel 6) Chrome/120' +); +``` diff --git a/packages/react-simplikit/src/utils/isIOS/zh-Hans/isIOS.md b/packages/react-simplikit/src/utils/isIOS/zh-Hans/isIOS.md new file mode 100644 index 00000000..d23d6421 --- /dev/null +++ b/packages/react-simplikit/src/utils/isIOS/zh-Hans/isIOS.md @@ -0,0 +1,44 @@ +# isIOS + +`isIOS` 是一个用于检测当前设备是否运行 iOS 或 iPadOS 的工具函数。不同平台之间存在以下差异。 + +- 在 iPadOS 13 之前,iPad 会将平台报告为 'iPad'(或在 UA 中匹配 /iPad/)。 +- 从 iPadOS 13 开始,Apple 为了让网站将 iPadOS 视为桌面级 Safari,将平台字符串改为了 'MacIntel'。但这些设备仍然暴露多点触控功能。 + +## 接口 + +```ts +function isIOS(userAgent?: string): boolean; +``` + +### 参数 + + + +### 返回值 + + + +## 示例 + +```tsx +if (isIOS()) { + // 仅适用于 iOS 的代码 + enableIOSOptimizations(); +} +``` + +```tsx +// 直接传入用户代理的情况 +const isIOSDevice = isIOS( + 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)' +); +``` diff --git a/packages/react-simplikit/src/utils/isKeyboardVisible/zh-Hans/isKeyboardVisible.md b/packages/react-simplikit/src/utils/isKeyboardVisible/zh-Hans/isKeyboardVisible.md new file mode 100644 index 00000000..8b826f3b --- /dev/null +++ b/packages/react-simplikit/src/utils/isKeyboardVisible/zh-Hans/isKeyboardVisible.md @@ -0,0 +1,36 @@ +# isKeyboardVisible + +`isKeyboardVisible` 是用于检查当前屏幕键盘是否显示的工具函数。该函数内部使用 `getKeyboardHeight()`,当键盘高度大于 0 时返回 `true`。 + +## 接口 + +```ts +function isKeyboardVisible(): boolean; +``` + +### 参数 + +该函数不接受任何参数。 + +### 返回值 + + + +## 示例 + +```tsx +if (isKeyboardVisible()) { + console.log('键盘已打开'); +} else { + console.log('键盘已关闭'); +} +``` + +```tsx +// 根据键盘是否显示来显示或隐藏元素 +const showFloatingButton = !isKeyboardVisible(); +``` diff --git a/packages/react-simplikit/src/utils/isServer/zh-Hans/isServer.md b/packages/react-simplikit/src/utils/isServer/zh-Hans/isServer.md new file mode 100644 index 00000000..744929a9 --- /dev/null +++ b/packages/react-simplikit/src/utils/isServer/zh-Hans/isServer.md @@ -0,0 +1,32 @@ +# isServer + +`isServer` 是一个用于检查代码是否在服务器上运行的工具函数。在 `window` 未定义的 SSR(服务器端渲染)环境中,它返回 `true`;在客户端环境中,它返回 `false`。 + +## 接口 + +```ts +function isServer(): boolean; +``` + +### 参数 + +此函数不接受任何参数。 + +### 返回值 + + + +## 示例 + +```tsx +if (isServer()) { + // SSR 安全的代码 + return null; +} + +// 仅在客户端运行的代码 +window.addEventListener('resize', handleResize); +``` diff --git a/packages/react-simplikit/src/utils/mergeProps/zh-Hans/mergeProps.md b/packages/react-simplikit/src/utils/mergeProps/zh-Hans/mergeProps.md new file mode 100644 index 00000000..6a687aa7 --- /dev/null +++ b/packages/react-simplikit/src/utils/mergeProps/zh-Hans/mergeProps.md @@ -0,0 +1,38 @@ +# mergeProps + +`mergeProps` 是将多个 props 对象合并为一个对象的工具函数。它会处理 `className`、`style` 以及 `function` 属性的合并。 + +## 接口 + +```ts +function mergeProps( + ...props: PropsList +): TupleToIntersection; +``` + +### 参数 + + + +### 返回值 + + + +## 示例 + +```tsx +const mergedProps = mergeProps( + { className: 'foo', style: { color: 'red' } }, + { className: 'bar', style: { backgroundColor: 'blue' } } +); +console.log(mergedProps); // { className: 'foo bar', style: { color: 'red', backgroundColor: 'blue' } } +``` diff --git a/packages/react-simplikit/src/utils/mergeRefs/zh-Hans/mergeRefs.md b/packages/react-simplikit/src/utils/mergeRefs/zh-Hans/mergeRefs.md new file mode 100644 index 00000000..c1a5ffc6 --- /dev/null +++ b/packages/react-simplikit/src/utils/mergeRefs/zh-Hans/mergeRefs.md @@ -0,0 +1,55 @@ +# mergeRefs + +此函数接收多个 refs(RefObject 或 RefCallback),并返回一个更新所有提供 refs 的单一 ref。当需要向单个元素传递多个 refs 时非常有用。如果回调 ref 返回清理函数(React 19),合并后的 ref 也会返回清理函数,并在分离时执行所有清理函数。 + +## 接口 + +```ts +function mergeRefs( + ...refs: Array | RefCallback | null | undefined> +): RefCallback; +``` + +### 参数 + + + +### 返回值 + + + +## 示例 + +```tsx +forwardRef(function Component(props, parentRef) { + const myRef = useRef(null); + + return
; +}); +``` + +```tsx +function Component(props) { + const ref = useRef(null); + const [height, setHeight] = useState(0); + + const measuredRef = useCallback(node => { + if (node == null) { + return; + } + + setHeight(node.offsetHeight); + }, []); + + return
; +} +``` diff --git a/packages/react-simplikit/src/utils/subscribeKeyboardHeight/zh-Hans/subscribeKeyboardHeight.md b/packages/react-simplikit/src/utils/subscribeKeyboardHeight/zh-Hans/subscribeKeyboardHeight.md new file mode 100644 index 00000000..32481c68 --- /dev/null +++ b/packages/react-simplikit/src/utils/subscribeKeyboardHeight/zh-Hans/subscribeKeyboardHeight.md @@ -0,0 +1,80 @@ +# subscribeKeyboardHeight + +`subscribeKeyboardHeight` 是一个用于订阅屏幕键盘高度变化的工具函数。提供的回调函数会在键盘高度每次发生变化时被调用,包括键盘出现、消失或尺寸改变等情况。在内部,该函数会同时监听 Visual Viewport 的 `resize` 和 `scroll` 事件。 + +- `resize`:视觉视口高度变化时触发 +- `scroll`:视觉视口偏移量变化时触发(在 iOS 上视口可以在不调整大小的情况下移动,因此这一点很重要) + +**性能优化** + +- 默认进行节流(16ms,约 60fps),以防止过多的回调调用 +- 高度未发生变化时跳过回调 + +## 接口 + +```ts +function subscribeKeyboardHeight( + options: SubscribeKeyboardHeightOptions +): SubscribeKeyboardHeightResult; +``` + +### 参数 + + + +### 返回值 + + + +## 示例 + +```tsx +const { unsubscribe } = subscribeKeyboardHeight({ + callback: height => { + footer.style.paddingBottom = `${height}px`; + }, + immediate: true, +}); + +// 之后需要清理时 +unsubscribe(); +```