微信小程序开发文档 第6页

Command.push(values: Object): Command 支持端：小程序 2.8.3, 云函数 1.2.1, Web 数组更新操作符。对一个值为数组的字段，往数组添加一个或多个值。或字段原为空，则创建该字段并设数组为传入值。 参数 values: Object 属性 类型 默认值 必填 说明 each Array.<any> 是 要插入的所有元素 position number 否 从哪个位置开始插入，不填则是尾部 sort number 否 对结果数组排序 slice number 否 限制结果数组长度 返回值 Command 参数说明 position 说明 要求必须同时有 each 参数存在。 非负数代表从数组开始位置数的位置，从 0 开始计。如果数值大于等于数组长度，则视为在尾部添加。负数代表从数组尾部倒数的位置，比如 -1 就代表倒数第二个元素的位置。如果负数数值的绝对值大于等于数组长度，则视为从数组头部添加。 sort 说明 要求必须同时有 each 参数存在。给定 1 代表升序，-1 代表降序。 如果数组元素是记录，则用 { <字段>: 1 | -1 } 的格式表示根据记录中的什么字段做升降序排序。 slice** 说明 要求必须同时有 each 参数存在 值 说明 0 将字段更新为空数组 正数 数组只保留前 n 个元素 负数 数组只保留后 n 个元素 升级说明 以上定义是从小程序 2.8.3 / 云函数 SDK 1.2.1 起支持，对于之前的版本，使用的是如下函数签名，新版中对旧版签名有兼容。 旧版签名：传入一个数组，该数组的每个元素会被追加到字段数组的尾部 function push(values: any[]): Command 示例 1：尾部添加元素 const _ = db.command db.collection('todos').doc('doc-id').update({ data: { tags: _.push(['mini-program', 'cloud']) } }) 示例 2：从第二个位置开始插入 const _ = db.command db.collection('todos').doc('doc-id').update({ data: { tags: _.push({ each: ['mini-program', 'cloud'], position: 1, }) } }) 示例 3：排序 插入后对整个数组做排序 const _ =...

Command.set(value: any): Command 支持端：小程序 , 云函数 , Web 更新操作符，用于设定字段等于指定值。 参数 value: any 返回值 Command 使用说明 这种方法相比传入纯 JS 对象的好处是能够指定字段等于一个对象 示例 // 以下方法只会更新 style.color 为 red，而不是将 style 更新为 { color: 'red' }，即不影响 style 中的其他字段 db.collection('todos').doc('doc-id').update({ data: { style: { color: 'red' } } }) // 以下方法更新 style 为 { color: 'red', size: 'large' } db.collection('todos').doc('doc-id').update({ data: { style: _.set({ color: 'red', size: 'large' }) } }) Command.remove(): Command 支持端：小程序 , 云函数 , Web 更新操作符，用于表示删除某个字段。 返回值 Command 示例代码 删除 style 字段： const _ = db.command db.collection('todos').doc('todo-id').update({ data: { style: _.remove() } }) Command.inc(value: number): Command 支持端：小程序 , 云函数 , Web 更新操作符，原子操作，用于指示字段自增 参数 value: number 自增量，可正可负 返回值 Command 原子自增 多个用户同时写，对数据库来说都是将字段自增，不会有后来者覆写前者的情况 示例代码 将一个 todo 的进度自增 10： const _ = db.command db.collection('todos').doc('todo-id').update({ data: { progress: _.inc(10) } }) Command.mul(value: number): Command 支持端：小程序 , 云函数 , Web 更新操作符，原子操作，用于指示字段自乘某个值 参数 value: number 自乘量，可正可负 返回值 Command 原子自乘 多个用户同时写，对数据库来说都是将字段自乘，不会有后来者覆写前者的情况 示例代码...

