Java 中文官方教程 2022 版（十四）（4）-阿里云开发者社区

Java 中文官方教程 2022 版（十四）（3）https://developer.aliyun.com/article/1486378

使用文本组件

原文：docs.oracle.com/javase/tutorial/uiswing/components/text.html

本节提供了在使用 Swing 文本组件时可能需要的背景信息。如果你打算使用未经样式化的文本组件 — 一个文本字段、密码字段、格式化文本字段或文本区域 — 请转到其操作页面，仅在必要时返回此处。如果你打算使用样式化文本组件，请参阅如何使用编辑窗格和文本窗格，并阅读本节。如果你不知道需要哪种组件，请继续阅读。

Swing 文本组件显示文本，并可选择允许用户编辑文本。程序需要文本组件来执行从简单任务（输入一个单词并按 Enter 键）到复杂任务（在亚洲语言中显示和编辑带有嵌入图像的样式文本）的各种任务。

Swing 提供了六个文本组件，以及支持各种复杂文本需求的支持类和接口。尽管它们用途和功能不同，但所有 Swing 文本组件都继承自相同的超类JTextComponent，为文本操作提供了高度可配置和强大的基础。

以下图显示了JTextComponent的层次结构。

以下图片显示了一个名为TextSamplerDemo的应用程序，该应用程序使用了每个 Swing 文本组件。

试一试：

点击“启动”按钮以使用Java™ Web Start运行 TextSamplerDemo（下载 JDK 7 或更高版本）。或者，要自行编译和运行示例，请参考示例索引。
在文本字段中输入一些文本，然后按 Enter 键。在密码字段中也做同样操作。当你按 Enter 键时，字段下方的标签会更新。
尝试在格式化文本字段中输入有效和无效日期。请注意，只有日期有效时，当你按 Enter 键时，字段下方的标签才会更新。
在文本区域和文本窗格中选择和编辑文本。使用键盘绑定，Ctrl-X、Ctrl-C 和 Ctrl-V，分别进行剪切、复制和粘贴文本。
尝试编辑已通过setEditable调用而变为不可编辑的编辑窗格中的文本。
在文本窗格中查找一个嵌入组件和一个嵌入图标的示例。

TextSamplerDemo示例以非常基本的方式使用文本组件。以下表格告诉您可以使用每种文本组件做什么。

组	描述	Swing 类
文本控件	也简称为文本字段，文本控件只能显示一行可编辑文本。像按钮一样，它们会生成动作事件。使用它们从用户那里获取少量文本信息，并在文本输入完成后执行操作。	`JTextField` 及其子类 `JPasswordField` 和 `JFormattedTextField`
普通文本区域	`JTextArea`可以显示多行可编辑文本。虽然文本区域可以显示任何字体的文本，但所有文本都是相同字体。使用文本区域允许用户输入任意长度的未格式化文本或显示未格式化的帮助信息。	`JTextArea`

| 样式文本区域 | 样式文本组件可以使用多种字体显示可编辑文本。一些样式文本组件允许嵌入图像甚至嵌入组件。样式文本组件是功能强大且多面向的组件，适用于高端需求，并提供比其他文本组件更多的自定义途径。由于它们如此强大和灵活，样式文本组件通常需要更多的初始编程来设置和使用。一个例外是编辑器窗格可以轻松地从 URL 加载格式化文本，这使它们非常适用于显示不可编辑的帮助信息。 | JEditorPane 及其子类

JTextPane |

本教程提供了关于JTextComponent类奠定的基础的信息，并告诉您如何完成一些常见的与文本相关的任务。

要了解更多关于 JavaFX 中文本组件的信息，请参阅在 JavaFX 中使用文本和文本效果和使用 JavaFX UI 控件：文本字段教程。

文本组件功能

原文：docs.oracle.com/javase/tutorial/uiswing/components/generaltext.html

JTextComponent类是 Swing 文本组件的基础。该类为其所有后代提供以下可定制功能：

一个称为文档的模型，用于管理组件的内容。
一个视图，用于在屏幕上显示组件。
一个称为编辑器工具包的控制器，用于读取和写入文本，并使用操作实现编辑功能。
支持无限的撤销和重做。
可插拔的插入符和支持插入符更改侦听器和导航过滤器。

