Katkıda Bulun
Geliştirici Araçları
Angular CLI

Kütüphaneler için Schematics

Bir Angular kütüphanesi oluşturduğunuzda, Angular CLI ile entegre eden şematiklerle birlikte sağlayabilir ve paketleyebilirsiniz. Şematiklerinizle, kullanıcılarınız kütüphanenizin başlangıç sürümünü yüklemek için ng add'ı, kütüphanenizde tanımlanan yapıtları oluşturmak için ng generate'i ve bozucu değişiklikler içeren yeni bir sürüm için projelerini uyarlamak üzere ng update'i kullanabilir.

Her üç şematik türü de kütüphanenizle paketleyebileceğiniz bir koleksiyonun parçası olabilir.

Schematics koleksiyonu oluşturma

Bir koleksiyon başlatmak için şematik dosyalarını oluşturmanız gerekir. Aşağıdaki adımlar, herhangi bir proje dosyasını değiştirmeden başlangıç desteğini nasıl ekleyeceğinizi gösterir.

  1. Kütüphanenizin kök klasöründe bir schematics klasörü oluşturun.

  2. schematics/ klasöründe, ilk şematiğiniz için bir ng-add klasörü oluşturun.

  3. schematics klasörünün kök düzeyinde bir collection.json dosyası oluşturun.

  4. collection.json dosyasını düzenleyerek koleksiyonunuzun başlangıç şemasını tanımlayın.

    projects/my-lib/schematics/collection.json (Schematics Collection)

    {
  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "ng-add": {
      "description": "Add my library to the project.",
      "factory": "./ng-add/index#ngAdd",
      "schema": "./ng-add/schema.json"
    }
  }
}
    • $schema yolu, Angular Devkit koleksiyon şemasına görelidir.
    • schematics nesnesi, bu koleksiyonun parçası olan adlandırılmış şematikleri tanımlar.
    • İlk giriş, ng-add adlı bir şematik içindir. Açıklamayı içerir ve şematiğiniz çalıştırıldığında çağrılan fabrika fonksiyonuna işaret eder.

  5. Kütüphane projenizin package.json dosyasında, şema dosyanızın yolunu içeren bir "schematics" girişi ekleyin. Angular CLI, komutları çalıştırırken koleksiyonunuzdaki adlandırılmış şematikleri bulmak için bu girişi kullanır.

projects/my-lib/package.json (Schematics Collection Reference)

{
  "name": "my-lib",
  "version": "0.0.1",
  "schematics": "./schematics/collection.json",
}

Oluşturduğunuz başlangıç şeması, CLI'a ng add komutunu destekleyen şematiğin nerede bulunacağını söyler. Artık o şematiği oluşturmaya hazırsınız.

Kurulum desteği sağlama

ng add komutu için bir şematik, kullanıcılarınız için başlangıç kurulum sürecini iyileştirebilir. Aşağıdaki adımlar bu tür bir şematiği tanımlar.

  1. <lib-root>/schematics/ng-add klasörüne gidin.
  2. Ana dosya olan index.ts'yi oluşturun.
  3. index.ts'yi açın ve şematik fabrika fonksiyonunuz için kaynak kodunu ekleyin.

projects/my-lib/schematics/ng-add/index.ts (ng-add Rule Factory)

import {Rule} from '@angular-devkit/schematics';
import {addRootImport} from '@schematics/angular/utility';
import {Schema} from './schema';

export function ngAdd(options: Schema): Rule {
  // Add an import `MyLibModule` from `my-lib` to the root of the user's project.
  return addRootImport(
    options.project,
    ({code, external}) => code`${external('MyLibModule', 'my-lib')}`,
  );
}

Angular CLI, kütüphanenin en son sürümünü otomatik olarak yükler ve bu örnek, uygulamanın köküne MyLibModule'u ekleyerek bir adım daha ileri gider. addRootImport fonksiyonu, bir kod bloğu döndürmesi gereken bir geri çağrım kabul eder. code fonksiyonuyla etiketlenen dizenin içine herhangi bir kod yazabilirsiniz ve herhangi bir harici sembol, uygun import deyimlerinin oluşturulmasını sağlamak için external fonksiyonuyla sarılmalıdır.

Bağımlılık türünü tanımlama

