12.6 行为¶
12.6 Actions
12.6.1 概述¶
12.6.1 General
除了跳转到文档中的目标位置外，注释或大纲项还可以指定要执行的操作 (PDF 1.1)，例如启动应用程序、播放声音、更改注释的外观状态。注释或大纲项字典中的可选 A 条目（参见 表 168 和 153）指定激活注释或大纲项时执行的操作；在 PDF 1.2 中，各种其他情况也可能触发操作（参见 12.6.3，“触发事件”）。此外，文档目录中的可选 OpenAction 条目（7.7.2，“文档目录”）可以指定打开文档时应执行的操作。PDF 包含各种标准操作类型，在 12.6.4，“操作类型”中有详细描述。
In addition to jumping to a destination in the document, an annotation or outline item may specify an action (PDF 1.1) to perform, such as launching an application, playing a sound, changing an annotation’s appearance state. The optional A entry in the annotation or outline item dictionary (see Tables 168 and 153) specifies an action performed when the annotation or outline item is activated; in PDF 1.2, a variety of other circumstances may trigger an action as well (see 12.6.3, “Trigger Events”). In addition, the optional OpenAction entry in a document’s catalogue (7.7.2, “Document Catalog”) may specify an action that shall be performed when the document is opened. PDF includes a wide variety of standard action types, described in detail in 12.6.4, “Action Types.”
12.6.2 行为字典¶
12.6.2 Action Dictionaries
动作字典定义了动作的特性和行为。表193展示了所有动作字典共有的必需和可选条目。字典可能包含特定于某种动作类型的附加条目；有关详细信息，请参见12.6.4，“动作类型”中对各个动作类型的描述。
| 键 | 类型 | 值 |
|---|---|---|
| Type | 名称 | （必需）应为FixedPrint。（注：此处根据上下文可能有误，正常动作字典的Type常见值不是FixedPrint ，可能是特定类型动作相关的内容，需结合具体场景确认） |
| S | 名称 | （必需）此字典描述的动作类型；有关具体值，请参见表194。 |
| Next | 字典或数组 | （可选；PDF 1.2）在由本字典表示的动作之后应执行的下一动作或动作序列。该值可以是单个动作字典，也可以是要按顺序执行的动作字典数组；有关进一步讨论，请参见注释。 |
注1
动作字典的Next条目（PDF 1.2）允许将动作序列链接在一起。例如，用鼠标点击链接注释的效果可能是播放声音、跳转到新页面并启动电影。请注意，Next条目不限于单个动作，它可以包含一个动作数组，而每个动作又可能有自己的Next条目。因此，这些动作可能形成一个树状结构，而不是简单的链表。每个Next数组中的动作将按顺序执行，每个动作执行后依次执行其Next条目中指定的任何动作，依此类推，递归执行。符合规范的阅读器应在异常情况下尝试提供合理的行为。例如，自引用动作不应执行多次，并且关闭文档或使下一个动作无法执行的动作应终止执行序列。应用程序还应提供某种机制，使用户能够中断并手动终止动作序列。
PDF 1.5引入了过渡动作，允许在动作序列期间控制绘制；见12.6.4.14，“过渡动作”。
注2
任何动作都不应修改其自身的动作字典或其所处动作树中的任何其他字典。这种修改对树中后续动作执行的影响是未定义的 。
An action dictionary defines the characteristics and behaviour of an action. Table 193 shows the required and optional entries that are common to all action dictionaries. The dictionary may contain additional entries specific to a particular action type; see the descriptions of individual action types in 12.6.4, “Action Types,” for details.
| Key | Type | Value |
|---|---|---|
| Type | name | (Required) Shall be FixedPrint. |
| S | name | (Required) The type of action that this dictionary describes; see Table 194 for specific values. |
| Next | dictionary or array | (Optional; PDF 1.2) The next action or sequence of actions that shall be performed after the action represented by this dictionary. The value is either a single action dictionary or an array of action dictionaries that shall be performed in order; see the Note for further discussion. |
NOTE 1
The action dictionary’s Next entry (PDF 1.2) allows sequences of actions to be chained together. For example, the effect of clicking a link annotation with the mouse might be to play a sound, jump to a new page, and start up a movie. Note that the Next entry is not restricted to a single action but may contain an array of actions, each of which in turn may have a Next entry of its own. The actions may thus form a tree instead of a simple linked list. Actions within each Next array are executed in order, each followed in turn by any actions specified in its Next entry, and so on recursively. Conforming readers should attempt to provide reasonable behavior in anomalous situations. For example, self-referential actions should not be executed more than once, and actions that close the document or otherwise render the next action impossible should terminate the execution sequence. Applications should also provide some mechanism for the user to interrupt and manually terminate a sequence of actions.
PDF 1.5 introduces transition actions, which allow the control of drawing during a sequence of actions; see 12.6.4.14, “Transition Actions.”
NOTE 2
No action should modify its own action dictionary or any other in the action tree in which it resides. The effect of such modification on subsequent execution of actions in the tree is undefined.
12.6.3 触发事件¶
12.6.3 Trigger Events
注释、页面对象或（从PDF 1.3开始）交互式表单字段可能包含一个名为AA的条目，该条目指定一个附加动作字典（PDF 1.2），用于扩展可触发动作执行的事件集。在PDF 1.4中，文档目录字典（见7.7.2，“文档目录”）也可能包含一个AA条目，用于触发影响整个文档的事件。表194至197展示了此类字典的内容。
PDF 1.5在注释的附加动作字典中引入了四个触发事件，以支持多媒体演示：
- PO和PC条目的功能与页面对象附加动作字典中的O和C条目（见表194）类似。然而，将这些触发器与注释关联起来可以使注释对象具有自包含性。
示例
包含此类动作的注释可以在页面之间复制或移动，而无需更改页面打开/关闭动作。
- PV和PI条目允许区分打开的页面和可见的页面。在任何时刻，根据页面布局，可能会有多个页面可见。
注1
对于这些触发事件，注释的F条目（见12.5.3，“注释标志”）指定的标志值不影响给定触发事件是否发生。
| 键 | 类型 | 值 |
|---|---|---|
| E | 字典 | （可选；PDF 1.2）当光标进入注释的活动区域时应执行的动作。 |
| X | 字典 | （可选；PDF 1.2）当光标离开注释的活动区域时应执行的动作。 |
| D | 字典 | （可选；PDF 1.2）当鼠标按钮在注释的活动区域内按下时应执行的动作。 |
| U | 字典 | （可选；PDF 1.2）当鼠标按钮在注释的活动区域内释放时应执行的动作。 为了向后兼容，如果注释字典中存在A条目，则该条目优先于此条目（见表168）。 |
| Fo | 字典 | （可选；PDF 1.2；仅小部件注释）当注释获得输入焦点时应执行的动作。 |
| BI | 字典 | （可选；PDF 1.2；仅小部件注释）（大写B，小写L）当注释失去输入焦点时应执行的动作。 |
| PO | 字典 | （可选；PDF 1.5）当包含注释的页面被打开时应执行的动作。 示例1 当用户从下一页或上一页导航到该页面，或者通过链接注释或大纲项导航到该页面时。 如果存在页面附加动作字典中的O动作（见表195）以及文档Catalog中的OpenAction条目（见表28），则应在执行这些动作之后执行此动作。 |
| PC | 字典 | （可选；PDF 1.5）当包含注释的页面被关闭时应执行的动作。 示例2 当用户导航到下一页或上一页，或者跟随链接注释或大纲项时。 如果存在页面附加动作字典中的C动作（见表195），则应在执行该动作之前执行此动作。 |
| PV | 字典 | （可选；PDF 1.5）当包含注释的页面变为可见时应执行的动作。 |
| PI | 字典 | （可选；PDF 1.5）当包含注释的页面在符合规范的阅读器的用户界面中不再可见时应执行的动作。 |
| 键 | 类型 | 值 |
|---|---|---|
| O | 字典 | （可选；PDF 1.2）当页面打开时（例如，当用户从下一页或上一页导航到该页面，或者通过链接注释或大纲项导航到该页面时）应执行的动作。此动作独立于文档Catalog中的OpenAction条目（见7.7.2，“文档目录”）可能定义的任何动作，并且应在执行此类动作之后执行。 |
| C | 字典 | （可选；PDF 1.2）当页面关闭时（例如，当用户导航到下一页或上一页，或者跟随链接注释或大纲项时）应执行的动作。此动作适用于正在关闭的页面，并且应在打开任何其他页面之前执行。 |
| 键 | 类型 | 值 |
|---|---|---|
| K | 字典 | （可选；PDF 1.3）当用户在文本字段或组合框中修改字符，或者在可滚动列表框中修改选择时，应执行的JavaScript动作。此动作可以检查添加的文本的有效性，并拒绝或修改它。 |
| F | 字典 | （可选；PDF 1.3）在字段格式化以显示其值之前应执行的JavaScript动作。此动作可以在格式化之前修改字段的值。 |
| V | 字典 | （可选；PDF 1.3）当字段的值发生更改时应执行的JavaScript动作。此动作可以检查新值的有效性。（名称V代表“验证”。） |
| C | 字典 | （可选；PDF 1.3）当另一个字段的值发生更改时，应执行的JavaScript动作，用于重新计算此字段的值。（名称C代表“计算。”）文档中字段的重新计算顺序应由交互式表单字典中的CO条目定义（见12.7.2，“交互式表单字典”）。 |
| 键 | 类型 | 值 |
|---|---|---|
| WC | 字典 | （可选；PDF 1.4）在关闭文档之前应执行的JavaScript动作。（名称WC代表“即将关闭”。） |
| WS | 字典 | （可选；PDF 1.4）在保存文档之前应执行的JavaScript动作。（名称WS代表“即将保存”。） |
| DS | 字典 | （可选；PDF 1.4）在保存文档之后应执行的JavaScript动作。（名称DS代表“已保存”。） |
| WP | 字典 | （可选；PDF 1.4）在打印文档之前应执行的JavaScript动作。（名称WP代表“即将打印”。） |
| DP | 字典 | （可选；PDF 1.4）在打印文档之后应执行的JavaScript动作。（名称DP代表“已打印”。） |
符合规范的阅读器应确保存在此类设备或用于模拟该设备的等效控件，以便正确执行相应的动作。与鼠标相关的触发事件受以下约束：
- E（进入）事件仅在鼠标按钮处于抬起状态时发生。
- X（退出）事件不能在没有先前的E事件的情况下发生。
- U（抬起）事件不能在没有先前的E和D事件的情况下发生。
- 在重叠或嵌套注释的情况下，进入第二个注释的活动区域会导致第一个注释发生X事件。
注2
与字段相关的触发事件K（按键）、F（格式化）、V（验证）和C（计算）未针对按钮字段定义（见12.7.4.2，“按钮字段”）。由这些事件触发的动作的效果仅受动作本身限制，并且可以发生在所描述事件范围之外。例如，尽管F事件用于在显示之前触发格式化字段值的动作，但由该事件触发的动作可以执行计算或对文档进行任何其他修改。
这些与字段相关的触发事件可以通过用户交互或编程方式发生，例如响应交互式表单字典中的NeedAppearances条目（见12.7.2，“交互式表单字典”）、导入FDF数据（12.7.7，“表单数据格式”）或JavaScript动作（12.6.4.16，“JavaScript动作”）。例如，用户修改字段值可以触发一系列计算以及对文档中其他字段的进一步格式化和验证 。
An annotation, page object, or (beginning with PDF 1.3) interactive form field may include an entry named AA that specifies an additional-actions dictionary (PDF 1.2) that extends the set of events that can trigger the execution of an action. In PDF 1.4, the document catalogue dictionary (see 7.7.2, “Document Catalog”) may also contain an AA entry for trigger events affecting the document as a whole. Tables 194 to 197 show the contents of this type of dictionary.
PDF 1.5 introduces four trigger events in annotation’s additional-actions dictionary to support multimedia presentations:
- The PO and PC entries have a similar function to the O and C entries in the page object’s additional-actions dictionary (see Table 194). However, associating these triggers with annotations allows annotation objects to be self-contained.
EXAMPLE
Annotations containing such actions can be copied or moved between pages without requiring page open/close actions to be changed.
- The PV and PI entries allow a distinction between pages that are open and pages that are visible. At any one time, while more than one page may be visible, depending on the page layout.
NOTE 1
For these trigger events, the values of the flags specified by the annotation’s F entry (see 12.5.3, “Annotation Flags”) have no bearing on whether a given trigger event occurs.
| Key | Type | Value |
|---|---|---|
| E | dictionary | (Optional; PDF 1.2) An action that shall be performed when the cursor enters the annotation’s active area. |
| X | dictionary | (Optional; PDF 1.2) An action that shall be performed when the cursor exits the annotation’s active area. |
| D | dictionary | (Optional; PDF 1.2) An action that shall be performed when the mouse button is pressed inside the annotation’s active area. |
| U | dictionary | (Optional; PDF 1.2) An action that shall be performed when the mouse button is released inside the annotation’s active area. For backward compatibility, the A entry in an annotation dictionary, if present, takes precedence over this entry (see Table 168). |
| Fo | dictionary | (Optional; PDF 1.2; widget annotations only) An action that shall be performed when the annotation receives the input focus. |
| BI | dictionary | (Optional; PDF 1.2; widget annotations only) (Uppercase B, lowercase L) An action that shall be performed when the annotation loses the input focus. |
| PO | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is opened. EXAMPLE 1 When the user navigates to it from the next or previous page or by means of a link annotation or outline item. The action shall be executed after the O action in the page’s additional-actions dictionary (see Table 195) and the OpenAction entry in the document Catalog (see Table 28), if such actions are present. |
| PC | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is closed. EXAMPLE 2 When the user navigates to the next or previous page, or follows a link annotation or outline item. The action shall be executed before the C action in the page’s additional-actions dictionary (see Table 195), if present. |
| PV | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation becomes visible. |
| PI | dictionary | (Optional; PDF 1.5) An action that shall be performed when the page containing the annotation is no longer visible in the conforming reader’s user interface. |
| Key | Type | Value |
|---|---|---|
| O | dictionary | (Optional; PDF 1.2) An action that shall be performed when the page is opened (for example, when the user navigates to it from the next or previous page or by means of a link annotation or outline item). This action is independent of any that may be defined by the OpenAction entry in the document Catalog (see 7.7.2, “Document Catalog”) and shall be executed after such an action. |
| C | dictionary | (Optional; PDF 1.2) An action that shall be performed when the page is closed (for example, when the user navigates to the next or previous page or follows a link annotation or an outline item). This action applies to the page being closed and shall be executed before any other page is opened. |
| Key | Type | Value |
|---|---|---|
| K | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed when the user modifies a character in a text field or combo box or modifies the selection in a scrollable list box. This action may check the added text for validity and reject or modify it. |
| F | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed before the field is formatted to display its value. This action may modify the field’s value before formatting. |
| V | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed when the field’s value is changed. This action may check the new value for validity. (The name V stands for “validate.”) |
| C | dictionary | (Optional; PDF 1.3) A JavaScript action that shall be performed to recalculate the value of this field when that of another field changes. (The name C stands for “calculate.”) The order in which the document’s fields are recalculated shall be defined by the CO entry in the interactive form dictionary (see 12.7.2, “Interactive Form Dictionary”). |
| Key | Type | Value |
|---|---|---|
| WC | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before closing a document. (The name WC stands for “will close.”) |
| WS | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before saving a document. (The name WS stands for “will save.”) |
| DS | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed after saving a document. (The name DS stands for “did save.”) |
| WP | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed before printing a document. (The name WP stands for “will print.”) |
| DP | dictionary | (Optional; PDF 1.4) A JavaScript action that shall be performed after printing a document. (The name DP stands for “did print.”) |
Conforming readers shall ensure the presence of such a device, or equivalent controls for simulating one, for the corresponding actions to be executed correctly. Mouse-related trigger events are subject to the following constraints:
- An E (enter) event may occur only when the mouse button is up.
- An X (exit) event may not occur without a preceding E event.
- A U (up) event may not occur without a preceding E and D event.
- In the case of overlapping or nested annotations, entering a second annotation’s active area causes an X event to occur for the first annotation.
NOTE 2
The field-related trigger events K (keystroke), F (format), V (validate), and ** C (calculate) are not defined for button fields (see 12.7.4.2, “Button Fields”). The effects of an action triggered by one of these events are limited only by the action itself and can occur outside the described scope of the event. For example, even though the F** event is used to trigger actions that format field values prior to display, it is possible for an action triggered by this event to perform a calculation or make any other modification to the document.
These field-related trigger events can occur either through user interaction or programmatically, such as in response to the NeedAppearances entry in the interactive form dictionary (see 12.7.2, “Interactive Form Dictionary”), importation of FDF data (12.7.7, “Forms Data Format”), or JavaScript actions (12.6.4.16, “JavaScript Actions”). For example, the user’s modifying a field value can trigger a cascade of calculations and further formatting and validation for other fields in the document.
12.6.4 操作类型¶
12.6.4 Action Types
12.6.4.1 概述¶
12.6.4.1 General
PDF 支持表 198 中列出的标准动作类型。以下子条款详细描述了每种类型。
| 动作类型 | 描述 | 在小节中讨论 |
|---|---|---|
| GoTo | 跳转到当前文档中的一个目标位置。 | 12.6.4.2，“跳转动作” |
| GoToR | （“远程跳转”）跳转到另一个文档中的一个目标位置。 | 12.6.4.3，“远程跳转动作” |
| GoToE | （“嵌入文件跳转”；PDF 1.6）跳转到嵌入文件中的一个目标位置。 | 12.6.4.4，“嵌入文件跳转动作” |
| Launch | 启动一个应用程序，通常用于打开一个文件。 | 12.6.4.5，“启动动作” |
| Thread | 开始阅读一个文章线索。 | 12.6.4.6，“线索动作” |
| URI | 解析一个统一资源标识符。 | 12.6.4.7，“URI动作” |
| Sound | （PDF 1.2）播放一个声音。 | 12.6.4.8，“声音动作” |
| Movie | （PDF 1.2）播放一个电影。 | 12.6.4.9，“电影动作” |
| Hide | （PDF 1.2）设置一个注释的隐藏标志。 | 12.6.4.10，“隐藏动作” |
| Named | （PDF 1.2）执行由符合规范的阅读器预定义的动作。 | 12.6.4.11，“命名动作” |
| SubmitForm | （PDF 1.2）将数据发送到一个统一资源定位符。 | 12.7.5.2，“提交表单动作” |
| ResetForm（PDF 1.2） | 将字段设置为其默认值。 | 12.7.5.3，“重置表单动作” |
| ImportData（PDF 1.2） | 从文件中导入字段值。 | 12.7.5.4，“导入数据动作” |
| JavaScript（PDF 1.3） | 执行一个JavaScript脚本。 | 12.6.4.16，“JavaScript动作” |
| SetOCGState（PDF 1.5） | 设置可选内容组的状态。 | 12.6.4.12，“设置OCG状态动作” |
| Rendition（PDF 1.5） | 控制多媒体内容的播放。 | 12.6.4.13，“呈现动作” |
| Trans（PDF 1.5） | 使用过渡字典更新文档的显示。 | 12.6.4.14，“过渡动作” |
| GoTo3DView（PDF 1.6） | 设置3D注释的当前视图。 | 12.6.4.15，“跳转到3D视图动作” |
注
设置状态的动作被认为是过时的，不应再使用 。
PDF supports the standard action types listed in Table 198. The following sub-clauses describe each of these types in detail.
| Action type | Description | Discussed in sub-clause |
|---|---|---|
| GoTo | Go to a destination in the current document. | 12.6.4.2, “Go-To Actions” |
| GoToR | (“Go-to remote”) Go to a destination in another document. | 12.6.4.3, “Remote Go-To Actions” |
| GoToE | (“Go-to embedded”; PDF 1.6) Go to a destination in an embedded file. | 12.6.4.4, “Embedded Go-To Actions” |
| Launch | Launch an application, usually to open a file. | 12.6.4.5, “Launch Actions” |
| Thread | Begin reading an article thread. | 12.6.4.6, “Thread Actions” |
| URI | Resolve a uniform resource identifier. | 12.6.4.7, “URI Actions” |
| Sound | (PDF 1.2) Play a sound. | 12.6.4.8, “Sound Actions” |
| Movie | (PDF 1.2) Play a movie. | 12.6.4.9, “Movie Actions” |
| Hide | (PDF 1.2) Set an annotation’s Hidden flag. | 12.6.4.10, “Hide Actions” |
| Named | (PDF 1.2) Execute an action predefined by the conforming reader. | 12.6.4.11, “Named Actions” |
| SubmitForm | (PDF 1.2) Send data to a uniform resource locator. | 12.7.5.2, “Submit-Form Action” |
| ResetForm(PDF 1.2) | Set fields to their default values. | 12.7.5.3, “Reset-Form Action” |
| ImportData(PDF 1.2) | Import field values from a file. | 12.7.5.4, “Import-Data Action” |
| JavaScript(PDF 1.3) | Execute a JavaScript script. | 12.6.4.16, “JavaScript Actions” |
| SetOCGState(PDF 1.5) | Set the states of optional content groups. | 12.6.4.12, “Set-OCG-State Actions” |
| Rendition(PDF 1.5) | Controls the playing of multimedia content. | 12.6.4.13, “Rendition Actions” |
| Trans(PDF 1.5) | Updates the display of a document, using a transition dictionary. | 12.6.4.14, “Transition Actions” |
| GoTo3DView(PDF 1.6) | Set the current view of a 3D annotation | 12.6.4.15, “Go-To-3D-View Actions,” |
NOTE
The set-state action is considered obsolete and should not be used.
12.6.4.2 操作指南¶
12.6.4.2 Go-To Actions
跳转动作会将视图更改为指定的目标位置（页面、位置和缩放因子）。表199展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动类型；对于跳转动作，应为GoTo。 |
| D | 字典 | （必需）要跳转的目标位置（见12.3.2，“目标位置”）。 |
注
在链接注释或大纲项的A条目中指定跳转动作（见表173和表153）与使用Dest条目直接指定目标位置的效果相同。例如，12.6.4.12，“设置OCG状态动作”中示例所示的使用跳转动作的链接注释，与下面直接指定目标位置的示例具有相同的效果。然而，跳转动作不够简洁，并且与PDF 1.0不兼容；因此，使用直接目标位置更为可取 。
EXAMPLE
93 0 obj
<< /Type /Annot
/Subtype /Link
/Rect [ 71 717 190 734 ]
/Border [ 16 16 1 ]
/A << /Type /Action
/S /GoTo
/D [ 3 0 R /FitR –4 399 199 533 ]
>>
>>
endobj
A go-to action changes the view to a specified destination (page, location, and magnification factor). Table 199 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoTo for a go-to action. |
| D | dictionary | (Required) The destination to jump to (see 12.3.2, “Destinations”). |
NOTE
Specifying a go-to action in the A entry of a link annotation or outline item (see Table 173 and Table 153) has the same effect as specifying the destination directly with the Dest entry. For example, the link annotation shown in the Example in 12.6.4.12, “Set-OCG-State Actions,” which uses a go-to action, has the same effect as the one in the following Example, which specifies the destination directly. However, the go-to action is less compact and is not compatible with PDF 1.0; therefore, using a direct destination is preferable.
EXAMPLE
93 0 obj
<< /Type /Annot
/Subtype /Link
/Rect [ 71 717 190 734 ]
/Border [ 16 16 1 ]
/A << /Type /Action
/S /GoTo
/D [ 3 0 R /FitR –4 399 199 533 ]
>>
>>
endobj
12.6.4.3 远程操作¶
12.6.4.3 Remote Go-To Actions
远程跳转动作与普通的跳转动作类似，但它会跳转到另一个PDF文件中的目标位置，而不是当前文件。表200展示了专门针对这种类型动作的动作字典条目。
注
远程跳转动作不能用于嵌入文件；见12.6.4.4，“嵌入文件跳转动作”。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动类型；对于远程跳转动作，应为GoToR。 |
| F | 文件规范 | （必需）目标位置所在的文件。 |
| D | 名称、字节字符串或数组 | （必需）要跳转的目标位置（见12.3.2，“目标位置”）。如果该值是一个定义显式目标位置的数组（如12.3.2.2，“显式目标位置”所述），其第一个元素应是远程文档内的页码，而不是对当前文档中页面对象的间接引用。第一页的编号为0。 |
| NewWindow | 布尔值 | （可选；PDF 1.2）一个标志，用于指定是否在新窗口中打开目标文档。如果此标志为false，则目标文档将在同一窗口中替换当前文档。如果此条目不存在，符合规范的阅读器应按照其偏好进行处理。 |
A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file instead of the current file. Table 200 shows the action dictionary entries specific to this type of action.
NOTE
Remote go-to actions cannot be used with embedded files; see 12.6.4.4, “Embedded Go-To Actions.”
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoToR for a remote go-to action. |
| F | file specification | (Required) The file in which the destination shall be located. |
| D | name, byte string, or array | (Required) The destination to jump to (see 12.3.2, “Destinations”). If the value is an array defining an explicit destination (as described under 12.3.2.2, “Explicit Destinations”), its first element shall be a page number within the remote document rather than an indirect reference to a page object in the current document. The first page shall be numbered 0. |
| NewWindow | boolean | (Optional; PDF 1.2) A flag specifying whether to open the destination document in a new window. If this flag is false, the destination document replaces the current document in the same window. If this entry is absent, the conforming reader should behave in accordance with its preference. |
12.6.4.4 嵌入式操作¶
12.6.4.4 Embedded Go-To Actions
嵌入式跳转动作（PDF 1.6）与远程跳转动作类似，但它允许在嵌入到另一个PDF文件中的PDF文件之间进行跳转（见7.11.4，“嵌入文件流”）。嵌入文件可以与文件附件注释（见12.5.6.15，“文件附件注释”）或嵌入文件名称树中的条目（见7.7.4，“名称字典”）相关联。嵌入文件反过来也可以包含嵌入文件。表201展示了专门针对嵌入式跳转动作的动作字典条目。
嵌入式跳转动作提供了一个完整的机制，用于在嵌套嵌入文件的层次结构中的一个文件与同一或不同层次结构中的另一个文件之间建立链接。应使用以下术语：
- 源文件：包含嵌入式跳转动作的文档。
- 目标文件：目标位置所在的文档。
- 动作字典中的T条目是一个目标字典，用于相对于源文件定位目标文件，其方式与相对路径描述文件系统中两个文件的物理关系类似。目标字典可以递归嵌套，以指定一个或多个中间目标，然后到达最终目标。在遍历层次结构时，每个中间目标都应被称为当前文档。最初，源文件是当前文档。
注
如果目标字典存在无限循环（例如，一个目标字典引用自身），则这是一个错误。符合规范的阅读器应尝试检测此类情况，并在发现时拒绝执行该动作。
- 子文档：嵌入在另一个PDF文件中的文档。
- 包含嵌入文件的文档称为其父文档。
- 根文档：未嵌入到另一个PDF文件中的文档。目标和源可以位于根文档或嵌入文档中。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于嵌入式跳转动作，应为GoToE。 |
| F | 文件规范 | （可选）相对于源文件根文档的目标文件的根文档。如果此条目不存在，则源文件和目标文件共享相同的根文档。 |
| D | 名称、字节字符串或数组 | （必需）要跳转到目标文件中的目标位置（见12.3.2，“目标位置”）。 |
| NewWindow | 布尔值 | （可选）如果为true，则应在新的窗口中打开目标文档；如果为false，则目标文档应在同一窗口中替换当前文档。如果此条目不存在，符合规范的阅读器应根据其偏好进行处理。 |
| T | 字典 | （如果存在F条目则为可选；否则必需）一个目标字典（见表202），用于指定到目标文档的路径信息。每个目标字典指定到目标的完整路径中的一个元素，并且可以嵌套其他目标字典来指定更多元素。 |
| 键 | 类型 | 值 |
|---|---|---|
| R | 名称 | （必需）指定当前文档与目标（可能是中间目标）之间的关系。有效值为 P（目标为当前文档的父文档）和 C（目标为当前文档的子文档）。 |
| N | 字节字符串 | （如果 R 的值为 C 且目标位于 EmbeddedFiles 名称树中，则必需；否则应不存在）EmbeddedFiles 名称树中文件的名称。 |
| P | 整数或字节字符串 | （如果 R 的值为 C 且目标与文件附件注释相关联，则必需；否则应不存在）如果该值是整数，则指定当前文档中包含文件附件注释的页码（从零开始计数）。如果该值是字符串，则指定当前文档中提供文件附件注释页码的命名目标。 |
| A | 整数或文本字符串 | （如果 R 的值为 C 且目标与文件附件注释相关联，则必需；否则应不存在）如果该值是整数，则指定由 P 指定的页面的 Annots 数组（见表30）中注释的索引（从零开始计数）。如果该值是文本字符串，则指定注释字典中的 NM 值（见表164）。 |
| T | 字典 | （可选）一个目标字典，用于指定到目标文档的附加路径信息。如果此条目不存在，则当前文档是包含目标的文件。 |
示例
以下示例说明了源和目标之间的几种可能关系。所示的每个对象都是嵌入式跳转动作的动作字典 。
1 0 obj % Link to a child
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document) >>
>>
endobj
2 0 obj
<< /Type /Action % Link to the parent
/S /GoToE
/D (Chapter 1)
/T << /R /P >>
>>
endobj
3 0 obj % Link to a sibling
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /P
/T << /R /C
/N (Another embedded document) >>
>>
>>
endobj
4 0 obj % Link to an embedded file in an external document
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
/T << /R /C
/N (Embedded document) >>
>>
endobj
5 0 obj % Link from an embedded file to a normal file
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
>>
endobj
6 0 obj % Link to a grandchild
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document)
/T << /R /C
/P (A destination name)
/A (annotName)
>>
>>
>>
endobj
7 0 obj % Link to a niece/nephew through the source’s parent
<< /Type /Action
/S /GoToE
/D (destination)
/T << /R /P
/T << /R /C
/N (Embedded document)
/T << /R /C
/P 3
/A (annotName)
>>
>>
>>
>>
endobj
An embedded go-to action (PDF 1.6) is similar to a remote go-to action but allows jumping to or from a PDF file that is embedded in another PDF file (see 7.11.4, “Embedded File Streams”). Embedded files may be associated with file attachment annotations (see 12.5.6.15, “File Attachment Annotations”) or with entries in the EmbeddedFiles name tree (see 7.7.4, “Name Dictionary”). Embedded files may in turn contain embedded files. Table 201 shows the action dictionary entries specific to embedded go-to actions.
Embedded go-to actions provide a complete facility for linking between a file in a hierarchy of nested embedded files and another file in the same or different hierarchy. The following terminology shall be used:
- The source is the document containing the embedded go-to action.
- The target is the document in which the destination lives.
- The T entry in the action dictionary is a target dictionary that locates the target in relation to the source, in much the same way that a relative path describes the physical relationship between two files in a file system. Target dictionaries may be nested recursively to specify one or more intermediate targets before reaching the final one. As the hierarchy is navigated, each intermediate target shall be referred to as the current document. Initially, the source is the current document.
NOTE
It is an error for a target dictionary to have an infinite cycle (for example, one where a target dictionary refers to itself). Conforming readers should attempt to detect such cases and refuse to execute the action if found.
- A child document shall be one that is embedded within another PDF file.
- The document in which a file is embedded shall be its parent.
- A root document is one that is not embedded in another PDF file. The target and source may be contained in root documents or embedded documents.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoToE for an embedded go-to action. |
| F | file specification | (Optional) The root document of the target relative to the root document of the source. If this entry is absent, the source and target share the same root document. |
| D | name, byte string, or array | (Required) The destination in the target to jump to (see 12.3.2, “Destinations”). |
| NewWindow | boolean | (Optional) If true, the destination document should be opened in a new window; if false, the destination document should replace the current document in the same window. If this entry is absent, the conforming reader should act according to its preference. |
| T | dictionary | (Optional if F is present; otherwise required) A target dictionary (see Table 202) specifying path information to the target document. Each target dictionary specifies one element in the full path to the target and may have nested target dictionaries specifying additional elements. |
| Key | Type | Value |
|---|---|---|
| R | name | (Required) Specifies the relationship between the current document and the target (which may be an intermediate target). Valid values are P (the target is the parent of the current document) and C (the target is a child of the current document). |
| N | byte string | (Required if the value of R is C and the target is located in the EmbeddedFiles name tree; otherwise, it shall be absent) The name of the file in the EmbeddedFiles name tree. |
| P | integer or byte string | (Required if the value of R is C and the target is associated with a file attachment annotation; otherwise, it shall be absent) If the value is an integer, it specifies the page number (zero-based) in the current document containing the file attachment annotation. If the value is a string, it specifies a named destination in the current document that provides the page number of the file attachment annotation. |
| A | integer or text string | (Required if the value of R is C and the target is associated with a file attachment annotation; otherwise, it shall be absent) If the value is an integer, it specifies the index (zero-based) of the annotation in the Annots array (see Table 30) of the page specified by P. If the value is a text string, it specifies the value of NM in the annotation dictionary (see Table 164). |
| T | dictionary | (Optional) A target dictionary specifying additional path information to the target document. If this entry is absent, the current document is the target file containing the destination. |
EXAMPLE
The following example illustrates several possible relationships between source and target. Each object shown is an action dictionary for an embedded go-to action.
1 0 obj % Link to a child
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document) >>
>>
endobj
2 0 obj
<< /Type /Action % Link to the parent
/S /GoToE
/D (Chapter 1)
/T << /R /P >>
>>
endobj
3 0 obj % Link to a sibling
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /P
/T << /R /C
/N (Another embedded document) >>
>>
>>
endobj
4 0 obj % Link to an embedded file in an external document
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
/T << /R /C
/N (Embedded document) >>
>>
endobj
5 0 obj % Link from an embedded file to a normal file
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/F (someFile.pdf)
>>
endobj
6 0 obj % Link to a grandchild
<< /Type /Action
/S /GoToE
/D (Chapter 1)
/T << /R /C
/N (Embedded document)
/T << /R /C
/P (A destination name)
/A (annotName)
>>
>>
>>
endobj
7 0 obj % Link to a niece/nephew through the source’s parent
<< /Type /Action
/S /GoToE
/D (destination)
/T << /R /P
/T << /R /C
/N (Embedded document)
/T << /R /C
/P 3
/A (annotName)
>>
>>
>>
>>
endobj
12.6.4.5 启动操作¶
12.6.4.5 Launch Actions
启动动作用于启动应用程序或打开/打印文档。表203展示了专门针对这种类型动作的动作字典条目。
可选的Win、Mac和Unix条目允许动作字典包含用于启动指定应用程序的平台特定参数。如果给定平台不存在此类条目，则应使用F条目。表203展示了Windows平台的平台特定启动参数。在发布时，Mac OS和UNIX平台的参数尚未定义。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于启动动作，应为Launch。 |
| F | 文件规范 | （如果Win、Mac或Unix条目均不存在，则必需）要启动的应用程序或要打开/打印的文档。如果此条目不存在且符合规范的阅读器不理解任何其他替代条目，则不应执行任何操作。 |
| Win | 字典 | （可选）包含参数的字典（见表204）。 |
| Mac | （未定义） | （可选）Mac OS特定的启动参数；尚未定义。 |
| Unix | （未定义） | （可选）UNIX特定的启动参数；尚未定义。 |
| NewWindow | 布尔值 | （可选；PDF 1.2）一个标志，用于指定是否在新窗口中打开目标文档。如果此标志为false，则目标文档将在同一窗口中替换当前文档。如果此条目不存在，符合规范的阅读器应根据其当前偏好进行处理。如果F条目指定的文件不是PDF文档，则应忽略此条目。 |
| 键 | 类型 | 值 |
|---|---|---|
| F | 字节字符串 | （必需）要启动的应用程序文件名或要打开/打印的文档名称，采用标准的Windows路径名格式。如果名称字符串包含反斜杠字符()，则该反斜杠本身应前面再加一个反斜杠。 此值应为简单字符串；它不是文件规范。 |
| D | 字节字符串 | （可选）指定默认目录的字节字符串，采用标准的DOS语法。 |
| O | ASCII字符串 | （可选）指定要执行的操作的ASCII字符串： open 打开文档。 print 打印文档。 如果F条目指定的是应用程序而不是文档，则应忽略此条目并启动该应用程序。默认值：open。 |
| P | 字节字符串 | （可选）应传递给由F条目指定的应用程序的参数字符串。如果F指定的是文档，则应省略此条目。 |
A launch action launches an application or opens or prints a document. Table 203 shows the action dictionary entries specific to this type of action.
The optional Win, Mac, and Unix entries allow the action dictionary to include platform-specific parameters for launching the designated application. If no such entry is present for the given platform, the F entry shall be used instead. Table 203 shows the platform-specific launch parameters for the Windows platform. Parameters for the Mac OS and UNIX platforms are not yet defined at the time of publication.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Launch for a launch action. |
| F | file specification | (Required if none of the entries Win, Mac, or Unix is present) The application that shall be launched or the document that shall be opened or printed. If this entry is absent and the conforming reader does not understand any of the alternative entries, it shall do nothing. |
| Win | dictionary | (Optional) A dictionary containing parameters (see Table 204). |
| Mac | (undefined) | (Optional) Mac OS–specific launch parameters; not yet defined. |
| Unix | (undefined) | (Optional) UNIX-specific launch parameters; not yet defined. |
| NewWindow | boolean | (Optional; PDF 1.2) A flag specifying whether to open the destination document in a new window. If this flag is false, the destination document replaces the current document in the same window. If this entry is absent, the conforming reader should behave in accordance with its current preference. This entry shall be ignored if the file designated by the F entry is not a PDF document. |
| Key | Type | Value |
|---|---|---|
| F | byte string | (Required) The file name of the application that shall be launched or the document that shall be opened or printed, in standard Windows pathname format. If the name string includes a backslash character (), the backslash shall itself be preceded by a backslash. This value shall be a simple string; it is not a file specification. |
| D | byte string | (Optional) A bye string specifying the default directory in standard DOS syntax. |
| O | ASCII string | (Optional) An ASCII string specifying the operation to perform: open Open a document. print Print a document. If the F entry designates an application instead of a document, this entry shall be ignored and the application shall be launched. Default value: open. |
| P | byte string | (Optional) A parameter string that shall be passed to the application designated by the F entry. This entry shall be omitted if F designates a document. |
12.6.4.6 线索动作¶
12.6.4.6 Thread Actions
线程动作会跳转到文章线索（见12.4.3，“文章”）上指定的线索珠（bead），该线索可以在当前文档中，也可以在其他文档中。表205展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于线程动作，应为Thread。 |
| F | 文件规范 | （可选）包含线索的文件。如果此条目不存在，则线索在当前文件中。 |
| D | 字典、整数或文本字符串 | （必需）目标线索，以以下形式之一指定： 对线索字典的间接引用（见12.4.3，“文章”）。在这种情况下，线索应在当前文件中。 线索在其文档的Catalog的Threads数组中的索引（见7.7.2，“文档目录”）。数组中的第一个线索索引为0。 线索信息字典中指定的线索标题（见表160）。如果两个或更多线索具有相同的标题，则应使用文档Catalog的Threads数组中第一个出现的线索。 |
| B | 字典或整数 | （可选）目标线索中的线索珠，以以下形式之一指定： 对线索珠字典的间接引用（见12.4.3，“文章”）。在这种情况下，线索应在当前文件中。 线索珠在其线索中的索引。线索中的第一个线索珠索引为0。 |
A thread action jumps to a specified bead on an article thread (see 12.4.3, “Articles”), in either the current document or a different one. Table 205 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Thread for a thread action. |
| F | file specification | (Optional) The file containing the thread. If this entry is absent, the thread is in the current file. |
| D | dictionary, integer, or text string | (Required) The destination thread, specified in one of the following forms: An indirect reference to a thread dictionary (see 12.4.3, “Articles”). In this case, the thread shall be in the current file. The index of the thread within the Threads array of its document’s Catalog (see 7.7.2, “Document Catalog”). The first thread in the array has index 0. The title of the thread as specified in its thread information dictionary (see Table 160). If two or more threads have the same title, the one appearing first in the document Catalog’s Threads array shall be used. |
| B | dictionary or integer | (Optional) The bead in the destination thread, specified in one of the following forms: An indirect reference to a bead dictionary (see 12.4.3, “Articles”). In this case, the thread shall be in the current file. The index of the bead within its thread. The first bead in a thread has index 0. |
12.6.4.7 URI 操作¶
12.6.4.7 URI Actions
统一资源标识符（URI）是一个字符串，用于标识（解析为）互联网上的资源 —— 通常是超文本链接的目标文件，不过它也可能解析为一个查询或其他实体。（URI在互联网RFC 2396《统一资源标识符（URI）：通用语法》中有详细描述；见Bibliography的参考文献。）
URI动作会导致解析一个URI。表206展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于URI动作，应为URI。 |
| F | 文件规范 | （可选）包含线索的文件。如果此条目不存在，则线索在当前文件中。（注：此处关于“线索”的描述可能与URI动作本身关联不大，可能是文档中其他相关概念混淆在此处，原文如此） |
| URI | ASCII字符串 | （必需）要解析的统一资源标识符，采用7位ASCII编码。 |
| IsMap | 布尔值 | （可选）一个标志，用于指定在解析URI时是否跟踪鼠标位置（见本表后的讨论）。默认值：false。 此条目仅适用于由用户点击注释触发的动作；对于与大纲项或文档的OpenAction条目相关的动作，应忽略此条目。 |
如果IsMap标志为true且用户通过点击注释触发了URI动作，则触发动作时鼠标位置的坐标应从设备空间转换为用户空间，然后相对于注释矩形左上角（即与该URI动作相关联的注释中Rect条目的值）进行偏移。
示例1
如果用户空间中的鼠标坐标为\((x_m, y_m)\)，且注释矩形从左下角的\((ll_x, ll_y)\)延伸到右上角的\((ur_x, ur_y)\)，则最终坐标\((x_f, y_f)\)如下：
如果得到的坐标\((x_f, y_f)\)是小数，则应将其四舍五入为最接近的整数值。然后，这些值将附加到要解析的URI中，用逗号（2Ch）分隔，并以问号（3Fh）开头，如本示例所示：
示例2
http://www.adobe.com/intro?100,200
注1
为了支持URI动作，PDF文档的Catalog（见7.7.2，“文档目录”）可能包含一个URI条目，其值是一个URI字典。这样的字典只应定义一个条目（见表207）。
| 键 | 类型 | 值 |
|---|---|---|
| Base | ASCII字符串 | （可选）用于解析相对URI引用的基础URI。文档中的URI动作可以指定部分形式的URI，相对于此基础地址进行解释。如果未指定基础URI，则此类部分URI将相对于文档本身的位置进行解释。此条目的使用方式与HTML 4.01规范中描述的主体元素 |
注2
Base条目允许在文档可能脱离上下文被访问的情况下记录文档的URI。例如，如果文档已移动到新位置，但包含指向其他未移动文档的相对链接，则Base条目可用于将这些链接指向其他文档的真实位置，而不是移动后文档的位置 。
A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet—typically a file that is the destination of a hypertext link, although it may also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax; see the Bibliography.)
A URI action causes a URI to be resolved. Table 206 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be URI for a URI action. |
| F | file specification | (Optional) The file containing the thread. If this entry is absent, the thread is in the current file. |
| URI | ASCII string | (Required) The uniform resource identifier to resolve, encoded in 7-bit ASCII. |
| IsMap | boolean | (Optional) A flag specifying whether to track the mouse position when the URI is resolved (see the discussion following this Table). Default value: false. This entry applies only to actions triggered by the user’s clicking an annotation; it shall be ignored for actions associated with outline items or with a document’s OpenAction entry. |
If the IsMap flag is true and the user has triggered the URI action by clicking an annotation, the coordinates of the mouse position at the time the action has been triggered shall be transformed from device space to user space and then offset relative to the upper-left corner of the annotation rectangle (that is, the value of the Rect entry in the annotation with which the URI action is associated).
EXAMPLE 1
If the mouse coordinates in user space are \((x_m , y_m)\) and the annotation rectangle extends from \((ll_x , ll_y)\) at the lower-left to \((ur_x , ur_y)\) at the upper-right, the final coordinates \((x_f, y_f)\) are as follows:
If the resulting coordinates \((x_f , y_f)\) are fractional, they shall be rounded to the nearest integer values. They shall then be appended to the URI to be resolved, separated by COMMAS (2Ch) and preceded by a QUESTION MARK (3Fh), as shown in this example:
EXAMPLE 2
http://www.adobe.com/intro?100,200
NOTE 1
To support URI actions, a PDF document’s Catalog (see 7.7.2, “Document Catalog”) may include a URI entry whose value is a URI dictionary. Only one entry shall be defined for such a dictionary (see Table 207).
| Key | Type | Value |
|---|---|---|
| Base | ASCII string | (Optional) The base URI that shall be used in resolving relative URI references. URI actions within the document may specify URIs in partial form, to be interpreted relative to this base address. If no base URI is specified, such partial URIs shall be interpreted relative to the location of the document itself. The use of this entry is parallel to that of the body element |
NOTE 2
The Base entry allows the URI of the document to be recorded in situations in which the document may be accessed out of context. For example, if a document has been moved to a new location but contains relative links to other documents that have not been moved, the Base entry could be used to refer such links to the true location of the other documents, rather than that of the moved document.
12.6.4.8 声音动作¶
12.6.4.8 Sound Actions
声音动作（PDF 1.2）通过计算机的扬声器播放声音。表208展示了专门针对这种类型动作的动作字典条目。声音相关内容见13.3，“声音”。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于声音动作，应为Sound。 |
| Sound | 流 | （必需）定义要播放声音的声音对象（见13.3，“声音”）。 |
| Volume | 数字 | （可选）播放声音的音量，范围为−1.0到1.0。默认值：1.0。 |
| Synchronous | 布尔值 | （可选）一个标志，用于指定是以同步方式还是异步方式播放声音。如果此标志为true，符合规范的阅读器将保持控制权，在声音完全播放完毕之前，除了取消声音外，不允许用户进行其他交互。默认值：false。 |
| Repeat | 布尔值 | （可选）一个标志，用于指定是否无限重复播放声音。如果存在此条目，则忽略Synchronous条目。默认值：false。 |
| Mix | 布尔值 | （可选）一个标志，用于指定是否将此声音与任何其他正在播放的声音混合。如果此标志为false，在开始播放此声音之前，将停止任何先前正在播放的声音；这可用于停止重复播放的声音（见Repeat）。默认值：false。 |
A sound action (PDF 1.2) plays a sound through the computer’s speakers. Table 208 shows the action dictionary entries specific to this type of action. Sounds are discussed in 13.3, “Sounds.”
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Sound for a sound action. |
| Sound | stream | (Required) A sound object defining the sound that shall be played (see 13.3, “Sounds”). |
| Volume | number | (Optional) The volume at which to play the sound, in the range −1.0 to 1.0. Default value: 1.0. |
| Synchronous | boolean | (Optional) A flag specifying whether to play the sound synchronously or asynchronously. If this flag is true, the conforming reader retains control, allowing no further user interaction other than canceling the sound, until the sound has been completely played. Default value: false. |
| Repeat | boolean | (Optional) A flag specifying whether to repeat the sound indefinitely. If this entry is present, the Synchronous entry shall be ignored. Default value: false. |
| Mix | boolean | (Optional) A flag specifying whether to mix this sound with any other sound already playing. If this flag is false, any previously playing sound shall be stopped before starting this sound; this can be used to stop a repeating sound (see Repeat). Default value: false. |
12.6.4.9 影片动作¶
12.6.4.9 Movie Actions
电影动作（PDF 1.2）可用于在浮动窗口或电影注释的注释矩形内播放电影（见12.5.6.17，“电影注释”和13.4，“电影”）。电影注释应与包含电影动作的链接注释或大纲项的目标页面相关联，或者与动作相关联的页面对象相关联。
注
电影动作本身并不保证在尝试播放电影之前会显示该电影所在的页面；此类页面切换动作应明确执行。
电影动作字典的内容与电影激活字典的内容相同（见表296），另外还有表209中显示的条目。与电影注释相关联的激活字典的内容提供默认值。电影动作字典中指定的任何信息都将覆盖这些默认值。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于电影动作，应为Movie。 |
| Annotation | 字典 | （可选）对电影注释的间接引用，用于标识要播放的电影。 |
| T | 文本字符串 | （可选）电影注释的标题，用于标识要播放的电影。 字典中应包含Annotation或T条目之一，但不能同时包含两者。 |
| Operation | 名称 | （可选）要对电影执行的操作： Play 开始播放电影，使用字典的Mode条目指定的播放模式（见表296）。如果电影当前处于暂停状态，在播放前应将其重新定位到开头（或者如果存在字典的Start条目，则定位到该条目指定的起始点）。 Stop 停止播放电影。 Pause 暂停正在播放的电影。 Resume 继续播放暂停的电影。 默认值：Play。 |
A movie action (PDF 1.2) can be used to play a movie in a floating window or within the annotation rectangle of a movie annotation (see 12.5.6.17, “Movie Annotations” and 13.4, “Movies”). The movie annotation shall be associated with the page that is the destination of the link annotation or outline item containing the movie action, or with the page object with which the action is associated.
NOTE
A movie action by itself does not guarantee that the page the movie is on will be displayed before attempting to play the movie; such page change actions shall be done explicitly.
The contents of a movie action dictionary are identical to those of a movie activation dictionary (see Table 296), with the additional entries shown in Table 209. The contents of the activation dictionary associated with the movie annotation provide the default values. Any information specified in the movie action dictionary overrides these values.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Movie for a movie action. |
| Annotation | dictionary | (Optional) An indirect reference to a movie annotation identifying the movie that shall be played. |
| T | text string | (Optional) The title of a movie annotation identifying the movie that shall be played. The dictionary shall include either an Annotation or a T entry but not both. |
| Operation | name | (Optional) The operation that shall be performed on the movie: PlayStart playing the movie, using the play mode specified by the dictionary’s Mode entry (see Table 296). If the movie is currently paused, it shall be repositioned to the beginning before playing (or to the starting point specified by the dictionary’s Start entry, if present). Stop Stop playing the movie. Pause Pause a playing movie. Resume Resume a paused movie. Default value: Play. |
12.6.4.10 隐藏操作¶
12.6.4.10 Hide Actions
隐藏动作（PDF 1.2）通过设置或清除注释的隐藏标志（见12.5.3，“注释标志”）来隐藏或显示屏幕上的一个或多个注释。这种类型的动作可以与外观流和触发事件（第12.5.5节“外观流”和第12.6.3节“触发事件”）结合使用，以在屏幕上显示弹出帮助信息。
注
注释的附加动作字典中的E（进入）和X（退出）触发事件可用于在用户将光标移入和移出页面上注释的活动区域时显示和隐藏该注释。这可用于弹出一个帮助标签或工具提示，描述在该页面位置点击的效果。
表210展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于隐藏动作，应为Hide。 |
| T | 字典、文本字符串或数组 | （必需）要隐藏或显示的注释，应以以下任何一种形式指定： 对注释字典的间接引用 一个文本字符串，给出受影响的交互式表单字段的关联小部件注释或注释的完全限定字段名（见12.7.3.2，“字段名”） 这样的字典或文本字符串的数组 |
| H | 布尔值 | （可选）一个标志，指示是否隐藏注释（true）或显示它（false）。默认值：true。 |
A hide action (PDF 1.2) hides or shows one or more annotations on the screen by setting or clearing their Hidden flags (see 12.5.3, “Annotation Flags”). This type of action can be used in combination with appearance streams and trigger events (Sections 12.5.5, “Appearance Streams,” and 12.6.3, “Trigger Events”) to display pop-up help information on the screen.
NOTE
The E (enter) and X (exit) trigger events in an annotation’s additional-actions dictionary can be used to show and hide the annotation when the user rolls the cursor in and out of its active area on the page. This can be used to pop up a help label, or tool tip, describing the effect of clicking at that location on the page.
Table 210 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Hide for a hide action. |
| T | dictionary, text string, or array | (Required) The annotation or annotations to be hidden or shown, shall be
specified in any of the following forms: An indirect reference to an annotation dictionary A text string giving the fully qualified field name of an interactive form field whose associated widget annotation or annotations are to be affected (see 12.7.3.2, “Field Names”) An array of such dictionaries or text strings |
| H | boolean | (Optional) A flag indicating whether to hide the annotation (true) or show it (false). Default value: true. |
12.6.4.11 命名动作¶
12.6.4.11 Named Actions
表211列出了几种符合规范的阅读器应支持的命名动作（PDF 1.2）；未来可能会添加更多名称。
| 名称 | 动作 |
|---|---|
| NextPage | 转到文档的下一页。 |
| PrevPage | 转到文档的上一页。 |
| FirstPage | 转到文档的第一页。 |
| LastPage | 转到文档的最后一页。 |
注
符合规范的阅读器可能支持其他非标准的命名动作，但使用这些动作的任何文档都不具有可移植性。如果查看器遇到一个不适合其查看平台的命名动作，或者如果查看器不识别该名称，它将不执行任何操作。
表212展示了专门针对命名动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于命名动作，应为Named。 |
| N | 名称 | （必需）要执行的动作的名称（见表211）。 |
Table 211 lists several named actions (PDF 1.2) that conforming readers shall support; further names may be added in the future.
| Name | Action |
|---|---|
| NextPage | Go to the next page of the document. |
| PrevPage | Go to the previous page of the document. |
| FirstPage | Go to the first page of the document. |
| LastPage | Go to the last page of the document.. |
NOTE
Conforming readers may support additional, nonstandard named actions, but any document using them is not portable. If the viewer encounters a named action that is inappropriate for a viewing platform, or if the viewer does not recognize the name, it shall take no action.
Table 212 shows the action dictionary entries specific to named actions.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Named for a named action. |
| N | name | (Required) The name of the action that shall be performed (see Table 211). |
12.6.4.12 设置 OCG 状态操作¶
12.6.4.12 Set-OCG-State Actions
设置可选内容组状态动作（PDF 1.5）用于设置一个或多个可选内容组的状态（见8.11，“可选内容”）。表213展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于设置可选内容组状态动作，应为SetOCGState。 |
| State | 数组 | （必需）由任意数量的序列组成的数组，每个序列以名称对象（ON、OFF或Toggle）开头，后跟一个或多个可选内容组字典。数组元素应从左到右处理；每个名称将应用于后续组，直到遇到下一个名称： ON 将后续组的状态设置为开启 OFF 将后续组的状态设置为关闭 Toggle 切换后续组的状态。 |
| PreserveRB | 布尔值 | （可选）如果为true，表示在应用State数组中的状态时，应保留可选内容组之间的单选按钮状态关系（由当前配置字典中的RBGroups条目指定；见表101）。也就是说，如果在处理State数组期间某个组被设置为ON（通过ON或Toggle），则属于同一单选按钮组的任何其他组都将被关闭。如果某个组被设置为OFF，则对其他组没有影响。 如果PreserveRB为false，则忽略任何单选按钮状态关系。 默认值：true。 |
执行设置可选内容组状态动作时，State数组应从左到右处理。每个名称将应用于数组中遇到的后续组，直到遇到下一个名称，如下例所示。
示例1
<< /S /SetOCGState
/State [/OFF 2 0 R 3 0 R /Toggle 16 0 R 19 0 R /ON 5 0 R]
>>
一个组可能在State数组中出现多次；每次遇到该组时，都将根据最近的名称设置其状态。ON、OFF和Toggle序列没有特定的顺序要求。数组中可以包含多个具有相同名称的序列。
示例2
如果数组包含[/OFF 1 0 R /Toggle 1 0 R]，执行动作后该组的状态将为ON。
注
虽然规范允许一个组在State数组中出现多次，但这并非用于实现动画或其他顺序绘制操作。PDF处理应用程序可以累积所有状态更改，并在重新绘制之前同时将净更改应用于所有受影响的组 。
A set-OCG-state action (PDF 1.5) sets the state of one or more optional content groups (see 8.11, “Optional Content”). Table 213 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be SetOCGState for a set-OCG-state action. |
| State | array | (Required) An array consisting of any number of sequences beginning with a name object (ON, OFF, or Toggle) followed by one or more optional content group dictionaries. The array elements shall be processed from left to right; each name shall be applied to the subsequent groups until the next name is encountered: ON sets the state of subsequent groups to ON OFF sets the state of subsequent groups to OFF Toggle reverses the state of subsequent groups. |
| PreserveRB | boolean | (Optional) If true, indicates that radio-button state relationships between optional content groups (as specified by the RBGroups entry in the current configuration dictionary; see Table 101) should be preserved when the states in the State array are applied. That is, if a group is set to ON (either by ON or Toggle) during processing of the State array, any other groups belonging to the same radio-button group shall be turned OFF. If a group is set to OFF, there is no effect on other groups. If PreserveRB is false, radio-button state relationships, if any, shall be ignored. Default value: true. |
When a set-OCG-state action is performed, the State array shall be processed from left to right. Each name shall be applied to subsequent groups in the array until the next name is encountered, as shown in the following example.
EXAMPLE 1
<< /S /SetOCGState
/State [/OFF 2 0 R 3 0 R /Toggle 16 0 R 19 0 R /ON 5 0 R]
>>
A group may appear more than once in the State array; its state shall be set each time it is encountered, based on the most recent name. ON, OFF and Toggle sequences have no required order. More than one sequence in the array may contain the same name.
EXAMPLE 2
If the array contained [/OFF 1 0 R /Toggle 1 0 R], the group’s state would be ON after the action was performed.
NOTE
While the specification allows a group to appear more than once in the State array, this is not intended to implement animation or any other sequential drawing operations. PDF processing applications are free to accumulate all state changes and apply only the net changes simultaneously to all affected groups before redrawing.
12.6.4.13 演绎行动¶
12.6.4.13 Rendition Actions
呈现动作（PDF 1.5）用于控制多媒体内容的播放（见13.2，“多媒体”）。此动作可通过以下方式使用：
- 开始播放呈现对象（见13.2.3，“呈现”），并将其与屏幕注释（见12.5.6.18，“屏幕注释”）相关联。除非另有指定，否则屏幕注释将指定呈现的播放位置。
- 停止、暂停或继续播放正在播放的呈现。
- 触发执行可能执行自定义操作的JavaScript脚本。表214列出了呈现动作字典中的条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于呈现动作，应为Rendition。 |
| R | 字典 | （当OP存在且值为0或4时必需；否则可选）一个呈现对象（见13.2.3，“呈现”）。 |
| AN | 字典 | （如果OP存在且值为0、1、2、3或4，则必需；否则可选）对屏幕注释的间接引用（见12.5.6.18，“屏幕注释”）。 |
| OP | 整数 | （如果不存在JS，则必需；否则可选）触发动作时要执行的操作。有效值应为：
|
| JS | 文本字符串或流 | （如果不存在OP，则必需；否则可选）包含在触发动作时要执行的JavaScript脚本的文本字符串或流。 |
JS条目和OP条目必须有一个存在。如果两者都存在，OP被视为备用项，当符合规范的阅读器无法执行JavaScript时将执行OP。如果OP的值无法识别且没有JS条目，则该动作无效。
在某些情况下，暂停（OP值为2）或继续（OP值为3）操作可能没有意义，或者播放器可能不支持这些操作。在这种情况下，应通知用户操作执行失败。
示例
一个JPEG图像
在执行呈现动作之前，符合规范的阅读器应确保屏幕注释字典的P条目引用有效的页面对象，并且该注释存在于页面对象的Annots数组中（见表30）。
即使注释本身不可见（例如，其隐藏或无视图标志（见表165）已设置），呈现也可能在屏幕注释占据的矩形区域内播放。如果屏幕注释由于其页面位置未由查看器显示而不可见，则呈现也不可见。但是，如果视图发生变化（例如通过滚动），则可能变得可见 。
A rendition action (PDF 1.5) controls the playing of multimedia content (see 13.2, “Multimedia”). This action may be used in the following ways:
- To begin the playing of a rendition object (see 13.2.3, “Renditions”), associating it with a screen annotation (see 12.5.6.18, “Screen Annotations”). The screen annotation specifies where the rendition shall be played unless otherwise specified.
- To stop, pause, or resume a playing rendition.
- To trigger the execution of a JavaScript script that may perform custom operations. Table 214 lists the entries in a rendition action dictionary.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Rendition for a rendition action. |
| R | dictionary | (Required when OP is present with a value of 0 or 4; otherwise optional) A rendition object (see 13.2.3, “Renditions”). |
| AN | dictionary | (Required if OP is present with a value of 0, 1, 2, 3 or 4; otherwise optional) An indirect reference to a screen annotation (see 12.5.6.18, “Screen Annotations”). |
| OP | integer | (Required if JS is not present; otherwise optional) The operation to perform when the action is triggered. Valid values shall be:
|
| JS | text string or stream | (Required if OP is not present; otherwise optional) A text string or stream containing a JavaScript script that shall be executed when the action is triggered. |
Either the JS entry or the OP entry shall be present. If both are present, OP is considered a fallback that shall be executed if the conforming reader is unable to execute JavaScripts. If OP has an unrecognized value and there is no JS entry, the action is invalid.
In some situations, a pause (OP value of 2) or resume (OP value of 3) operation may not make sense or the player may not support it. In such cases, the user should be notified of the failure to perform the operation.
EXAMPLE
A JPEG image
Before a rendition action is executed, the conforming reader shall make sure that the P entry of the screen annotation dictionary references a valid page object and that the annotation is present in the page object’s Annots array (see Table 30).
A rendition may play in the rectangle occupied by a screen annotation, even if the annotation itself is not visible; for example, if its Hidden or NoView flags (see Table 165) are set. If a screen annotation is not visible because its location on the page is not being displayed by the viewer, the rendition is not visible. However, it may become visible if the view changes, such as by scrolling.
12.6.4.14 过渡行动¶
12.6.4.14 Transition Actions
转换动作（PDF 1.5）可用于在一系列动作执行期间控制绘制操作。如12.6.2，“动作字典”中所讨论的，动作字典中的Next条目可以指定一个动作序列。符合规范的阅读器通常应在该序列开始时暂停绘制，并在序列结束时恢复绘制。如果在动作序列中存在转换动作，符合规范的阅读器应渲染上一次动作完成后页面视图区域的状态，并使用动作字典中指定的转换效果来显示该状态（见表215）。一旦此转换完成，绘制操作将再次暂停。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于转换动作，应为Trans。 |
| Trans | 字典 | （必需）用于更新显示的转换效果（见表162）。 |
A transition action (PDF 1.5) may be used to control drawing during a sequence of actions. As discussed in 12.6.2, “Action Dictionaries,” the Next entry in an action dictionary may specify a sequence of actions. Conforming readers shall normally suspend drawing when such a sequence begins and resume drawing when it ends. If a transition action is present during a sequence, the conforming reader shall render the state of the page viewing area as it exists after completion of the previous action and display it using a transition specified in the action dictionary (see Table 215). Once this transition completes, drawing shall be suspended again.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be Trans for a transition action. |
| Trans | dictionary | (Required) The transition to use for the update of the display (see Table 162). |
12.6.4.15 进入 3D 视图操作¶
12.6.4.15 Go-To-3D-View Actions
跳转到3D视图动作（PDF 1.6）用于标识一个3D注释，并为该注释指定一个要使用的视图（见13.6，“3D艺术作品”）。表216展示了跳转到3D视图动作字典中的条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于跳转到3D视图动作，应为GoTo3DView。 |
| TA | 字典 | （必需）要设置视图的目标注释。 |
| V | （多种类型） | （必需）要使用的视图。它可以是以下类型之一： 一个3D视图字典（见[13.6.4]，“3D视图”）。 一个整数，指定3D流中VA数组的索引（见表300）。 一个文本字符串，与VA数组中某个视图的IN条目匹配（见表304）。 一个名称，用于指示VA数组中的第一个（F）、最后一个（L）、下一个（N）、上一个（P）或默认（D）条目；见本表后的讨论。 |
V条目选择要应用于TA指定的注释的视图。此视图可以是3D流的VA条目指定的预定义视图之一（见表300），也可以是此处指定的唯一视图。
如果预定义视图是通过名称N（下一个）或P（上一个）指定的，则应按以下方式解释：
- 当上一个应用的视图是通过VA数组指定的时，N和P分别表示VA数组中的下一个和上一个条目（如有必要，会循环）。
- 当上一个视图不是通过VA指定的时，使用N或P应恢复到默认视图 。
A go-to-3D-view action (PDF 1.6) identifies a 3D annotation and specifies a view for the annotation to use (see 13.6, “3D Artwork”). Table 216 shows the entries in a go-to-3D-view action dictionary.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be GoTo3DView for a transition action. |
| TA | dictionary | (Required) The target annotation for which to set the view. |
| V | (various) | (Required) The view to use. It may be one of the following types: A 3D view dictionary (see [13.6.4], “3D Views”). An integer specifying an index into the VA array in the 3D stream (see Table 300). A text string matching the IN entry in one of the views in the VA array (see Table 304). A name that indicates the first (F), last (L), next (N), previous (P), or default (D) entries in the VA array; see discussion following this Table. |
The V entry selects the view to apply to the annotation specified by TA. This view may be one of the predefined views specified by the VA entry of the 3D stream (see Table 300) or a unique view specified here.
If the predefined view is specified by the names N (next) or P (previous), it should be interpreted in the following way:
- When the last view applied was specified by means of the VA array, N and P indicate the next and previous entries, respectively, in the VA array (wrapping around if necessary).
- When the last view was not specified by means of VA, using N or P should result in reverting to the default view.
12.6.4.16 JavaScript 动作¶
12.6.4.16 JavaScript Actions
当调用JavaScript动作时，符合规范的处理器应执行用JavaScript编程语言编写的脚本。根据脚本的性质，文档中的各种交互式表单字段可能会更新其值或改变其视觉外观。Mozilla开发中心的客户端JavaScript参考和Adobe Acrobat JavaScript API参考（见参考文献）详细介绍了JavaScript脚本的内容和效果。表217展示了专门针对这种类型动作的动作字典条目。
| 键 | 类型 | 值 |
|---|---|---|
| S | 名称 | （必需）此字典描述的动作类型；对于JavaScript动作，应为JavaScript。 |
| JS | 文本字符串或文本流 | （必需）包含要执行的JavaScript脚本的文本字符串或文本流。 字符串或流的内容应使用PDFDocEncoding或Unicode编码（后者通过Unicode前缀U+FEFF标识）进行编码。 |
为了支持在JavaScript脚本中使用带参数的函数调用，PDF文档名称字典（见7.7.4，“名称字典”）中的JavaScript条目可能包含一个名称树，该名称树将名称字符串映射到文档级JavaScript动作。当文档打开时，此名称树中的所有动作都将被执行，从而为文档中的其他脚本定义可用的JavaScript函数。
注
名称字典中与各个JavaScript动作相关联的名称字符串仅作为组织和打包脚本的一种便捷方式。这些名称是任意的，无需与JavaScript命名空间有任何关联 。
Upon invocation of a JavaScript action, a conforming processor shall execute a script that is written in the JavaScript programming language. Depending on the nature of the script, various interactive form fields in the document may update their values or change their visual appearances. Mozilla Development Center’s Client- Side JavaScript Reference and the Adobe JavaScript for Acrobat API Reference (see the Bibliography) give details on the contents and effects of JavaScript scripts. Table 217 shows the action dictionary entries specific to this type of action.
| Key | Type | Value |
|---|---|---|
| S | name | (Required) The type of action that this dictionary describes; shall be JavaScript for a JavaScript action. |
| JS | text string or text stream | (Required) A text string or text stream containing the JavaScript script to be executed. PDFDocEncoding or Unicode encoding (the latter identified by the Unicode prefix U+ FEFF) shall be used to encode the contents of the string or stream. |
To support the use of parameterized function calls in JavaScript scripts, the JavaScript entry in a PDF document’s name dictionary (see 7.7.4, “Name Dictionary”) may contain a name tree that maps name strings to document-level JavaScript actions. When the document is opened, all of the actions in this name tree shall be executed, defining JavaScript functions for use by other scripts in the document.
NOTE
The name strings associated with individual JavaScript actions in the name dictionary serve merely as a convenient means for organizing and packaging scripts. The names are arbitrary and need not bear any relation to the JavaScript name space.