ใช้ SDK ของเว็บที่สร้างขึ้น

Firebase Data Connect SDK ของไคลเอ็นต์ช่วยให้คุณเรียกใช้การค้นหาและการเปลี่ยนแปลงฝั่งเซิร์ฟเวอร์ได้โดยตรงจากแอป Firebase คุณสร้าง SDK ของไคลเอ็นต์ที่กำหนดเองแบบขนานไปกับการออกแบบสคีมา การค้นหา และการเปลี่ยนแปลงที่คุณนําไปใช้กับบริการ Data Connect จากนั้นผสานรวมเมธอดจาก SDK นี้เข้ากับตรรกะไคลเอ็นต์

ดังที่เราได้กล่าวไว้ในที่อื่นๆ สิ่งสำคัญที่ควรทราบคือData Connect โค้ดฝั่งไคลเอ็นต์ไม่ได้ส่งการค้นหาและการเปลี่ยนแปลง และไม่ได้ดำเนินการบนเซิร์ฟเวอร์ แต่เมื่อมีการใช้งาน ระบบจะจัดเก็บการดำเนินการ Data Connect ไว้ในเซิร์ฟเวอร์ เช่น Cloud Functions ซึ่งหมายความว่าคุณต้องติดตั้งใช้งานการเปลี่ยนแปลงฝั่งไคลเอ็นต์ที่เกี่ยวข้องเพื่อหลีกเลี่ยงไม่ให้ผู้ใช้เดิมใช้งานไม่ได้ (เช่น ในแอปเวอร์ชันเก่า)

ด้วยเหตุนี้ Data Connect จึงมีสภาพแวดล้อมสำหรับนักพัฒนาแอปและเครื่องมือที่ช่วยให้คุณสร้างต้นแบบของสคีมา คำค้นหา และการเปลี่ยนแปลงที่ใช้งานในเซิร์ฟเวอร์ได้ นอกจากนี้ยังสร้าง SDK ฝั่งไคลเอ็นต์โดยอัตโนมัติขณะที่คุณสร้างต้นแบบ

เมื่ออัปเดตบริการและแอปไคลเอ็นต์ซ้ำแล้ว การอัปเดตทั้งฝั่งเซิร์ฟเวอร์และฝั่งไคลเอ็นต์ก็พร้อมใช้งาน

เวิร์กโฟลว์การพัฒนาไคลเอ็นต์คืออะไร

หากทำตามเริ่มต้นใช้งาน คุณจะได้รับข้อมูลเกี่ยวกับขั้นตอนการพัฒนาโดยรวมสำหรับ Data Connect ในคำแนะนำนี้ คุณจะเห็นข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับการสร้าง Web SDK จากสคีมาของคุณ และการทำงานกับการค้นหาและการเปลี่ยนแปลงของไคลเอ็นต์

โดยสรุป หากต้องการใช้ Web SDK ที่สร้างขึ้นในแอปไคลเอ็นต์ คุณจะต้องทำตามขั้นตอนเบื้องต้นต่อไปนี้

  1. เพิ่ม Firebase ไปยังแอปเว็บ

จากนั้นให้ทำดังนี้

  1. พัฒนาสคีมาแอป
  2. เริ่มต้นโค้ดฝั่งไคลเอ็นต์ด้วย JavaScript SDK หรือ ไลบรารี React หรือ Angular
  3. สำหรับ React และ Angular ให้ติดตั้งแพ็กเกจ Tanstack Query

  4. ตั้งค่าการสร้าง SDK โดยทำดังนี้

    • ด้วยปุ่มเพิ่ม SDK ลงในแอปใน ส่วนขยาย Data Connect VS Code
    • โดยการอัปเดต connector.yaml สำหรับ JavaScript SDK หรือ React หรือ Angular

  5. นำเข้าไลบรารีและโค้ดที่สร้างขึ้นด้วย JavaScript SDK หรือ React หรือ Angular

  6. ใช้การเรียกไปยังการค้นหาและการเปลี่ยนแปลงด้วย JavaScript SDK หรือ React หรือ Angular

  7. ทดสอบโดยการตั้งค่าData Connectโปรแกรมจำลองด้วย JavaScript SDK หรือ React หรือ Angular

