@accessible/popover 中文文档教程
<Popover>
npm i @accessible/popover
一个可访问的、“包含电池”的 React 弹出组件。
Features
- Several placement options You can render the popover anywhere! Top, top-left, bottom, center, inside, outside, literally anywhere!
- Containment policies The popover is configured to contain itself inside the window using a containment policy. It's also optional, so you can turn it off.
- Auto-repositioning Use the props
repositionOnScrollorrepositionOnResizeto reposition the popover automatically when the scroll position or size of the window changes. - Style-agnostic You can use this component with the styling library of your choice. It
works with CSS-in-JS, SASS, plain CSS, plain
styleobjects, anything! - Portal-friendly The popover will render into React portals of your choice when configured to do so.
- a11y/aria-compliant This component works with screen readers out of the box and manages focus for you.
Quick Start
```jsx 和谐 import {Popover, Target, Trigger}
从 '@accessible/popover' const Component = () => (
Hello world
<Trigger on="hover">
<a href="/profile/me">
<img src="avatar.jpg" />
</a>
</Trigger>
)
## API
### Components
| Component | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`<Popover>`](#popover) | This component creates the context for your popover target and trigger and contains some configuration options. |
| [`<Target>`](#target) | This component wraps any React element and turns it into a popover target. |
| [`<Trigger>`](#trigger) | This component wraps any React element and turns it into a popover trigger. |
| [`<Close>`](#close) | This is a convenience component that wraps any React element and adds an onClick handler to close the popover. | |
### Hooks
| Hook | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`usePopover()`](#usepopover) | This hook provides the value of the popover's [PopoverContextValue object](#popovercontextvalue). |
| [`useControls()`](#usecontrols) | This hook provides access to the popover's `open`, `close`, `toggle`, and `reposition` functions. |
| [`usePlacement()`](#useplacement) | This hook provides access to the popover's rendered placement. |
| [`useIsOpen()`](#useisopen) | This hook provides access to the popover's `isOpen` value. |
### `<Popover>`
This component creates the context for your popover target and trigger and contains some
configuration options.
#### Props
| Prop | Type | Default | Required? | Description |
| ------------------ | --------------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultOpen | `boolean` | `false` | No | This sets the default open state of the popover. By default the popover is closed. |
| open | `boolean` | `undefined` | No | You can control the open/closed state of the popover with this prop. When it isn't undefined, this value will take precedence over any calls to `open()`, `close()`, or `toggle()`. |
| onChange | `(isOpen: boolean) => void` | `undefined` | No | This callback will be invoked each time the open state changes. |
| repositionOnResize | `boolean` | `false` | No | Setting this to `true` will update the position of the popover when the window's dimensions change and the popover is currently open. |
| repositionOnScroll | `boolean` | `false` | No | Setting this to `true` will update the position of the popover when the window's scroll position changes and the popover is currently open. |
| containPolicy | [`ContainPolicy`](#containpolicy) | `"flip"` | No | This tells the popover what to do when it overflows outside the dimensions of the window. By default it will flip its position on both the `x` and `y` axis to attempt to remain within the bounds of the window. See [`ContainPolicy`](#containpolicy) for more options. |
| id | `string` | `undefined` | No | By default this component creates a unique id for you, as it is required for certain aria attributes. Supplying an id here overrides the auto id feature. |
#### `ContainPolicy`
| Policy | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `"flip"` | This will attempt to flip its position on both the `x` and `y` axis to attempt to remain within the bounds of the window. |
| `"flipX"` | This will attempt to flip its position on only the `x` axis to attempt to remain within the bounds of the window. |
| `"flipY"` | This will attempt to flip its position on only the `y` axis to attempt to remain within the bounds of the window. |
| `function` | You can decide what to do with the popover on your own by providing a callback with the signature <code>(placement: string, triggerRect: ClientRect, popoverRect: ClientRect) => Placement | PlacementResult</code> where [`Placement`](#placement) is a string returning an alternative placement and `PlacementResult` is an object shaped `{placement: Placement, style: CSSProperties}` |
### `<Target>`
This component wraps any React element and turns it into a popover target.
#### Props
| Prop | Type | Default | Required? | Description |
| ------------- | ----------------------------------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| placement | [`Placement`](#placement) | `"bottom"` | No | This tells the target where it should render relative to its triggering element. |
| portal | <code>boolean | string </code> | `false` | No | When `true` this will render the popover into a React portal with the id `#portals`. You can render it into any portal by providing its query selector here, e.g. `#foobar`, `[data-portal=true]`, or `.foobar`. |
| closeOnEscape | `boolean` | `true` | No | By default the popover will close when the `Escape` key is pressed. You can turn this off by providing `false` here. |
| closedClass | `string` | `undefined` | No | This class name will be applied to the child element when the popover is `closed`. |
| openClass | `string` | `"popover--open"` | No | This class name will be applied to the child element when the popover is `open`. |
| closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the popover is `closed` in addition to the default styles that set the target's visibility. |
| openStyle | `React.CSSProperties` | `undefined` | No | These styles name will be applied to the child element when the popover is `open` in addition to the default styles that set the target's visibility. |
| children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
#### Placement
These are the default placements allowed by the popover relative to its triggering element
| Placement | Description |
| ---------------- | ------------------------------------------------ |
| top |  |
| topLeft |  |
| topRight |  |
| right |  |
| rightTop |  |
| rightBottom |  |
| bottom |  |
| bottomLeft |  |
| bottomRight |  |
| left |  |
| leftTop |  |
| leftBottom |  |
| innerTop |  |
| innerTopLeft |  |
| innerTopRight |  |
| innerRight |  |
| innerBottom |  |
| innerBottomLeft |  |
| innerBottomRight |  |
| innerLeft |  |
| center |  |
#### Example
jsx和谐 <目标位置="innerTopLeft">
Menu
//
### `<Trigger>`
This component wraps any React element and turns it into a popover trigger.
#### Props
| Prop | Type | Default | Required? | Description |
| ----------- | --------------------------------------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| on | <code>"hover" | "click" | "focus" </code> | `undefined` | Yes | `"hover"` causes the popover to open on `mouseenter` and close on `mouseleave`. `"click"` causes the popover to toggle its visibility each `click` event. `"focus"` causes the popover to open when the child element is focused while nothing happens on blur. |
| closedClass | `string` | `undefined` | No | This class name will be applied to the child element when the popover is `closed`. |
| openClass | `string` | `undefined` | No | This class name will be applied to the child element when the popover is `open`. |
| closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the popover is `closed`. |
| openStyle | `React.CSSProperties` | `undefined` | No | These styles name will be applied to the child element when the popover is `open`. |
| children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
#### Example
jsx和谐 <触发=“点击”>
//
### `<Close>`
This is a convenience component that wraps any React element and adds an onClick handler to close the popover.
#### Props
| Prop | Type | Default | Required? | Description |
| -------- | -------------------- | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| children | `React.ReactElement` | `undefined` | Yes | The child is cloned by this component and has aria attributes injected into its props as well as the events defined above. |
jsx和谐 <关闭>
//
### `usePopover()`
This hook provides the value of the popover's [PopoverContextValue object](#popovercontextvalue)
#### Example
jsx和谐 const 组件 = () => { const {open, close, toggle, isOpen} = usePopover() return }
### `PopoverContextValue`
打字稿
接口 PopoverContextValue {
// true 当弹出窗口打开且可见时
// false 关闭时
isOpen：布尔值
// 打开弹出框
打开：（）=> 空白
// 关闭弹出框
关闭：（）=> 空白
// 在打开/关闭状态之间切换弹出框
切换：（）=>； 空白
// 调用它会强制弹出窗口重新定位
// 自己到指定位置
重新定位：（nextPlacement：放置）=> 空白
// 弹窗目标的ID
编号：字符串
// 应用于弹出框目标的样式
样式：React.CSSProperties
// 弹出框的渲染位置
放置：放置
// 设置 popover 目标的 ref
targetRef: React.MutableRefObjecttriggeredBy 变量
setTriggeredBy：（触发器：字符串）=> 空白
}
### `usePlacement()`
This hook provides access to the popover's rendered placement
#### Example
jsx和谐 const 组件 = () => { const 放置 = usePlacement() 返回 （ <目标展示位置="顶部">
arrow--${placement}} />
)
}
### `useControls()`
This hook provides access to the popover's `open`, `close`, `toggle`, and `reposition` functions
#### Example
jsx和谐 const 组件 = () => { const {打开、关闭、切换} = useControls() 返回 （ <目标>
### `useIsOpen()`
This hook provides access to the popover's `isOpen` value
#### Example
jsx和谐 const 组件 = () => { 常量 isOpen = useIsOpen() 返回 （ <目标>
Am I open? {isOpen ? 'Yes' : 'No'}
)
}
```
LICENSE
麻省理工学院
更多
