automating-keynote

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Automating Keynote (JXA-first, AppleScript discovery)

实现Keynote自动化（优先使用JXA，结合AppleScript探索）

Relationship to the macOS automation skill

与macOS自动化技能的关系

This skill focuses on Keynote-specific automation (documents, slides, charts).
Use
```
automating-mac-apps
```
for cross-app workflows or general macOS scripting foundations.
Assumes Apple Events knowledge from the related skill.
PyXA Installation: To use PyXA examples in this skill, see the installation instructions in
```
automating-mac-apps
```
skill (PyXA Installation section).

本技能专注于Keynote专属的自动化操作（文档、幻灯片、图表等）。
跨应用工作流或通用macOS脚本基础操作请使用
```
automating-mac-apps
```
技能。
假定使用者已掌握相关技能中的Apple Events知识。
PyXA安装： 若要使用本技能中的PyXA示例，请查看
```
automating-mac-apps
```
技能中的安装说明（PyXA安装章节）。

Core Framing

核心框架

JXA (JavaScript for Automation) enables macOS app scripting with JavaScript syntax.
AppleScript dictionaries define Keynote's object model—discover via Script Editor.
JXA objects are specifiers: read with methods like
```
.name()
```
, write with assignments.
Production scripts use JXA for reliability; AppleScript for prototyping.
Important: The JXA
```
Path()
```
function is required when specifying file paths to Keynote (e.g., for images, exports, or opening documents). Use
```
Path("/path/to/file")
```
instead of plain strings.

JXA（JavaScript for Automation）允许使用JavaScript语法编写macOS应用脚本。
AppleScript字典定义了Keynote的对象模型——可通过Script Editor探索。
JXA对象是指定符：使用
```
.name()
```
等方法读取，通过赋值操作写入。
生产环境脚本优先使用JXA以保证可靠性；AppleScript用于原型开发。
重要提示： 向Keynote指定文件路径（例如图片、导出文件或打开文档的路径）时，必须使用JXA的
```
Path()
```
函数。请使用
```
Path("/path/to/file")
```
而非纯字符串。

Workflow (default)

默认工作流程

Discover terms in Script Editor > File > Open Dictionary > Keynote.

Prototype minimal AppleScript:

tell application "Keynote" to get name of document 1

Port to JXA:

Application("Keynote").documents[0].name()

with try-catch blocks.

Validate with read-only probes:

Application("Keynote").documents.length > 0

Use UI scripting only when dictionary lacks features (e.g.
```
Application("System Events")
```
).

在Script Editor中通过「文件」>「打开字典」>「Keynote」探索术语。

编写极简AppleScript原型：

tell application "Keynote" to get name of document 1

。

转换为JXA代码：
```
Application("Keynote").documents[0].name()
```
，并添加try-catch块。

使用只读探测验证：

Application("Keynote").documents.length > 0

。

仅当字典中缺少对应功能时才使用UI脚本（例如
```
Application("System Events")
```
）。

Quick Examples

快速示例

Prototype (AppleScript):

applescript

tell application "Keynote"
    get name of document 1
end tell

Production (JXA):

javascript

const keynote = Application("Keynote");
if (keynote.documents.length > 0) {
    console.log(keynote.documents[0].name());
}

Create Slide:

javascript

const doc = keynote.documents[0];
const slide = doc.slides.push(keynote.Slide({baseSlide: doc.masterSlides['Title - Center']}));
slide.defaultTitleItem.objectText = "New Slide";

Add Image to Slide (note Path() usage):

javascript

const slide = doc.slides[0];
const img = keynote.Image({
  file: Path("/Users/you/Desktop/diagram.png"),  // Path() required!
  position: { x: 100, y: 100 },
  width: 800
});
slide.images.push(img);

原型（AppleScript）：

applescript

tell application "Keynote"
    get name of document 1
end tell

生产环境代码（JXA）：

javascript

const keynote = Application("Keynote");
if (keynote.documents.length > 0) {
    console.log(keynote.documents[0].name());
}

创建幻灯片：

javascript

const doc = keynote.documents[0];
const slide = doc.slides.push(keynote.Slide({baseSlide: doc.masterSlides['Title - Center']}));
slide.defaultTitleItem.objectText = "New Slide";

向幻灯片添加图片（注意Path()的使用）：

javascript

const slide = doc.slides[0];
const img = keynote.Image({
  file: Path("/Users/you/Desktop/diagram.png"),  // 必须使用Path()!
  position: { x: 100, y: 100 },
  width: 800
});
slide.images.push(img);

Validation Checklist

验证清单

After implementing Keynote automation:

Verify Keynote is running and accessible
Test slide creation with master slide assignment
Confirm image paths use
```
Path()
```
function
Check text rendering in default text items
Validate export operations complete without errors

实现Keynote自动化后，请检查以下项：

验证Keynote已运行且可访问
测试基于母版幻灯片的幻灯片创建功能
确认图片路径使用了
```
Path()
```
函数
检查默认文本项中的文本渲染效果
验证导出操作可无错误完成

When Not to Use

不适用场景

For cross-platform presentation automation (use PowerPoint with Python libraries)
When AppleScript alone suffices (skip JXA complexity)
For web-based presentations (Google Slides, reveal.js)
For non-macOS platforms

跨平台演示文稿自动化（请结合Python库使用PowerPoint）
仅用AppleScript即可满足需求时（避免JXA的复杂性）
基于Web的演示文稿（Google Slides、reveal.js）
非macOS平台

What to load

需加载的资源

Keynote JXA basics + runtime caveats:

automating-keynote/references/keynote-basics.md

Keynote recipes (slides, text, images, export):

automating-keynote/references/keynote-recipes.md

Deck generator example:

automating-keynote/references/keynote-deck-generator.md

Chart-aware deck pattern:

automating-keynote/references/keynote-chart-aware-deck.md

Advanced workflows (charts bridge, magic move, UI scripting):
```
automating-keynote/references/keynote-advanced.md
```

PyXA (Python) practical examples:

automating-keynote/references/keynote-pyxa.md

PyXA API Reference (complete class/method docs):

automating-keynote/references/keynote-pyxa-api-reference.md

Keynote JXA基础 + 运行时注意事项：

automating-keynote/references/keynote-basics.md

Keynote操作指南（幻灯片、文本、图片、导出）：
```
automating-keynote/references/keynote-recipes.md
```

演示文稿生成器示例：

automating-keynote/references/keynote-deck-generator.md

支持图表的演示文稿模式：

automating-keynote/references/keynote-chart-aware-deck.md

高级工作流（图表桥接、神奇移动、UI脚本）：
```
automating-keynote/references/keynote-advanced.md
```

PyXA（Python）实用示例：

automating-keynote/references/keynote-pyxa.md

PyXA API参考（完整类/方法文档）：

automating-keynote/references/keynote-pyxa-api-reference.md

automating-keynote

Original

Translation

Automating Keynote (JXA-first, AppleScript discovery)

实现Keynote自动化（优先使用JXA，结合AppleScript探索）

Contents

目录

Relationship to the macOS automation skill

与macOS自动化技能的关系

Core Framing

核心框架

Workflow (default)

默认工作流程

Quick Examples

快速示例

Validation Checklist

验证清单

When Not to Use

不适用场景

What to load

需加载的资源