Kütüphanenin projenin package.json yapılandırma dosyasındaki dependencies'e mi, devDependencies'e mi yoksa hiç kaydedilmemesi mi gerektiğini yapılandırmak için ng-add'in save seçeneğini kullanın.

projects/my-lib/package.json (ng-add Reference)

"ng-add": {
    "save": "devDependencies"
  },

Olası değerler:

Değerler Ayrıntılar
false Paketi package.json'a ekleme
true Paketi dependencies'e ekle
"dependencies" Paketi dependencies'e ekle
"devDependencies" Paketi devDependencies'e ekle

Schematics'lerinizi derleme

Şematiklerinizi kütüphanenizle birlikte paketlemek için kütüphaneyi şematikleri ayrı olarak derleyecek şekilde yapılandırmanız ve ardından bunları pakete eklemeniz gerekir. Şematiklerinizi kütüphanenizi derledikten sonra derlemeniz gerekir, böylece doğru dizine yerleştirilirler.

  • Kütüphanenizin, şematiklerinizi dağıtılan kütüphanenize nasıl derleyeceğine ilişkin talimatlar içeren özel bir TypeScript yapılandırma dosyasına ihtiyacı vardır
  • Şematikleri kütüphane paketine eklemek için kütüphanenin package.json dosyasına betikler ekleyin

Angular çalışma alanınızda my-lib adlı bir kütüphane projeniz olduğunu varsayalım. Kütüphaneye şematikleri nasıl derleyeceğini söylemek için, kütüphane derlemesini yapılandıran oluşturulan tsconfig.lib.json dosyasının yanına bir tsconfig.schematics.json dosyası ekleyin.

  1. tsconfig.schematics.json dosyasını düzenleyerek aşağıdaki içeriği ekleyin.

    projects/my-lib/tsconfig.schematics.json (TypeScript Config)

    {
  "compilerOptions": {
    "baseUrl": ".",
    "lib": [
      "es2018",
      "dom"
    ],
    "declaration": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "noEmitOnError": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noImplicitThis": true,
    "noUnusedParameters": true,
    "noUnusedLocals": true,
    "rootDir": "schematics",
    "outDir": "../../dist/my-lib/schematics",
    "skipDefaultLibCheck": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strictNullChecks": true,
    "target": "es6",
    "types": [
      "jasmine",
      "node"
    ]
  },
  "include": [
    "schematics/**/*"
  ],
  "exclude": [
    "schematics/*/files/**/*"
  ]
}
    Seçenekler Ayrıntılar
    rootDir schematics klasörünüzün derlenecek girdi dosyalarını içerdiğini belirtir.
    outDir Kütüphanenin çıktı klasörüne eşlenir. Varsayılan olarak bu, çalışma alanınızın kökündeki dist/my-lib klasörüdür.

  2. Şematik kaynak dosyalarınızın kütüphane paketine derlendiğinden emin olmak için, kütüphane projenizin kök klasöründeki (projects/my-lib) package.json dosyasına aşağıdaki betikleri ekleyin.

    projects/my-lib/package.json (Build Scripts)

    {
  "name": "my-lib",
  "version": "0.0.1",
  "scripts": {
    "build": "tsc -p tsconfig.schematics.json",
    "postbuild": "copyfiles schematics/*/schema.json schematics/*/files/** schematics/collection.json ../../dist/my-lib/"
  },
  "peerDependencies": {
    "@angular/common": "^22.0.0",
    "@angular/core": "^22.0.0"
  },
  "schematics": "./schematics/collection.json",
  "ng-add": {
    "save": "devDependencies"
  },
  "devDependencies": {
    "copyfiles": "file:../../node_modules/copyfiles",
    "typescript": "file:../../node_modules/typescript"
  }
}
    • build betiği, özel tsconfig.schematics.json dosyasını kullanarak şematiğinizi derler
    • postbuild betiği, build betiği tamamlandıktan sonra şematik dosyalarını kopyalar
    • Hem build hem de postbuild betikleri copyfiles ve typescript bağımlılıklarını gerektirir. Bağımlılıkları yüklemek için devDependencies içinde tanımlanan yola gidin ve betikleri çalıştırmadan önce npm install komutunu çalıştırın.

