Module java.desktop
Package javax.swing

Class JScrollPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JScrollPane
所有已实现的接口:
ImageObserver, MenuContainer, Serializable, Accessible, ScrollPaneConstants
@JavaBean(defaultProperty="UI", description="A specialized container that manages a viewport, optional scrollbars and headers") public class JScrollPane extends JComponent implements ScrollPaneConstants, Accessible
提供轻量级组件的可滚动视图。 JScrollPane 管理一个视口，可选的垂直和水平滚动条，以及可选的行和列标题视口。您可以在如何使用滚动窗格中找到 JScrollPane 的面向任务的文档，这是 The Java Tutorial 中的一个部分。请注意，JScrollPane 不支持重量级组件。

示例:

以下文本描述此图像。

JViewport 提供了一个窗口，或者说是数据源的“视口”--例如，一个文本文件。该数据源是由 JViewport 视图显示的可滚动客户端（也称为数据模型）。一个 JScrollPane 基本上由 JScrollBar、一个 JViewport 和它们之间的连接组成，如右侧的图表所示。

除了滚动条和视口，JScrollPane 还可以有一个列标题和一个行标题。每个都是您使用 setRowHeaderView 和 setColumnHeaderView 指定的 JViewport 对象。列标题视口会自动左右滚动，跟踪主视口的左右滚动（但不会垂直滚动）。行标题以类似的方式工作。

当两个滚动条相遇时，行标题与列标题相遇，或者滚动条与其中一个标题相遇时，这两个组件都会停在角落的边缘，留下一个默认情况下为空的矩形空间。这些空间可能存在于四个角中的任意数量。在上图中，右上角的空间存在，并由标签“角组件”标识。

通过使用 setCorner 方法，任意数量的这些空白空间可以被替换为将组件添加到特定角落。 （注意：同一组件不能添加到多个角落。）如果您想要向滚动窗格添加一些额外的装饰或功能，这将非常有用。每个角落组件的大小完全由围绕它的标题和/或滚动条的大小确定。

只有在该角落存在空白空间时，角落组件才会可见。例如，考虑将组件设置到具有列标题的滚动窗格的右上角。如果滚动窗格的垂直滚动条不存在，可能是因为视图组件还没有增长到需要它的大小，那么角落组件将不会显示（因为该角落由标题和垂直滚动条相遇而创建的空白空间不存在）。通过始终显示滚动条，使用 setVerticalScrollBarPolicy(VERTICAL_SCROLLBAR_ALWAYS)，将确保角落组件的空间始终存在。

要在主视口周围添加边框，您可以使用 setViewportBorder。（当然，您也可以使用 setBorder 在整个滚动窗格周围添加边框。）

通常希望执行的一个操作是设置当主视口视图小于视口或不透明时将使用的背景颜色。这可以通过设置视口的背景颜色，通过 scrollPane.getViewport().setBackground() 来实现。之所以设置视口的颜色而不是滚动窗格的颜色，是因为默认情况下 JViewport 是不透明的，这意味着它将完全使用其背景颜色填充其背景。因此，当 JScrollPane 绘制其背景时，视口通常会覆盖它。

默认情况下，JScrollPane 使用 ScrollPaneLayout 来处理其子组件的布局。 ScrollPaneLayout 决定如何调整视口视图的大小，有两种方式：

  1. 如果视图实现了 Scrollable，则使用 getPreferredScrollableViewportSize、getScrollableTracksViewportWidth 和 getScrollableTracksViewportHeight 的组合，否则
  2. 使用 getPreferredSize。

警告: Swing 不是线程安全的。有关更多信息，请参阅 Swing 的线程策略。

警告: 该类的序列化对象将不兼容未来的 Swing 版本。当前的序列化支持适用于短期存储或在运行相同版本的 Swing 应用程序之间进行 RMI。从 1.4 版开始，已将所有 JavaBeans 的长期存储支持添加到 java.beans 包中。请参阅 XMLEncoder。