查看名为TextComponentDemo的示例以探索这些功能。尽管TextComponentDemo示例包含一个自定义的JTextPane实例，但本节讨论的功能被所有JTextComponent子类继承。

上方文本组件是自定义文本窗格。下方文本组件是JTextArea的一个实例，用作报告对文本窗格内容所做的所有更改的日志。窗口底部的状态行报告选择的位置或插入符的位置，具体取决于是否选择了文本。

试试这个：

单击“启动”按钮以使用Java™ Web Start运行 TextComponentDemo（下载 JDK 7 或更高版本）。或者，要自行编译和运行示例，请参考示例索引。
使用鼠标选择文本并将光标放置在文本窗格中。有关选择和光标的信息显示在窗口底部。
通过键盘输入文本。您可以使用键盘上的箭头键或四个 emacs 键绑定（Ctrl-B（向后移动一个字符），Ctrl-F（向前移动一个字符），Ctrl-N（向下移动一行）和 Ctrl-P（向上移动一行））来移动插入符。
打开编辑菜单，并使用其菜单项在文本窗格中编辑文本。在窗口底部的文本区域中进行选择。由于文本区域不可编辑，因此只有一些编辑菜单的命令，如复制到剪贴板，才有效。但需要注意的是，该菜单同时适用于文本组件。
使用“样式”菜单中的项目将不同的样式应用于文本窗格中的文本。

使用TextComponentDemo示例作为参考点，本节涵盖以下主题：

将文本操作与菜单和按钮关联
将文本操作与按键绑定
实现撤销和重做
概念：关于文档
实现文档过滤器
监听文档更改
监听插入符和选择更改
概念：关于编辑工具包

将文本操作与菜单和按钮关联

所有 Swing 文本组件都支持标准的编辑命令，如剪切、复制、粘贴和插入字符。每个编辑命令由一个Action对象表示和实现。（要了解更多关于操作的信息，请参阅如何使用操作。）操作允许您将命令与 GUI 组件（如菜单项或按钮）关联起来，从而围绕文本组件构建 GUI。

您可以在任何文本组件上调用getActions方法，以接收包含此组件支持的所有操作的数组。还可以将操作数组加载到HashMap中，以便您的程序可以按名称检索操作。以下是从TextComponentDemo示例中获取文本窗格中的操作并将其加载到HashMap中的代码。

private HashMap<Object, Action> createActionTable(JTextComponent textComponent) {
        HashMap<Object, Action> actions = new HashMap<Object, Action>();
        Action[] actionsArray = textComponent.getActions();
        for (int i = 0; i < actionsArray.length; i++) {
            Action a = actionsArray[i];
            actions.put(a.getValue(Action.NAME), a);
        }
        return actions;
    }

以下是从哈希映射中按名称检索操作的方法：

private Action getActionByName(String name) {
    return actions.get(name);
}

您可以在程序中逐字使用这两种方法。

以下代码显示了如何创建剪切菜单项并将其与从文本组件中删除文本的操作关联起来。