Oluşturma desteği sağlama

Kullanıcılarınızın kütüphanenizde tanımlanan bir yapıtı oluşturmak için ng generate komutunu kullanmalarına olanak tanıyan, koleksiyonunuza adlandırılmış bir şematik ekleyebilirsiniz.

Kütüphanenizin bazı kurulum gerektiren my-service adlı bir servis tanımladığını varsayalım. Kullanıcılarınızın aşağıdaki CLI komutunu kullanarak bunu oluşturabilmesini istiyorsunuz.

ng generate my-lib:my-service

Başlamak için schematics klasöründe my-service adlı yeni bir alt klasör oluşturun.

Yeni şematiği yapılandırma

Koleksiyona bir şematik eklediğinizde, koleksiyonun şemasında ona işaret etmeniz ve bir kullanıcının komuta geçirebileceği seçenekleri tanımlayan yapılandırma dosyaları sağlamanız gerekir.

  1. schematics/collection.json dosyasını düzenleyerek yeni şematik alt klasörüne işaret edin ve yeni şematik için girdileri belirten bir şema dosyasına bir işaretçi ekleyin.

    projects/my-lib/schematics/collection.json (Schematics Collection)

    {
  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "ng-add": {
      "description": "Add my library to the project.",
      "factory": "./ng-add/index#ngAdd",
      "schema": "./ng-add/schema.json"
    },
    "my-service": {
      "description": "Generate a service in the project.",
      "factory": "./my-service/index#myService",
      "schema": "./my-service/schema.json"
    }
  }
}

  2. <lib-root>/schematics/my-service klasörüne gidin.

  3. Bir schema.json dosyası oluşturun ve şematik için mevcut seçenekleri tanımlayın.

    projects/my-lib/schematics/my-service/schema.json (Schematic JSON Schema)

    {
  "$schema": "http://json-schema.org/schema",
  "$id": "SchematicsMyService",
  "title": "My Service Schema",
  "type": "object",
  "properties": {
    "name": {
      "description": "The name of the service.",
      "type": "string"
    },
    "path": {
      "type": "string",
      "format": "path",
      "description": "The path to create the service.",
      "visible": false,
      "$default": {
        "$source": "workingDirectory"
      }
    },
    "project": {
      "type": "string",
      "description": "The name of the project.",
      "$default": {
        "$source": "projectName"
      }
    }
   },
  "required": [
    "name"
  ]
}
    • id: Koleksiyondaki şema için benzersiz bir kimlik.
    • title: Şemanın insan tarafından okunabilir bir açıklaması.
    • type: Özellikler tarafından sağlanan türün açıklayıcısı.
    • properties: Şematik için mevcut seçenekleri tanımlayan bir nesne.

    Her seçenek bir anahtarı bir tür, açıklama ve isteğe bağlı takma adla ilişkilendirir. Tür, beklediğiniz değerin biçimini tanımlar ve açıklama, kullanıcı şematiğiniz için kullanım yardımı istediğinde görüntülenir.

    Şematik seçenekleri için ek özelleştirmeler hakkında çalışma alanı şemasına bakın.

  4. Bir schema.ts dosyası oluşturun ve schema.json dosyasında tanımlanan seçeneklerin değerlerini depolayan bir arayüz tanımlayın.

    projects/my-lib/schematics/my-service/schema.ts (Schematic Interface)

    export interface Schema {
  // The name of the service.
  name: string;

  // The path to create the service.
  path?: string;

  // The name of the project.
  project?: string;
}
    Seçenekler Ayrıntılar
    name Oluşturulan servis için sağlamak istediğiniz ad.
    path Şematiğe sağlanan yolu geçersiz kılar. Varsayılan yol değeri geçerli çalışma dizinine dayanır.
    project Şematiğin çalıştırılacağı belirli bir proje sağlar. Şematikte, seçenek kullanıcı tarafından sağlanmazsa bir varsayılan sağlayabilirsiniz.

Şablon dosyalarını ekleme

