1 | # @livelybone/react-popper
|
2 | [![NPM Version](http://img.shields.io/npm/v/@livelybone/react-popper.svg?style=flat-square)](https://www.npmjs.com/package/@livelybone/react-popper)
|
3 | [![Download Month](http://img.shields.io/npm/dm/@livelybone/react-popper.svg?style=flat-square)](https://www.npmjs.com/package/@livelybone/react-popper)
|
4 | ![gzip with dependencies: 14.4kb](https://img.shields.io/badge/gzip--with--dependencies-14.4kb-brightgreen.svg "gzip with dependencies: 14.4kb")
|
5 | ![typescript](https://img.shields.io/badge/typescript-supported-blue.svg "typescript")
|
6 | ![pkg.module](https://img.shields.io/badge/pkg.module-supported-blue.svg "pkg.module")
|
7 |
|
8 | > `pkg.module supported`, which means that you can apply tree-shaking in you project
|
9 |
|
10 | [中文文档](./README-CN.md)
|
11 |
|
12 | A wrap of [react-popper](http://npmjs.com/react-popper)
|
13 | 1. achieved visible controlling via click/hover event or ref.show/ref.hide/ref.toggle
|
14 | 2. achieved position controlling of arrow
|
15 |
|
16 | ## repository
|
17 | https://github.com/livelybone/react-popper.git
|
18 |
|
19 | ## Demo
|
20 | https://github.com/livelybone/react-popper#readme
|
21 |
|
22 | ## Run Example
|
23 | Your can see the usage by run the example of the module, here is the step:
|
24 |
|
25 | 1. Clone the library `git clone https://github.com/livelybone/react-popper.git`
|
26 | 2. Go to the directory `cd your-module-directory`
|
27 | 3. Install npm dependencies `npm i`(use taobao registry: `npm i --registry=http://registry.npm.taobao.org`)
|
28 | 4. Open service `npm run dev`
|
29 | 5. See the example(usually is `http://127.0.0.1/examples/test.html`) in your browser
|
30 |
|
31 | ## Installation
|
32 | ```bash
|
33 | npm i -S @livelybone/react-popper
|
34 | ```
|
35 |
|
36 | ## Global name
|
37 | `ReactPopper`
|
38 |
|
39 | ## Interface
|
40 | See in [index.d.ts](./index.d.ts)
|
41 |
|
42 | ## Usage
|
43 | ```typescript jsx
|
44 | import React from 'react'
|
45 | import ReactPopper, { PopperRefProps, ReactPopperProps, TriggerType } from '@livelybone/react-popper'
|
46 | import 'node_modules/@livelybone/react-popper/lib/css/index.scss'
|
47 |
|
48 | let popper = null
|
49 |
|
50 | /** The popper auto show or hide when click the reference element */
|
51 | const Comp = (
|
52 | <div className="reference">
|
53 | <ReactPopper
|
54 | className="custom-popper"
|
55 | forceShow={false}
|
56 | trigger={TriggerType.click}
|
57 | placement="bottom-start"
|
58 | positionFixed={true}
|
59 | referenceRef={undefined}
|
60 | modifiers={undefined}
|
61 | ref={p => popper = p}
|
62 | arrowPosition="middle"
|
63 | arrowOffset={15}
|
64 | >
|
65 | popper text
|
66 | </ReactPopper>
|
67 | </div>
|
68 | )
|
69 |
|
70 | /** Control it outside the component */
|
71 | // show
|
72 | // warning: Do not use `popper.setState({ visible: true })`, otherwise, a bug that the position of the popper do not update when needs to be updated will be cause
|
73 | popper.show()
|
74 |
|
75 | // hide
|
76 | popper.hide()
|
77 |
|
78 | // toggle
|
79 | popper.toggle()
|
80 | ```
|
81 |
|
82 | You can receive the popper props and the instance of the component in the children function
|
83 | ```typescript jsx
|
84 | import React from 'react'
|
85 | import ReactPopper, { PopperRefProps, ReactPopperProps, TriggerType } from '@livelybone/react-popper'
|
86 | import 'node_modules/@livelybone/react-popper/lib/css/index.scss'
|
87 |
|
88 | /** The popper auto show or hide when click the reference element */
|
89 | const Comp = (
|
90 | <div className="reference">
|
91 | <ReactPopper
|
92 | className="custom-popper"
|
93 | forceShow={false}
|
94 | trigger={TriggerType.click}
|
95 | placement="bottom-start"
|
96 | positionFixed={true}
|
97 | referenceRef={undefined}
|
98 | modifiers={undefined}
|
99 | arrowPosition="middle"
|
100 | arrowOffset={15}
|
101 | >
|
102 | {({popperRef, ...popperProps}) => {
|
103 | return <>
|
104 | popper text
|
105 | <button onClick={() => popperRef.hide()}>hide the popper</button>
|
106 | </>
|
107 | }}
|
108 | </ReactPopper>
|
109 | </div>
|
110 | )
|
111 | ```
|
112 |
|
113 | Use in html, see what your can use in [CDN: unpkg](https://unpkg.com/@livelybone/react-popper/lib/umd/)
|
114 | ```html
|
115 | <-- use what you want -->
|
116 | <script src="https://unpkg.com/@livelybone/react-popper/lib/umd/<--module-->.js"></script>
|
117 | ```
|
118 |
|
119 | ## Props
|
120 | ```typescript
|
121 | import { ReactNode, RefObject } from 'react'
|
122 | import { PopperProps } from 'react-popper'
|
123 |
|
124 | enum TriggerType {
|
125 | click = 0,
|
126 | hover = 1,
|
127 | }
|
128 |
|
129 | interface ReactPopperProps {
|
130 | /**
|
131 | * 强制显示 popper 组件
|
132 | *
|
133 | * Force to show the popper
|
134 | * */
|
135 | forceShow?: boolean
|
136 | /**
|
137 | * 关联 dom 元素用于控制 popper 是否显示的事件
|
138 | *
|
139 | * Determine what event of reference element will make the popper show or hide
|
140 | *
|
141 | * Default: TriggerType.click
|
142 | * */
|
143 | trigger?: TriggerType
|
144 | className?: string
|
145 | /**
|
146 | * Popper 的位置
|
147 | *
|
148 | * Placement of popper
|
149 | *
|
150 | * Default: 'bottom-start'
|
151 | * */
|
152 | placement?: PopperProps['placement']
|
153 | /**
|
154 | * 关联元素
|
155 | *
|
156 | * Reference element
|
157 | *
|
158 | * Default: The parent element of the component element
|
159 | * */
|
160 | referenceRef?: PopperProps['referenceElement']
|
161 | children?: ReactNode
|
162 | /**
|
163 | * Modifiers config of popperjs
|
164 | * See in https://popper.js.org/popper-documentation.html#Popper.Defaults.modifiers
|
165 | * */
|
166 | modifiers?: PopperProps['modifiers']
|
167 | /**
|
168 | * Default: true
|
169 | * */
|
170 | positionFixed?: PopperProps['positionFixed']
|
171 | /**
|
172 | * Arrow 箭头的问题
|
173 | *
|
174 | * Position of arrow
|
175 | *
|
176 | * Default: 'middle'
|
177 | * */
|
178 | arrowPosition?: 'start' | 'end' | 'middle'
|
179 | /**
|
180 | * Arrow 箭头的偏移量
|
181 | *
|
182 | * Position offset of arrow
|
183 | *
|
184 | * Default: 15
|
185 | * */
|
186 | arrowOffset?: number
|
187 | }
|
188 |
|
189 | interface PopperRefProps {
|
190 | show(): void
|
191 |
|
192 | hide(): void
|
193 |
|
194 | toggle(): void
|
195 | }
|
196 | ```
|
197 |
|
198 | ## style
|
199 | For building style, you can use the css or scss file in lib directory.
|
200 | ```js
|
201 | // scss
|
202 | import 'node_modules/@livelybone/react-popper/lib/css/index.scss'
|
203 |
|
204 | // css
|
205 | import 'node_modules/@livelybone/react-popper/lib/css/index.css'
|
206 | ```
|
207 | Or
|
208 | ```scss
|
209 | // scss
|
210 | @import 'node_modules/@livelybone/react-popper/lib/css/index.scss';
|
211 |
|
212 | // css
|
213 | @import 'node_modules/@livelybone/react-popper/lib/css/index.css';
|
214 | ```
|
215 |
|
216 | Or, you can build your custom style by copying and editing `index.scss`
|
217 |
|
218 | ## QA
|
219 |
|
220 | 1. Error `Error: spawn node-sass ENOENT`
|
221 |
|
222 | > You may need install node-sass globally, `npm i -g node-sass`
|