Command.expr(aggregateExpression: Expression): Command 支持端：云函数 1.4.0 查询操作符，用于在查询语句中使用聚合表达式，方法接收一个参数，该参数必须为聚合表达式 参数 aggregateExpression: Expression 要添加进数组的一个或多个元素 返回值 Command 使用说明 expr 可用于在聚合 match 流水线阶段中引入聚合表达式 如果聚合 match 阶段是在 lookup 阶段内，此时的 expr 表达式内可使用 lookup 中使用 let 参数定义的变量，具体示例可见 lookup 的 指定多个连接条件 例子 expr 可用在普通查询语句（where）中引入聚合表达式 示例代码 1：比较同一个记录中的两个字段 假设 items 集合的数据结构如下： { "_id": string, "inStock": number, // 库存量 "ordered": number // 被订量 } 找出被订量大于库存量的记录： const _ = db.command const $ = _.aggregate db.collection('items').where(_.expr($.gt('$ordered', '$inStock'))).get() 示例代码 2：与条件语句组合使用 假设 items 集合的数据结构如下： { "_id": string, "price": number } 假设加个小于等于 10 的打 8 折，大于 10 的打 5 折，让数据库查询返回打折后价格小于等于 8 的记录： const _ = db.command const $ = _.aggregate db.collection('items').where(_.expr( $.lt( $.cond({ if: $.gte('$price', 10), then: $.multiply(['$price', '0.5']), else: $.multiply(['$price', '0.8']), }) , 8 ) ).get()

Command.geoNear(options: Object): Command 支持端：小程序 , 云函数 , Web 按从近到远的顺序，找出字段值在给定点的附近的记录。 参数 options: Object 属性 类型 默认值 必填 说明 geometry GeoPoint 是 地理位置点 (Point) maxDistance number 否 选填，最大距离，单位为米 minDistance number 否 选填，最小距离，单位为米 返回值 Command 索引要求 需对查询字段建立地理位置索引 示例代码 找出离给定位置 1 公里到 5 公里范围内的记录 const _ = db.command db.collection('restaurants').where({ location: _.geoNear({ geometry: db.Geo.Point(113.323809, 23.097732), minDistance: 1000, maxDistance: 5000, }) }).get() Command.geoWithin(options: Object): Command 支持端：小程序 , 云函数 , Web 找出字段值在指定区域内的记录，无排序。指定的区域必须是多边形（Polygon）或多边形集合（MultiPolygon）。 参数 options: Object 属性 类型 默认值 必填 说明 geometry Object 是 地理信息结构，Polygon，MultiPolygon，或 { centerSphere } 返回值 Command 索引要求 需对查询字段建立地理位置索引 示例代码 1：给定多边形 const _ = db.command const { Point, LineString, Polygon } = db.Geo db.collection('restaurants').where({ location: _.geoWithin({ geometry: Polygon([ LineString([ Point(0, 0), Point(3, 2), Point(2, 3), Point(0, 0) ]) ]), }) }) 示例代码 2：给定圆形 可以不用 geometry 而用 centerSphere 构建一个圆形。 centerShpere 从公共库 2.8.3 开始支持 centerSphere 对应的值的定义是：[ [经度, 纬度], 半径 ] 半径需以弧度计，比如需要 10km 的半径，则用距离除以地球半径...

Command.all(values: any[]): Command 支持端：小程序 2.8.3, 云函数 1.2.1, Web 数组查询操作符。用于数组字段的查询筛选条件，要求数组字段中包含给定数组的所有元素。 参数 values: any[] 返回值 Command 示例代码 1：普通数组 找出 tags 数组字段同时包含 cloud 和 database 的记录 const _ = db.command db.collection('todos').where({ tags: _.all(['cloud', 'database']) }) .get({ success: console.log, fail: console.error }) 示例代码 2：对象数组 如果数组元素是对象，则可以用 _.elemMatch 匹配对象的部分字段 假设有字段 places 定义如下： { "type": string "area": number "age": number } 找出数组字段中至少同时包含一个满足 “area 大于 100 且 age 小于 2” 的元素和一个满足 “type 为 mall 且 age 大于 5” 的元素 const _ = db.command db.collection('todos').where({ places: _.all([ _.elemMatch({ area: _.gt(100), age: _.lt(2), }), _.elemMatch({ name: 'mall', age: _.gt(5), }), ]), }) .get({ success: console.log, fail: console.error, }) Command.elemMatch(condition: Object|Command): Command 支持端：小程序 2.8.3, 云函数 1.2.1, Web 用于数组字段的查询筛选条件，要求数组中包含至少一个满足 elemMatch 给定的所有条件的元素 参数 condition: Object|Command 匹配条件 返回值 Command 示例代码：数组是对象数组的情况 假设集合示例数据如下： { "_id": "a0", "city": "x0", "places": [{ "type": "garden", "area": 300, "age": 1 }, {...

Command.exists(value: boolean): Command 支持端：小程序 2.8.3, 云函数 1.2.1, Web 判断字段是否存在 参数 value: boolean 返回值 Command 示例代码 找出存在 tags 字段的记录 const _ = db.command db.collection('todos').where({ tags: _.exists(true) }) .get({ success: console.log, fail: console.error }) Command.mod(divisor: number, remainder: number): Command 支持端：小程序 2.8.3, 云函数 1.2.1, Web 查询筛选操作符，给定除数 divisor 和余数 remainder，要求字段作为被除数时 value % divisor = remainder。 参数 divisor: number remainder: number 返回值 Command 示例代码 找出进度为 10 的倍数的字段的记录 const _ = db.command db.collection('todos').where({ progress: _.mod(10, 0) }) .get({ success: console.log, fail: console.error })

Command.eq(value: any): Command 支持端：小程序 , 云函数 , Web 查询筛选条件，表示字段等于某个值。eq 指令接受一个字面量 (literal)，可以是 number, boolean, string, object, array, Date。 参数 value: any 返回值 Command 使用说明 比如筛选出所有自己发表的文章，除了用传对象的方式： const openID = 'xxx' db.collection('articles').where({ _openid: openID }) 还可以用指令： const _ = db.command const openID = 'xxx' db.collection('articles').where({ _openid: _.eq(openid) }) 注意 eq 指令比对象的方式有更大的灵活性，可以用于表示字段等于某个对象的情况，比如： // 这种写法表示匹配 stat.publishYear == 2018 且 stat.language == 'zh-CN' db.collection('articles').where({ stat: { publishYear: 2018, language: 'zh-CN' } }) // 这种写法表示 stat 对象等于 { publishYear: 2018, language: 'zh-CN' } const _ = db.command db.collection('articles').where({ stat: _.eq({ publishYear: 2018, language: 'zh-CN' }) }) Command.neq(value: any): Command 支持端：小程序 , 云函数 , Web 查询筛选条件，表示字段不等于某个值。eq 指令接受一个字面量 (literal)，可以是 number, boolean, string, object, array, Date。 参数 value: any 返回值 Command 使用说明 表示字段不等于某个值，和 eq 相反 Command.lt(value: any): Command 支持端：小程序 , 云函数 , Web 查询筛选操作符，表示需小于指定值。可以传入 Date 对象用于进行日期比较。 参数 value: any 返回值 Command 示例代码 找出进度小于 50 的 todo const _ = db.command db.collection('todos').where({ progress: _.lt(50) }) .get({ success: console.log, fail: console.error }) Command.lte(value: any): Command 支持端：小程序 , 云函数 , Web 查询筛选操作符，表示需小于或等于指定值。可以传入 Date 对象用于进行日期比较。 参数...

Command.and(expressions: any[]): Command 支持端：小程序 , 云函数 , Web 查询操作符，用于表示逻辑 “与” 的关系，表示需同时满足多个查询筛选条件 参数 expressions: any[] 返回值 Command 使用说明 and 有两种使用情况： 1. 用在根查询条件 此时需传入多个查询条件，表示需同时满足提供的多个完整查询条件 const _ = db.command db.collection('todo').where(_.and([ { progress: _.gt(50) }, { tags: 'cloud' } ])).get() 但以上用 and 组成的查询条件是不必要的，因为传入的对象的各字段隐式组成了 “与” 的关系，上述条件等价于下方更简洁的写法： const _ = db.command db.collection('todo').where({ progress: _.gt(50), tags: 'cloud' }).get() 通常需要显示使用 and 是用在有跨字段或操作的时候，如以下表示 “progress 字段大于 50 或 tags 字段等于 cloud 或 tags 数组字段（如果 tags 是数组）中含有 cloud”： const _ = db.command db.collection('todo').where(_.and([ _.or({ progress: _.gt(50) }), _.or({ tags: 'cloud' }) ])).get() 2. 用在字段查询条件 需传入多个查询操作符或常量，表示字段需满足或匹配给定的条件。 如以下用前置写法的方式表示 “progress 字段值大于 50 且小于 100” const _ = db.command db.collection('todo').where({ progress: _.and(_.gt(50), _.lt(100)) }) 还可以用后置写法的方式表示同样的条件： const _ = db.command db.collection('todo').where({ progress: _.gt(50).and(_.lt(100)) }) 注意 Command 默认也可以直接链式调用其他 Command，默认表示多个 Command 的与操作，因此上述代码还可以精简为： const _ = db.command db.collection('todo').where({ progress: _.gt(50).lt(100) }) 调用风格 方法接收两种传参方式，一是传入一个数组参数，二是传入多个参数，效果一样。 // 传入数组 function and(expressions: Expression[]): Command // 传入多参数 function and(...expressions: Expression[]):...

Transaction 数据库事务操作对象 方法： Transaction.collection(name: string): Collection 支持端：云函数 事务中获取集合的引用。方法接受一个 name 参数，指定需引用的集合名称。 参数 name: string 集合名称 返回值 Collection 集合引用 注意事项 在事务中仅能进行单记录操作，也就是不能使用 where、aggregate 接口，可以使用的接口如下： collection 获取集合引用 |-- add 新增记录 |-- doc 获取记录引用 |-- get 获取记录内容 |-- update 更新记录内容 |-- set 替换记录内容 |-- remove 删除记录 Transaction.rollback(reason: any): Promise<void> 支持端：云函数 终止并回滚事务 参数 reason: any 终止后，希望在 runTransaction 返回的 Promise reject 时接收到的值。 返回值 Promise.<void> 终止完成 示例代码 const cloud = require('wx-server-sdk') cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) const db = cloud.database({ throwOnNotFound: false, }) const _ = db.command try { const result = await db.runTransaction(async transaction => { const aaaRes = await transaction.collection('account').doc('aaa').get() // ... // 终止事务 await transaction.rollback(-100) }) } catch (e) { // e === -100 console.error(`transaction error`, e) } Transaction.commit(reason: any): Promise<void> 支持端：云函数 提交事务 参数 reason: any 终止后，希望在 runTransaction 返回的...

Geo 数据库地理位置结构集 方法： Geo.Point(longitude: number, latitude: number): GeoPoint 支持端：小程序 , 云函数 , Web 构造一个地理位置 ”点“。方法接受两个必填参数，第一个是经度（longitude），第二个是纬度（latitude），务必注意顺序。 参数 longitude: number 经度 latitude: number 纬度 返回值 GeoPoint 索引 如存储地理位置信息的字段有被查询的需求，务必对字段建立地理位置索引 示例代码 db.collection('todos').add({ data: { description: 'eat an apple', location: db.Geo.Point(113, 23) } }).then(console.log).catch(console.error) 除了使用接口构造一个点外，也可以使用等价的 GeoJSON 的 点 (Point) 的 JSON 表示，其格式如下： { "type": "Point", "coordinates": [longitude, latitude] // 数字数组：[经度, 纬度] } 示例代码 db.collection('todos').add({ data: { description: 'eat an apple', location: { type: 'Point', coordinates: [113, 23] } } }).then(console.log).catch(console.error) Geo.LineString(points: GeoPoint[]): GeoPoint 支持端：小程序 2.6.3, 云函数 构造一个地理位置的 ”线“。一个线由两个或更多的点有序连接组成。 参数 points: GeoPoint[] “点” 数组 返回值 GeoPoint 索引 如存储地理位置信息的字段有被查询的需求，务必对字段建立地理位置索引 示例代码 db.collection('todos').add({ data: { description: 'eat an apple', location: db.Geo.LineString([ db.Geo.Point(113, 23), db.Geo.Point(120, 50), // ... 可选更多点 ]) } }).then(console.log).catch(console.error) 除了使用接口构造一条 LineString 外，也可以使用等价的 GeoJSON 的 线 (LineString) 的 JSON 表示，其格式如下： { "type": "LineString", "coordinates": [ [p1_lng, p1_lat], [p2_lng, p2_lng] // ... 可选更多点 ] } 示例代码...