ใช้โค้ดฝั่งไคลเอ็นต์กับ Firebase JavaScript SDK

ส่วนนี้จะครอบคลุมวิธีติดตั้งใช้งานไคลเอ็นต์โดยใช้ Firebase JavaScript SDK

หากใช้ React หรือ Angular โปรดดูวิธีการตั้งค่าและลิงก์สำรองไปยัง เอกสารประกอบเพิ่มเติมเกี่ยวกับการสร้าง Data Connect SDK สำหรับเฟรมเวิร์ก

เริ่มต้นแอป

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้ลําดับ Firebase มาตรฐาน

initializeApp({...});

ติดตั้ง JavaScript SDK ที่สร้างขึ้น

ใช้ Firebase CLI เพื่อตั้งค่า Data Connect SDK ที่สร้างขึ้นในแอป คำสั่ง init ควรตรวจหาแอปทั้งหมดในโฟลเดอร์ปัจจุบันและติดตั้ง SDK ที่สร้างขึ้นโดยอัตโนมัติ

firebase init dataconnect:sdk

เชื่อมต่อแอปกับData Connect

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

อัปเดต SDK ขณะสร้างต้นแบบ

หากคุณติดตั้งส่วนขยาย Data Connect VS Code ไว้ ระบบจะอัปเดต SDK ที่สร้างขึ้นให้เป็นเวอร์ชันล่าสุดอยู่เสมอ

หากไม่ได้ใช้ส่วนขยาย Data Connect VS Code คุณสามารถใช้ Firebase CLI เพื่อให้ SDK ที่สร้างขึ้นเป็นเวอร์ชันล่าสุดอยู่เสมอ

firebase dataconnect:sdk:generate --watch

สร้าง SDK ในไปป์ไลน์การสร้าง

คุณใช้ Firebase CLI เพื่อสร้าง SDK การเชื่อมต่อข้อมูลในกระบวนการสร้าง CI/CD ได้

firebase dataconnect:sdk:generate

นำเข้าไลบรารี

คุณต้องนำเข้า 2 ชุดเพื่อเริ่มต้นใช้งานโค้ดฝั่งไคลเอ็นต์ ได้แก่ การนำเข้าทั่วไป Data Connectและการนำเข้า SDK ที่เฉพาะเจาะจงซึ่งสร้างขึ้น

โปรดสังเกตออบเจ็กต์ ConnectorConfig ที่รวมอยู่ในการนำเข้าทั่วไป

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@dataconnect/generated';

ใช้การค้นหาจาก JavaScript SDK

โค้ดที่สร้างขึ้นจะมี Query Ref ที่กำหนดไว้ล่วงหน้าอยู่แล้ว สิ่งที่คุณต้องทำ ก็เพียงแค่นำเข้าและเรียกใช้ฟังก์ชัน execute

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

เรียกใช้เมธอดการค้นหา SDK

ตัวอย่างการใช้ฟังก์ชันแป้นพิมพ์ลัดการดำเนินการเหล่านี้มีดังนี้

import { listMovies } from '@dataconnect/generated';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

ติดตามการเปลี่ยนแปลง

คุณสามารถติดตามการเปลี่ยนแปลง (ซึ่งจะอัปเดตทุกครั้งที่คุณเรียกใช้คําค้นหา)

const listRef = listAllMoviesRef();

// subscribe will immediately invoke the query if no execute was called on it previously.
subscribe(listRef, ({ data }) => {
 updateUIWithMovies(data.movies);
});

await createMovie({ title: 'Empire Strikes Back', releaseYear: 1980, genre: "Sci-Fi", rating: 5 });\
await listMovies(); // will update the subscription above`

