automating-contacts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Automating Contacts (JXA-first, AppleScript discovery)

Contacts自动化（优先JXA，结合AppleScript查询）

Relationship to Other Skills

与其他技能的关联

Standalone for Contacts: Use this skill for Contacts-specific operations (querying, CRUD, groups).
Reuse
automating-mac-apps
for: TCC permissions setup, shell command helpers, UI scripting fallbacks, and ObjC bridge patterns.
Integration: Load both skills when combining Contacts automation with broader macOS scripting.
PyXA Installation: To use PyXA examples in this skill, see the installation instructions in
```
automating-mac-apps
```
skill (PyXA Installation section).

Contacts独立技能： 此技能适用于Contacts专属操作（查询、CRUD、群组管理）。
复用
automating-mac-apps
技能：用于TCC权限设置、Shell命令助手、UI脚本降级方案以及ObjC桥接模式。
集成使用： 当需要将Contacts自动化与更广泛的macOS脚本编写结合时，同时加载这两个技能。
PyXA安装： 若要使用本技能中的PyXA示例，请查看
```
automating-mac-apps
```
技能中的安装说明（PyXA安装章节）。

Core Framing

核心框架

Contacts dictionary is AppleScript-first; discover there, implement in JXA
Object specifiers: read with methods (
```
name()
```
,
```
emails()
```
), write with assignments
Multi-value fields (emails, phones, addresses) are elements; use constructor +
```
.push()
```
Group membership:
```
add ... to
```
command or
```
.people.push
```
; handle duplicates defensively
TCC permissions required: running host must have Contacts access

Contacts字典以AppleScript优先；先在AppleScript中查询验证，再用JXA实现
对象指定符：通过方法读取（如
```
name()
```
、
```
emails()
```
），通过赋值写入
多值字段（邮箱、电话、地址）为元素类型；使用构造函数 +
```
.push()
```
添加
群组成员：使用
```
add ... to
```
命令或
```
.people.push
```
；需防御性处理重复成员
需要TCC权限：运行主体必须获得Contacts访问权限

Workflow (default)

工作流（默认）

Inspect the Contacts dictionary in Script Editor (JavaScript view).
Prototype minimal AppleScript to validate verbs; port to JXA with specifier reads/writes.
Use
```
.whose
```
for coarse filtering; fall back to hybrid (coarse filter + JS refine) when needed.
Create records with proxy +
```
make
```
, then assign primitives and push multi-values;
```
Contacts.save()
```
to persist.
Verify persistence: check
```
person.id()
```
exists after save; handle TCC permission errors.
Manage groups after person creation; guard against duplicate membership with existence checks.
For photos or broken bridges, use ObjC/clipboard fallback; for heavy queries, batch read or pre-filter.
Test operations: run→check results→fix errors in iterative loop.

在脚本编辑器（JavaScript视图）中查看Contacts字典。
编写最简AppleScript原型验证操作逻辑；再移植到JXA，处理指定符的读写。
使用
```
.whose
```
进行粗粒度过滤；必要时降级为混合方式（粗过滤 + JavaScript精调）。
通过代理 +
```
make
```
创建记录，然后赋值基本属性并添加多值字段；调用
```
Contacts.save()
```
持久化。
验证持久化：保存后检查
```
person.id()
```
是否存在；处理TCC权限错误。
创建联系人后管理群组；添加成员前检查是否已存在，避免重复。
针对照片或桥接异常场景，使用ObjC/剪贴板降级方案；针对大量查询，采用批量读取或预过滤。
测试操作：执行→检查结果→迭代修复错误。

Validation Checklist

验证清单

Contacts permissions granted (System Settings > Privacy & Security > Contacts)
Dictionary inspected and verbs validated in Script Editor
AppleScript prototype runs without errors
JXA port handles specifiers correctly
Multi-value fields pushed to arrays properly
Groups existence checked before creation
Operations saved and verified with
```
.id()
```
checks
Error handling wraps all operations

