Skip to content

UIPasteboard ​

UIPasteboard 表示系统剪贴板。App 把一段文字写进去,用户就能在任何 App 里粘贴它;用户在别的 App 里复制的文字,App 也能从它读出来。

系统剪贴板只有一个,所有 App 共用。它由系统提供,从 UIPasteboard.generalPasteboard 取。

读和写都通过 string 属性,是同步的:赋值的那一行执行完,文字已经在剪贴板里;读的那一行返回时,拿到的就是内容。

继承关系:EventTarget → NSObject → UIPasteboard

复制、粘贴按钮怎么写才不惊扰用户,见指南复制和粘贴文字。

构造函数 ​

不能用 new 创建。new UIPasteboard() 抛 TypeError: Illegal constructor: UIPasteboard is created by the runtime, not by new。实例从 UIPasteboard.generalPasteboard 取。

静态属性 ​

UIPasteboard.generalPasteboard 只读

整个系统共用的剪贴板。每次读得到同一个对象。

实例属性 ​

还继承 NSObject 的属性。

属性说明
string剪贴板里的文字。读它可能弹出系统提示,写入替换原有的内容
hasStrings 只读剪贴板里有没有文字。只查询,没有系统提示
changeCount 只读内容变化的计数。只查询,没有系统提示

事件 ​

用 addEventListener() 监听。

事件什么时候派发
change这个 App 自己修改了剪贴板的内容。别的 App 修改时不派发

读取时的系统提示 ​

读 string 时,如果剪贴板里的内容是用户在别的 App 里复制的,系统会先弹出一个提示,让用户决定是否允许这个 App 粘贴。用户回应之前,读 string 的那一行不返回。 这段时间里 App 的代码不执行:定时器不触发,事件回调不执行,界面不响应。

在真机(iPhone 14)上实测过一次:读别的 App 复制的内容,这一行用了 6613 毫秒才返回。这个时长就是用户看到提示到点下按钮的时间,它取决于用户,没有上限。

情况会不会有提示
读 string,内容是别的 App 复制的会(真机实测)
读 string,内容是这个 App 自己写进去的不会。未在真机验证,来自 iOS 的规则;模拟器上读自己写的内容立刻返回
读 hasStrings不会
读 changeCount不会
写 string不会

用户在提示里选了不允许时 string 读到什么,未在模拟器验证。模拟器上是否出现这个提示,未在模拟器验证。

所以只在用户明确要粘贴时读 string,见指南里的推荐的做法。

示例 ​

下面的代码从空白 App 开始,在屏幕上放一个按钮。点它,把一个订单号放进剪贴板。

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const pasteboard = UIPasteboard.generalPasteboard;

  const button = UIButton.buttonWithType('system');
  button.setTitle('复制订单号', { forState: ['normal'] });
  button.frame = new CGRect(40, 120, 200, 44);
  page.view.addSubview(button);

  button.addEventListener('click', () => {
    pasteboard.string = '20261112-0042';
    console.log('已复制');
  });
});

效果

  • 屏幕左上方出现一个文字按钮「复制订单号」。
  • 点它,控制台输出 已复制。
  • 切到别的 App(比如备忘录),长按输入区域选「粘贴」,出现 20261112-0042。

这段代码没有作为一个整体在模拟器运行过。「写进去再读出来是同一段文字」在验收用例里核对过;切到别的 App 粘贴这一步未在模拟器验证。

对应的 iOS API ​

ObjCJS
UIPasteboard.generalPasteboardUIPasteboard.generalPasteboard
pasteboard.string = @"文字"pasteboard.string = '文字'
NSString *text = pasteboard.stringconst text = pasteboard.string
pasteboard.hasStringspasteboard.hasStrings
pasteboard.changeCountpasteboard.changeCount
监听 UIPasteboardChangedNotificationpasteboard.addEventListener('change', …)

与浏览器的对照:

浏览器Nacre
await navigator.clipboard.writeText('文字')pasteboard.string = '文字',同步
await navigator.clipboard.readText()pasteboard.string,同步,可能停住界面等用户回应
没有对应pasteboard.hasStrings、pasteboard.changeCount

参见 ​