Appwrite Flutter 控制台 SDK

pub package License Version Build Status Twitter Account Discord

此 SDK 兼容 Appwrite 服务器版本 0.14.x。对于旧版本，请查看 以前的版本。

Appwrite 是一个开源的后端即服务服务器，它通过非常易于使用的 REST API 来抽象和简化复杂且重复的开发任务。Appwrite 旨在帮助您更快、更安全地开发应用程序。使用 Flutter 控制台 SDK 将您的应用程序与 Appwrite 服务器集成，可以轻松开始与所有 Appwrite 后端 API 和工具进行交互。有关完整的 API 文档和教程，请访问 https://appwrite.io/docs

Appwrite

安装

将此添加到您的包的 pubspec.yaml 文件中

dependencies:
  appwrite: ^5.0.0

您可以从命令行安装包

pub get appwrite

入门

添加您的 Flutter 平台

要初始化您的 SDK 并开始与 Appwrite 服务进行交互，您需要为您的项目添加一个新的 Flutter 平台。要添加新平台，请转到您的 Appwrite 控制台，选择您在上一步中创建的项目，然后点击“添加平台”按钮。

在选项中，选择添加一个新的 Flutter 平台并添加您的应用凭据。Appwrite Flutter SDK 目前支持构建 Android、iOS、Linux、Mac OS、Web 和 Windows 应用程序。

如果您正在为多个设备构建 Flutter 应用程序，您需要为每个不同的设备遵循此过程。

Android

对于 Android，首先添加您的应用名称和包名。您的包名通常是您应用的 applicationId，位于应用级别的 build.gradle 文件中。通过注册您的新应用平台，您就允许您的应用与 Appwrite API 通信。

为了捕获 Appwrite OAuth 回调 URL，需要将以下 Activity 添加到您的 AndroidManifest.xml 中。请务必将 [PROJECT_ID] 字符串替换为您实际的 Appwrite 项目 ID。您可以在控制台的项目设置屏幕中找到您的 Appwrite 项目 ID。

<manifest>
    <application>
        <activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
            <intent-filter android:label="flutter_web_auth">
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="appwrite-callback-[PROJECT_ID]" />
            </intent-filter>
        </activity>
    </application>
</manifest>

iOS

对于 iOS，首先添加您的应用名称和 Bundle ID。您可以在 Xcode 中为您应用的主目标页面的“General”选项卡中找到您的 Bundle Identifier。

Appwrite SDK 在 iOS 12+ 上使用 ASWebAuthenticationSession，在 iOS 11 上使用 SFAuthenticationSession 来允许 OAuth 认证。您必须将 Xcode 中的 iOS Deployment Target 更改为 iOS >= 11，才能在模拟器或真实设备上构建您的应用程序。

  1. 在 Xcode 中，打开您应用 ios 文件夹中的 Runner.xcworkspace。
  2. 要查看您应用的设置，请在 Xcode 项目导航器中选择 Runner 项目。然后，在主视图侧边栏中，选择 Runner 目标。
  3. 选择 General 选项卡。
  4. 在 Deployment Info 中，“Target”选择 iOS 11.0

Linux

对于 Linux，添加您的应用名称和包名。您的包名通常是您 pubspec.yaml 文件中的 name。如果您找不到正确的包名，请在 Linux 上运行应用程序，并进行任何带有关联异常处理的请求，您应该在收到的错误消息中获得需要添加的应用 ID。

Mac OS

对于 Mac OS，添加您的应用名称和 Bundle ID。您可以在 Xcode 中为您应用的主目标页面的“General”选项卡中找到您的 Bundle Identifier。

Web

Appwrite 0.7 和 Appwrite Flutter SDK 0.3.0 已添加对 Flutter Web 的支持。要构建与 Appwrite 集成的 Web 应用，您只需在 Appwrite 项目的仪表板上添加一个 Web 平台，并列出您的网站将用于允许与 Appwrite API 通信的域。

对于 Web，为了捕获 OAuth2 回调 URL 并使用 JavaScript postMessage() 将其发送到应用程序，您需要在 Flutter 项目的 ./web 文件夹内创建一个 HTML 文件。例如 auth.html，内容如下。

