@accessible/disclosure 中文文档教程
<Disclosure>
npm i @accessible/disclosure
的可访问且通用的披露
Features
- [x] Style-agnostic You can use this component with the styling library of your choice. It
works with CSS-in-JS, SASS, plain CSS, plain
style
objects, anything! - [x] Portal-friendly The disclosure target will render into React portals of your choice when configured to do so.
- [x] a11y/aria-compliant This component works with screen readers out of the box and manages focus for you.
Quick Start
用于React
组件jsx和谐 从“反应”导入*作为反应 import * as Disclosure from '@accessible/disclosure'
const Component = () => ( <披露.披露> <披露.触发>
<Disclosure.Target>
<div className='my-disclosure'>
<Disclosure.CloseButton>
<button>Close me</button>
</Disclosure.CloseButton>
<div>I've been disclosed!</div>
</div>
</Disclosure.Target>
)
## API
### Components
| Component | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [`<Disclosure>`](#disclosure) | This component creates the context for your disclosure target and trigger and contains some configuration options. |
| [`<Target>`](#target) | This component wraps any React element and turns it into a disclosure target. |
| [`<Trigger>`](#trigger) | This component wraps any React element and turns it into a disclosure trigger. |
| [`<CloseButton>`](#closebutton) | This is a convenience component that wraps any React element and adds an onClick handler to close the disclosure. | |
### Hooks
| Hook | Description |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`useDisclosure()`](#usedisclosure) | This hook provides the value of the disclosure's [DisclosureContextValue object](#disclosurecontextvalue). |
| [`useA11yTarget()`](#usea11ytargettarget-options) | A React hook for creating a headless disclosure target to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html). |
| [`useA11yTrigger()`](#usea11ytriggertarget-options) | A React hook for creating a headless disclosure trigger to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html). |
| [`useA11yCloseButton()`](#usea11yclosebuttontarget-options) | A React hook for creating a headless close button to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html). |
### <Disclosure>
This component creates the context for your disclosure 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 disclosure. By default the disclosure is closed. |
| open | `boolean` | `undefined` | No | This creates a controlled disclosure component where the open state of the disclosure is controlled by this property. |
| onChange | `(open: boolean) => void` | `undefined` | No | This callback is invoked any time the `open` state of the disclosure changes. |
| 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. |
| children | `React.ReactNode` | `undefined` | No | Your disclosure contents and any other children. |
### useA11yTarget(target, options?)
A React hook for creating a headless disclosure target to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html).
#### Arguments
| Argument | Type | Required? | Description |
| -------- | -------------------------------------------------- | --------- | --------------------------- |
| target | <code>React.RefObject<T> \| T \| null</code> | Yes | A React ref or HTML element |
| options | [`UseA11yTargetOptions`](#usea11ytargetoptions) | No | Configuration options |
#### UseA11yTargetOptions
TS 导出接口 UseA11yTargetOptions { /**
- Adds this class name to props when the disclosure is open / openClass?: string /*
- Adds this class name to props when the disclosure is closed / closedClass?: string /*
- Adds this style to props when the disclosure is open / openStyle?: React.CSSProperties /*
- Adds this style to props when the disclosure is closed / closedStyle?: React.CSSProperties /*
- Prevents the
window
from scrolling when the target is - focused after opening. / preventScroll?: boolean /*
- When
true
, this closes the target element when theEscape
- key is pressed.
- @default true */ closeOnEscape?: boolean }
#### Returns
TS 接口 A11yProps { 只读'aria-hidden':布尔值 只读 ID:字符串 | 不明确的 只读类名:字符串 | 不明确的 只读风格:{ 能见度:“可见” | '隐' } & React.CSS 属性 }
#### Example
jsx 和谐 从“反应”导入*作为反应 导入 {useA11yTarget}
从 '@accessible/disclosure' const MyTarget = () => { const ref = React.useRef(null) const a11yProps = useA11yTarget(ref, {preventScroll: true})
返回 (
### <Target>
This component wraps any React element and turns it into a disclosure target.
#### Props
| Prop | Type | Default | Required? | Description |
| ------------- | ------------------------------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| portal | <code>boolean \| string \| PortalizeProps </code> | `false` | No | When `true` this will render the disclosure 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 disclosure 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 disclosure is `closed`. |
| openClass | `string` | `undefined` | No | This class name will be applied to the child element when the disclosure is `open`. |
| closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the disclosure 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 disclosure is `open` in addition to the default styles that set the target's visibility. |
| preventScroll | `boolean` | `false` | No | When `true` this will prevent your browser from scrolling the document to bring the newly-focused tab into view. |
| 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和谐 <目标>
//
### useA11yTrigger(target, options?)
A React hook for creating a headless disclosure trigger to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html).
In addition to providing accessibility props to your component, this hook will add events
for interoperability between actual <button> elements and fake ones e.g. <a> and <div> to the
target element
#### Arguments
| Argument | Type | Required? | Description |
| -------- | -------------------------------------------------- | --------- | --------------------------- |
| target | <code>React.RefObject<T> \| T \| null</code> | Yes | A React ref or HTML element |
| options | [`UseA11yTriggerOptions`](#usea11ytriggeroptions) | No | Configuration options |
#### UseA11yTriggerOptions
TS 导出接口 UseA11yTriggerOptions { /**
- Adds this class name to props when the disclosure is open / openClass?: string /*
- Adds this class name to props when the disclosure is closed / closedClass?: string /*
- Adds this style to props when the disclosure is open / openStyle?: React.CSSProperties /*
- Adds this style to props when the disclosure is closed / closedStyle?: React.CSSProperties /*
- Adds an onClick handler in addition to the default one that
- toggles the disclosure's open state. */ onClick?: (e: MouseEvent) => any }
#### Returns
TS 接口 A11yProps { 只读'aria-controls':字符串| 不明确的 只读'aria-expanded':布尔值 只读角色:“按钮” 只读标签索引:0 只读类名:字符串 | 不明确的 只读样式:React.CSSProperties | 不明确的 }
#### Example
jsx 和谐 从“反应”导入*作为反应 导入 {useA11yTrigger}
从 '@accessible/disclosure' const MyTrigger = () => { const ref = React.useRef(null) const a11yProps = useA11yTrigger(ref, { openClass: '打开', closedClass: '关闭', })
返回 (
### <Trigger>
This component wraps any React element and adds an `onClick` handler which toggles the open state
of the disclosure target.
#### Props
| Prop | Type | Default | Required? | Description |
| ----------- | --------------------- | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| closedClass | `string` | `undefined` | No | This class name will be applied to the child element when the disclosure is `closed`. |
| openClass | `string` | `undefined` | No | This class name will be applied to the child element when the disclosure is `open`. |
| closedStyle | `React.CSSProperties` | `undefined` | No | These styles will be applied to the child element when the disclosure is `closed`. |
| openStyle | `React.CSSProperties` | `undefined` | No | These styles name will be applied to the child element when the disclosure 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. |
jsx 和谐 <触发=“点击”>
//
### useA11yCloseButton(target, options?)
A React hook for creating a headless close button to [WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-faq.html).
In addition to providing accessibility props to your component, this hook will add events
for interoperability between actual <button> elements and fake ones e.g. <a> and <div> to the
target element
#### Arguments
| Argument | Type | Required? | Description |
| -------- | --------------------------------------------------------- | --------- | --------------------------- |
| target | <code>React.RefObject<T> \| T \| null</code> | Yes | A React ref or HTML element |
| options | [`UseA11yCloseButtonOptions`](#usea11yclosebuttonoptions) | No | Configuration options |
#### UseA11yCloseButtonOptions
TS 导出接口 UseA11yCloseButtonOptions { /**
- Adds an onClick handler in addition to the default one that
- closes the disclosure. */ onClick?: (e: MouseEvent) => any }
#### Returns
TS 接口 A11yProps { 只读'aria-controls':字符串| 不明确的 只读'aria-expanded':布尔值 只读'aria-label':'关闭' 只读角色:“按钮” 只读标签索引:0 }
#### Example
jsx 和谐 从“反应”导入*作为反应 导入 {useA11yCloseButton}
从 '@accessible/disclosure' const MyTrigger = () => { const ref = React.useRef(null) const a11yProps = useA11yCloseButton(ref, { onClick: () =>; console.log('关闭!'), })
返回 (
### <CloseButton>
This is a convenience component that wraps any React element and adds an onClick handler which closes the disclosure.
#### 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 和谐 <关闭按钮>
//
### useDisclosure()
This hook provides the value of the disclosure's [DisclosureContextValue object](#disclosurecontextvalue)
### DisclosureContextValue
打字稿 导出接口 DisclosureContextValue { /**
- The open state of the disclosure / isOpen: boolean /*
- Opens the disclosure / open: () => void /*
- Closes the disclosure / close: () => void /*
- Toggles the open state of the disclosure / toggle: () => void /*
- A unique ID for the disclosure target */ id?: string }
#### Example
jsx和谐 const 组件 = () => { const {open, close, toggle, isOpen} = useDisclosure() return } ```
LICENSE
麻省理工学院