@ ariakit/反应- utils
重要内容: 这个软件包是Ariakit的内部依赖性,不遵循语义化的版本,意思是断裂变化可能发生在补丁和小版本中. 你也许想用 @ariakit/react 换句话说.
Ariakit React包使用的共享反应工具.
目录
安装
npm i @ariakit/react-utils
使用量
从包根导入助手 :
import { useEvent } from "@ariakit/react-utils";
这一一揽子方案只采用无害环境管理,并暴露出单一的公众切入点.
API 参考
钩子
反应钩用于 refs,事件,ids,效果,和元素元数据.
useSafeLayoutEffect
const useSafeLayoutEffect: typeof React.useLayoutEffect;
React.useLayoutEffect 倒计时 React.useEffect 在服务器侧.
useInitialValue
function useInitialValue<T>(value: T | (() => T)): T;
返回一个即使参数更新也不会改变的值.
示例
function Component({ prop }) {
const initialProp = useInitialValue(prop);
}
useLiveRef
function useLiveRef<T>(value: T): RefObject<T>;
创建一个 React.RefObject 以新值不断更新.
示例
function Component({ prop }) {
const propRef = useLiveRef(prop);
}
useEvent
function useEvent<T extends AnyFunction>(callback?: T): T;
创建一个稳定的回调函数,可以访问最新的状态,可以在事件处理器和效果回调中使用. 在渲染相中使用时会抛出.
示例
function Component(props) {
const onClick = useEvent(props.onClick);
React.useEffect(() => {}, [onClick]);
}
useTransactionState
function useTransactionState<T>(
callback?: ((state: SetStateAction<T | null>) => void) | null,
): readonly [T | null, React.Dispatch<SetStateAction<T | null>>];
创建反应状态,当状态在清理时更改并滚回上一个状态时,该状态会调用回调函数.
useMergeRefs
function useMergeRefs(
...refs: Array<Ref<any> | undefined>
): ((value: unknown) => (() => void) | undefined) | undefined;
将 React Refs 合并为单一的记忆函数 ref 这样您就可以把它传递给一个元素.
示例
const Component = React.forwardRef((props, ref) => {
const internalRef = React.useRef();
return <div {...props} ref={useMergeRefs(internalRef, ref)} />;
});
useId
function useId(defaultId?: string): string | undefined;
生成一个独特的ID. 使用React的用法,如果可用的话.
useDeferredValue
function useDeferredValue<T>(value: T): T;
使用React's used DeferredValue(如果有的话).
useTagName
function useTagName(
refOrElement?: RefObject<HTMLElement | null> | HTMLElement | null,
type?: string | ComponentType,
): string | undefined;
通过解析元素 ref来返回标记名称 .
示例
function Component(props) {
const ref = React.useRef();
const tagName = useTagName(ref, "button"); // div
return <div ref={ref} {...props} />;
}
useAttribute
function useAttribute(
refOrElement: RefObject<HTMLElement | null> | HTMLElement | null,
attributeName: string,
defaultValue?: string,
): string | undefined;
返回元素的属性值.
示例
function Component(props) {
const ref = React.useRef();
const role = useAttribute(ref, "role", props.role);
return <div ref={ref} {...props} />;
}
useUpdateEffect
function useUpdateEffect(effect: EffectCallback, deps?: DependencyList): void;
A 类 React.useEffect 它不会运行 在第一个渲染.
useUpdateLayoutEffect
function useUpdateLayoutEffect(
effect: EffectCallback,
deps?: DependencyList,
): void;
A 类 React.useLayoutEffect 它不会运行 在第一个渲染.
useForceUpdate
function useForceUpdate(): [never[], React.ActionDispatch<[]>];
类似 useState 财务报告和审定财务报表 useReducer,但唯一目的是重置组件.
useBooleanEvent
function useBooleanEvent<T extends unknown[]>(
booleanOrCallback: boolean | ((...args: T) => boolean),
): (...args: T) => boolean;
返回类似事件召回 useEvent,但它也接受布尔值,该值将变成函数.
useWrapElement
function useWrapElement<P>(
props: P & { wrapElement?: WrapElement },
callback: WrapElement,
deps: DependencyList = [],
): P & { wrapElement: WrapElement };
带额外道具返回 wrapElement 道具 (英语).
usePortalRef
function usePortalRef(
portalProp = false,
portalRefProp?:
| RefCallback<HTMLElement>
| MutableRefObject<HTMLElement | null>,
): {
portalRef: ((value: unknown) => (() => void) | undefined) | undefined;
portalNode: HTMLElement | null;
domReady: true | HTMLElement | null;
};
合并门户参考道具并返回 a domReady 用于下面使用Portal的组件.
useMetadataProps
function useMetadataProps<T, K extends keyof any>(
props: { onLoadedMetadataCapture?: AnyFunction & { [key in K]?: T } },
key: K,
value: T,
): readonly [
(AnyFunction & { [key in K]?: T | undefined })[K] | undefined,
{ readonly onLoadedMetadataCapture: any },
];
一个传递元数据道具的钩子,而不把它们泄露给DOM.
useIsMouseMoving
function useIsMouseMoving(): () => boolean;
返回检查鼠标是否移动的函数 .
一般公用事业
提供参考、元素和道具的帮助.
setRef
function setRef<T>(
ref: RefCallback<T> | MutableRefObject<T> | null | undefined,
value: T,
): void | (() => void);
设置函数和对象React ref.
提供回调参考清理功能时返回.
isValidElementWithRef
function isValidElementWithRef<P extends { ref?: Ref<any> }>(
element: unknown,
): element is ReactElement<P> & { ref?: Ref<any> };
检查元素是否为具有可读性的有效反应元素 .
getRefProperty
function getRefProperty(element: unknown): Ref<any> | undefined;
从 React 元素获取 ref 属性 .
mergeProps
function mergeProps<T extends HTMLAttributes<any>>(base: T, overrides: T): T;
将两套道具合并.
系统公用事业
用于创建和组合 Ariakit React 组件的助手.
forwardRef
function forwardRef<T extends React.FC<any>>(render: T): T;
一样 React.forwardRef 但通过 ref 作为道具并返回具有同一种通用类型的组件.
手势控取 undefined 被丢弃,所以传出者的行为与省略相同,组件保留它自己计算的值.
memo
function memo<T extends React.FC<any>>(
Component: T,
propsAreEqual?: (
prevProps: Readonly<React.ComponentPropsWithoutRef<T>>,
nextProps: Readonly<React.ComponentPropsWithoutRef<T>>,
) => boolean,
): T;
一样 React.memo 但返回具有相同通用类型的组件.
createElement
function createElement(
Type: React.ElementType,
props: Props<React.ElementType, Options>,
): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
创建支持 render 财务报告和审定财务报表 wrapElement 道具来.
createHook
function createHook<
T extends React.ElementType,
P extends AnyObject = EmptyObject,
>(useProps: (props: Props<T, P>) => HTMLProps<T, P>): Hook<T, P>;
创建一个接受道具并返回道具的组件钩子,这样它们就可以被传递到反应元素.
createStoreContext
type StoreProvider<T extends Store> = React.ComponentType<{
value: T | undefined;
children?: React.ReactNode;
}>;
function createStoreContext<T extends Store>(
providers: StoreProvider<T>[] = [],
scopedProviders: StoreProvider<T>[] = [],
): {
context: React.Context<T | undefined>;
scopedContext: React.Context<T | undefined>;
useContext: () => T | undefined;
useScopedContext: (onlyScoped?: boolean) => T | undefined;
useProviderContext: () => T | undefined;
ContextProvider: (
props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
) => React.JSX.Element;
ScopedContextProvider: (
props: React.ComponentPropsWithoutRef<React.Provider<T | undefined>>,
) => React.JSX.Element;
};
创建有钩和提供者组件的 Ariakit 商店上下文 .
公用事业类型
Ariakit React 组件的共享类型 .
RenderProp
type RenderProp<P = React.HTMLAttributes<any> & { ref?: React.Ref<any> }> = (
props: P,
) => React.ReactNode;
彩色道具类型.
示例
const children: RenderProp = (props) => <div {...props} />;
WrapElement
type WrapElement = (element: React.ReactElement) => React.ReactElement;
这个 wrapElement 道具 (英语).
Options
interface Options {
wrapElement?: WrapElement;
/**
* Allows the component to be rendered as a different HTML element or React
* component. The value can be a React element or a function that takes in the
* original component props and gives back a React element with the props
* merged.
*
* Some Ariakit components detect the type of the underlying element when they
* mount. If the render element's type may change while the component is
* mounted, pass a
* [`key`](https://react.dev/learn/preserving-and-resetting-state) prop that
* changes with the element type so React remounts the component with the new
* element. Remounting resets uncontrolled state, so keep the relevant state
// ... 11 more lines
* for more details.
*/
render?: RenderProp | React.ReactElement;
}
自定义道具,包括 render 道具 (英语).
HTMLProps
type HTMLProps<
T extends React.ElementType,
P extends AnyObject = EmptyObject,
> = Omit<React.ComponentPropsWithRef<T>, keyof P> & {
[index: `data-${string}`]: unknown;
};
基于元素类型的HTML道具,不包括自定义道具.
示例
type ButtonHTMLProps = HTMLProps<"button", { custom?: boolean }>;
Props
type Props<T extends React.ElementType, P extends AnyObject = EmptyObject> = P &
HTMLProps<T, P>;
基于元素类型的道具,包括自定义道具.
Hook
type Hook<T extends React.ElementType, P extends AnyObject = EmptyObject> = <
ElementType extends React.ElementType = T,
>(
props?: Props<ElementType, P>,
) => HTMLProps<ElementType, P>;
支持 render 道具并返回基于元素类型的HTML道具.
示例
type UseButton = Hook<"button", { custom?: boolean }>;