<!DOCTYPE html>
<title>Authentication complete</title>
<p>Authentication is complete. If this does not happen automatically, please
close the window.
<script>
  window.opener.postMessage({
    flutter-web-auth: window.location.href
  }, window.location.origin);
  window.close();
</script>

传递给身份验证服务的重定向 URL 必须与应用程序正在运行的 URL（方案、主机、端口（如果需要））相同，并且路径必须指向创建的 HTML 文件，在这种情况下为 /auth.html。authenticate() 方法的 callbackUrlScheme 参数不考虑这一点，因此可以在代码中使用针对原生平台的方案。

Flutter Web 跨域通信和 Cookie

在运行 Flutter Web 时，请确保您的 Appwrite 服务器和您的 Flutter 客户端使用相同的顶级域和相同的协议（HTTP 或 HTTPS）进行通信。当尝试在不同域或协议之间通信时，您可能会收到 HTTP 状态错误 401，因为一些现代浏览器出于隐私保护目的会阻止跨站或不安全的 Cookie。在生产环境中，Appwrite 允许您为每个项目设置多个 自定义域。

Windows

对于 Windows，添加您的应用名称和包名。您的包名通常是您 pubspec.yaml 文件中的 name。如果您找不到正确的包名，请在 Windows 上运行应用程序，并进行任何带有关联异常处理的请求，您应该在收到的错误消息中获得需要添加的应用 ID。

初始化您的 SDK

使用您的 Appwrite 服务器 API 端点和项目 ID 初始化您的 SDK，这些信息可以在您的项目设置页面中找到。

import 'package:appwrite/appwrite.dart';

void main() {
  Client client = Client();

  client
    .setEndpoint('https:///v1') // Your Appwrite Endpoint
    .setProject('5e8cf4f46b5e8') // Your project ID
    .setSelfSigned() // Use only on dev mode with a self-signed SSL cert
  ;
}

在开始向新的 Appwrite 实例发送任何 API 调用之前，请确保您的 Android 或 iOS 模拟器具有到 Appwrite 服务器主机名或 IP 地址的网络访问权限。

当尝试从模拟器或移动设备连接到 Appwrite 时，localhost 是设备或模拟器的hostname，而不是您的本地 Appwrite 实例。您应该用您的私有 IP 替换 localhost 作为 Appwrite 端点的hostname。您也可以使用 ngrok 等服务来代理 Appwrite API。

发出您的第一个请求

一旦设置好 SDK 对象，就可以访问任何 Appwrite 服务并选择任何请求进行发送。任何您想使用的服务方法的完整文档可以在您的 SDK 文档或 [API 参考](https://appwrite.io/docs) 部分找到。

// Register User
Account account = Account(client);
Response user = await account
  .create(
    userId: '[USER_ID]',
    email: '[email protected]',
    password: 'password',
    name: 'My Name'
  );

完整示例

import 'package:appwrite/appwrite.dart';

void main() {
  Client client = Client();


  client
    .setEndpoint('https:///v1') // Your Appwrite Endpoint
    .setProject('5e8cf4f46b5e8') // Your project ID
    .setSelfSigned() // Use only on dev mode with a self-signed SSL cert
    ;


  // Register User
  Account account = Account(client);

  Response user = await account
    .create(
      userId: '[USER_ID]',
      email: '[email protected]',
      password: 'password',
      name: 'My Name'
    );
}

错误处理

Appwrite Flutter SDK 会抛出带有 message、code 和 response 属性的 AppwriteException 对象。您可以通过捕获 AppwriteException 来处理任何错误，并向用户显示 message，或根据提供的错误信息自行处理。下面是一个示例。

Users users = Users(client);

try {
  final response = await users.create(userId: '[USER_ID]', email: ‘email@example.com’,password: ‘password’, name: ‘name’);
  print(response.data);
} on AppwriteException catch(e) {
  //show message to user or do other operation based on error as required
  print(e.message);
}

了解更多

您可以使用以下资源来了解更多并获得帮助

贡献

此库是由 Appwrite 自定义 SDK 生成器 自动生成的。要了解如何帮助我们改进此 SDK，请在发送拉取请求之前查看 贡献指南。

许可证

有关更多信息，请参阅 BSD-3-Clause 许可证 文件。

GitHub

查看 Github