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 | ![typescript](https://img.shields.io/badge/typescript-supported-blue.svg "typescript")
|
5 | ![pkg.module](https://img.shields.io/badge/pkg.module-supported-blue.svg "pkg.module")
|
6 |
|
7 | > `pkg.module supported`, which means that you can apply tree-shaking in you project
|
8 |
|
9 | [English Document](./README.md)
|
10 |
|
11 | 对 [react-popper](http://npmjs.com/react-popper) 的再封装
|
12 | 1. 实现自动显示隐藏(通过 click/hover 事件),在组件外部可以通过 ref.show/ref.hide/ref.toggle 手动隐藏显示
|
13 | 2. 实现 arrow 位置控制
|
14 |
|
15 | ## repository
|
16 | https://github.com/livelybone/react-popper.git
|
17 |
|
18 | ## Demo
|
19 | https://github.com/livelybone/react-popper#readme
|
20 |
|
21 | ## Run Example
|
22 | 你可以通过运行项目的 example 来了解这个组件的使用,以下是启动步骤:
|
23 |
|
24 | 1. 克隆项目到本地 `git clone https://github.com/livelybone/form.git`
|
25 | 2. 进入本地克隆目录 `cd your-module-directory`
|
26 | 3. 安装项目依赖 `npm i`(使用 taobao 源: `npm i --registry=http://registry.npm.taobao.org`)
|
27 | 4. 启动服务 `npm run dev`
|
28 | 5. 在你的浏览器看 example (地址通常是 `http://127.0.0.1:3000/examples/test.html`)
|
29 |
|
30 | ## Installation
|
31 | ```bash
|
32 | npm i -S @livelybone/react-popper
|
33 | ```
|
34 |
|
35 | ## Global name
|
36 | `ReactPopper`
|
37 |
|
38 | ## Interface
|
39 | 去 [index.d.ts](./index.d.ts) 查看可用方法和参数
|
40 |
|
41 | ## Usage
|
42 | ```typescript jsx
|
43 | import React from 'react'
|
44 | import ReactPopper, { PopperRefProps, ReactPopperProps, TriggerType } from '@livelybone/react-popper'
|
45 | import 'node_modules/@livelybone/react-popper/lib/css/index.scss'
|
46 |
|
47 | let popper = null
|
48 |
|
49 | /** The popper auto show or hide when click the reference element */
|
50 | const Comp = (
|
51 | <div className="reference">
|
52 | <ReactPopper
|
53 | className="custom-popper"
|
54 | forceShow={false}
|
55 | trigger={TriggerType.click}
|
56 | placement="bottom-start"
|
57 | positionFixed={true}
|
58 | referenceRef={undefined}
|
59 | modifiers={undefined}
|
60 | ref={p => popper = p}
|
61 | arrowPosition="middle"
|
62 | arrowOffset={15}
|
63 | >
|
64 | popper text
|
65 | </ReactPopper>
|
66 | </div>
|
67 | )
|
68 |
|
69 | /** Control it outside the component */
|
70 | // show
|
71 | // 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
|
72 | popper.show()
|
73 |
|
74 | // hide
|
75 | popper.hide()
|
76 |
|
77 | // toggle
|
78 | popper.toggle()
|
79 | ```
|
80 |
|
81 | You can receive the popper props and the instance of the component in the children function
|
82 | ```typescript jsx
|
83 | import React from 'react'
|
84 | import ReactPopper, { PopperRefProps, ReactPopperProps, TriggerType } from '@livelybone/react-popper'
|
85 | import 'node_modules/@livelybone/react-popper/lib/css/index.scss'
|
86 |
|
87 | /** The popper auto show or hide when click the reference element */
|
88 | const Comp = (
|
89 | <div className="reference">
|
90 | <ReactPopper
|
91 | className="custom-popper"
|
92 | forceShow={false}
|
93 | trigger={TriggerType.click}
|
94 | placement="bottom-start"
|
95 | positionFixed={true}
|
96 | referenceRef={undefined}
|
97 | modifiers={undefined}
|
98 | arrowPosition="middle"
|
99 | arrowOffset={15}
|
100 | >
|
101 | {({popperRef, ...popperProps}) => {
|
102 | return <>
|
103 | popper text
|
104 | <button onClick={() => popperRef.hide()}>hide the popper</button>
|
105 | </>
|
106 | }}
|
107 | </ReactPopper>
|
108 | </div>
|
109 | )
|
110 | ```
|
111 |
|
112 | Use in html, see what your can use in [CDN: unpkg](https://unpkg.com/@livelybone/react-popper/lib/umd/)
|
113 | ```html
|
114 | <-- use what you want -->
|
115 | <script src="https://unpkg.com/@livelybone/react-popper/lib/umd/<--module-->.js"></script>
|
116 | ```
|
117 |
|
118 | ## Props
|
119 | ```typescript
|
120 | import { ReactNode, RefObject } from 'react'
|
121 | import { PopperProps } from 'react-popper'
|
122 |
|
123 | enum TriggerType {
|
124 | click = 0,
|
125 | hover = 1,
|
126 | }
|
127 |
|
128 | interface ReactPopperProps {
|
129 | /**
|
130 | * 强制显示 popper 组件
|
131 | *
|
132 | * Force to show the popper
|
133 | * */
|
134 | forceShow?: boolean
|
135 | /**
|
136 | * 关联 dom 元素用于控制 popper 是否显示的事件
|
137 | *
|
138 | * Determine what event of reference element will make the popper show or hide
|
139 | *
|
140 | * Default: TriggerType.click
|
141 | * */
|
142 | trigger?: TriggerType
|
143 | className?: string
|
144 | /**
|
145 | * Popper 的位置
|
146 | *
|
147 | * Placement of popper
|
148 | *
|
149 | * Default: 'bottom-start'
|
150 | * */
|
151 | placement?: PopperProps['placement']
|
152 | /**
|
153 | * 关联元素
|
154 | *
|
155 | * Reference element
|
156 | *
|
157 | * Default: The parent element of the component element
|
158 | * */
|
159 | referenceRef?: PopperProps['referenceElement']
|
160 | children?: ReactNode
|
161 | /**
|
162 | * Modifiers config of popperjs
|
163 | * See in https://popper.js.org/popper-documentation.html#Popper.Defaults.modifiers
|
164 | * */
|
165 | modifiers?: PopperProps['modifiers']
|
166 | /**
|
167 | * Default: true
|
168 | * */
|
169 | positionFixed?: PopperProps['positionFixed']
|
170 | /**
|
171 | * Arrow 箭头的问题
|
172 | *
|
173 | * Position of arrow
|
174 | *
|
175 | * Default: 'middle'
|
176 | * */
|
177 | arrowPosition?: 'start' | 'end' | 'middle'
|
178 | /**
|
179 | * Arrow 箭头的偏移量
|
180 | *
|
181 | * Position offset of arrow
|
182 | *
|
183 | * Default: 15
|
184 | * */
|
185 | arrowOffset?: number
|
186 | }
|
187 |
|
188 | interface PopperRefProps {
|
189 | show(): void
|
190 |
|
191 | hide(): void
|
192 |
|
193 | toggle(): void
|
194 | }
|
195 | ```
|
196 |
|
197 | ## style
|
198 | 你可能需要主动引入样式文件来应用组件的样式:
|
199 | ```js
|
200 | // scss
|
201 | import 'node_modules/@auraxy/react-select/lib/css/index.scss'
|
202 |
|
203 | // css
|
204 | import 'node_modules/@auraxy/react-select/lib/css/index.css'
|
205 | ```
|
206 | Or
|
207 | ```scss
|
208 | // scss
|
209 | @import 'node_modules/@auraxy/react-select/lib/css/index.scss';
|
210 |
|
211 | // css
|
212 | @import 'node_modules/@auraxy/react-select/lib/css/index.css';
|
213 | ```
|
214 |
|
215 | 你也可以通过引入自定义的组件样式文件来自定义样式,文件可以通过复制并修改 `node_modules/@auraxy/react-select/lib/css/index.scss` 得到
|
216 |
|
217 | ## QA
|
218 |
|
219 | 1. Error `Error: spawn node-sass ENOENT`
|
220 |
|
221 | > 你可能需要全局安装 node-sass,`npm i -g node-sass`
|