จัดการการเปลี่ยนแปลงฟิลด์การแจงนับ

สคีมาของแอปสามารถมีการแจงนับ ซึ่งการค้นหา GraphQL จะเข้าถึงได้

เมื่อการออกแบบแอปมีการเปลี่ยนแปลง คุณอาจเพิ่มค่าที่รองรับ enum ใหม่ ตัวอย่างเช่น สมมติว่าในภายหลังวงจรแอปพลิเคชัน คุณตัดสินใจที่จะเพิ่มค่า FULLSCREEN ลงใน AspectRatio enum

ในเวิร์กโฟลว์ Data Connect คุณสามารถใช้เครื่องมือการพัฒนาในเครื่องเพื่อ อัปเดตการค้นหาและ SDK ได้

อย่างไรก็ตาม ก่อนที่จะเผยแพร่ไคลเอ็นต์เวอร์ชันที่อัปเดตแล้ว ไคลเอ็นต์เวอร์ชันเก่าที่ติดตั้งใช้งาน อาจใช้งานไม่ได้

ตัวอย่างการใช้งานที่ยืดหยุ่น

เพิ่มกิ่ง default ลงในคำสั่ง switch เหนือค่า enum เสมอ หรือ เพิ่มกิ่ง else ลงในบล็อก if/else if ที่เปรียบเทียบกับค่า enum ภาษา JavaScript/TypeScript ไม่ได้บังคับใช้ แต่เป็นวิธี ทำให้โค้ดฝั่งไคลเอ็นต์มีความแข็งแกร่งในกรณีที่มีการเพิ่มค่า enum ใหม่

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

ใช้การเปลี่ยนแปลงจาก JavaScript SDK

คุณเข้าถึงการเปลี่ยนแปลงได้ในลักษณะเดียวกับการค้นหา

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

เชื่อมต่อกับโปรแกรมจำลอง Data Connect

คุณเลือกเชื่อมต่อกับโปรแกรมจำลองได้โดยเรียกใช้ connectDataConnectEmulator แล้วส่งอินสแตนซ์ Data Connect ดังนี้

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

หากต้องการเปลี่ยนไปใช้ทรัพยากรการใช้งานจริง ให้แสดงความคิดเห็นในบรรทัดสำหรับการเชื่อมต่อกับ โปรแกรมจำลอง

ใช้โค้ดฝั่งไคลเอ็นต์สำหรับ React และ Angular

Firebase Data Connect มี SDK ที่สร้างขึ้นพร้อม Hook สำหรับ React และ Angular โดยใช้ไลบรารีจากพาร์ทเนอร์ของเราที่ Invertase TanStack Query Firebase

ไลบรารีนี้มีชุดฮุกที่ช่วยให้จัดการงานแบบอะซิงโครนัสกับ Firebase ในแอปพลิเคชันได้ง่ายขึ้นมาก

เริ่มต้นแอป

ก่อนอื่น ให้เริ่มต้นแอปโดยใช้ลําดับ Firebase มาตรฐานเช่นเดียวกับเว็บแอป Firebase อื่นๆ

initializeApp({...});

ติดตั้งแพ็กเกจ Firebase ของ TanStack Query

ติดตั้งแพ็กเกจสำหรับ TanStack Query ในโปรเจ็กต์

โต้ตอบ

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

Angular

ng add @angular/fire

สร้าง SDK ของ React หรือ Angular

เช่นเดียวกับ SDK เว็บมาตรฐานตามที่อธิบายไว้ก่อนหน้านี้ เครื่องมือของ Firebase จะจัดการการสร้าง SDK โดยอัตโนมัติตามสคีมาและการดำเนินการของคุณ

หากเพิ่งเพิ่ม React หรือ Angular ลงในโปรเจ็กต์ ให้เรียกใช้ firebase init dataconnect:sdk อีกครั้งเพื่อกำหนดค่า SDK ที่สร้างขึ้นใหม่ให้รวมการเชื่อมโยงเฟรมเวิร์กเพิ่มเติม

