Composables

API reference for composables

setupPage

Obtain corresponding resource data on the resources page.

function setupPage<Type extends PageType>({ type }: { type: Type }): Ref<PageTypeMap[Type]>

type PageType = 'article' | 'desk' | 'tag' | 'author'

interface PageTypeMap {
  article: Article
  desk: Desk
  tag: Tag
  author: Author
}
 

Parameters

  • type: return the data of the passed in type.
 

Returns

interface 
 

Examples

<script lang="ts" setup>
const article = setupPage({ type: 'article' })
<script />

<template>
  <div>
    <ul>
      <li>title: {{ article.title }}</li>
    </ul>
  </div>
</template> 
 

 

useField

Obtain custom field values through useField.

function useField<Type extends FieldType>(key: string, type: Type): UseFieldReturn<Type, false>
function useField<Type extends FieldType, IsAll extends boolean>(
  key: string,
  type: Type,
  all: IsAll
): UseFieldReturn<Type, IsAll>

enum FieldType {
  Text = 'TEXT',
  Number = 'NUM',
  Bool = 'BOOL',
  File = 'FILE',
  URL = 'URL',
  Color = 'COLOR',
  Date = 'DATE',
  RichText = 'RICHTEXT',
  Json = 'JSON',
  Ref = 'REF',
}

interface FieldTypeMap {
  [FieldType.Text]: string
  [FieldType.Number]: number
  [FieldType.Bool]: boolean
  [FieldType.File]: string
  [FieldType.URL]: string
  [FieldType.Color]: string
  [FieldType.Date]: Date
  [FieldType.RichText]: unknown
  [FieldType.Json]: unknown
  [FieldType.Ref]: unknown
}

type UseFieldReturn<Type, IsAll extends boolean> = Type extends FieldType
  ? IsAll extends true
    ? Ref<FieldTypeMap[Type][]>
    : Ref<FieldTypeMap[Type]>
  : IsAll extends true
  ? Ref<unknown[]>
  : Ref<unknown>
 

Parameters

  • key: the format of the key is <group key>.<field key>
  • type: type of custom field
  • all: setting true will return an array of all values of the field
 

Returns

interface FieldTypeMap {
  [FieldType.Text]: string
  [FieldType.Number]: number
  [FieldType.Bool]: boolean
  [FieldType.File]: string
  [FieldType.URL]: string
  [FieldType.Color]: string
  [FieldType.Date]: Date
  [FieldType.RichText]: unknown
  [FieldType.Json]: unknown
  [FieldType.Ref]: unknown
}
 

Examples

Using the custom field value of a tag group

 
  1. Setting custom fields in your content model
    1. Notion image
      Notion image
  1. Create custom field values of a tag in a tag group
    1. Notion image
  1. Use useField in the resource page to get the corresponding custom field value
    1. <script lang="ts" setup>
      	const customColor = useField('
 

 

useArticle

  1. Pass data from useProvideArticle
  1. If useProvideArticle isn’t set, this will show an error
 

Examples

<script lang="ts" setup>
const article = useArticle()
</script>

<template>
	<div>{{ article.content }}</div>
</template>
 

 

useSite

Access the metadata for your publication site via this hook

  • publication name
  • logo
  • social links
  • favicon
  • timezone
 
interface Site {
  
 

Examples

<script lang="ts" setup>
const site = useSite()
<script />

<template>
  <h1>{{ site.publicationName }}</h1>
</template> 
 

 

useSearchClient

interface UseSearchClientInput {
  /**
   * Fields for query, this is a comma separated string
   */
  queryBy?: string
  /**
   * API key, this will override the key in runtimeConfig
   */
  apiKey?: string
}

declare function useSearchClient(params?: UseSearchClientInput): {
    searchClient: any;
    indexName: string;
}
 

Parameters

  • UseSearchClientInput:
    • queryBy: Fields for query, this is a comma separated string
    • apiKey: API key, this will override the key in runtimeConfig
 

Returns

interface UseSearchClientReturn {
    searchClient: any;
    indexName: string;
}
 

Examples

<script lang="ts" setup>
 

 

useFillArticles

Obtain a specific number of articles that meet the criteria.

⚠️
This function must used in the setup scope
interface DeskConditionOption {
  
 

Parameters

  • count: Required
    • Enter the number of articles you need to obtain
  • conditionInput: Optional
    • 預設使用所有文章進行填充,如果需要限制填充條件則可使用這個餐數,將所需條件使用陣列傳入,陣列內值為 string 時預設以 Desk name 作為條件。
  • conditionMeta: Optional
    • cacheKey: Parameter used to control the internal cache id. This id must be global and unique, otherwise the later data will overwrite the previous data. This parameter should not be entered manually, unless you encounter an edge case that requires it.
 

Returns

interface 
 

Examples

<script lang="ts" setup>
const { articles: alphabetArticles } = useFillArticles(10, [
 

 

useArticleLoader

Allow articles to be easily loaded into pages such as desk pages, tag pages, etc., automatically reading the current page desk, or accepting the incoming desk as a filter.

// This is same as `useFillArticles`
interface 
 

Parameters

  • chunk infinite scroll when loading articles one by one, when passing false it will load article one by one without wrapping in an array, which is the default behavior for both useArticleLoader and InfiniteScroll
  • preload the number of articles preloaded at the start, these articles will appear directly in the html. If not given then the default is the amount of chunk or 0
  • condition Same condition input as useFillArticles, if not it will try to use the same desk or tag as the current page
 

Returns

interface 
 

Examples

<script lang="ts" setup>
const { preload, createLoadMore } = useArticleLoader({ preload: 4, chunk: 4 })
</script>

<template>
  <div>
    <div class="flex gap-2"><ArticleLayout v-for="article of preload" :key="article.id" :article="article" /></div>
    <div>Infinite scroll start</div>
    <InfiniteScroll v-slot="articles" :source="createLoadMore">
      <div class="flex gap-2 mb-2">
        <ArticleLayout v-for="article of articles" :key="article.id" :article="article" />
      </div>
    </InfiniteScroll>
  </div>
</template>
 

 

useLoadMore

This hook makes it easy to implement infinite scroll, read more articles, etc.

declare function useLoadMore<T>(generatorSource: () => AsyncGenerator<T>): {
  loading: Ref<boolean>
  isDone: Ref<boolean>
  list: Article[]
  loadMore: () => Promise<T | undefined>
  onLoadMore: EventHookOn<T>
  onLoadDone: EventHook<void>
}
 

Parameters

  • generatorSource: Required
    • An AsyncGenerator is passed in as an argument, and the source object created by the generatorSource returns a set of content data each time .next() is called.
 

Returns

interface UseLoadMoreReturn {
  
 

Examples

<script setup lang="ts">
async function* GenSource() {
  const articles = await getAllArticles()
  for (const article of articles) {
    yield article
  }
}

const { loading, list, loadMore, onLoadMore, onLoadDone } = useLoadMore(GenSource)

onLoadMore((item) => {})
onLoadDone(() => {})

const onClick = async () => {
  if (loading) return
  await loadMore()
}
</script>

<template>
  <div>
    <div v-for="(article, index) of list" :key="index">
      <ArticleLayout :article="article" />
    </div>
    <div v-if="loading">Loading...</div>
  </div>
  <button @click="onClick">more</button>
</template>
 

Last updated on January 16, 2023