Jelajahi Sumber

Docs: Reviewed and improved documentation of the BalloonPanelView class.

Aleksander Nowodzinski 8 tahun lalu
induk
melakukan
3787ceffdc
1 mengubah file dengan 87 tambahan dan 16 penghapusan
  1. 87 16
      packages/ckeditor5-ui/src/panel/balloon/balloonpanelview.js

+ 87 - 16
packages/ckeditor5-ui/src/panel/balloon/balloonpanelview.js

@@ -21,6 +21,40 @@ const defaultLimiterElement = global.document.body;
 /**
  * The balloon panel view class.
  *
+ * A floating container which can
+ * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#pin pin} to any
+ * {@link module:utils/dom/position~Options#target target} in DOM and remain in that position
+ * e.g. when the web page is scrolled.
+ *
+ * The balloon panel can be used to display contextual, non-blocking UI like forms, toolbars and
+ * the like in its {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView#content} view
+ * collection.
+ *
+ * There is a number of {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}
+ * that the balloon can use, automatically switching from one to another when the viewport space becomes
+ * scarce to keep the balloon visible to the user as long as it is possible. The balloon will also
+ * accept any custom position set provided by the user compatible with the
+ * {@link module:utils/dom/position~Options options}.
+ *
+ *		const panel = new BalloonPanelView( locale );
+ *		const childView = new ChildView();
+ *		const positions = BalloonPanelView.defaultPositions;
+ *
+ *		panel.init();
+ *
+ *		// Add a child view to the panel's content collection.
+ *		panel.content.add( childView );
+ *
+ *		// Start pinning the panel to an element with the "target" id DOM.
+ *		// The balloon will remain pinned until unpin() is called.
+ *		panel.pin( {
+ *			target: document.querySelector( '#target' ),
+ *			positions: [
+ *				positions.northArrowSouth,
+ *				positions.southArrowNorth
+ *			]
+ *		} );
+ *
  * @extends module:ui/view~View
  */
 export default class BalloonPanelView extends View {
@@ -54,14 +88,12 @@ export default class BalloonPanelView extends View {
 		 * Balloon panel's current position. The position name is reflected in the CSS class set
 		 * to the balloon, i.e. `.ck-balloon-panel_arrow_nw` for "arrow_nw" position. The class
 		 * controls the minor aspects of the balloon's visual appearance like placement
-		 * of the "arrow". To support a new position, an additional CSS must be created.
+		 * of an {@link #withArrow arrow}. To support a new position, an additional CSS must be created.
 		 *
 		 * Default position names correspond with
 		 * {@link module:ui/panel/balloon/balloonpanelview~BalloonPanelView.defaultPositions}.
 		 *
-		 * See {@link #attachTo} to learn about custom balloon positions.
-		 *
-		 * See {@link #withArrow}.
+		 * See the {@link #attachTo} and {@link #pin} methods to learn about custom balloon positions.
 		 *
 		 * @observable
 		 * @default 'arrow_nw'
@@ -89,7 +121,7 @@ export default class BalloonPanelView extends View {
 		this.set( 'withArrow', true );
 
 		/**
-		 * Additional css class added to the {#element}.
+		 * An additional CSS class added to the {@link #element}.
 		 *
 		 * @observable
 		 * @member {String} #className
@@ -134,7 +166,7 @@ export default class BalloonPanelView extends View {
 	}
 
 	/**
-	 * Shows the balloon panel.
+	 * Shows the panel.
 	 *
 	 * See {@link #isVisible}.
 	 */
@@ -143,7 +175,7 @@ export default class BalloonPanelView extends View {
 	}
 
 	/**
-	 * Hides the balloon panel.
+	 * Hides the panel.
 	 *
 	 * See {@link #isVisible}.
 	 */
@@ -152,11 +184,31 @@ export default class BalloonPanelView extends View {
 	}
 
 	/**
-	 * Attaches the balloon panel to a specified DOM element or range with a smart heuristics.
+	 * Attaches the panel to a specified {@link module:utils/dom/position~Options#target} with a
+	 * smart positioning heuristics that choses from available positions to make sure the panel
+	 * is visible to the user i.e. within the limits of the viewport.
+	 *
+	 * This method accepts configuration {@link module:utils/dom/position~Options options}
+	 * to set the `target`, optional `limiter` and `positions` the balloon should chose from.
+	 *
+	 *		const panel = new BalloonPanelView( locale );
+	 *		const positions = BalloonPanelView.defaultPositions;
+	 *
+	 *		panel.init();
+	 *
+	 *		// Attach the panel to an element with the "target" id DOM.
+	 *		panel.attachTo( {
+	 *			target: document.querySelector( '#target' ),
+	 *			positions: [
+	 *				positions.northArrowSouth,
+	 *				positions.southArrowNorth
+	 *			]
+	 *		} );
 	 *
-	 * See {@link @link module:utils/dom/position~getOptimalPosition}.
+	 * **Note**: Attaching the panel will also automatically {@link #show} it.
 	 *
-	 * TODO: More docs and examples.
+	 * **Note**: An attached panel will not follow its target when the window is scrolled or resized.
+	 * See the {@link #pin} method for more permanent positioning strategy.
 	 *
 	 * @param {module:utils/dom/position~Options} options Positioning options compatible with
 	 * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is
@@ -184,14 +236,33 @@ export default class BalloonPanelView extends View {
 	}
 
 	/**
-	 * Works the same way as {module:ui/panel/balloon/balloonpanelview~BalloonPanelView.attachTo}
-	 * except that the position of the panel is continuously updated when any ancestor of the
-	 * {@link module:utils/dom/position~Options#target} or {@link module:utils/dom/position~Options#limiter}
-	 * is being scrolled or when the browser window is being resized.
+	 * Works the same way as the {@link #attachTo} method except that the position of the panel is
+	 * continuously updated when:
+	 *
+	 * * any ancestor of the {@link module:utils/dom/position~Options#target}
+	 * or {@link module:utils/dom/position~Options#limiter} is scrolled,
+	 * * the browser window gets resized or scrolled.
+	 *
+	 * Thanks to that, the panel always sticks to the {@link module:utils/dom/position~Options#target},
+	 * immune to the changing environment.
+	 *
+	 *		const panel = new BalloonPanelView( locale );
+	 *		const positions = BalloonPanelView.defaultPositions;
+	 *
+	 *		panel.init();
+	 *
+	 *		// Pin the panel to an element with the "target" id DOM.
+	 *		panel.pin( {
+	 *			target: document.querySelector( '#target' ),
+	 *			positions: [
+	 *				positions.northArrowSouth,
+	 *				positions.southArrowNorth
+	 *			]
+	 *		} );
 	 *
-	 * Thanks to this, the panel always sticks to the {@link module:utils/dom/position~Options#target}.
+	 * To leave the pinned state, use the {@link #unpin} method.
 	 *
-	 * See: {@link #unpin}.
+	 * **Note**: Pinning the panel will also automatically {@link #show} it.
 	 *
 	 * @param {module:utils/dom/position~Options} options Positioning options compatible with
 	 * {@link module:utils/dom/position~getOptimalPosition}. Default `positions` array is