跳到主要内容

快速开始

数据模型是云开发提供的一种声明式数据管理方案，通过可视化界面定义数据结构和关系，自动生成类型安全的 SDK，让您专注于业务逻辑而无需关心底层数据操作。

前置条件​

在开始之前，请确保您已经：

  • 创建了云开发环境，如若还没有请参考 开通云开发环境
  • 具备基本的 JavaScript/TypeScript 开发经验

快速上手​

本教程将通过一个博客应用示例，演示如何使用数据模型管理文章和评论数据。我们将学习：

  1. 如何创建和配置数据模型
  2. 如何初始化和使用 SDK
  3. 如何进行基本的数据操作

让我们开始吧！

第一步：创建数据模型​

1.1 进入数据模型管理页面​

访问 云开发平台/数据库，然后点击「添加模型」开始创建新的数据模型。

创建数据模型

1.2 设计数据模型​

我们将创建文章数据模型来构建一个简单的博客系统：

文章模型（post）​

首先创建文章模型，包含以下字段：

字段名字段类型描述是否必填
title单行文本文章标题是
slug单行文本文章别名，用于 SEO 优化是
body富文本文章正文内容是

1.3 系统默认字段​

创建数据模型时，系统会自动添加以下系统字段，并在数据操作时自动维护：

系统字段描述自动更新时机
_id数据唯一标识符创建时自动生成
createdAt创建时间戳创建时自动生成
updatedAt更新时间戳每次更新时自动更新
_openid用户标识（小程序）用户端操作时自动生成
owner数据所有者创建时自动设置
createBy创建者标识创建时自动设置
updateBy最后修改者每次更新时自动更新

💡 开发优势：开发者无需手动管理这些字段，系统自动处理数据的生命周期管理，让您专注于业务逻辑实现。

第二步：添加 SDK​

2.1 下载 SDK 文件​

根据您的开发平台选择对应的 SDK：

平台文档链接
小程序本教程重点介绍
Web 应用在 Web 页面中调用
云函数在云函数中调用

对于小程序开发，请下载 SDK 文件并保存到项目目录：

  1. 下载 SDK 文件：wxCloudClientSDK.umd.js
  2. 将文件保存到小程序项目的根目录（通常是 miniprogram 目录）
  3. 文件命名为：wxCloudClientSDK.umd.js

2.2 初始化 SDK​

在小程序的 app.js 文件中添加初始化代码：

// 引入数据模型 SDK
const {
    init
} = require("./wxCloudClientSDK.umd.js");

App({
    onLaunch() {
        // 初始化云开发
        wx.cloud.init({
            env: "your-env-id", // 替换为您的云开发环境 ID
            traceUser: true,
        });

        // 初始化数据模型客户端
        const client = init(wx.cloud);

        // 将 models 挂载到全局，方便在页面中使用
        this.globalData.models = client.models;

        console.log("数据模型 SDK 初始化完成");
    },

    globalData: {
        models: null, // 数据模型实例
    }
});
提示

⚠️ 重要：请将 your-env-id 替换为您实际的云开发环境 ID

第三步：使用数据模型进行 CRUD 操作​

3.1 在页面中获取 models 实例​

在小程序页面中，首先获取 models 实例：

// pages/index/index.js
const app = getApp();

Page({
    data: {
        posts: [],
        loading: false,
    },

    onLoad() {
        // 获取数据模型实例
        this.models = app.globalData.models;

        // 加载文章列表
        this.loadPosts();
    },

    // 其他方法...
});

3.2 创建数据（Create）​

使用 create() 方法创建新文章：

// 创建新文章
async createPost() {
    try {
        this.setData({
            loading: true
        });

        const {
            data
        } = await this.models.post.create({
            data: {
                title: "我的第一篇文章",
                body: "这是文章的内容，支持富文本格式。\n\n可以包含多行文本。",
                slug: "my-first-post",
            },
        });

        console.log("文章创建成功:", data);
        // 输出: { id: "7d8ff72c665eb6c30243b6313aa8539e" }

        // 刷新文章列表
        this.loadPosts();

        wx.showToast({
            title: "文章创建成功",
            icon: "success",
        });
    } catch (error) {
        console.error("创建文章失败:", error);
        wx.showToast({
            title: "创建失败",
            icon: "error",
        });
    } finally {
        this.setData({
            loading: false
        });
    }
},

3.3 查询数据（Read）​

使用 list() 方法获取文章列表：

// 加载文章列表
async loadPosts() {
    try {
        this.setData({
            loading: true
        });

        const {
            data
        } = await this.models.post.list({
            filter: {
                where: {}, // 查询条件，空对象表示查询所有
            },
            pageSize: 10, // 每页数量
            pageNumber: 1, // 页码（从 1 开始）
            getCount: true, // 是否获取总数
            sort: {
                createdAt: -1, // 按创建时间倒序排列
            },
        });

        console.log("查询结果:", data);

        this.setData({
            posts: data.records,
            total: data.total,
        });

    } catch (error) {
        console.error("加载文章失败:", error);
        wx.showToast({
            title: "加载失败",
            icon: "error",
        });
    } finally {
        this.setData({
            loading: false
        });
    }
},

返回数据结构示例：

{
  "records": [
    {
      "_id": "e2764d2d665ecbc9024b058f1d6b33a4",
      "title": "我的第一篇文章",
      "body": "这是文章的内容...",
      "slug": "my-first-post",
      "createdAt": 1717488585078,
      "updatedAt": 1717490751944,
      "_openid": "95fblM7nvPi01yQmYxBvBg",
      "owner": "Anonymous(95fblM7nvPi01yQmYxBvBg)"
    }
  ],
  "total": 1
}

3.4 更新数据（Update）​

// 更新文章
async updatePost(postId, updateData) {
    try {
        const {
            data
        } = await this.models.post.update({
            filter: {
                where: {
                    _id: postId,
                },
            },
            data: updateData,
        });

        console.log("更新成功:", data);
        wx.showToast({
            title: "更新成功",
            icon: "success",
        });

        // 刷新列表
        this.loadPosts();
    } catch (error) {
        console.error("更新失败:", error);
        wx.showToast({
            title: "更新失败",
            icon: "error",
        });
    }
},

3.5 删除数据（Delete）​

// 删除文章
async deletePost(postId) {
    try {
        await this.models.post.delete({
            filter: {
                where: {
                    _id: postId,
                },
            },
        });

        wx.showToast({
            title: "删除成功",
            icon: "success",
        });

        // 刷新列表
        this.loadPosts();
    } catch (error) {
        console.error("删除失败:", error);
        wx.showToast({
            title: "删除失败",
            icon: "error",
        });
    }
},

下一步​

恭喜！您已经掌握了数据模型的基本使用方法。接下来可以：

开始构建您的应用吧！🚀