Bir projeye yapıtlar eklemek için şematiğinizin kendi şablon dosyalarına ihtiyacı vardır. Şematik şablonları, kod çalıştırma ve değişken değiştirme için özel sözdizimini destekler.

  1. schematics/my-service/ klasörü içinde bir files/ klasörü oluşturun.

  2. Dosya oluşturmak için kullanılacak bir şablonu tanımlayan __name@dasherize__.service.ts.template adlı bir dosya oluşturun. Bu şablon, Angular'ın HttpClient'ını zaten bir http özelliğine enjekte edilmiş olarak içeren bir servis oluşturacaktır.

    import { Service } from '@angular/core';
import { HttpClient } from '@angular/common/http';

@Service()
export class <%= classify(name) %>Service {
   private http = inject(HttpClient);
}
    • classify ve dasherize metotları, şematiğinizin kaynak şablonunu ve dosya adını dönüştürmek için kullandığı yardımcı fonksiyonlardır.
    • name, fabrika fonksiyonunuzdan bir özellik olarak sağlanır. Şemada tanımladığınız name ile aynıdır.

Fabrika fonksiyonunu ekleme

Artık altyapı yerinde olduğuna göre, kullanıcının projesinde ihtiyaç duyduğunuz değişiklikleri gerçekleştiren ana fonksiyonu tanımlayabilirsiniz.

Schematics çerçevesi, hem yol hem de içerik şablonlarını destekleyen bir dosya şablonlama sistemi sağlar. Sistem, girdi Tree'sine yüklenen dosyalar veya yollar içinde tanımlanan yer tutucular üzerinde çalışır. Bunları Rule'a geçirilen değerlerle doldurur.

Bu veri yapıları ve sözdiziminin ayrıntıları için Schematics README belgesine bakın.

  1. Ana dosya index.ts'yi oluşturun ve şematik fabrika fonksiyonunuz için kaynak kodunu ekleyin.

  2. İlk olarak, ihtiyacınız olacak şematik tanımlarını içe aktarın. Schematics çerçevesi, bir şematiği çalıştırırken kurallar oluşturmak ve kullanmak için birçok yardımcı fonksiyon sunar.

    projects/my-lib/schematics/my-service/index.ts (Imports)

    import {
  Rule,
  Tree,
  SchematicsException,
  apply,
  url,
  applyTemplates,
  move,
  chain,
  mergeWith,
} from '@angular-devkit/schematics';

import {strings, normalize, virtualFs, workspaces} from '@angular-devkit/core';

  3. Şematiğinizin seçenekleri için tür bilgisi sağlayan tanımlı şema arayüzünü içe aktarın.

    projects/my-lib/schematics/my-service/index.ts (Schema Import)

    import {
  Rule,
  Tree,
  SchematicsException,
  apply,
  url,
  applyTemplates,
  move,
  chain,
  mergeWith,
} from '@angular-devkit/schematics';

import {strings, normalize, virtualFs, workspaces} from '@angular-devkit/core';

import {Schema as MyServiceSchema} from './schema';

  4. Oluşturma şematiğini oluşturmak için boş bir kural fabrikasıyla başlayın.

    projects/my-lib/schematics/my-service/index.ts (Initial Rule)

    export function myService(options: MyServiceSchema): Rule {
  return (tree: Tree) => tree;
}

Bu kural fabrikası, ağacı değiştirmeden döndürür. Seçenekler, ng generate komutundan geçirilen seçenek değerleridir.

Bir oluşturma kuralı tanımlama

Artık kullanıcının uygulamasını, kütüphanenizde tanımlanan servis için kurmak üzere gerçekten değiştiren kodu oluşturmak için çerçeveye sahipsiniz.

Kullanıcının kütüphanenizi yüklediği Angular çalışma alanı birden fazla proje (uygulama ve kütüphane) içerir. Kullanıcı projeyi komut satırında belirtebilir veya varsayılana bırakabilir. Her iki durumda da, bu şematiğin uygulandığı belirli projeyi tanımlamanız gerekir, böylece proje yapılandırmasından bilgi alabilirsiniz.

Bunu, fabrika fonksiyonuna geçirilen Tree nesnesini kullanarak yapın. Tree metotları, çalışma alanınızdaki eksiksiz dosya ağacına erişmenizi sağlar ve şematiğin yürütülmesi sırasında dosyaları okumanıza ve yazmanıza olanak tanır.

