• English

      • ctx.collection

      The Collection instance associated with the current RunJS execution context, used to access collection metadata, field definitions, primary keys, and other configurations. It usually originates from ctx.blockModel.collection or ctx.collectionField?.collection.

      Use Cases

      ScenarioDescription
      JSBlockThe collection bound to the block; can access name, getFields, filterTargetKey, etc.
      JSField / JSItem / JSColumnThe collection the current field belongs to (or the parent block's collection), used to retrieve field lists, primary keys, etc.
      Table Column / Detail BlockUsed for rendering based on collection structure or passing filterByTk when opening popups.

      Note: ctx.collection is available in scenarios where a data block, form block, or table block is bound to a collection. In an independent JSBlock that is not bound to a collection, it may be null. It is recommended to perform a null check before use.

      Type Definition

      collection: Collection | null | undefined;

      Common Properties

      PropertyTypeDescription
      namestringCollection name (e.g., users, orders)
      titlestringCollection title (includes internationalization)
      filterTargetKeystring | string[]Primary key field name, used for filterByTk and getFilterByTK
      dataSourceKeystringData source key (e.g., main)
      dataSourceDataSourceThe data source instance it belongs to
      templatestringCollection template (e.g., general, file, tree)
      titleableFieldsCollectionField[]List of fields that can be displayed as titles
      titleCollectionFieldCollectionFieldThe title field instance

      Common Methods

      MethodDescription
      getFields(): CollectionField[]Get all fields (including inherited ones)
      getField(name: string): CollectionField | undefinedGet a single field by field name
      getFieldByPath(path: string): CollectionField | undefinedGet a field by path (supports associations, e.g., user.name)
      getAssociationFields(types?): CollectionField[]Get association fields; types can be ['one'], ['many'], etc.
      getFilterByTK(record): anyExtract the primary key value from a record, used for the API's filterByTk

      Relationship with ctx.collectionField and ctx.blockModel

      RequirementRecommended Usage
      Collection associated with current contextctx.collection (equivalent to ctx.blockModel?.collection or ctx.collectionField?.collection)
      Collection definition of the current fieldctx.collectionField?.collection (the collection the field belongs to)
      Association target collectionctx.collectionField?.targetCollection (the target collection of an association field)

      In scenarios like sub-tables, ctx.collection might be the association target collection; in standard forms/tables, it is usually the collection bound to the block.

      Examples

      Get Primary Key and Open Popup

      const primaryKey = ctx.collection?.filterTargetKey ?? 'id';
await ctx.openView(popupUid, {
  mode: 'dialog',
  params: {
    filterByTk: ctx.record?.[primaryKey],
    record: ctx.record,
  },
});

      Iterate Through Fields for Validation or Linkage

      const fields = ctx.collection?.getFields() ?? [];
const requiredFields = fields.filter((f) => f.options?.required);
for (const f of requiredFields) {
  const v = ctx.form?.getFieldValue(f.name);
  if (v == null || v === '') {
    ctx.message.warning(`${f.title} is required`);
    return;
  }
}

      Get Association Fields

      const oneToMany = ctx.collection?.getAssociationFields(['many']) ?? [];
// Used for building sub-tables, associated resources, etc.

      Notes

      • filterTargetKey is the primary key field name of the collection. Some collections may use a string[] for composite primary keys. If not configured, 'id' is commonly used as a fallback.
      • In scenarios like sub-tables or association fields, ctx.collection may point to the association target collection, which differs from ctx.blockModel.collection.
      • getFields() merges fields from inherited collections; local fields override inherited fields with the same name.
      • ctx.collectionField: The collection field definition of the current field
      • ctx.blockModel: The parent block hosting the current JS, containing collection
      • ctx.model: The current model, which may contain collection