Align article components with columns in your layout.
- Apple News Format
- Apple News API
You set the number of columns you want in your design using the
layout property of Article Document. To determine the position for a component, like a heading, you align the left edge of the component with a column in your layout. (The component will automatically line up with the left edge of the column.) See Layout and Planning the Layout for Your Article.
Layout columns are referred to by number—from left to right—starting with 0. You use this column system to figure out the positioning for all the components in your article and then, in your
article file, you’ll use a ComponentLayout object to specify the position settings.
Specify Positions for Components
Specify the starting column and how many columns you want a component to span. For example, in the previous figure, a pull quote component is positioned at column 0 and spans three columns. The figure also shows a caption component positioned at column 7 that spans three columns.
To specify the positioning for components, you create a component layout object at one of two levels. If you create a component layout object in ArticleDocument.componentLayouts, it can be referred to by multiple components. Two components that use the same component layout object start in the same column, span the same number of columns, and so on.
If you create a component layout object as a property for a specific component, it can be used only by that component.
The following code example shows a component layout object called
heading1Layout. This component layout object has been created in ArticleDocument.componentLayouts so it can be used by other components in the article.
Fine-Tune the Position of Components
You can use the
margin property of a ComponentLayout object to specify the top and bottom margins (in points) for a component and to create space above and below the component. Specify a single number to use for both measurements, or—to specify different settings for the top and bottom margins—use the Margin object.
In addition to using
margin, you can also use the
padding property of the
Component object to define the space inside a component. With the
padding property, you can set spacing for both sides of the component, as well as for the top and bottom. The
padding property is different from margins in that it applies to the spacing inside the component; margins are applied to the spacing of the component within the article.
An Anchor object located within the component object lets you associate the placement of one component with another component so you can align components vertically in your layout. The position of the target component determines the position of the component that has the anchor.
Align and Position Content
To make your content span the entire device screen, use the
ignore property of the ComponentLayout object.
In the following code example,
ignore is set to
true for the
image object, which causes padding on both sides of the screen to be ignored.
To make content extend past the columns of your article layout and into the margin that you added, but not into the extra padding added by the Apple News app, use the
ignore property of the ComponentLayout object. This property allows a component be full-width on most screens, while preventing it from growing too wide on very wide screens like Mac. Use
ignore only if you have not specified a value for
In the following code example, the
image object ignores the left and right margins specified in the document layout and spans the full width and the margin of the document. See Layout.
What Changed in iOS 13 and macOS 10.15
Prior to iOS 13 and macOS 10.15, the
ignore property of the ComponentLayout object caused a component to span the entire screen.
In iOS 13 and macOS 10.15, the
ignore property of the
Component object now allows a component to span the entire screen until the screen becomes wider than the document
margin and the document
To make a component span the entire screen, regardless of the screen width, use the
ignore property of the
If you previously used the
ignore property, you must update your
article file to use the
ignore property instead.
The following figure shows an
image object with
ignore set to
To make the image object span only the document width plus margin, set