Proje yapılandırmasını alma

  1. Hedef projeyi belirlemek için, çalışma alanı yapılandırma dosyası angular.json'ın içeriğini okumak üzere workspaces.readWorkspace metodunu kullanın. workspaces.readWorkspace kullanmak için Tree'den bir workspaces.WorkspaceHost oluşturmanız gerekir. Fabrika fonksiyonunuza aşağıdaki kodu ekleyin.

    projects/my-lib/schematics/my-service/index.ts (Schema Import)

    import {
  Rule,
  Tree,
  SchematicsException,
  apply,
  url,
  applyTemplates,
  move,
  chain,
  mergeWith,
} from '@angular-devkit/schematics';

import {strings, normalize, virtualFs, workspaces} from '@angular-devkit/core';

import {Schema as MyServiceSchema} from './schema';

function createHost(tree: Tree): workspaces.WorkspaceHost {
  return {
    async readFile(path: string): Promise<string> {
      const data = tree.read(path);
      if (!data) {
        throw new SchematicsException('File not found.');
      }
      return virtualFs.fileBufferToString(data);
    },
    async writeFile(path: string, data: string): Promise<void> {
      return tree.overwrite(path, data);
    },
    async isDirectory(path: string): Promise<boolean> {
      return !tree.exists(path) && tree.getDir(path).subfiles.length > 0;
    },
    async isFile(path: string): Promise<boolean> {
      return tree.exists(path);
    },
  };
}

export function myService(options: MyServiceSchema): Rule {
  return async (tree: Tree) => {
    const host = createHost(tree);
    const {workspace} = await workspaces.readWorkspace('/', host);

  };
}

    Bağlamın var olduğunu kontrol ettiğinizden ve uygun hatayı fırlattığınızdan emin olun.

  2. Artık proje adına sahip olduğunuza göre, projeye özgü yapılandırma bilgilerini almak için kullanın.

    projects/my-lib/schematics/my-service/index.ts (Project)

    const project = options.project != null ? workspace.projects.get(options.project) : null;
    if (!project) {
      throw new SchematicsException(`Invalid project name: ${options.project}`);
    }

    const projectType = project.extensions.projectType === 'application' ? 'app' : 'lib';

    workspace.projects nesnesi, projeye özgü tüm yapılandırma bilgilerini içerir.

  3. options.path, şematik uygulandığında şematik şablon dosyalarının taşınacağı yeri belirler.

    Şematiğin şemasındaki path seçeneği varsayılan olarak geçerli çalışma diziniyle değiştirilir. path tanımlanmamışsa, proje yapılandırmasından sourceRoot'u projectType ile birlikte kullanın.

    projects/my-lib/schematics/my-service/index.ts (Project Info)

    if (options.path === undefined) {
      options.path = `${project.sourceRoot}/${projectType}`;
    }

Kuralı tanımlama

Bir Rule, harici şablon dosyalarını kullanabilir, dönüştürebilir ve dönüştürülmüş şablonla başka bir Rule nesnesi döndürebilir. Şematiğiniz için gereken özel dosyaları oluşturmak üzere şablonlamayı kullanın.

  1. Fabrika fonksiyonunuza aşağıdaki kodu ekleyin.

    projects/my-lib/schematics/my-service/index.ts (Template transform)

    const templateSource = apply(url('./files'), [
      applyTemplates({
        classify: strings.classify,
        dasherize: strings.dasherize,
        name: options.name,
      }),
      move(normalize(options.path as string)),
    ]);
    Metotlar Ayrıntılar
    apply() Bir kaynağa birden fazla kural uygular ve dönüştürülmüş kaynağı döndürür. 2 argüman alır, bir kaynak ve kurallar dizisi.
    url() Dosya sisteminizden, şematiğe göre kaynak dosyaları okur.
    applyTemplates() Şematik şablonuna ve şematik dosya adlarına sunmak istediğiniz metotların ve özelliklerin bir argümanını alır. Bir Rule döndürür. Burada classify() ve dasherize() metotlarını ve name özelliğini tanımlarsınız.
    classify() Bir değer alır ve değeri başlık harfleriyle döndürür. Örneğin, sağlanan ad my service ise, MyService olarak döndürülür.
    dasherize() Bir değer alır ve değeri tireli ve küçük harflerle döndürür. Örneğin, sağlanan ad MyService ise, my-service olarak döndürülür.
    move() Şematik uygulandığında sağlanan kaynak dosyaları hedeflerine taşır.

  2. Son olarak, kural fabrikası bir kural döndürmelidir.

    projects/my-lib/schematics/my-service/index.ts (Chain Rule)

    return chain([mergeWith(templateSource)]);

    chain() metodu, birden fazla kuralı tek bir kurala birleştirmenize olanak tanır, böylece tek bir şematikte birden fazla işlem gerçekleştirebilirsiniz. Burada yalnızca şablon kurallarını şematik tarafından yürütülen herhangi bir kodla birleştiriyorsunuz.