protected JMenu createEditMenu() {
    JMenu menu = new JMenu("Edit");
    ...
    menu.add(getActionByName(DefaultEditorKit.cutAction));
    ...

此代码通过之前展示的方便方法按名称获取操作。然后将操作添加到菜单中。这就是你需要做的一切。菜单和操作会处理其他所有事情。请注意，操作的名称来自DefaultEditorKit。该工具包提供了基本文本编辑的操作，并且是 Swing 提供的所有编辑工具包的超类。因此，除非被自定义覆盖，否则其功能对所有文本组件都可用。

为了效率，文本组件共享操作。通过getActionByName(DefaultEditorKit.cutAction)返回的Action对象由窗口底部的不可编辑JTextArea共享。这种共享特性有两个重要的影响：

通常，您不应修改从编辑工具包获取的Action对象。如果这样做，更改会影响程序中的所有文本组件。
Action对象可以在程序中操作其他文本组件，有时会超出您的意图。在这个例子中，即使它是不可编辑的，JTextArea也与JTextPane共享动作。（在文本区域中选择一些文本，然后选择剪切到剪贴板菜单项。您会听到一声哔声，因为文本区域是不可编辑的。）如果您不想共享，请自行实例化Action对象。DefaultEditorKit定义了许多有用的Action子类。

以下是创建样式菜单并将粗体菜单项放入其中的代码：

protected JMenu createStyleMenu() {
    JMenu menu = new JMenu("Style");
    Action action = new StyledEditorKit.BoldAction();
    action.putValue(Action.NAME, "Bold");
    menu.add(action);
    ...

StyledEditorKit提供了Action子类来实现对带样式文本的编辑命令。您会注意到，这段代码创建了BoldAction类的一个实例，而不是从编辑器工具包中获取动作。因此，这个动作不会与任何其他文本组件共享，更改其名称不会影响任何其他文本组件。

将文本动作与键盘快捷键关联

除了将动作与 GUI 组件关联外，还可以通过使用文本组件的输入映射将动作与键盘快捷键关联。输入映射在如何使用键绑定中有描述。

TextComponentDemo示例中的文本窗格支持四个默认未提供的键绑定。

按下 Ctrl-B 将光标向后移动一个字符
按下 Ctrl-F 将光标向前移动一个字符
按下 Ctrl-N 将光标向下移动一行
按下 Ctrl-P 将光标向上移动一行

以下代码将 Ctrl-B 键绑定添加到文本窗格。添加上面列出的其他三个绑定的代码类似。

InputMap inputMap = textPane.getInputMap();
KeyStroke key = KeyStroke.getKeyStroke(KeyEvent.VK_B,
                                       Event.CTRL_MASK);
inputMap.put(key, DefaultEditorKit.backwardAction);

首先，代码获取文本组件的输入映射。接下来，它找到代表 Ctrl-B 键序列的KeyStroke对象。最后，代码将该键序列绑定到将光标向后移动的Action。

实现撤销和重做

实现撤销和重做有两个部分：

记住可撤销的编辑。
实现撤销和重做命令并为其提供用户界面。

第一部分：记住可撤销的编辑

要支持撤销和重做，文本组件必须记住每次编辑的发生，编辑的顺序以及撤销每次编辑所需的内容。示例程序使用UndoManager类的一个实例来管理其可撤销编辑的列表。撤销管理器是在声明成员变量的地方创建的：

protected UndoManager undo = new UndoManager();

现在，让我们看看程序如何发现可撤销的编辑并将其添加到撤销管理器中。

当文档内容发生可撤销编辑时，文档会通知感兴趣的监听器。实现撤销和重做的一个重要步骤是在文本组件的文档上注册一个可撤销编辑监听器。以下代码向文本窗格的文档添加了MyUndoableEditListener的一个实例：

doc.addUndoableEditListener(new MyUndoableEditListener());

我们示例中使用的可撤销编辑侦听器将编辑添加到撤销管理器的列表中：

protected class MyUndoableEditListener
          implements UndoableEditListener {
    public void undoableEditHappened(UndoableEditEvent e) {
        //Remember the edit and update the menus
        undo.addEdit(e.getEdit());
        undoAction.updateUndoState();
        redoAction.updateRedoState();
    }
}

请注意，此方法更新两个对象：undoAction和redoAction。这些是分别附加到撤销和重做菜单项的操作对象。下一步将向您展示如何创建菜单项以及如何实现这两个操作。有关可撤销编辑侦听器和可撤销编辑事件的一般信息，请参阅如何编写可撤销编辑侦听器。

注意：

默认情况下，每个可撤销编辑都会撤消一个字符输入。通过一些努力，可以将编辑分组，以便一系列按键组合成一个可撤销编辑。以这种方式分组编辑需要您定义一个类，拦截文档的可撤销编辑事件，如果适当则将它们组合并将结果转发给您的可撤销编辑侦听器。

第 2 部分：实现撤销和重做命令

实现撤销和重做的第一步是创建要放入编辑菜单中的操作。

JMenu menu = new JMenu("Edit");
//Undo and redo are actions of our own creation
undoAction = new UndoAction();
menu.add(undoAction);
redoAction = new RedoAction();
menu.add(redoAction);
...

撤销和重做操作由自定义的AbstractAction子类实现：UndoAction和RedoAction，分别。这些类是示例主类的内部类。

当用户调用undo命令时，将调用UndoAction类的actionPerformed方法：

public void actionPerformed(ActionEvent e) {
    try {
        undo.undo();
    } catch (CannotUndoException ex) {
        System.out.println("Unable to undo: " + ex);
        ex.printStackTrace();
    }
    updateUndoState();
    redoAction.updateRedoState();
}

此方法调用撤销管理器的undo方法，并更新菜单项以反映新的撤销/重做状态。

类似地，当用户调用redo命令时，将调用RedoAction类的actionPerformed方法：

public void actionPerformed(ActionEvent e) {
    try {
        undo.redo();
    } catch (CannotRedoException ex) {
        System.out.println("Unable to redo: " + ex);
        ex.printStackTrace();
    }
    updateRedoState();
    undoAction.updateUndoState();
}

此方法类似于撤销，只是调用撤销管理器的redo方法。

UndoAction和RedoAction类中的大部分代码专门用于根据当前状态启用和禁用操作，并更改菜单项的名称以反映要撤消或重做的编辑。

注意：

TextComponentDemo示例中的撤销和重做实现取自随 JDK 软件提供的NotePad演示。许多程序员也可以直接复制此撤销/重做实现而无需修改。

概念：关于文档

与其他 Swing 组件一样，文本组件将其数据（称为模型）与数据的视图分开。如果您尚未熟悉 Swing 组件使用的模型-视图分离，请参考使用模型。

文本组件的模型称为文档，是实现Document接口的类的实例。文档为文本组件提供以下服务：

包含文本。文档将文本内容存储在Element对象中，这些对象可以表示任何逻辑文本结构，如段落，或共享样式的文本运行。我们在这里不描述Element对象。
通过remove和insertString方法支持编辑文本。
通知文档侦听器和可撤销编辑侦听器文本更改。
管理Position对象，跟踪文本中的特定位置，即使文本被修改。
允许您获取有关文本的信息，例如其长度以及文本段作为字符串。

Swing 文本包包含Document的一个子接口，StyledDocument，它添加了使用样式标记文本的支持。一个JTextComponent子类，JTextPane，要求其文档是StyledDocument而不仅仅是Document。

javax.swing.text包提供了以下文档类层次结构，这些类实现了各种JTextComponent子类的专门文档：

PlainDocument是文本字段、密码字段和文本区域的默认文档。PlainDocument提供一个基本容器，其中所有文本以相同字体显示。即使编辑器窗格是一个样式化文本组件，但默认情况下它使用PlainDocument的一个实例。标准JTextPane的默认文档是DefaultStyledDocument的一个实例，用于以无特定格式显示样式文本的容器。但是，任何特定编辑器窗格或文本窗格使用的文档实例取决于绑定到其上的内容类型。如果使用setPage方法将文本加载到编辑器窗格或文本窗格中，则窗格使用的文档实例可能会更改。有关详细信息，请参阅如何使用编辑器窗格和文本窗格。

虽然你可以设置文本组件的文档，但通常更容易允许它自动设置，并在必要时使用文档过滤器来更改文本组件的数据设置方式。您可以通过安装文档过滤器或将文本组件的文档替换为自己的文档来实现某些自定义。例如，TextComponentDemo示例中的文本窗格具有一个限制文本窗格可以包含字符数量的文档过滤器。

实现文档过滤器

要实现文档过滤器，请创建DocumentFilter的子类，然后使用AbstractDocument类中定义的setDocumentFilter方法将其附加到文档上。虽然可能存在不是从AbstractDocument继承的文档，但默认情况下，Swing 文本组件使用AbstractDocument子类作为其文档。

TextComponentDemo 应用程序有一个文档过滤器，DocumentSizeFilter，限制文本窗格可以包含的字符数。以下是创建过滤器并将其附加到文本窗格文档的代码：

*...//Where member variables are declared:*
JTextPane textPane;
AbstractDocument doc;
static final int MAX_CHARACTERS = 300;
...
textPane = new JTextPane();
...
StyledDocument styledDoc = textPane.getStyledDocument();
if (styledDoc instanceof AbstractDocument) {
    doc = (AbstractDocument)styledDoc;
    doc.setDocumentFilter(new DocumentSizeFilter(MAX_CHARACTERS));
}

为了限制文档中允许的字符数，DocumentSizeFilter覆盖了DocumentFilter类的insertString方法，每次插入文本到文档时都会调用该方法。它还覆盖了replace方法，当用户粘贴新文本时最有可能被调用。一般来说，文本插入可能发生在用户键入或粘贴新文本时，或者调用setText方法时。这是DocumentSizeFilter类对insertString方法的实现：

public void insertString(FilterBypass fb, int offs,
                         String str, AttributeSet a)
    throws BadLocationException {
    if ((fb.getDocument().getLength() + str.length()) <= maxCharacters)
        super.insertString(fb, offs, str, a);
    else
        Toolkit.getDefaultToolkit().beep();
}

replace的代码类似。DocumentFilter类定义的方法的FilterBypass参数只是一个使文档能够以线程安全方式更新的对象。

因为前面的文档过滤器涉及文档数据的添加，它仅覆盖了insertString和replace方法。大多数文档过滤器还会覆盖DocumentFilter的remove方法。

监听文档的更改

您可以在文档上注册两种不同类型的监听器：文档监听器和可撤销编辑监听器。本小节描述了文档监听器。有关可撤销编辑监听器的信息，请参阅实现撤销和重做。

文档会通知已注册的文档监听器文档的更改。使用文档监听器在文档中插入或删除文本，或文本样式更改时创建反应。

TextComponentDemo 程序使用文档监听器在文本窗格发生更改时更新更改日志。以下代码行将MyDocumentListener类的一个实例注册为文本窗格文档的监听器：

doc.addDocumentListener(new MyDocumentListener());

这是MyDocumentListener类的实现：

protected class MyDocumentListener implements DocumentListener {
    public void insertUpdate(DocumentEvent e) {
        displayEditInfo(e);
    }
    public void removeUpdate(DocumentEvent e) {
        displayEditInfo(e);
    }
    public void changedUpdate(DocumentEvent e) {
        displayEditInfo(e);
    }
    private void displayEditInfo(DocumentEvent e) {
            Document document = (Document)e.getDocument();
            int changeLength = e.getLength();
            changeLog.append(e.getType().toString() + ": "
                + changeLength + " character"
                + ((changeLength == 1) ? ". " : "s. ")
                + " Text length = " + document.getLength()
                + "." + newline);
    }
}

监听器实现了处理三种不同类型文档事件的三种方法：插入、删除和样式更改。StyledDocument 实例可以触发这三种类型的事件。PlainDocument 实例仅触发插入和删除事件。有关文档监听器和文档事件的一般信息，请参阅如何编写文档监听器。

请记住，此文本窗格的文档过滤器限制了文档中允许的字符数。如果尝试添加的文本超出文档过滤器允许的范围，文档过滤器将阻止更改，并且监听器的insertUpdate方法不会被调用。只有在更改已经发生时，文档监听器才会被通知更改。

您可能希望在文档监听器中更改文档的文本。**但是，您绝对不应该在文档监听器中修改文本组件的内容。**如果这样做，程序很可能会死锁。相反，您可以使用格式化文本字段或提供文档过滤器。

监听插入符和选择更改

TextComponentDemo 程序使用一个插入符监听器来显示插入符的当前位置，或者如果选择了文本，则显示选择的范围。

此示例中的插入符监听器类是一个JLabel子类。以下是创建插入符监听器标签并将其设置为文本窗格的插入符监听器的代码：

//Create the status area
CaretListenerLabel caretListenerLabel = new CaretListenerLabel(
                                                "Caret Status");
...
textPane.addCaretListener(caretListenerLabel);

插入符监听器必须实现一个方法，即caretUpdate，每次插入符移动或选择更改时都会调用该方法。以下是CaretListenerLabel对caretUpdate的实现：

public void caretUpdate(CaretEvent e) {
    //Get the location in the text
    int dot = e.getDot();
    int mark = e.getMark();
    if (dot == mark) {  // no selection
        try {
            Rectangle caretCoords = textPane.modelToView(dot);
            //Convert it to view coordinates
            setText("caret: text position: " + dot +
                    ", view location = [" +
                    caretCoords.x + ", " + caretCoords.y + "]" +
                    newline);
        } catch (BadLocationException ble) {
            setText("caret: text position: " + dot + newline);
        }
     } else if (dot < mark) {
        setText("selection from: " + dot + " to " + mark + newline);
     } else {
        setText("selection from: " + mark + " to " + dot + newline);
     }
}

如您所见，此监听器会更新其文本标签以反映插入符或选择的当前状态。监听器从插入符事件对象获取要显示的信息。有关插入符监听器和插入符事件的一般信息，请参阅如何编写插入符监听器。

与文档监听器一样，插入符监听器是被动的。它对插入符或选择的更改做出反应，但不会更改插入符或选择本身。如果要更改插入符或选择，请使用导航过滤器或自定义插入符。

实现导航过滤器类似于实现文档过滤器。首先，编写一个NavigationFilter的子类。然后使用setNavigationFilter方法将子类的实例附加到文本组件。

您可能会创建一个自定义插入符来自定义插入符的外观。要创建自定义插入符，请编写一个实现Caret接口的类，可能是通过扩展DefaultCaret类。然后将您的类的实例作为参数提供给文本组件的setCaret方法。

概念：关于编辑器工具包

文本组件使用EditorKit将文本组件的各个部分联系在一起。编辑器工具包提供视图工厂、文档、插入符和操作。编辑器工具包还读取和写入特定格式的文档。尽管所有文本组件都使用编辑器工具包，但某些组件会隐藏它们的编辑器工具包。您无法设置或获取文本字段或文本区域使用的编辑器工具包。编辑窗格和文本窗格提供getEditorKit方法以获取当前编辑器工具包，并提供setEditorKit方法以更改它。

对于所有组件，JTextComponent类提供了 API，让您间接调用或自定义一些编辑工具包的功能。例如，JTextComponent提供了read和write方法，这些方法调用编辑工具包的read和write方法。JTextComponent还提供了一个方法，getActions，它返回组件支持的所有操作。

Swing 文本包提供以下编辑工具包：

DefaultEditorKit

读取和写入纯文本，并提供一组基本的编辑命令。有关文本系统如何处理换行符的详细信息可以在DefaultEditorKit API 文档中找到。简而言之，'\n’字符在内部使用，但在写入文件时使用文档或平台的换行符。所有其他编辑工具包都是DefaultEditorKit类的子类。

StyledEditorKit

读取和写入样式文本，并为样式文本提供一组最小的操作。这个类是DefaultEditorKit的子类，是JTextPane默认使用的编辑工具包。

HTMLEditorKit

读取、写入和编辑 HTML。这是StyledEditorKit的子类。

上述每个编辑工具包都已注册到JEditorPane类，并与工具包读取、写入和编辑的文本格式相关联。当文件加载到编辑窗格中时，窗格会检查文件的格式与其注册的工具包是否匹配。如果找到支持该文件格式的注册工具包，则窗格将使用该工具包来读取文件、显示和编辑。因此，编辑窗格有效地将自身转换为该文本格式的编辑器。您可以通过为其创建编辑工具包，然后使用JEditorPane的registerEditorKitForContentType将您的工具包与您的文本格式相关联，从而扩展JEditorPane以支持您自己的文本格式。

Java 中文官方教程 2022 版（十四）（4）

使用文本组件

文本组件功能

将文本操作与菜单和按钮关联

将文本动作与键盘快捷键关联

实现撤销和重做

概念：关于文档

实现文档过滤器

监听文档的更改

监听插入符和选择更改

概念：关于编辑器工具包

热门文章

最新文章

相关课程

相关电子书

相关实验场景