นำเข้าไลบรารี

คุณต้องนำเข้า 4 ชุดเพื่อเริ่มต้นใช้งานโค้ดไคลเอ็นต์ React หรือ Angular ได้แก่ การนำเข้าทั่วไป Data Connect การนำเข้า TanStack ทั่วไป และการนำเข้าที่เฉพาะเจาะจงสำหรับ SDK ที่สร้างขึ้นสำหรับ JS และ React

โปรดสังเกตประเภท ConnectorConfig ที่รวมอยู่ในการนําเข้าทั่วไป

โต้ตอบ

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/react";

Angular

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/angular";

ใช้การค้นหาและการเปลี่ยนแปลงในไคลเอ็นต์ React หรือ Angular

เมื่อตั้งค่าเสร็จแล้ว คุณจะรวมเมธอดจาก SDK ที่สร้างขึ้นได้

ในข้อมูลโค้ดต่อไปนี้ ให้สังเกตเมธอดที่นำหน้าด้วย use useListAllMovies สำหรับ React และเมธอดที่นำหน้าด้วย inject injectListAllMovies สำหรับ Angular ซึ่งทั้ง 2 เมธอด มาจาก SDK ที่สร้างขึ้น

โต้ตอบ

การดำเนินการดังกล่าวทั้งหมดใน SDK ที่สร้างขึ้น ทั้งการค้นหาและการเปลี่ยนแปลง จะเรียกใช้การเชื่อมโยง TanStackQuery

import { useListAllMovies } from '@dataconnect/generated/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

Angular

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

ใช้การค้นหาที่โหลดซ้ำอัตโนมัติกับ React และ Angular

คุณกำหนดค่าคิวรีให้โหลดซ้ำโดยอัตโนมัติเมื่อข้อมูลมีการเปลี่ยนแปลงได้

โต้ตอบ

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause Tanstack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

Angular

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

เชื่อมต่อกับโปรแกรมจำลอง Data Connect

คุณเลือกเชื่อมต่อกับโปรแกรมจำลองได้โดยการเรียกใช้ connectDataConnectEmulator แล้วส่งอินสแตนซ์ Data Connect ไปยัง Hook ที่สร้างขึ้น ดังนี้

โต้ตอบ 

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

Angular 

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

หากต้องการเปลี่ยนไปใช้ทรัพยากรการใช้งานจริง ให้แสดงความคิดเห็นในบรรทัดสำหรับการเชื่อมต่อกับ โปรแกรมจำลอง

ประเภทข้อมูลใน SDK

เซิร์ฟเวอร์ Data Connect แสดงถึงประเภทข้อมูล GraphQL ทั่วไป โดยจะแสดงใน SDK ดังนี้

ประเภทการเชื่อมต่อข้อมูล TypeScript
การประทับเวลา สตริง
วันที่ สตริง
UUID สตริง
Int64 สตริง
เตียงคู่ ตัวเลข
ทศนิยม ตัวเลข

อัปเดต SDK ขณะสร้างต้นแบบ

หากคุณติดตั้งส่วนขยาย Data Connect VS Code ไว้ ระบบจะอัปเดต SDK ที่สร้างขึ้นให้เป็นเวอร์ชันล่าสุดอยู่เสมอ

หากไม่ได้ใช้ส่วนขยาย Data Connect VS Code คุณสามารถใช้ Firebase CLI เพื่อให้ SDK ที่สร้างขึ้นเป็นเวอร์ชันล่าสุดอยู่เสมอ

firebase dataconnect:sdk:generate --watch

สร้าง SDK ในไปป์ไลน์การสร้าง

คุณใช้ Firebase CLI เพื่อสร้าง SDK การเชื่อมต่อข้อมูลในกระบวนการสร้าง CI/CD ได้

firebase dataconnect:sdk:generate