Flutter客户端通信插件sanity_client的使用

Sanity Client 是一个强大的 Dart 客户端，用于连接 Sanity.io 项目并执行 GROQ 查询。这个包提供了一种类型安全和高效的方式来与 Sanity 的 HTTP API 交互，使您能够轻松地在 Dart 和 Flutter 应用程序中获取和管理内容。

特性 ✨

• GROQ 支持 🔍: 支持执行强大的 GROQ 查询，并且具有完整的类型安全性。
• HTTP API 支持 🌐:
  • 完整支持 Sanity 的 HTTP API 参数
  • 可配置的 API 版本
  • 发布/草稿内容视角
  • 调试时的查询解释
  • CDN 支持以提高性能
• 资产处理 🖼️:
  • 灵活的图像 URL 构建器
  • 支持外部图像服务（Cloudinary、ImageKit）
  • 文件资产管理
• 类型安全 🛡️:
  • 强类型查询和响应
  • 正确的错误处理和验证
  • 空安全支持

安装 📦

将以下内容添加到您的 pubspec.yaml 文件中：

dependencies:
  sanity_client: ^1.0.0

使用 💡

基本设置

创建一个带有您的项目配置的 SanityClient 实例：

import 'package:sanity_client/sanity_client.dart';

final client = SanityClient(
  SanityConfig(
    projectId: 'your_project_id',
    dataset: 'your_dataset',
    apiVersion: 'v2024-02-16',
    useCdn: true,
  ),
);

执行查询

运行 GROQ 查询来获取您的内容：

// 简单查询
final movies = await client.fetch('''
  *[_type == "movie"] {
    _id,
    title,
    releaseDate,
    "director": crewMembers[job == "Director"][0].person->name
  }
''');

// 带参数的查询
final recentMovies = await client.fetch('''
  *[_type == "movie" && releaseDate >= \$fromDate] {
    _id,
    title,
    releaseDate,
    "poster": poster.asset->url
  }
''', parameters: {
  'fromDate': '2024-01-01',
});

图像 URL 构建

生成带有转换的图像 URL：

final imageUrl = client.imageUrl
    .image(imageRef)
    .width(800)
    .height(600)
    .fit('crop')
    .toString();

自定义图像服务（可选）

使用外部图像服务：

// 使用 Cloudinary
client.imageUrlBuilder = (ref) {
  return CloudinaryUrlBuilder(
    cloudName: 'your-cloud-name',
    imageId: ref.asset.id,
  );
};

配置 🔧

SanityConfig 类支持多种选项：

final config = SanityConfig(
  projectId: 'your_project_id',
  dataset: 'your_dataset',
  
  // 认证（可选）
  token: 'your_token',  // 访问私有数据集
  
  // 内容交付选项
  useCdn: true,         // 使用 CDN 以提高性能
  perspective: Perspective.published,  // 切换查询执行的视角
  
  // API 选项
  apiVersion: 'v2024-02-16',
  explainQuery: false,  // 获取调试的查询解释
);

错误处理 🚨

客户端提供了适当的错误处理：

try {
  final result = await client.fetch(query);
  // 处理成功
} on SanityError catch (e) {
  // 处理 Sanity 特定的错误
  print('Sanity error: ${e.message}');
} catch (e) {
  // 处理其他错误
  print('Error: $e');
}

示例 Demo

下面是一个完整的示例，展示了如何在 Flutter 应用中使用 sanity_client 插件：

import 'package:flutter/material.dart';
import 'package:sanity_client/sanity_client.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sanity Client Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  [@override](/user/override)
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  List<dynamic> _movies = [];

  [@override](/user/override)
  void initState() {
    super.initState();
    _fetchMovies();
  }

  Future<void> _fetchMovies() async {
    final client = SanityClient(
      SanityConfig(
        projectId: 'your_project_id',
        dataset: 'your_dataset',
        token: 'your_token',
        perspective: Perspective.published,
        explainQuery: true,
        useCdn: true,
        apiVersion: 'v2024-02-16',
      ),
    );

    final query = '''
      *[_type == "movie"]{
        _id,
        title,
        releaseDate,
        "director": crewMembers[job == "Director"][0].person->name
      }
    ''';

    try {
      final response = await client.fetch(query);
      setState(() {
        _movies = response;
      });
    } catch (e) {
      print('Error fetching movies: $e');
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Sanity Client Demo'),
      ),
      body: ListView.builder(
        itemCount: _movies.length,
        itemBuilder: (context, index) {
          final movie = _movies[index];
          return ListTile(
            title: Text(movie['title']),
            subtitle: Text(movie['releaseDate']),
            trailing: Text(movie['director'] ?? 'No Director'),
          );
        },
      ),
    );
  }
}