自 JDK 1.2 起:
1.2
参见:

  • Field Details

  • Constructor Details

    • JScrollPane

      public JScrollPane(Component view, int vsbPolicy, int hsbPolicy)
      创建一个JScrollPane，在视口中显示视图组件，其视图位置可以通过一对滚动条控制。滚动条策略指定何时显示滚动条，例如，如果vsbPolicy为VERTICAL_SCROLLBAR_AS_NEEDED，则仅当视图在垂直方向上不适合时才会出现垂直滚动条。可用的策略设置在setVerticalScrollBarPolicy(int)和setHorizontalScrollBarPolicy(int)中列出。
      参数：
      view - 要在滚动窗格视口中显示的组件
      vsbPolicy - 指定垂直滚动条策略的整数
      hsbPolicy - 指定水平滚动条策略的整数
      参见：

    • JScrollPane

      public JScrollPane(Component view)
      创建一个JScrollPane，显示指定组件的内容，当组件的内容大于视图时，水平和垂直滚动条都会出现。
      参数：
      view - 要在滚动窗格视口中显示的组件
      参见：

    • JScrollPane

      public JScrollPane(int vsbPolicy, int hsbPolicy)
      创建一个空的（没有视口视图）JScrollPane，具有指定的滚动条策略。可用的策略设置在setVerticalScrollBarPolicy(int)和setHorizontalScrollBarPolicy(int)中列出。
      参数：
      vsbPolicy - 指定垂直滚动条策略的整数
      hsbPolicy - 指定水平滚动条策略的整数
      参见：

    • JScrollPane

      public JScrollPane()
      创建一个空的（没有视口视图）JScrollPane，当需要时会同时出现水平和垂直滚动条。

  • Method Details

    • getUI

      @BeanProperty(hidden=true, visualUpdate=true, description="The UI object that implements the Component\'s LookAndFeel.") public ScrollPaneUI getUI()
      返回渲染此组件的外观和感觉（L&F）对象。
      覆盖：
      getUI 在类 JComponent中
      返回：
      渲染此组件的ScrollPaneUI对象
      参见：

    • setUI

      public void setUI(ScrollPaneUI ui)
      设置提供此组件外观和感觉（L&F）的ScrollPaneUI对象。
      参数：
      ui - ScrollPaneUI L&F对象
      参见：

    • updateUI

      public void updateUI()
      用当前默认外观更换当前ScrollPaneUI对象的版本。在默认外观更改时调用。
      覆盖：
      updateUI 在类 JComponent中
      参见：

    • getUIClassID

      @BeanProperty(bound=false, hidden=true) public String getUIClassID()
      返回用于构造用于渲染此组件的L&F类名称的后缀。
      覆盖：
      getUIClassID 在类 JComponent中
      返回：
      字符串"ScrollPaneUI"
      参见：

    • setLayout

      public void setLayout(LayoutManager layout)
      为此JScrollPane设置布局管理器。此方法覆盖了java.awt.Container中的setLayout，以确保只能在JScrollPane中使用ScrollPaneLayout的子类作为布局管理器。如果layout非空，则会在其上调用syncWithScrollPane。
      覆盖：
      setLayout 在类 Container中
      参数：
      layout - 指定的布局管理器
      抛出：
      ClassCastException - 如果布局不是ScrollPaneLayout
      参见：

    • isValidateRoot

      @BeanProperty(hidden=true) public boolean isValidateRoot()
      被覆盖以返回true，以便对此JScrollPane的任何后代调用revalidate将导致从此JScrollPane开始的整个树被验证。
      覆盖:
      isValidateRoot 在类 JComponent中
      返回:
      true
      参见:

    • getVerticalScrollBarPolicy

      public int getVerticalScrollBarPolicy()
      返回垂直滚动条策略值。
      返回:
      verticalScrollBarPolicy 属性
      参见:

    • setVerticalScrollBarPolicy

      @BeanProperty(preferred=true, enumerationValues={"ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED","ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER","ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS"}, description="The scrollpane vertical scrollbar policy") public void setVerticalScrollBarPolicy(int policy)
      确定滚动窗格中何时出现垂直滚动条。合法值为：
      • ScrollPaneConstants.VERTICAL_SCROLLBAR_AS_NEEDED
      • ScrollPaneConstants.VERTICAL_SCROLLBAR_NEVER
      • ScrollPaneConstants.VERTICAL_SCROLLBAR_ALWAYS
      参数:
      policy - 上述三个值之一
      抛出:
      IllegalArgumentException - 如果 policy 不是上述合法值之一
      参见:

    • getHorizontalScrollBarPolicy

      public int getHorizontalScrollBarPolicy()
      返回水平滚动条策略值。
      返回:
      horizontalScrollBarPolicy 属性
      参见:

    • setHorizontalScrollBarPolicy

      @BeanProperty(preferred=true, enumerationValues={"ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED","ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER","ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS"}, description="The scrollpane scrollbar policy") public void setHorizontalScrollBarPolicy(int policy)
      确定滚动窗格中何时出现水平滚动条。选项为：
      • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_AS_NEEDED
      • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_NEVER
      • ScrollPaneConstants.HORIZONTAL_SCROLLBAR_ALWAYS
      参数:
      policy - 上述三个值之一
      抛出:
      IllegalArgumentException - 如果 policy 不是上述合法值之一
      参见:

    • getViewportBorder

      public Border getViewportBorder()
      返回围绕视口的 Border 对象。
      返回:
      viewportBorder 属性
      参见:

    • setViewportBorder

      @BeanProperty(preferred=true, description="The border around the viewport.") public void setViewportBorder(Border viewportBorder)
      在视口周围添加边框。请注意，边框不直接设置在视口上，JViewport 不支持 JComponent 边框属性。同样，设置 JScrollPane 的视口不会影响 viewportBorder 属性。

      此属性的默认值由外观实现计算。

      参数:
      viewportBorder - 要添加的边框
      参见:

    • getViewportBorderBounds

      @BeanProperty(bound=false) public Rectangle getViewportBorderBounds()
      返回视口边框的边界。
      返回:
      指定视口边框的 Rectangle 对象

    • createHorizontalScrollBar

      public JScrollBar createHorizontalScrollBar()
      默认情况下返回一个 JScrollPane.ScrollBar。子类可以重写此方法，强制 ScrollPaneUI 实现使用 JScrollBar 子类。用于由 ScrollPaneUI 实现创建水平滚动条。
      返回:
      具有水平方向的 JScrollBar
      参见:

    • getHorizontalScrollBar

      public JScrollBar getHorizontalScrollBar()
      返回控制视口水平视图位置的水平滚动条。
      返回:
      horizontalScrollBar 属性
      参见:

    • setHorizontalScrollBar

      @BeanProperty(expert=true, description="The horizontal scrollbar.") public void setHorizontalScrollBar(JScrollBar horizontalScrollBar)
      将控制视口水平视图位置的滚动条添加到滚动窗格。通常情况下不需要此操作，因为 JScrollPane 默认创建水平和垂直滚动条。
      参数:
      horizontalScrollBar - 要添加的水平滚动条
      参见:

    • createVerticalScrollBar

      public JScrollBar createVerticalScrollBar()
      默认情况下返回一个 JScrollPane.ScrollBar。子类可以重写此方法，强制 ScrollPaneUI 实现使用 JScrollBar 子类。用于由 ScrollPaneUI 实现创建垂直滚动条。
      返回:
      具有垂直方向的 JScrollBar
      参见:

    • getVerticalScrollBar

      public JScrollBar getVerticalScrollBar()
      返回控制视口垂直视图位置的垂直滚动条。
      返回:
      verticalScrollBar 属性
      参见:

    • setVerticalScrollBar

      @BeanProperty(expert=true, description="The vertical scrollbar.") public void setVerticalScrollBar(JScrollBar verticalScrollBar)
      将控制视口垂直视图位置的滚动条添加到滚动窗格。通常情况下不需要此操作，因为 JScrollPane 默认创建垂直和水平滚动条。
      参数:
      verticalScrollBar - 要添加的新垂直滚动条
      参见:

    • createViewport

      protected JViewport createViewport()
      默认情况下返回一个新的 JViewport。用于在 setViewportView、setRowHeaderView 和 setColumnHeaderView 中创建（如有必要的话）视口。子类可以重写此方法以返回 JViewport 的子类。
      返回:
      一个新的 JViewport

    • getViewport

      public JViewport getViewport()
      返回当前的 JViewport。
      返回:
      viewport 属性
      参见:

    • setViewport

      @BeanProperty(expert=true, visualUpdate=true, description="The viewport child for this scrollpane") public void setViewport(JViewport viewport)
      移除旧的视口（如果存在）；强制新视口的 viewPosition 位于 +x,+y 象限；将行和列头（如果有）与新视口同步；最后将滚动条和头部与新视口同步。

      大多数应用程序会发现使用 setViewportView 更方便，以添加视口和视图到滚动窗格。

      参数:
      viewport - 要使用的新视口；如果视口为 null，仍会移除旧视口，并将新视口设置为 null
      参见:

    • setViewportView

      public void setViewportView(Component view)
      如有必要创建视口，然后设置其视图。不直接将视图提供给 JScrollPane 构造函数的应用程序应使用此方法指定要在滚动窗格中显示的可滚动子项。例如： 
       JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
      应用程序不应直接向滚动窗格添加子项。
      参数:
      view - 要添加到视口的组件
      参见:

    • getRowHeader

      public JViewport getRowHeader()
      返回行头。
      返回:
      rowHeader 属性
      参见:

    • setRowHeader

      @BeanProperty(expert=true, description="The row header child for this scrollpane") public void setRowHeader(JViewport rowHeader)
      移除旧的行头（如果存在）；如果新行头不为 null，将其 viewPosition 的 y 坐标与视口（如果有）同步，然后将其添加到滚动窗格中。

      大多数应用程序会发现使用 setRowHeaderView 更方便，以添加行头组件及其视口到滚动窗格。

      参数:
      rowHeader - 要使用的新行头；如果 null，仍会移除旧行头，并将新行头设置为 null
      参见:

    • setRowHeaderView

      public void setRowHeaderView(Component view)
      创建必要的行标题视口，设置其视图，然后将行标题视口添加到滚动窗格中。例如： 
       JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
 scrollpane.setRowHeaderView(myBigComponentsRowHeader);
      参数:
      view - 要显示为行标题的组件
      参见:

    • getColumnHeader

      public JViewport getColumnHeader()
      返回列标题。
      返回:
      columnHeader 属性
      参见:

    • setColumnHeader

      @BeanProperty(visualUpdate=true, description="The column header child for this scrollpane") public void setColumnHeader(JViewport columnHeader)
      移除旧的列标题（如果存在）；如果新的列标题不为null，则将其视图位置的x坐标与视口（如果存在）同步，然后将其添加到滚动窗格中。

      大多数应用程序会发现使用setColumnHeaderView更方便，以将列标题组件及其视口添加到滚动窗格中。

      参数:
      columnHeader - 新的列标题是一个JViewport
      参见:

    • setColumnHeaderView

      public void setColumnHeaderView(Component view)
      如果需要，创建列标题视口，设置其视图，然后将列标题视口添加到滚动窗格中。例如： 
       JScrollPane scrollpane = new JScrollPane();
 scrollpane.setViewportView(myBigComponentToScroll);
 scrollpane.setColumnHeaderView(myBigComponentsColumnHeader);
      参数:
      view - 要显示为列标题的组件
      参见:

    • getCorner

      public Component getCorner(String key)
      返回指定角落的组件。指定角落的key值可以是以下之一：
      • ScrollPaneConstants.LOWER_LEFT_CORNER
      • ScrollPaneConstants.LOWER_RIGHT_CORNER
      • ScrollPaneConstants.UPPER_LEFT_CORNER
      • ScrollPaneConstants.UPPER_RIGHT_CORNER
      • ScrollPaneConstants.LOWER_LEADING_CORNER
      • ScrollPaneConstants.LOWER_TRAILING_CORNER
      • ScrollPaneConstants.UPPER_LEADING_CORNER
      • ScrollPaneConstants.UPPER_TRAILING_CORNER
      参数:
      key - 如上所示的值之一
      返回:
      由给定键标识的角落组件（可能为null），如果键无效则返回null
      参见:

    • setCorner

      public void setCorner(String key, Component corner)
      添加一个子组件，将出现在滚动窗格的一个角落中（如果有空间）。例如，当两个滚动条都显示（在滚动窗格的右侧和底部边缘）时，下左角组件将显示在两个滚动条末端之间的空间中。 key 的合法值为：
      • ScrollPaneConstants.LOWER_LEFT_CORNER
      • ScrollPaneConstants.LOWER_RIGHT_CORNER
      • ScrollPaneConstants.UPPER_LEFT_CORNER
      • ScrollPaneConstants.UPPER_RIGHT_CORNER
      • ScrollPaneConstants.LOWER_LEADING_CORNER
      • ScrollPaneConstants.LOWER_TRAILING_CORNER
      • ScrollPaneConstants.UPPER_LEADING_CORNER
      • ScrollPaneConstants.UPPER_TRAILING_CORNER

      尽管“corner”不匹配任何bean属性签名，但会生成带有属性名称设置为角落键的PropertyChange事件。

      参数:
      key - 标识组件将出现在哪个角落
      corner - 以下组件之一：
      • lowerLeft
      • lowerRight
      • upperLeft
      • upperRight
      抛出:
      IllegalArgumentException - 如果角落键无效

    • setComponentOrientation

      public void setComponentOrientation(ComponentOrientation co)
      根据ComponentOrientation参数确定垂直和水平滚动条的方向。
      覆盖:
      setComponentOrientation 在类中 Component
      参数:
      co - 以下值之一：
      • java.awt.ComponentOrientation.LEFT_TO_RIGHT
      • java.awt.ComponentOrientation.RIGHT_TO_LEFT
      • java.awt.ComponentOrientation.UNKNOWN
      参见:

    • isWheelScrollingEnabled

      @BeanProperty(description="Flag for enabling/disabling mouse wheel scrolling") public boolean isWheelScrollingEnabled()
      指示是否响应鼠标滚轮进行滚动。默认情况下启用鼠标滚轮滚动。
      返回:
      如果启用了鼠标滚轮滚动，则为true，否则为false
      自:
      1.4
      参见:

    • setWheelScrollingEnabled

      @BeanProperty(description="Flag for enabling/disabling mouse wheel scrolling") public void setWheelScrollingEnabled(boolean handleWheel)
      启用/禁用响应鼠标滚轮移动进行滚动。默认情况下启用鼠标滚轮滚动。
      参数:
      handleWheel - 如果应自动执行鼠标滚轮事件的滚动，则为true，否则为false。
      自:
      1.4
      参见:

    • paramString

      protected String paramString()
      返回此JScrollPane的字符串表示形式。此方法仅用于调试目的，返回的字符串的内容和格式可能因实现而异。返回的字符串可能为空，但不会为null。
      覆盖:
      paramString 在类中 JComponent
      返回:
      此JScrollPane的字符串表示形式。

    • getAccessibleContext

      @BeanProperty(bound=false) public AccessibleContext getAccessibleContext()
      获取与此JScrollPane关联的AccessibleContext。对于滚动窗格，AccessibleContext采用AccessibleJScrollPane的形式。如果需要，将创建一个新的AccessibleJScrollPane实例。
      指定者:
      getAccessibleContext 在接口中 Accessible
      覆盖:
      getAccessibleContext 在类中 Component
      返回:
      作为此JScrollPane的AccessibleContext的AccessibleJScrollPane