下面概述了 Bundle Builder API 的规范，包括 TypeScript 定义及详细说明。
BundleDocument 接口
已配置的集合中单个文档的规范：
type BundleDocument = {
// A list of document IDs to serve in the bundle.
docs?: Array<string>;
// A map containing individual named queries and their definitions.
queries?: Map<string, QueryDefinition[]>;
// A map of parameters and their definitions, which can be provided to a query definition.
params?: Map<string, ParamDefinition>;
// Specifies how long to keep the bundle in the client's cache, in seconds. If not defined, client-side cache is disabled.
clientCache?: string;
// Only used in combination with Firebase Hosting. Specifies how long to keep the bundle in Firebase Hosting CDN cache, in seconds.
serverCache: string;
// Specifies how long (in seconds) to keep the bundle in a Cloud Storage bucket, in seconds. If not defined, Cloud Storage bucket is not accessed.
fileCache?: string;
// If a 'File Cache' is specified, bundles created before this timestamp will not be file cached.
notBefore?: Timestamp;
};
ParamDefinition 接口
在 BundleDocument 中定义的单个参数的规范。
type ParamDefinition = {
// Whether this parameter is required. If not provided as a query string, an error will be thrown.
required: boolean;
// The type of value which will be parsed, defaults to 'string'.
type?:
| "string"
| "integer"
| "float"
| "boolean"
| "string-array"
| "integer-array"
| "float-array";
};
例如，假定有以下参数：
params: {
name: {
required: true,
type: 'string',
}
}
向捆绑包 HTTP 端点发出请求时，可以通过查询参数（例如 ?name=david）提供该参数。该参数可以在 QueryDefinition（见下文）值 ($name) 内使用，用于动态创建捆绑包。
QueryDefinition 接口
查询定义用于在捆绑包上创建命名的查询。queries 映射中的每个对象都会创建一个新的命名查询，并会使用对象的键作为名称。每个查询都必须指定一个集合，并且可以视需要指定若干要执行的查询条件。
type QueryDefinition = {
// The collection to perform the query on.
collection: string;
// An optional list of conditions to perform on the specified collection.
conditions?: QueryCondition[];
};
conditions 参数可以包含由若干 QueryCondition 接口组成的数组。数组中的每一项只能包含一个条件。
type QueryCondition = {
// Performs a `where` filter on the collection on a given FieldPath, operator and value.
where?: [
string,
(
| "<"
| "<="
| "=="
| ">="
| ">"
| "!="
| "array-contains"
| "in"
| "not-in"
| "array-contains-any"
),
any
];
orderBy?: [string, ("asc" | "desc")?];
limit?: number;
limitToLast?: number;
offset?: number;
startAt?: string;
startAfter?: string;
endAt?: string;
endBefore?: string;
};
例如，如需在 products 集合上创建一个名为“products”的查询，并且包含 where 和 limit 条件，则数据结构输出应如下所示：
queries: {
products: {
collection: 'products',
conditions: [
{ where: ['type', '==', 'featured'] },
{ limit: 10 },
],
}
}
向 in、not-in 或 array-contains-any 过滤条件提供数组值时，您必须提供以英文逗号分隔的值，因为 Firestore 不支持嵌套数组值。例如：
{ where: ['category', 'in', 'womens,shorts'] }, // ['womens', 'shorts']
所有数字值都会被解析为数值，不过如果需要将数字值用作字符串，将该值用括号括起来即可：
{ where: ['price', 'in', '1,2.5'] }, // [1, 2.5]
{ where: ['price', 'in', '"1","2.5"'] }, // ['1', '2.5']
条件也可以与参数一起使用。例如，如果定义了一个 type 参数（见上文），则可以向条件值提供该参数，以便通过 $ 语法提供动态数据捆绑包：
// ?type=featured
conditions: [
{ where: ['type', '==', '$type'] },