Aşağıdaki şematik kural fonksiyonunun eksiksiz bir örneğine bakın.

projects/my-lib/schematics/my-service/index.ts

import {
  Rule,
  Tree,
  SchematicsException,
  apply,
  url,
  applyTemplates,
  move,
  chain,
  mergeWith,
} from '@angular-devkit/schematics';

import {strings, normalize, virtualFs, workspaces} from '@angular-devkit/core';

import {Schema as MyServiceSchema} from './schema';

function createHost(tree: Tree): workspaces.WorkspaceHost {
  return {
    async readFile(path: string): Promise<string> {
      const data = tree.read(path);
      if (!data) {
        throw new SchematicsException('File not found.');
      }
      return virtualFs.fileBufferToString(data);
    },
    async writeFile(path: string, data: string): Promise<void> {
      return tree.overwrite(path, data);
    },
    async isDirectory(path: string): Promise<boolean> {
      return !tree.exists(path) && tree.getDir(path).subfiles.length > 0;
    },
    async isFile(path: string): Promise<boolean> {
      return tree.exists(path);
    },
  };
}

export function myService(options: MyServiceSchema): Rule {
  return async (tree: Tree) => {
    const host = createHost(tree);
    const {workspace} = await workspaces.readWorkspace('/', host);


    const project = options.project != null ? workspace.projects.get(options.project) : null;
    if (!project) {
      throw new SchematicsException(`Invalid project name: ${options.project}`);
    }

    const projectType = project.extensions.projectType === 'application' ? 'app' : 'lib';

    if (options.path === undefined) {
      options.path = `${project.sourceRoot}/${projectType}`;
    }

    const templateSource = apply(url('./files'), [
      applyTemplates({
        classify: strings.classify,
        dasherize: strings.dasherize,
        name: options.name,
      }),
      move(normalize(options.path as string)),
    ]);

    return chain([mergeWith(templateSource)]);
  };
}

Kurallar ve yardımcı metotlar hakkında daha fazla bilgi için Sağlanan Kurallar belgesine bakın.

Kütüphane schematic'inizi çalıştırma

Kütüphanenizi ve şematiklerinizi derledikten sonra, projenize karşı çalıştırmak için şematik koleksiyonunu yükleyebilirsiniz. Aşağıdaki adımlar, daha önce oluşturduğunuz şematiği kullanarak bir servis oluşturmayı gösterir.

Kütüphanenizi ve schematics'lerinizi derleme

Çalışma alanınızın kökünden, kütüphaneniz için ng build komutunu çalıştırın.

ng build my-lib

Ardından, şematiği derlemek için kütüphane dizininize geçin

cd projects/my-lib
npm run build

Kütüphaneyi bağlama

Kütüphaneniz ve şematikleriniz paketlenmiş ve çalışma alanınızın kökündeki dist/my-lib klasörüne yerleştirilmiştir. Şematiği çalıştırmak için kütüphaneyi node_modules klasörünüze bağlamanız gerekir. Çalışma alanınızın kökünden, dağıtılabilir kütüphanenizin yolunu belirterek npm link komutunu çalıştırın.

npm link dist/my-lib

Schematic'i çalıştırma

Artık kütüphaneniz yüklü olduğuna göre, ng generate komutunu kullanarak şematiği çalıştırın.

ng generate my-lib:my-service --name my-data

Konsolda, şematiğin çalıştırıldığını ve my-data.service.ts dosyasının uygulama klasörünüzde oluşturulduğunu göreceksiniz.

CREATE src/app/my-data.service.ts (208 bytes)