> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/permission/clipboard.md).

# 剪贴板

{% hint style="info" %}
**需要进行权限设置**

`getClipboardText`在使用前需要设置剪贴板权限。请先查看权限设置指南。
{% endhint %}

***

### 1. 获取剪贴板文本

**SDK 函数：** `getClipboardText`

这是一个读取剪贴板中保存的文本的函数。

**签名**

```typescript
function getClipboardText(): Promise<string>;
```

**返回值**

* `Promise<string>`

  返回剪贴板中保存的文本。如果剪贴板中没有文本，则返回空字符串。

**权限方法**

* getClipboardText.getPermission

  返回剪贴板读取权限的当前状态。 `allowed` · `denied` · `notDetermined` · `osPermissionDenied` 返回其中之一。
* getClipboardText.openPermissionDialog

  显示一个重新请求剪贴板读取权限的对话框。若允许则 `allowed`，拒绝时 `denied`会返回。

**错误**

权限被拒绝时 `GetClipboardTextPermissionError`会发生。 `error instanceof GetClipboardTextPermissionError`可以确认。

```typescript
class GetClipboardTextPermissionError extends PermissionError {
  constructor();
}
```

**示例**

{% tabs %}
{% tab title="Web（JS）" %}

```js
import { getClipboardText, GetClipboardTextPermissionError } from '@apps-in-toss/web-framework';

async function handleGetClipboardText() {
  try {
    const clipboardText = await getClipboardText();
    console.log('剪贴板文本:', clipboardText || '剪贴板中没有文本。');
  } catch (error) {
    if (error instanceof GetClipboardTextPermissionError) {
      console.log('没有剪贴板读取权限');
    }
  }
}
```

{% endtab %}

{% tab title="Web（React）" %}

```tsx
import { getClipboardText, GetClipboardTextPermissionError } from '@apps-in-toss/web-framework';
import { useState } from 'react';

function PasteButton() {
  const [text, setText] = useState('');

  const handlePress = async () => {
    try {
      const clipboardText = await getClipboardText();
      setText(clipboardText || '剪贴板中没有文本。');
    } catch (error) {
      if (error instanceof GetClipboardTextPermissionError) {
        // 没有剪贴板读取权限
      }
    }
  };

  return (
    <div>
      <span>{text}</span>
      <input type="button" value="粘贴" onClick={handlePress} />
      <input
        type="button"
        value="查看权限"
        onClick={async () => {
          const permission = await getClipboardText.getPermission();
          alert(permission);
        }}
      />
      <input
        type="button"
        value="请求权限"
        onClick={async () => {
          const permission = await getClipboardText.openPermissionDialog();
          alert(permission);
        }}
      />

  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { getClipboardText, GetClipboardTextPermissionError } from '@apps-in-toss/framework';
import { useState } from 'react';
import { Alert, Button, Text, View } from 'react-native';

function PasteButton() {
  const [text, setText] = useState('');

  const handlePress = async () => {
    try {
      const clipboardText = await getClipboardText();
      setText(clipboardText || '剪贴板中没有文本。');
    } catch (error) {
      if (error instanceof GetClipboardTextPermissionError) {
        // 没有剪贴板读取权限
      }
    }
  };

  return (
    <View>
      <Text>{text}</Text>
      <Button title="粘贴" onPress={handlePress} />
      <Button
        title="查看权限"
        onPress={async () => {
          const permission = await getClipboardText.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="请求权限"
        onPress={async () => {
          const permission = await getClipboardText.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </View>
  );
}
```

{% endtab %}
{% endtabs %}

***

### 2. 复制剪贴板文本

**SDK 函数：** `setClipboardText`

这是一个将文本复制到剪贴板的函数。用户可以在其他地方粘贴。

**签名**

```typescript
function setClipboardText(text: string): Promise<void>;
```

**参数**

* **text** · 必需 · `string`

  这是要复制到剪贴板的文本。

**权限方法**

* setClipboardText.getPermission

  返回剪贴板写入权限的当前状态。 `allowed` · `denied` · `notDetermined` · `osPermissionDenied` 返回其中之一。
* setClipboardText.openPermissionDialog

  显示一个重新请求剪贴板写入权限的对话框。若允许则 `allowed`，拒绝时 `denied`会返回。

**错误**

权限被拒绝时 `SetClipboardTextPermissionError`会发生。 `error instanceof SetClipboardTextPermissionError`可以确认。

```typescript
class SetClipboardTextPermissionError extends PermissionError {
  constructor();
}
```

**示例**

{% tabs %}
{% tab title="Web（JS）" %}

```js
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/web-framework';

async function handleSetClipboardText() {
  try {
    await setClipboardText('要复制的文本');
    console.log('文本已复制！');
  } catch (error) {
    if (error instanceof SetClipboardTextPermissionError) {
      console.log('没有剪贴板写入权限');
    }
  }
}
```

{% endtab %}

{% tab title="Web（React）" %}

```tsx
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/web-framework';

function CopyButton() {
  const handleCopy = async () => {
    try {
      await setClipboardText('要复制的文本');
      console.log('文本已复制！');
    } catch (error) {
      if (error instanceof SetClipboardTextPermissionError) {
        // 没有剪贴板写入权限
      }
    }
  };

  return (
    <>
      <input type="button" value="复制" onClick={handleCopy} />
      <input
        type="button"
        value="查看权限"
        onClick={async () => {
          const permission = await setClipboardText.getPermission();
          alert(permission);
        }}
      />
      <input
        type="button"
        value="请求权限"
        onClick={async () => {
          const permission = await setClipboardText.openPermissionDialog();
          alert(permission);
        }}
      />
    </>
  );
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
import { setClipboardText, SetClipboardTextPermissionError } from '@apps-in-toss/framework';
import { Alert, Button } from 'react-native';

function CopyButton() {
  const handleCopy = async () => {
    try {
      await setClipboardText('要复制的文本');
      console.log('文本已复制！');
    } catch (error) {
      if (error instanceof SetClipboardTextPermissionError) {
        // 没有剪贴板写入权限
      }
    }
  };

  return (
    <>
      <Button title="复制" onPress={handleCopy} />
      <Button
        title="查看权限"
        onPress={async () => {
          const permission = await setClipboardText.getPermission();
          Alert.alert(permission);
        }}
      />
      <Button
        title="请求权限"
        onPress={async () => {
          const permission = await setClipboardText.openPermissionDialog();
          Alert.alert(permission);
        }}
      />
    </>
  );
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/permission/clipboard.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.