已授予Contacts权限（系统设置 > 隐私与安全性 > Contacts）
已查看字典并在脚本编辑器中验证操作逻辑
AppleScript原型可正常运行无错误
JXA移植版本可正确处理指定符
多值字段已正确添加到数组
创建群组前已检查是否存在
操作已保存并通过
```
.id()
```
验证
所有操作已包裹错误处理

Quickstart (upsert + group)

快速入门（更新插入 + 群组管理）

javascript

const Contacts = Application("Contacts");
const email = "ada@example.com";
try {
  const existing = Contacts.people.whose({ emails: { value: { _equals: email } } })();
  const person = existing.length ? existing[0] : Contacts.Person().make();
  person.firstName = "Ada";
  person.lastName = "Lovelace";
  
  // Handle multi-value email
  const work = Contacts.Email({ label: "Work", value: email });
  person.emails.push(work);
  Contacts.save();
  
  // Handle groups with error checking
  let grp;
  try { 
    grp = Contacts.groups.byName("VIP"); 
    grp.name(); // Verify exists
  } catch (e) {
    grp = Contacts.Group().make(); 
    grp.name = "VIP";
  }
  Contacts.add(person, { to: grp });
  Contacts.save();
  console.log("Contact upserted successfully");
} catch (error) {
  console.error("Contacts operation failed:", error);
}

javascript

const Contacts = Application("Contacts");
const email = "ada@example.com";
try {
  const existing = Contacts.people.whose({ emails: { value: { _equals: email } } })();
  const person = existing.length ? existing[0] : Contacts.Person().make();
  person.firstName = "Ada";
  person.lastName = "Lovelace";
  
  // Handle multi-value email
  const work = Contacts.Email({ label: "Work", value: email });
  person.emails.push(work);
  Contacts.save();
  
  // Handle groups with error checking
  let grp;
  try { 
    grp = Contacts.groups.byName("VIP"); 
    grp.name(); // Verify exists
  } catch (e) {
    grp = Contacts.Group().make(); 
    grp.name = "VIP";
  }
  Contacts.add(person, { to: grp });
  Contacts.save();
  console.log("Contact upserted successfully");
} catch (error) {
  console.error("Contacts operation failed:", error);
}

Pitfalls

注意事项

TCC Permissions: Photos/attachments require TCC + Accessibility; use clipboard fallback if blocked
Yearless birthdays: Not cleanly scriptable; use full dates
Advanced triggers: Delegate geofencing to Shortcuts app
Heavy queries: Batch read or pre-filter to avoid timeouts

TCC权限： 照片/附件需要TCC + 辅助功能权限；若被阻止，使用剪贴板降级方案
无年份生日： 无法通过脚本正常处理；请使用完整日期
高级触发器： 地理围栏功能请委托给Shortcuts应用
大量查询： 采用批量读取或预过滤避免超时

When Not to Use

不适用于以下场景

Non-macOS platforms (use platform-specific APIs)
Simple AppleScript-only solutions (skip JXA complexity)
iCloud sync operations (use native Contacts framework)
User-facing apps (use native Contacts framework)
Cross-platform contact management (use CardDAV or vCard APIs)

非macOS平台（使用平台专属API）
仅需简单AppleScript的解决方案（无需JXA的复杂度）
iCloud同步操作（使用原生Contacts框架）
用户面向的应用（使用原生Contacts框架）
跨平台联系人管理（使用CardDAV或vCard API）

What to load

需加载的资源

JXA basics & specifiers:

automating-contacts/references/contacts-basics.md

Recipes (query, create, multi-values, groups):

automating-contacts/references/contacts-recipes.md

Advanced (hybrid filters, clipboard image, TCC, date pitfalls):
```
automating-contacts/references/contacts-advanced.md
```

Dictionary & type map:

automating-contacts/references/contacts-dictionary.md

PyXA API Reference (complete class/method docs):

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

JXA基础与指定符：

automating-contacts/references/contacts-basics.md

实践案例（查询、创建、多值字段、群组）：
```
automating-contacts/references/contacts-recipes.md
```
进阶内容（混合过滤、剪贴板图片、TCC、日期陷阱）：
```
automating-contacts/references/contacts-advanced.md
```

字典与类型映射：

automating-contacts/references/contacts-dictionary.md

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

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